Merge pull request #2538 from obsidian-tasks-group/indent-explanations

feat: Use indentation to separate global & code block query explanation

docs/Queries/Explaining Queries.md

@@ -43,16 +43,16 @@ the results begin with the following, on `2022-10-21`:
 ```text
 Explanation of this Tasks code block query:
 
-starts after 2 years ago =>
-  start date is after 2020-10-21 (Wednesday 21st October 2020) OR no start date
+  starts after 2 years ago =>
+    start date is after 2020-10-21 (Wednesday 21st October 2020) OR no start date
 
-scheduled after 1 week ago =>
-  scheduled date is after 2022-10-14 (Friday 14th October 2022)
+  scheduled after 1 week ago =>
+    scheduled date is after 2022-10-14 (Friday 14th October 2022)
 
-due before tomorrow =>
-  due date is before 2022-10-22 (Saturday 22nd October 2022)
+  due before tomorrow =>
+    due date is before 2022-10-22 (Saturday 22nd October 2022)
 
-No grouping instructions supplied.
+  No grouping instructions supplied.
 ```
 <!-- endSnippet -->
 
@@ -80,10 +80,10 @@ the results begin with the following:
 ```text
 Explanation of this Tasks code block query:
 
-path regex matches /^Root/Sub-Folder/Sample File\.md/i =>
-  using regex:     '^Root\/Sub-Folder\/Sample File\.md' with flag 'i'
+  path regex matches /^Root/Sub-Folder/Sample File\.md/i =>
+    using regex:     '^Root\/Sub-Folder\/Sample File\.md' with flag 'i'
 
-No grouping instructions supplied.
+  No grouping instructions supplied.
 ```
 <!-- endSnippet -->
 
@@ -105,14 +105,14 @@ the results begin with the following, on `2022-10-21`:
 ```text
 Explanation of this Tasks code block query:
 
-not done
+  not done
 
-(due before tomorrow) AND (is recurring) =>
-  AND (All of):
-    due date is before 2022-10-22 (Saturday 22nd October 2022)
-    is recurring
+  (due before tomorrow) AND (is recurring) =>
+    AND (All of):
+      due date is before 2022-10-22 (Saturday 22nd October 2022)
+      is recurring
 
-No grouping instructions supplied.
+  No grouping instructions supplied.
 ```
 <!-- endSnippet -->
 
@@ -142,21 +142,21 @@ the results begin with the following, on `2022-10-21`:
 ```text
 Explanation of this Tasks code block query:
 
-( (description includes 1) AND (description includes 2) AND (description includes 3) ) OR ( (description includes 5) AND (description includes 6) AND (description includes 7) ) AND NOT (description includes 7) =>
-  OR (At least one of):
-    AND (All of):
-      description includes 1
-      description includes 2
-      description includes 3
-    AND (All of):
+  ( (description includes 1) AND (description includes 2) AND (description includes 3) ) OR ( (description includes 5) AND (description includes 6) AND (description includes 7) ) AND NOT (description includes 7) =>
+    OR (At least one of):
       AND (All of):
-        description includes 5
-        description includes 6
-        description includes 7
-      NOT:
-        description includes 7
-
-No grouping instructions supplied.
+        description includes 1
+        description includes 2
+        description includes 3
+      AND (All of):
+        AND (All of):
+          description includes 5
+          description includes 6
+          description includes 7
+        NOT:
+          description includes 7
+
+  No grouping instructions supplied.
 ```
 <!-- endSnippet -->
 
@@ -190,22 +190,22 @@ the results begin with the following, on `2022-10-21`:
 ```text
 Explanation of the global query:
 
-heading includes tasks
+  heading includes tasks
 
-No grouping instructions supplied.
+  No grouping instructions supplied.
 
-At most 50 tasks.
+  At most 50 tasks.
 
 Explanation of this Tasks code block query:
 
-not done
+  not done
 
-due next week =>
-  due date is between:
-    2022-10-24 (Monday 24th October 2022) and
-    2022-10-30 (Sunday 30th October 2022) inclusive
+  due next week =>
+    due date is between:
+      2022-10-24 (Monday 24th October 2022) and
+      2022-10-30 (Sunday 30th October 2022) inclusive
 
-No grouping instructions supplied.
+  No grouping instructions supplied.
 ```
 <!-- endSnippet -->
 
