refactor: Simplify implementations of RecurringField and StatusField (#816)

* refactor: Introduce new class FilterInstruction

* refactor: Introduce new class FilterInstructions

* refactor: Reimplement RecurringField using FilterInstructions

* refactor: Simplify calling FilterInstructions.push()

* refactor: Rename FilterInstructions.push() to .add()

* chore: Better JSDoc for FilterInstruction and FilterInstructions

* chore: Remove a code sample that won't normally be called directly

Author: claremacrae

src/Query/Filter/Filter.ts

@@ -4,7 +4,7 @@ import type { Task } from '../../Task';
  * A filtering function, that takes a Task object and returns
  * whether it matches a particular filtering instruction.
  */
-type Filter = (task: Task) => boolean;
+export type Filter = (task: Task) => boolean;
 
 /**
  * A class which stores one of:

src/Query/Filter/FilterInstruction.ts

@@ -0,0 +1,42 @@
+import { Filter, FilterOrErrorMessage } from './Filter';
+
+/**
+ * Implementation of a single instruction for filtering tasks, and its corresponding predicate.
+ *
+ * This is really a helper to simplify the implementation of individual filter
+ * instructions, hiding away the details of parsing individual instruction lines.
+ *
+ * This will usually be accessed via {@link FilterInstructions.add}
+ *
+ * @see FilterInstructions
+ */
+export class FilterInstruction {
+    private readonly _instruction: string;
+    private readonly _filter: Filter;
+
+    /**
+     * Constructor:
+     * @param instruction - Full text of the instruction for the filter: must be matched exactly
+     * @param filter
+     */
+    constructor(instruction: string, filter: Filter) {
+        this._instruction = instruction;
+        this._filter = filter;
+    }
+
+    public canCreateFilterForLine(line: string): boolean {
+        return line == this._instruction;
+    }
+
+    public createFilterOrErrorMessage(line: string): FilterOrErrorMessage {
+        const result = new FilterOrErrorMessage();
+
+        if (line === this._instruction) {
+            result.filter = this._filter;
+            return result;
+        }
+
+        result.error = `do not understand filter: ${line}`;
+        return result;
+    }
+}

src/Query/Filter/FilterInstructions.ts

@@ -0,0 +1,41 @@
+import { FilterInstruction } from './FilterInstruction';
+import { Filter, FilterOrErrorMessage } from './Filter';
+
+/**
+ * Implementation of a collection of instructions for filtering tasks.
+ *
+ * @example
+ *     private readonly _filters = new FilterInstructions();
+ *     this._filters.add('is recurring', (task) => task.recurrence !== null);
+ *
+ * @see FilterInstruction
+ */
+export class FilterInstructions {
+    private readonly _filters: FilterInstruction[] = [];
+
+    public add(instruction: string, filter: Filter) {
+        this._filters.push(new FilterInstruction(instruction, filter));
+    }
+
+    public canCreateFilterForLine(line: string): boolean {
+        for (const filter of this._filters) {
+            if (filter.canCreateFilterForLine(line)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    public createFilterOrErrorMessage(line: string): FilterOrErrorMessage {
+        for (const filter of this._filters) {
+            const x = filter.createFilterOrErrorMessage(line);
+            if (x.error === undefined) {
+                return x;
+            }
+        }
+
+        const result = new FilterOrErrorMessage();
+        result.error = `do not understand filter: ${line}`;
+        return result;
+    }
+}

src/Query/Filter/RecurringField.ts

@@ -1,33 +1,25 @@
 import { Field } from './Field';
-import { FilterOrErrorMessage } from './Filter';
+import type { FilterOrErrorMessage } from './Filter';
+import { FilterInstructions } from './FilterInstructions';
 
 export class RecurringField extends Field {
-    private readonly instructionForFieldPresence = 'is recurring';
-    private readonly instructionForFieldAbsence = 'is not recurring';
+    private readonly _filters = new FilterInstructions();
+
+    constructor() {
+        super();
+        this._filters.add('is recurring', (task) => task.recurrence !== null);
+        this._filters.add(
+            'is not recurring',
+            (task) => task.recurrence === null,
+        );
+    }
 
     public canCreateFilterForLine(line: string): boolean {
-        return (
-            line === this.instructionForFieldAbsence ||
-            line === this.instructionForFieldPresence
-        );
+        return this._filters.canCreateFilterForLine(line);
     }
 
     public createFilterOrErrorMessage(line: string): FilterOrErrorMessage {
-        const result = new FilterOrErrorMessage();
-
-        if (line === this.instructionForFieldPresence) {
-            result.filter = (task) => task.recurrence !== null;
-            return result;
-        }
-
-        if (line === this.instructionForFieldAbsence) {
-            result.filter = (task) => task.recurrence === null;
-            return result;
-        }
-
-        result.error = `do not understand filter: ${line}`;
-
-        return result;
+        return this._filters.createFilterOrErrorMessage(line);
     }
 
     protected fieldName(): string {

src/Query/Filter/StatusField.ts

@@ -1,34 +1,27 @@
-import { Status } from '../../Task';
+import { Status, Task } from '../../Task';
 import { Field } from './Field';
-import { FilterOrErrorMessage } from './Filter';
+import type { FilterOrErrorMessage } from './Filter';
+import { FilterInstructions } from './FilterInstructions';
 
 export class StatusField extends Field {
-    private readonly instructionForFieldPresence = 'done';
-    private readonly instructionForFieldAbsence = 'not done';
+    private readonly _filters = new FilterInstructions();
 
-    public canCreateFilterForLine(line: string): boolean {
-        return (
-            line === this.instructionForFieldAbsence ||
-            line === this.instructionForFieldPresence
+    constructor() {
+        super();
+
+        this._filters.add('done', (task: Task) => task.status === Status.Done);
+        this._filters.add(
+            'not done',
+            (task: Task) => task.status !== Status.Done,
         );
     }
 
-    public createFilterOrErrorMessage(line: string): FilterOrErrorMessage {
-        const result = new FilterOrErrorMessage();
-
-        if (line === this.instructionForFieldPresence) {
-            result.filter = (task) => task.status === Status.Done;
-            return result;
-        }
-
-        if (line === this.instructionForFieldAbsence) {
-            result.filter = (task) => task.status !== Status.Done;
-            return result;
-        }
-
-        result.error = `do not understand filter: ${line}`;
+    public canCreateFilterForLine(line: string): boolean {
+        return this._filters.canCreateFilterForLine(line);
+    }
 
-        return result;
+    public createFilterOrErrorMessage(line: string): FilterOrErrorMessage {
+        return this._filters.createFilterOrErrorMessage(line);
     }
 
     protected fieldName(): string {