Merge pull request #1954 from ilandikov/feat-reverse-sorting-of-groups

feat: reverse sorting of groups

Author: claremacrae

src/Query/Filter/Field.ts

@@ -264,6 +264,87 @@ export abstract class Field {
         return false;
     }
 
+    /**
+     * Parse a 'group by' line and return a {@link Grouper} object.
+     *
+     * Returns null line does not match this field or is invalid,
+     * or this field does not support grouping.
+     */
+    public parseGroupLine(line: string): Grouper | null {
+        if (!this.supportsGrouping()) {
+            return null;
+        }
+
+        if (!this.canCreateGrouperForLine(line)) {
+            return null;
+        }
+
+        return this.createGrouperFromLine(line);
+    }
+
+    /**
+     * Returns true if the class can parse the given 'group by' instruction line.
+     *
+     * Current implementation simply checks whether the class does support grouping,
+     * and whether the line matches this.grouperRegExp().
+     * @param line - A line from a ```tasks``` block.
+     *
+     * @see {@link createGrouperFromLine}
+     */
+    public canCreateGrouperForLine(line: string): boolean {
+        if (!this.supportsGrouping()) {
+            return false;
+        }
+
+        return Field.lineMatchesFilter(this.grouperRegExp(), line);
+    }
+
+    /**
+     * Parse the line, and return either a {@link Grouper} object or null.
+     *
+     * This default implementation works for all fields that support
+     * the default grouping pattern of `group by <fieldName> (reverse)?`.
+     *
+     * Fields that offer more complicated 'group by' options can override
+     * this method.
+     *
+     * @param line - A 'group by' line from a ```tasks``` block.
+     *
+     * @see {@link canCreateGrouperForLine}
+     */
+    public createGrouperFromLine(line: string): Grouper | null {
+        if (!this.supportsGrouping()) {
+            return null;
+        }
+
+        const match = Field.getMatch(this.grouperRegExp(), line);
+        if (match === null) {
+            return null;
+        }
+
+        const reverse = !!match[1];
+        return this.createGrouper(reverse);
+    }
+
+    /**
+     * Return a regular expression that will match a correctly-formed
+     * instruction line for grouping Tasks by this field.
+     *
+     * Throws if this field does not support grouping.
+     *
+     * `match[1]` will be either `reverse` or undefined.
+     *
+     * Fields that offer more complicated 'group by' options can override
+     * this method.
+     */
+    protected grouperRegExp(): RegExp {
+        if (!this.supportsGrouping()) {
+            throw Error(`grouperRegExp() unimplemented for ${this.fieldNameSingular()}`);
+        }
+
+        return new RegExp(`^group by ${this.fieldNameSingularEscaped()}( reverse)?$`);
+    }
+
     /**
      * Return a function to get a list of a task's group names, for use in grouping by this field's value.
      *
@@ -276,11 +357,29 @@ export abstract class Field {
 
     /**
      * Create a {@link Grouper} object for grouping tasks by this field's value.
+     * @param reverse - false for normal group order, true for reverse group order.
+     */
+    public createGrouper(reverse: boolean): Grouper {
+        return new Grouper(this.fieldNameSingular(), this.grouper(), reverse);
+    }
+
+    /**
+     * Create a {@link Grouper} object for grouping tasks by this field's value,
+     * in the standard/normal group order for this field.
+     *
+     * @see {@link createReverseGrouper}
+     */
+    public createNormalGrouper(): Grouper {
+        return this.createGrouper(false);
+    }
+
+    /**
+     * Create a {@link Grouper} object for grouping tasks by this field's value,
+     * in the reverse of the standard/normal group order for this field.
      *
-     * For now, parsing of `group by` lines is currently done in {@link FilterParser.parseGrouper()}.
-     * Later, this will probably be moved to the {@link Field} classes.
+     * @see {@link createNormalGrouper}
      */
-    public createGrouper(): Grouper {
-        return new Grouper(this.fieldNameSingular(), this.grouper());
+    public createReverseGrouper(): Grouper {
+        return this.createGrouper(true);
     }
 }

src/Query/Filter/MultiTextField.ts

