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

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

Author: claremacrae

Diff for: 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]].

Diff for: 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 -->
 

Diff for: 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 -->
 

Diff for: 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 -->
 

Diff for: 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 -->
 

Diff for: 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`;

Diff for: 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);
     }
 
     /**

Diff for: 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);
     }
 
     /**

Diff for: 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);
     }

Diff for: 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.
             "
         `);

Diff for: tests/Query.test.ts

@@ -268,6 +268,7 @@ describe('Query parsing', () => {
             expect(query.error).toBeUndefined();
             expect(query.sorting.length).toEqual(1);
             expect(query.sorting[0]).toBeDefined();
+            expect(query.sorting[0].instruction).toEqual(filter);
 
             // Assert Uppercase
             expect(queryUpperCase.error).toBeUndefined();
@@ -1197,6 +1198,8 @@ describe('Query', () => {
                 "description includes hello
 
                 No grouping instructions supplied.
+
+                No sorting instructions supplied.
                 "
             `);
         });
@@ -1438,6 +1441,8 @@ with \ backslash)`;
                     description includes line 1 continued with \\ backslash
 
                 No grouping instructions supplied.
+
+                No sorting instructions supplied.
                 "
             `);
             expect(queryUpperCase.explainQuery()).toMatchInlineSnapshot(`
@@ -1447,6 +1452,8 @@ with \ backslash)`;
                     description includes line 1 continued with \\ backslash
 
                 No grouping instructions supplied.
+
+                No sorting instructions supplied.
                 "
             `);
         });

Diff for: tests/Query/Explain/DocsSamplesForExplain.test.explain_boolean_combinations.approved.explanation.text

@@ -8,3 +8,5 @@ Explanation of this Tasks code block query:
       is recurring
 
   No grouping instructions supplied.
+
+  No sorting instructions supplied.

Diff for: tests/Query/Explain/DocsSamplesForExplain.test.explain_expands_dates.approved.explanation.text

@@ -10,3 +10,5 @@ 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.

Diff for: tests/Query/Explain/DocsSamplesForExplain.test.explain_explains_task_block_with_global_query_active.approved.explanation.text

@@ -4,6 +4,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:
@@ -16,3 +18,5 @@ Explanation of this Tasks code block query:
       2022-10-30 (Sunday 30th October 2022) inclusive
 
   No grouping instructions supplied.
+
+  No sorting instructions supplied.

Diff for: tests/Query/Explain/DocsSamplesForExplain.test.explain_line_continuation_-_double_slash.approved.explanation.text

@@ -3,3 +3,5 @@ Explanation of this Tasks code block query:
   description includes \
 
   No grouping instructions supplied.
+
+  No sorting instructions supplied.

Diff for: tests/Query/Explain/DocsSamplesForExplain.test.explain_line_continuation_-_single_slash.approved.explanation.text

@@ -6,3 +6,5 @@ Explanation of this Tasks code block query:
       priority is lowest
 
   No grouping instructions supplied.
+
+  No sorting instructions supplied.

Diff for: tests/Query/Explain/DocsSamplesForExplain.test.explain_nested_boolean_combinations.approved.explanation.text

@@ -15,3 +15,5 @@ Explanation of this Tasks code block query:
           description includes 7
 
   No grouping instructions supplied.
+
+  No sorting instructions supplied.

Diff for: tests/Query/Explain/DocsSamplesForExplain.test.explain_placeholders.approved.explanation.text

@@ -11,3 +11,5 @@ Explanation of this Tasks code block query:
   description includes Some Cryptic String 
 
   No grouping instructions supplied.
+
+  No sorting instructions supplied.

Diff for: tests/Query/Explain/DocsSamplesForExplain.test.explain_regular_expression.approved.explanation.text

@@ -4,3 +4,5 @@ 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.

Diff for: tests/Query/Explain/Explainer.test.ts

@@ -65,6 +65,9 @@ limit groups 3
             group by priority reverse
             group by happens
 
+            sort by description reverse
+            sort by path
+
             At most 50 tasks.
 
             At most 3 tasks per group (if any "group by" options are supplied).
@@ -91,6 +94,9 @@ limit groups 3
               group by priority reverse
               group by happens
 
+              sort by description reverse
+              sort by path
+
               At most 50 tasks.
 
               At most 3 tasks per group (if any "group by" options are supplied).
@@ -146,6 +152,18 @@ describe('explain groupers', () => {
     });
 });
 
+describe('explain sorters', () => {
+    it('should explain "sort by" options', () => {
+        const source = 'sort by due\nsort by priority()';
+        const query = new Query(source);
+        expect(explainer.explainSorters(query)).toMatchInlineSnapshot(`
+            "sort by due
+            sort by priority
+            "
+        `);
+    });
+});
+
 describe('explain limits', () => {
     it('should explain limit 5', () => {
         const source = 'limit 5';

Diff for: tests/Query/Filter/ReferenceDocs/FilterReference/DateFieldReference.test.explain_date_reference_filters-date-examples.approved.explanation.text

@@ -33,3 +33,5 @@ due May =>
   due date is on 2023-05-01 (Monday 1st May 2023)
 
 No grouping instructions supplied.
+
+No sorting instructions supplied.

Diff for: tests/Query/Filter/ReferenceDocs/FilterReference/DateFieldReference.test.explain_date_reference_last-this-next-week-month-quarter-year.approved.explanation.text

@@ -74,3 +74,5 @@ due next year =>
 description includes ------------------------------
 
 No grouping instructions supplied.
+
+No sorting instructions supplied.

Diff for: tests/Query/Filter/ReferenceDocs/FilterReference/DateFieldReference.test.explain_date_reference_last-this-next-weekday.approved.explanation.text

@@ -104,3 +104,5 @@ due next sunday =>
 description includes ------------------------------
 
 No grouping instructions supplied.
+
+No sorting instructions supplied.

Diff for: tests/Query/Filter/TextField.test.explains_regular_expression_searches_bulk_test.approved.txt

@@ -108,4 +108,6 @@ tags regex matches /(home|pc_mac|town)/ =>
 
 No grouping instructions supplied.
 
+No sorting instructions supplied.
+
 Error: None

Diff for: tests/Sort.test.ts

@@ -31,15 +31,15 @@ describe('Sort', () => {
 
         // Normal way round
         {
-            const sortByDescriptionLength = new Sorter('junk', comparator, false);
+            const sortByDescriptionLength = new Sorter('sort by description length', 'junk', comparator, false);
             expect(sortByDescriptionLength.comparator(short, long)).toEqual(1);
             expect(sortByDescriptionLength.comparator(short, short)).toEqual(0);
             expect(sortByDescriptionLength.comparator(long, short)).toEqual(-1);
         }
 
         // Reversed
         {
-            const sortByDescriptionLength = new Sorter('junk', comparator, true);
+            const sortByDescriptionLength = new Sorter('sort by description length reverse', 'junk', comparator, true);
             expect(sortByDescriptionLength.comparator(short, long)).toEqual(-1);
             expect(sortByDescriptionLength.comparator(short, short)).toEqual(-0);
             expect(sortByDescriptionLength.comparator(long, short)).toEqual(1);