@@ -234,17 +234,17 @@ the results begin with the following:
 ```text
 Explanation of this Tasks code block query:
 
-path includes some/sample/file path.md
+  path includes some/sample/file path.md
 
-root includes some/
+  root includes some/
 
-folder includes some/sample/
+  folder includes some/sample/
 
-filename includes file path.md
+  filename includes file path.md
 
-description includes Some Cryptic String 
+  description includes Some Cryptic String 
 
-No grouping instructions supplied.
+  No grouping instructions supplied.
 ```
 <!-- endSnippet -->
 

docs/Queries/Line Continuations.md

@@ -31,12 +31,12 @@ explain
 ```text
 Explanation of this Tasks code block query:
 
-(priority is highest) OR (priority is lowest) =>
-  OR (At least one of):
-    priority is highest
-    priority is lowest
+  (priority is highest) OR (priority is lowest) =>
+    OR (At least one of):
+      priority is highest
+      priority is lowest
 
-No grouping instructions supplied.
+  No grouping instructions supplied.
 ```
 <!-- endSnippet -->
 
@@ -74,9 +74,9 @@ explain
 ```text
 Explanation of this Tasks code block query:
 
-description includes \
+  description includes \
 
-No grouping instructions supplied.
+  No grouping instructions supplied.
 ```
 <!-- endSnippet -->
 

docs/Queries/Regular Expressions.md

@@ -95,10 +95,10 @@ path regex matches /^Root/Sub-Folder/Sample File\.md/i
 ```text
 Explanation of this Tasks code block query:
 
-path regex matches /^Root/Sub-Folder/Sample File\.md/i =>
-  using regex:     '^Root\/Sub-Folder\/Sample File\.md' with flag 'i'
+  path regex matches /^Root/Sub-Folder/Sample File\.md/i =>
+    using regex:     '^Root\/Sub-Folder\/Sample File\.md' with flag 'i'
 
-No grouping instructions supplied.
+  No grouping instructions supplied.
 ```
 <!-- endSnippet -->
 

docs/Scripting/Placeholders.md

@@ -43,17 +43,17 @@ the results begin with the following, which demonstrates how each value inside `
 ```text
 Explanation of this Tasks code block query:
 
-path includes some/sample/file path.md
+  path includes some/sample/file path.md
 
-root includes some/
+  root includes some/
 
-folder includes some/sample/
+  folder includes some/sample/
 
-filename includes file path.md
+  filename includes file path.md
 
-description includes Some Cryptic String 
+  description includes Some Cryptic String 
 