@@ -63,7 +63,15 @@ export abstract class MultiTextField extends TextField {
     /**
      * This overloads {@link Field.createGrouper} to put a plural field name in the {@link Grouper.property}.
      */
-    public createGrouper(): Grouper {
-        return new Grouper(this.fieldNamePlural(), this.grouper());
+    public createGrouper(reverse: boolean): Grouper {
+        return new Grouper(this.fieldNamePlural(), this.grouper(), reverse);
+    }
+
+    protected grouperRegExp(): RegExp {
+        if (!this.supportsGrouping()) {
+            throw Error(`grouperRegExp() unimplemented for ${this.fieldNameSingular()}`);
+        }
+
+        return new RegExp(`^group by ${this.fieldNamePlural()}( reverse)?$`);
     }
 }

src/Query/FilterParser.ts

@@ -23,7 +23,6 @@ import { RecurrenceField } from './Filter/RecurrenceField';
 import type { FilterOrErrorMessage } from './Filter/Filter';
 import type { Sorter } from './Sorter';
 import type { Grouper } from './Grouper';
-import { MultiTextField } from './Filter/MultiTextField';
 import { FolderField } from './Filter/FolderField';
 import { RootField } from './Filter/RootField';
 import { BacklinkField } from './Filter/BacklinkField';
@@ -102,19 +101,9 @@ export function parseGrouper(line: string): Grouper | null {
     // See if any of the fields can parse the line.
     for (const creator of fieldCreators) {
         const field = creator();
-        const fieldName = field.fieldNameSingular();
-        if (field.supportsGrouping()) {
-            if (line === `group by ${fieldName}`) {
-                return field.createGrouper();
-            }
-
-            // MultiTextField is written as a plural ('group by tags')
-            // See also MultiTextField.createGrouper()
-            if (field instanceof MultiTextField) {
-                if (line === `group by ${field.fieldNamePlural()}`) {
-                    return field.createGrouper();
-                }
-            }
+        const grouper = field.parseGroupLine(line);
+        if (grouper) {
+            return grouper;
         }
     }
     return null;

src/Query/Grouper.ts

@@ -34,8 +34,11 @@ export class Grouper {
      */
     public readonly grouper: GrouperFunction;
 
-    constructor(property: string, grouper: GrouperFunction) {
+    public readonly reverse: boolean;
+
+    constructor(property: string, grouper: GrouperFunction, reverse: boolean) {
         this.property = property;
         this.grouper = grouper;
+        this.reverse = reverse;
     }
 }

src/Query/TaskGroups.ts

@@ -13,6 +13,7 @@ import { TaskGroup } from './TaskGroup';
  * @see {@link Query.grouping}
  */
 export class TaskGroups {
+    private _groupers: Grouper[];
     private _groups: TaskGroup[] = new Array<TaskGroup>();
     private _totalTaskCount = 0;
 
@@ -26,6 +27,7 @@ export class TaskGroups {
         // Grouping doesn't change the number of tasks, and all the tasks
         // will be shown in at least one group.
         this._totalTaskCount = tasks.length;
+        this._groupers = groups;
 
         const taskGroupingTree = new TaskGroupingTree(groups, tasks);
         this.addTasks(taskGroupingTree);
@@ -103,9 +105,10 @@ export class TaskGroups {
                 // In future, we will add control over the sorting of group headings,
                 // which will likely involve adjusting this code to sort by applying a Comparator
                 // to the first Task in each group.
+                const grouper = this._groupers[i];
                 const result = groupNames1[i].localeCompare(groupNames2[i], undefined, { numeric: true });
                 if (result !== 0) {
-                    return result;
+                    return grouper.reverse ? -result : result;
                 }
             }
             // identical if we reach here

tests/CustomMatchers/CustomMatchersForGrouping.ts

@@ -24,7 +24,7 @@ export function toSupportGroupingWithProperty(field: Field, property: string) {
         };
     }
 
-    const fieldGrouper = field.createGrouper();
+    const fieldGrouper = field.createNormalGrouper();
     if (fieldGrouper.property !== property) {
         return {
             message: () =>

tests/DocumentationSamples/DocsSamplesForStatuses.test.ts

@@ -208,9 +208,9 @@ function verifyTransitionsAsMarkdownTable(statuses: Status[]) {
         table.addRow(cells);
     }
 
-    showGroupNamesForAllTasks('status', new StatusField().createGrouper().grouper);
-    showGroupNamesForAllTasks('status.type', new StatusTypeField().createGrouper().grouper);
-    showGroupNamesForAllTasks('status.name', new StatusNameField().createGrouper().grouper);
+    showGroupNamesForAllTasks('status', new StatusField().createNormalGrouper().grouper);
+    showGroupNamesForAllTasks('status.type', new StatusTypeField().createNormalGrouper().grouper);
+    showGroupNamesForAllTasks('status.name', new StatusNameField().createNormalGrouper().grouper);
 
     table.verifyForDocs();
 }

tests/Query.test.ts

@@ -201,25 +201,45 @@ describe('Query parsing', () => {
         // In alphabetical order, please
         const filters = [
             'group by created',
+            'group by created reverse',
             'group by backlink',
+            'group by backlink reverse',
             'group by done',
+            'group by done reverse',
             'group by due',
+            'group by due reverse',
             'group by filename',
+            'group by filename reverse',
             'group by folder',
+            'group by folder reverse',
             'group by happens',
+            'group by happens reverse',
             'group by heading',
+            'group by heading reverse',
             'group by path',
+            'group by path reverse',
             'group by priority',
+            'group by priority reverse',
             'group by recurrence',
+            'group by recurrence reverse',
             'group by recurring',
+            'group by recurring reverse',
             'group by root',
+            'group by root reverse',
             'group by scheduled',
+            'group by scheduled reverse',
             'group by start',
+            'group by start reverse',
             'group by status',
+            'group by status reverse',
             'group by status.name',
+            'group by status.name reverse',
             'group by status.type',
+            'group by status.type reverse',
             'group by tags',
+            'group by tags reverse',
             'group by urgency',
+            'group by urgency reverse',
         ];
         test.concurrent.each<string>(filters)('recognises %j', (filter) => {
             // Arrange

tests/Query/Filter/BacklinkField.test.ts

@@ -58,7 +58,7 @@ describe('grouping by backlink', () => {
         'path "%s" and heading "%s" should have groups: %s',
         (path: string, heading: string | null, groups: string[]) => {
             // Arrange
-            const grouper = new BacklinkField().createGrouper().grouper;
+            const grouper = new BacklinkField().createNormalGrouper().grouper;
             const t = '- [ ] xyz';
 
             // Assert

tests/Query/Filter/CreatedDateField.test.ts

@@ -97,7 +97,7 @@ describe('grouping by created date', () => {
 
     it('group by created date', () => {
         // Arrange
-        const grouper = new CreatedDateField().createGrouper();
+        const grouper = new CreatedDateField().createNormalGrouper();
         const taskWithDate = new TaskBuilder().createdDate('1970-01-01').build();
         const taskWithoutDate = new TaskBuilder().build();