Merge pull request #3364 from obsidian-tasks-group/explain-layout-statements

feat: Include layout instructions in 'explain' output

Author: claremacrae

docs/Queries/Explaining Queries.md

@@ -21,7 +21,6 @@ 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 [[query file defaults]]-generated instructions are listed (since Tasks 7.15.0).
-  - Note that `show/hide` [[layout]] are not yet shown in `explain` output, however. We are tracking this in [issue #2093](https://github.com/obsidian-tasks-group/obsidian-tasks/issues/2093).
 - Any [[Grouping|'group by']] instructions are listed (since Tasks 5.4.0).
 - Any [[Sorting|'sort by']] instructions are listed (since Tasks 5.4.0).
 
@@ -255,22 +254,16 @@ Explanation of the Query File Defaults (from properties/frontmatter in the query
 
   not done
 
+  short mode
+
+  show tree
+
 Explanation of this Tasks code block query:
 
   No filters supplied. All tasks will match the query.
 ```
 <!-- endSnippet -->
 
-> [!info]- Why are the generated layout instructions not visible?
-> The Query File Defaults will have generated these instructions:
->
-> ```text
-> short mode
-> show tree
-> ```
->
-> Currently, the `explain` output does not display [[layout]] instructions.  We are tracking this in [issue #2093](https://github.com/obsidian-tasks-group/obsidian-tasks/issues/2093).
-
 ### Placeholder values are expanded
 
 > [!released]

src/Query/Explain/Explainer.ts

@@ -1,5 +1,6 @@
 import { getSettings } from '../../Config/Settings';
 import type { Query } from '../Query';
+import type { Statement } from '../Statement';
 
 export class Explainer {
     private readonly indentation: string;
@@ -35,6 +36,7 @@ export class Explainer {
         results.push(this.explainFilters(query));
         results.push(this.explainGroups(query));
         results.push(this.explainSorters(query));
+        results.push(this.explainLayout(query));
         results.push(this.explainQueryLimits(query));
         results.push(this.explainDebugSettings());
 
@@ -57,19 +59,15 @@ export class Explainer {
     }
 
     public explainGroups(query: Query) {
-        if (query.grouping.length === 0) {
-            return '';
-        }
-
-        return query.grouping.map((group) => group.statement.explainStatement(this.indentation)).join('\n\n') + '\n';
+        return this.explainStatements(query.grouping.map((group) => group.statement));
     }
 
     public explainSorters(query: Query) {
-        if (query.sorting.length === 0) {
-            return '';
-        }
+        return this.explainStatements(query.sorting.map((sort) => sort.statement));
+    }
 
-        return query.sorting.map((sort) => sort.statement.explainStatement(this.indentation)).join('\n\n') + '\n';
+    public explainLayout(query: Query) {
+        return this.explainStatements(query.layoutStatements);
     }
 
     public explainQueryLimits(query: Query) {
@@ -107,6 +105,14 @@ export class Explainer {
         return result;
     }
 
+    private explainStatements(statements: Statement[]) {
+        if (statements.length === 0) {
+            return '';
+        }
+
+        return statements.map((statement) => statement.explainStatement(this.indentation)).join('\n\n') + '\n';
+    }
+
     private indent(description: string) {
         return this.indentation + description;
     }

src/Query/Query.ts

@@ -34,8 +34,11 @@ export class Query implements IQuery {
 
     private _limit: number | undefined = undefined;
     private _taskGroupLimit: number | undefined = undefined;
+
     private readonly _taskLayoutOptions: TaskLayoutOptions = new TaskLayoutOptions();
     private readonly _queryLayoutOptions: QueryLayoutOptions = new QueryLayoutOptions();
+    public readonly layoutStatements: Statement[] = [];
+
     private readonly _filters: Filter[] = [];
     private _error: string | undefined = undefined;
     private readonly _sorting: Sorter[] = [];
@@ -106,9 +109,11 @@ export class Query implements IQuery {
         switch (true) {
             case this.shortModeRegexp.test(line):
                 this._queryLayoutOptions.shortMode = true;
+                this.saveLayoutStatement(statement);
                 break;
             case this.fullModeRegexp.test(line):
                 this._queryLayoutOptions.shortMode = false;
+                this.saveLayoutStatement(statement);
                 break;
             case this.explainQueryRegexp.test(line):
                 this._queryLayoutOptions.explainQuery = true;
@@ -124,7 +129,7 @@ export class Query implements IQuery {
             case this.parseGroupBy(line, statement):
                 break;
             case this.hideOptionsRegexp.test(line):
-                this.parseHideOptions(line);
+                this.parseHideOptions(statement);
                 break;
             case this.commentRegexp.test(line):
                 // Comment lines are ignored
@@ -341,7 +346,8 @@ ${statement.explainStatement('    ')}
         }
     }
 
-    private parseHideOptions(line: string): void {
+    private parseHideOptions(statement: Statement): void {
+        const line = statement.anyPlaceholdersExpanded;
         const hideOptionsMatch = line.match(this.hideOptionsRegexp);
         if (hideOptionsMatch === null) {
             return;
@@ -350,14 +356,20 @@ ${statement.explainStatement('    ')}
         const option = hideOptionsMatch[2].toLowerCase();
 
         if (parseQueryShowHideOptions(this._queryLayoutOptions, option, hide)) {
+            this.saveLayoutStatement(statement);
             return;
         }
         if (parseTaskShowHideOptions(this._taskLayoutOptions, option, !hide)) {
+            this.saveLayoutStatement(statement);
             return;
         }
         this.setError('do not understand hide/show option', new Statement(line, line));
     }
 
+    private saveLayoutStatement(statement: Statement) {
+        this.layoutStatements.push(statement);
+    }
+
     private parseFilter(line: string, statement: Statement) {
         const filterOrError = FilterParser.parseFilter(line);
         if (filterOrError != null) {

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

@@ -5,6 +5,10 @@ Explanation of the Query File Defaults (from properties/frontmatter in the query
 
   not done
 
+  short mode
+
+  show tree
+
 Explanation of this Tasks code block query:
 
   No filters supplied. All tasks will match the query.

tests/Query/Explain/Explainer.test.ts

@@ -106,6 +106,10 @@ limit groups 3
 
             sort by path
 
+            show urgency
+
+            short mode
+
             At most 50 tasks.
 
             At most 3 tasks per group (if any "group by" options are supplied).
@@ -155,6 +159,10 @@ limit groups 3
 
               sort by path
 
+              show urgency
+
+              short mode
+
               At most 50 tasks.
 
               At most 3 tasks per group (if any "group by" options are supplied).
@@ -312,6 +320,31 @@ describe('explain sorters', () => {
     });
 });
 
+describe('explain layout instructions', () => {
+    function explainLayout(source: string) {
+        const query = new Query(source);
+        return explainer.explainLayout(query);
+    }
+
+    it('should explain hide due date', () => {
+        expect(explainLayout('hide due date')).toEqual('hide due date\n');
+    });
+
+    it('should explain show tree', () => {
+        expect(explainLayout('show tree')).toEqual('show tree\n');
+    });
+
+    it('should explain short mode', () => {
+        expect(explainLayout('short')).toEqual('short\n');
+        expect(explainLayout('short mode')).toEqual('short mode\n');
+    });
+
+    it('should explain full mode', () => {
+        expect(explainLayout('full')).toEqual('full\n');
+        expect(explainLayout('full mode')).toEqual('full mode\n');
+    });
+});
+
 describe('explain limits', () => {
     it('should explain limit 5', () => {
         const source = 'limit 5';

tests/Query/QueryRendererHelper.test.ts

@@ -74,6 +74,44 @@ describe('explain', () => {
 
               not done
 
+              short mode
+
+              show tree
+
+              show tags
+
+              show id
+
+              show depends on
+
+              show priority
+
+              show recurrence rule
+
+              show on completion
+
+              show created date
+
+              show start date
+
+              show scheduled date
+
+              show due date
+
+              show cancelled date
+
+              show done date
+
+              show urgency
+
+              show backlink
+
+              show edit button
+
+              show postpone button
+
+              show task count
+
             Explanation of this Tasks code block query:
 
               No filters supplied. All tasks will match the query.