Merge pull request #3365 from obsidian-tasks-group/explain-remaining-instructions

feat: Explain 'ignore global filter'

Author: claremacrae

docs/Queries/Global Query.md

@@ -35,7 +35,7 @@ You can set a global query in the settings that Tasks will add to the start of a
 
 If you need to ignore the Global Query in a given Tasks block you may add `ignore global query` instruction to any place of the block.
 
-For example, this allows you to have your task seaches ignore certain folders by default. And then in few searches, you can enable searching for tasks in those folders.
+For example, this allows you to have your task searches ignore certain folders by default. And then in a few searches, you can enable searching for tasks in those folders.
 
 > [!example]
 >
@@ -44,6 +44,9 @@ For example, this allows you to have your task seaches ignore certain folders by
 > ignore global query
 > ```
 
+> [!note]
+> Any use of `ignore global query` inside the Global Query itself is harmless, but ignored.
+
 > [!released]
 The `ignore global query` instruction was added in Tasks 4.6.0.
 

src/Config/GlobalQuery.ts

@@ -49,7 +49,9 @@ export class GlobalQuery {
      * @param tasksFile
      */
     public query(tasksFile: OptionalTasksFile = undefined): Query {
-        return new Query(this._source, tasksFile);
+        const query = new Query(this._source, tasksFile);
+        query.removeIllegalGlobalQueryInstructions();
+        return query;
     }
 
     /**

src/Query/Explain/Explainer.ts

@@ -33,6 +33,7 @@ export class Explainer {
          *     - end with a single newline.
          */
         const results: string[] = [];
+        results.push(this.explainIgnoreGlobalQuery(query));
         results.push(this.explainFilters(query));
         results.push(this.explainGroups(query));
         results.push(this.explainSorters(query));
@@ -50,6 +51,13 @@ export class Explainer {
         return result;
     }
 
+    private explainIgnoreGlobalQuery(query: Query) {
+        if (!query.ignoreGlobalQuery) {
+            return '';
+        }
+        return this.indent('ignore global query\n');
+    }
+
     public explainFilters(query: Query) {
         if (query.filters.length === 0) {
             return this.indent('No filters supplied. All tasks will match the query.\n');

src/Query/Query.ts

@@ -96,6 +96,16 @@ export class Query implements IQuery {
         }
     }
 
+    /**
+     * Remove any instructions that are not valid for Global Queries:
+     */
+    public removeIllegalGlobalQueryInstructions() {
+        // It does not make sense to use 'ignore global query'
+        // in global queries: the value is ignored, and it would be confusing
+        // for 'explain' output to report that it had been supplied:
+        this._ignoreGlobalQuery = false;
+    }
+
     public get filePath(): string | undefined {
         return this.tasksFile?.path ?? undefined;
     }
@@ -117,6 +127,7 @@ export class Query implements IQuery {
                 break;
             case this.explainQueryRegexp.test(line):
                 this._queryLayoutOptions.explainQuery = true;
+                // We intentionally do not explain the 'explain' statement, as it clutters up documentation.
                 break;
             case this.ignoreGlobalQueryRegexp.test(line):
                 this._ignoreGlobalQuery = true;

src/Query/QueryRendererHelper.ts

@@ -40,8 +40,8 @@ export function explainResults(
     }
 
     const explainer = new Explainer('  ');
-    function explainQuery(label: string, globalQueryQuery: Query) {
-        return `${label}:\n\n${explainer.explainQuery(globalQueryQuery)}`;
+    function explainQuery(label: string, query: Query) {
+        return `${label}:\n\n${explainer.explainQuery(query)}`;
     }
 
     const tasksBlockQuery = new Query(source, tasksFile);

tests/Config/GlobalQuery.test.ts

@@ -32,6 +32,12 @@ describe('GlobalQuery tests', () => {
         expect(globalQuery.query().source).toEqual('# this should be the new global query');
     });
 
+    it('should ignore any "ignore global query" instruction', () => {
+        const globalQuery = new GlobalQuery('ignore global query');
+
+        expect(globalQuery.query().ignoreGlobalQuery).toEqual(false);
+    });
+
     it.each(['', ' ', '\n', '\n     \n    ', '  \n    \n'])(
         'should have no instructions if only line breaks and spaces were set in the query',
         (globalQuerySource) => {

tests/Query/Explain/Explainer.test.ts

@@ -65,6 +65,8 @@ show urgency
 short mode
 limit 50
 limit groups 3
+
+ignore global query
 `;
 
     it('all types of instruction - not indented', () => {
@@ -73,7 +75,9 @@ limit groups 3
 
         const query = new Query(sampleOfAllInstructionTypes, new TasksFile('sample.md'));
         expect(explainer.explainQuery(query)).toMatchInlineSnapshot(`
-            "filter by function \\
+            "ignore global query
+
+            filter by function \\
                  task.path === '{{query.file.path}}'
              =>
             filter by function task.path === '{{query.file.path}}' =>
@@ -126,7 +130,9 @@ limit groups 3
         const query = new Query(sampleOfAllInstructionTypes, new TasksFile('sample.md'));
         const indentedExplainer = new Explainer('  ');
         expect(indentedExplainer.explainQuery(query)).toMatchInlineSnapshot(`
-            "  filter by function \\
+            "  ignore global query
+
+              filter by function \\
                    task.path === '{{query.file.path}}'
                =>
               filter by function task.path === '{{query.file.path}}' =>
@@ -343,6 +349,11 @@ describe('explain layout instructions', () => {
         expect(explainLayout('full')).toEqual('full\n');
         expect(explainLayout('full mode')).toEqual('full mode\n');
     });
+
+    it('should NOT explain explain', () => {
+        // Intentionally do not explain the 'explain' instruction, as it just clutters up the documentation.
+        expect(explainLayout('explain')).toEqual('');
+    });
 });
 
 describe('explain limits', () => {

tests/Query/QueryRendererHelper.test.ts

@@ -148,6 +148,8 @@ describe('explain', () => {
         expect(explainResults(query.source, new GlobalFilter(), globalQuery)).toMatchInlineSnapshot(`
             "Explanation of this Tasks code block query:
 
+              ignore global query
+
               No filters supplied. All tasks will match the query.
             "
         `);
@@ -163,6 +165,8 @@ describe('explain', () => {
         expect(explainResults(query.source, new GlobalFilter(), globalQuery, queryFile)).toMatchInlineSnapshot(`
             "Explanation of the Query File Defaults (from properties/frontmatter in the query's file):
 
+              ignore global query
+
               description includes I came from the TQ_extra_instructions property
 
             Explanation of this Tasks code block query:
@@ -171,6 +175,27 @@ describe('explain', () => {
             "
         `);
     });
+
+    it('should discard "ignore global query" from explanation if present in the global query itself', () => {
+        const globalQuery = new GlobalQuery('ignore global query');
+        const querySource = 'description includes from query';
+
+        const explanation = explainResults(querySource, new GlobalFilter(), globalQuery);
+
+        // It does not make sense to put 'ignore global query' in the global query.
+        // If the user did so, we should ignore it in any explanations.
+        expect(explanation).not.toContain('ignore global query');
+        expect(explanation).toMatchInlineSnapshot(`
+            "Explanation of the global query:
+
+              No filters supplied. All tasks will match the query.
+
+            Explanation of this Tasks code block query:
+
+              description includes from query
+            "
+        `);
+    });
 });
 
 /**