Merge pull request #2539 from obsidian-tasks-group/explain-sortby

feat: Make 'explain' show 'sort by' commands

Author: claremacrae

docs/Introduction.md

@@ -14,7 +14,7 @@ _In recent [releases](https://github.com/obsidian-tasks-group/obsidian-tasks/rel
 -->
 
 - X.Y.Z: 🔥 Add [[Layout#Full Mode|'full mode']] to turn off `short mode`.
-- X.Y.Z: 🔥 Add any [[Grouping|'group by']] instructions to [[Explaining Queries|explain]] output.
+- X.Y.Z: 🔥 Add any [[Grouping|'group by']] and [[Sorting|'sort by']] instructions to [[Explaining Queries|explain]] output.
 - 5.3.0: 🔥 Add [[Postponing|postpone button]] to Tasks query results.
 - 5.3.0: 🔥 Add [[Toggling and Editing Statuses#'Change task status' context menu|'change task status' menu]] to Reading mode and Tasks query results.
 - 5.3.0: 🔥 Add documentation section about [[About Editing|editing tasks]].

docs/Queries/Explaining Queries.md

@@ -21,6 +21,7 @@ This has a number of benefits:
   - This often explains why tasks are missing from results.
 - If there is a [[Global Query|global query]] enabled, it too is included in the explanation.
 - Any [[Grouping|'group by']] instructions are listed (since Tasks X.Y.Z)
+- Any [[Sorting|'sort by']] instructions are listed (since Tasks X.Y.Z)
 
 ## Examples
 
@@ -53,6 +54,8 @@ Explanation of this Tasks code block query:
     due date is before 2022-10-22 (Saturday 22nd October 2022)
 
   No grouping instructions supplied.
+
+  No sorting instructions supplied.
 ```
 <!-- endSnippet -->
 
@@ -84,6 +87,8 @@ Explanation of this Tasks code block query:
     using regex:     '^Root\/Sub-Folder\/Sample File\.md' with flag 'i'
 
   No grouping instructions supplied.
+
+  No sorting instructions supplied.
 ```
 <!-- endSnippet -->
 
@@ -113,6 +118,8 @@ Explanation of this Tasks code block query:
       is recurring
 
   No grouping instructions supplied.
+
+  No sorting instructions supplied.
 ```
 <!-- endSnippet -->
 
@@ -157,6 +164,8 @@ Explanation of this Tasks code block query:
           description includes 7
 
   No grouping instructions supplied.
+
+  No sorting instructions supplied.
 ```
 <!-- endSnippet -->
 
@@ -194,6 +203,8 @@ Explanation of the global query:
 
   No grouping instructions supplied.
 
+  No sorting instructions supplied.
+
   At most 50 tasks.
 
 Explanation of this Tasks code block query:
@@ -206,6 +217,8 @@ Explanation of this Tasks code block query:
       2022-10-30 (Sunday 30th October 2022) inclusive
 
   No grouping instructions supplied.
+
+  No sorting instructions supplied.
 ```
 <!-- endSnippet -->
 
@@ -245,6 +258,8 @@ Explanation of this Tasks code block query:
   description includes Some Cryptic String 
 
   No grouping instructions supplied.
+
+  No sorting instructions supplied.
 ```
 <!-- endSnippet -->
 

docs/Queries/Line Continuations.md

@@ -37,6 +37,8 @@ Explanation of this Tasks code block query:
       priority is lowest
 
   No grouping instructions supplied.
+
+  No sorting instructions supplied.
 ```
 <!-- endSnippet -->
 
@@ -77,6 +79,8 @@ Explanation of this Tasks code block query:
   description includes \
 
   No grouping instructions supplied.
+
+  No sorting instructions supplied.
 ```
 <!-- endSnippet -->
 

docs/Queries/Regular Expressions.md

@@ -99,6 +99,8 @@ Explanation of this Tasks code block query:
     using regex:     '^Root\/Sub-Folder\/Sample File\.md' with flag 'i'
 
   No grouping instructions supplied.
+
+  No sorting instructions supplied.
 ```
 <!-- endSnippet -->
 

docs/Scripting/Placeholders.md

@@ -54,6 +54,8 @@ Explanation of this Tasks code block query:
   description includes Some Cryptic String 
 
   No grouping instructions supplied.
+
+  No sorting instructions supplied.
 ```
 <!-- endSnippet -->
 

src/Query/Explain/Explainer.ts

@@ -34,6 +34,7 @@ export class Explainer {
         const results: string[] = [];
         results.push(this.explainFilters(query));
         results.push(this.explainGroups(query));
+        results.push(this.explainSorters(query));
         results.push(this.explainQueryLimits(query));
         results.push(this.explainDebugSettings());
 
@@ -73,6 +74,19 @@ export class Explainer {
         return result;
     }
 
+    public explainSorters(query: Query) {
+        const numberOfSorters = query.sorting.length;
+        if (numberOfSorters === 0) {
+            return this.indent('No sorting instructions supplied.\n');
+        }
+
+        let result = '';
+        for (let i = 0; i < numberOfSorters; i++) {
+            result += this.indentation + query.sorting[i].instruction + '\n';
+        }
+        return result;
+    }
+
     public explainQueryLimits(query: Query) {
         function getPluralisedText(limit: number) {
             let text = `At most ${limit} task`;

src/Query/Filter/Field.ts

@@ -175,6 +175,21 @@ export abstract class Field {
         return new RegExp(`^sort by ${this.fieldNameSingularEscaped()}( reverse)?`, 'i');
     }
 
+    /**
+     * Reconstruct a 'sorter by' instruction to use for sorting of this field.
+     *
+     * This is used to simplify the construction of {@link Sorter} objects.
+     * @param reverse
+     * @protected
+     */
+    protected sorterInstruction(reverse: boolean) {
+        let instruction = `sort by ${this.fieldNameSingular()}`;
+        if (reverse) {
+            instruction += ' reverse';
+        }
+        return instruction;
+    }
+
     /**
      * Return a function to compare two Task objects, for use in sorting by this field's value.
      *
@@ -190,7 +205,7 @@ export abstract class Field {
      * @param reverse - false for normal sort order, true for reverse sort order.
      */
     public createSorter(reverse: boolean): Sorter {
-        return new Sorter(this.fieldNameSingular(), this.comparator(), reverse);
+        return new Sorter(this.sorterInstruction(reverse), this.fieldNameSingular(), this.comparator(), reverse);
     }
 
     /**

src/Query/Filter/TagsField.ts

@@ -72,7 +72,7 @@ export class TagsField extends MultiTextField {
         const reverse = !!match[1];
         const propertyInstance = isNaN(+match[2]) ? 1 : +match[2];
         const comparator = TagsField.makeCompareByTagComparator(propertyInstance);
-        return new Sorter(this.fieldNameSingular(), comparator, reverse);
+        return new Sorter(line, this.fieldNameSingular(), comparator, reverse);
     }
 
     /**

src/Query/Sorter.ts

@@ -16,18 +16,21 @@ export type Comparator = (a: Task, b: Task) => number;
  * It stores the comparison function as a {@link Comparator}.
  */
 export class Sorter {
+    public readonly instruction: string;
     public readonly property: string;
     public readonly comparator: Comparator;
 
     /**
      * Constructor.
      *
+     * @param instruction - the query instruction that created this object
      * @param property - the name of the property.
      * @param comparator - {@link Comparator} function, for sorting in the standard direction.
      *                     If `reverse` is true, it will automatically be converted to reverse the sort direction.
      * @param reverse - whether the sort order should be reversed.
      */
-    constructor(property: string, comparator: Comparator, reverse: boolean) {
+    constructor(instruction: string, property: string, comparator: Comparator, reverse: boolean) {
+        this.instruction = instruction;
         this.property = property;
         this.comparator = Sorter.maybeReverse(reverse, comparator);
     }

tests/Config/DebugSettings.test.ts

@@ -39,6 +39,8 @@ describe('DebugSettings', () => {
 
             No grouping instructions supplied.
 
+            sort by status
+
             NOTE: All sort instructions, including default sort order, are disabled, due to 'ignoreSortInstructions' setting.
             "
         `);