-No grouping instructions supplied.
+  No grouping instructions supplied.
 ```
 <!-- endSnippet -->
 

src/Query/Explain/Explainer.ts

@@ -2,6 +2,16 @@ import { getSettings } from '../../Config/Settings';
 import type { Query } from '../Query';
 
 export class Explainer {
+    private readonly indentation: string;
+
+    /**
+     * Constructor.
+     * @param indentation - the indentation to use for the output. Defaults to 'not indented'.
+     */
+    constructor(indentation: string = '') {
+        this.indentation = indentation;
+    }
+
     /**
      * Generate a text description of the contents of a query.
      *
@@ -40,25 +50,25 @@ export class Explainer {
     public explainFilters(query: Query) {
         const numberOfFilters = query.filters.length;
         if (numberOfFilters === 0) {
-            return 'No filters supplied. All tasks will match the query.\n';
+            return this.indent('No filters supplied. All tasks will match the query.\n');
         }
 
         return query.filters
             .map((filter) => {
-                return filter.explainFilterIndented('');
+                return filter.explainFilterIndented(this.indentation);
             })
             .join('\n');
     }
 
     public explainGroups(query: Query) {
         const numberOfGroups = query.grouping.length;
         if (numberOfGroups === 0) {
-            return 'No grouping instructions supplied.\n';
+            return this.indent('No grouping instructions supplied.\n');
         }
 
         let result = '';
         for (let i = 0; i < numberOfGroups; i++) {
-            result += query.grouping[i].instruction + '\n';
+            result += this.indentation + query.grouping[i].instruction + '\n';
         }
         return result;
     }
@@ -76,13 +86,13 @@ export class Explainer {
 
         if (query.limit !== undefined) {
             const result = getPluralisedText(query.limit) + '.\n';
-            results.push(result);
+            results.push(this.indent(result));
         }
 
         if (query.taskGroupLimit !== undefined) {
             const result =
                 getPluralisedText(query.taskGroupLimit) + ' per group (if any "group by" options are supplied).\n';
-            results.push(result);
+            results.push(this.indent(result));
         }
         return results.join('\n');
     }
@@ -91,9 +101,14 @@ export class Explainer {
         let result = '';
         const { debugSettings } = getSettings();
         if (debugSettings.ignoreSortInstructions) {
-            result +=
-                "NOTE: All sort instructions, including default sort order, are disabled, due to 'ignoreSortInstructions' setting.\n";
+            result += this.indent(
+                "NOTE: All sort instructions, including default sort order, are disabled, due to 'ignoreSortInstructions' setting.\n",
+            );
         }
         return result;
     }
+
+    private indent(description: string) {
+        return this.indentation + description;
+    }
 }

src/Query/Filter/Filter.ts

@@ -38,7 +38,7 @@ export class Filter {
         if (unindentedExplanation === this.instruction) {
             return `${indent}${this.instruction}\n`;
         } else {
-            return `${indent}${this.instruction} =>\n${explanation.asString('  ')}\n`;
+            return `${indent}${this.instruction} =>\n${explanation.asString(indent + '  ')}\n`;
         }
     }
 }

src/lib/QueryRendererHelper.ts

@@ -1,6 +1,7 @@
 import type { GlobalFilter } from '../Config/GlobalFilter';
 import type { GlobalQuery } from '../Config/GlobalQuery';
 import { Query } from '../Query/Query';
+import { Explainer } from '../Query/Explain/Explainer';
 
 /**
  * @summary
@@ -36,15 +37,17 @@ export function explainResults(
         result += `Only tasks containing the global filter '${globalFilter.get()}'.\n\n`;
     }
 
+    const explainer = new Explainer('  ');
     const tasksBlockQuery = new Query(source, path);
 
     if (!tasksBlockQuery.ignoreGlobalQuery) {
         if (globalQuery.hasInstructions()) {
-            result += `Explanation of the global query:\n\n${globalQuery.query(path).explainQuery()}\n`;
+            const globalQueryQuery = globalQuery.query(path);
+            result += `Explanation of the global query:\n\n${explainer.explainQuery(globalQueryQuery)}\n`;
         }
     }
 
-    result += `Explanation of this Tasks code block query:\n\n${tasksBlockQuery.explainQuery()}`;
+    result += `Explanation of this Tasks code block query:\n\n${explainer.explainQuery(tasksBlockQuery)}`;
 
     return result;
 }

tests/Query/Explain/DocsSamplesForExplain.test.explain_boolean_combinations.approved.explanation.text

@@ -1,10 +1,10 @@
 Explanation of this Tasks code block query:
 
-not done
+  not done
 
-(due before tomorrow) AND (is recurring) =>
-  AND (All of):
-    due date is before 2022-10-22 (Saturday 22nd October 2022)
-    is recurring
+  (due before tomorrow) AND (is recurring) =>
+    AND (All of):
+      due date is before 2022-10-22 (Saturday 22nd October 2022)
+      is recurring
 
-No grouping instructions supplied.
+  No grouping instructions supplied.

tests/Query/Explain/DocsSamplesForExplain.test.explain_expands_dates.approved.explanation.text

@@ -1,12 +1,12 @@
 Explanation of this Tasks code block query:
 
-starts after 2 years ago =>
-  start date is after 2020-10-21 (Wednesday 21st October 2020) OR no start date
+  starts after 2 years ago =>
+    start date is after 2020-10-21 (Wednesday 21st October 2020) OR no start date
 
-scheduled after 1 week ago =>
-  scheduled date is after 2022-10-14 (Friday 14th October 2022)
+  scheduled after 1 week ago =>
+    scheduled date is after 2022-10-14 (Friday 14th October 2022)
 
-due before tomorrow =>
-  due date is before 2022-10-22 (Saturday 22nd October 2022)
+  due before tomorrow =>
+    due date is before 2022-10-22 (Saturday 22nd October 2022)
 
-No grouping instructions supplied.
+  No grouping instructions supplied.