Merge pull request #3437 from ilandikov/feat-include-instruction

feat: Partial implementation of 'include' instruction

Author: claremacrae

docs/Scripting/Includes.md

@@ -0,0 +1,13 @@
+---
+publish: true
+---
+
+# Includes
+
+<span class="related-pages">#feature/scripting</span>
+
+```text
+include my_snippet_from_settings
+```
+
+You can only include full lines (valid instructions).

docs/Scripting/Placeholders.md

@@ -75,6 +75,16 @@ Explanation of this Tasks code block query:
 
 It is now possible to use properties in the query file. See [[Obsidian Properties#Using Query Properties in Searches]]
 
+## Using includes.xxx
+
+You can do the following:
+
+```text
+{{includes.my_snippet_from_settings}}
+```
+
+See also [[Includes]].
+
 ## Error checking: invalid variables
 
 If there are any unknown properties in the placeholders, a clear message is written.

src/Query/Query.ts

@@ -58,6 +58,7 @@ export class Query implements IQuery {
     private readonly limitRegexp = /^limit (groups )?(to )?(\d+)( tasks?)?/i;
 
     private readonly commentRegexp = /^#.*/;
+    private readonly includeRegexp = /^include +(.*)/i;
 
     constructor(source: string, tasksFile: OptionalTasksFile = undefined) {
         this._queryId = this.generateQueryId(10);
@@ -117,6 +118,9 @@ export class Query implements IQuery {
     private parseLine(statement: Statement) {
         const line = statement.anyPlaceholdersExpanded;
         switch (true) {
+            case this.includeRegexp.test(line):
+                this.parseInclude(line, statement);
+                break;
             case this.shortModeRegexp.test(line):
                 this._queryLayoutOptions.shortMode = true;
                 this.saveLayoutStatement(statement);
@@ -443,6 +447,24 @@ ${statement.explainStatement('    ')}
         return false;
     }
 
+    private parseInclude(_line: string, _statement: Statement) {
+        const include = this.includeRegexp.exec(_line);
+        if (include) {
+            const includeName = include[1].trim();
+            const includeValue = getSettings().includes[includeName];
+            if (!includeValue) {
+                this.setError(`Cannot find include "${includeName}" in the Tasks settings`, _statement);
+                return;
+            }
+
+            includeValue.split('\n').forEach((instruction) => {
+                const statement = new Statement(_statement.rawInstruction, _statement.anyContinuationLinesRemoved);
+                statement.recordExpandedPlaceholders(instruction);
+                this.parseLine(statement);
+            });
+        }
+    }
+
     /**
      * Creates a unique ID for correlation of console logging.
      *

tests/Scripting/Includes.test.ts

@@ -1,7 +1,19 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import moment from 'moment';
 import { getSettings, resetSettings, updateSettings } from '../../src/Config/Settings';
 import { Query } from '../../src/Query/Query';
 import { TasksFile } from '../../src/Scripting/TasksFile';
 
+window.moment = moment;
+
+beforeEach(() => {
+    jest.useFakeTimers();
+    jest.setSystemTime(new Date('2025-04-28'));
+});
+
 afterEach(() => {
     resetSettings();
 });
@@ -17,6 +29,127 @@ describe('include tests', () => {
         expect(query.filters.length).toEqual(1);
         expect(query.filters[0].statement.anyPlaceholdersExpanded).toEqual('not done');
     });
+
+    it('should accept whole-line include filter instruction', () => {
+        updateSettings({ includes: { not_done: 'not done' } });
+
+        const source = 'include not_done';
+        const query = new Query(source, new TasksFile('stuff.md'));
+
+        expect(query.error).toBeUndefined();
+        expect(query.source).toEqual('include not_done');
+        expect(query.filters.length).toEqual(1);
+        expect(query.filters[0].statement.anyPlaceholdersExpanded).toEqual('not done');
+    });
+
+    it('should accept whole-line include layout instruction', () => {
+        updateSettings({ includes: { show_tree: 'show tree' } });
+
+        const source = 'include show_tree';
+        const query = new Query(source, new TasksFile('stuff.md'));
+
+        expect(query.error).toBeUndefined();
+        expect(query.source).toEqual('include show_tree');
+        expect(query.queryLayoutOptions.hideTree).toEqual(false);
+        expect(query.layoutStatements[0].anyPlaceholdersExpanded).toEqual('show tree');
+    });
+
+    it('should accept multi-line include', () => {
+        updateSettings({ includes: { multi_line: 'scheduled tomorrow\nhide backlink' } });
+
+        const source = 'include multi_line';
+        const query = new Query(source, new TasksFile('stuff.md'));
+
+        expect(query.error).toBeUndefined();
+
+        expect(query.filters.length).toEqual(1);
+        expect(query.filters[0].statement.anyPlaceholdersExpanded).toEqual('scheduled tomorrow');
+
+        expect(query.queryLayoutOptions.hideBacklinks).toEqual(true);
+        expect(query.layoutStatements[0].anyPlaceholdersExpanded).toEqual('hide backlink');
+    });
+
+    it('should give a meaningful error for non-existent include', () => {
+        updateSettings({ includes: {} });
+
+        const source = 'include not_existent';
+        const query = new Query(source, new TasksFile('stuff.md'));
+
+        expect(query.error).toMatchInlineSnapshot(`
+            "Cannot find include "not_existent" in the Tasks settings
+            Problem line: "include not_existent""
+        `);
+        expect(query.source).toEqual('include not_existent');
+    });
+
+    it('should support nested include instructions', () => {
+        updateSettings({
+            includes: {
+                inside: 'not done',
+                out: 'include inside\nhide edit button',
+            },
+        });
+
+        const source = 'include out';
+        const query = new Query(source, new TasksFile('stuff.md'));
+
+        expect(query.error).toBeUndefined();
+        expect(query.source).toEqual('include out');
+
+        expect(query.filters.length).toEqual(1);
+        expect(query.filters[0].statement.anyPlaceholdersExpanded).toEqual('not done');
+
+        expect(query.queryLayoutOptions.hideEditButton).toEqual(true);
+        expect(query.layoutStatements[0].anyPlaceholdersExpanded).toEqual('hide edit button');
+    });
+
+    it('should explain two levels of nested includes', () => {
+        updateSettings({
+            includes: {
+                inside: '(happens this week) AND (starts before today)',
+                out: 'include inside\nnot done',
+            },
+        });
+
+        const source = 'include out';
+        const query = new Query(source, new TasksFile('stuff.md'));
+
+        expect(query.explainQuery()).toMatchInlineSnapshot(`
+            "include out =>
+            (happens this week) AND (starts before today) =>
+              AND (All of):
+                happens this week =>
+                  due, start or scheduled date is between:
+                    2025-04-28 (Monday 28th April 2025) and
+                    2025-05-04 (Sunday 4th May 2025) inclusive
+                starts before today =>
+                  start date is before 2025-04-28 (Monday 28th April 2025) OR no start date
+
+            include out =>
+            not done
+            "
+        `);
+    });
+
+    it('should give meaningful error message about included text', () => {
+        updateSettings({
+            includes: {
+                inside: 'apple sauce',
+                out: 'include inside',
+            },
+        });
+
+        const source = 'include out';
+        const query = new Query(source, new TasksFile('stuff.md'));
+
+        expect(query.error).toMatchInlineSnapshot(`
+            "do not understand query
+            Problem statement:
+                include out =>
+                apple sauce
+            "
+        `);
+    });
 });
 
 describe('include settings tests', () => {