Merge pull request #3292 from obsidian-tasks-group/feat-placeholder-expressions

feat: Placeholders can now contain expressions

Author: claremacrae

docs/Getting Started/Obsidian Properties.md

@@ -208,6 +208,14 @@ It can be used in your query in two ways:
     description includes {{query.file.property('search-text')}}
     ```
 
+1. An entire instruction controlled by front-matter value:
+
+    ```javascript
+    {{const prop = 'TQ-explain';    return query.file.hasProperty(prop) ?  ( query.file.property(prop) ? 'explain' : '') : '';}}
+
+    {{const prop = 'TQ-show-tree';  return query.file.hasProperty(prop) && ( query.file.property(prop) ? 'show' : 'hide') + ' tree' || ''}}
+    ```
+
 1. Scripting, which allows creation of a custom filter, which works when the search term is empty
 
     ```javascript

docs/Quick Reference.md

@@ -12,6 +12,11 @@ _In recent [Tasks releases](https://github.com/obsidian-tasks-group/obsidian-tas
 
 ## 7.x releases
 
+- X.Y.Z:
+  - Add `query.file.hasProperty()` and `query.file.property()` in custom filters
+  - Add `{{query.file.hasProperty()}}` and `{{query.file.property()}}` in placeholders - see [[Obsidian Properties#Using Query Properties in Placeholders|Using Query Properties in Placeholders]].
+  - Placeholders can now call functions and contain expressions.
+  - Add Chinese translation of [[Settings]], [[Editing a Status]] and [[Check your Statuses]]
 - 7.14.0:
   - Add [[Editing Dates#Date-picker on task dates|date picker]] to Reading mode and Tasks query search results.
 - 7.13.0:

docs/What is New/Changelog.md

@@ -15,6 +15,29 @@
     "sample_link_property": "text",
     "creation date": "datetime",
     "project": "text",
-    "sample_text_multiline_property": "text"
+    "sample_text_multiline_property": "text",
+    "TQ-explain": "checkbox",
+    "TQ-short-mode": "checkbox",
+    "TQ-show-tree": "checkbox",
+    "TQ-show-tags": "checkbox",
+    "TQ-show-id": "checkbox",
+    "TQ-show-depends-on": "checkbox",
+    "TQ-show-priority": "checkbox",
+    "TQ-show-recurrence-rule": "checkbox",
+    "TQ-show-on-completion": "checkbox",
+    "TQ-show-created-date": "checkbox",
+    "TQ-show-start-date": "checkbox",
+    "TQ-show-scheduled-date": "checkbox",
+    "TQ-show-due-date": "checkbox",
+    "TQ-show-cancelled-date": "checkbox",
+    "TQ-show-done-date": "checkbox",
+    "TQ-show-urgency": "checkbox",
+    "TQ-show-backlink": "checkbox",
+    "TQ-show-edit-button": "checkbox",
+    "TQ-show-postpone-button": "checkbox",
+    "TQ-show-task-count": "checkbox",
+    "TQ-sort-by": "multitext",
+    "TQ-group-by": "multitext",
+    "TQ-extra-instructions": "text"
   }
 }

resources/sample_vaults/Tasks-Demo/.obsidian/types.json

@@ -0,0 +1,116 @@
+---
+TQ-explain: false
+TQ-short-mode: false
+TQ-show-tree: true
+TQ-show-tags: true
+TQ-show-id: true
+TQ-show-depends-on: true
+TQ-show-priority: true
+TQ-show-recurrence-rule: true
+TQ-show-on-completion: true
+TQ-show-created-date: true
+TQ-show-start-date: true
+TQ-show-scheduled-date: true
+TQ-show-due-date: true
+TQ-show-cancelled-date: true
+TQ-show-done-date: true
+TQ-show-urgency: true
+TQ-show-backlink: true
+TQ-show-edit-button: true
+TQ-show-postpone-button: true
+TQ-show-task-count: true
+TQ-sort-by:
+  - description
+TQ-group-by:
+  - status.type
+  - happens reverse
+  - function task.tags.sort().join(' ')
+TQ-extra-instructions: |-
+  # press shift-return to add new lines
+  # not done
+  # sort by done date
+---
+# Placeholder examples to capture in tests and docs
+
+- [ ] #task Parent task #todo #health 🆔 abcdef ⛔ 123456,abc123 🔼 🔁 every day when done 🏁 delete ➕ 2023-07-01 🛫 2023-07-02 ⏳ 2023-07-03 📅 2023-07-04 ❌ 2023-07-06 ✅ 2023-07-05 ^dcf64c
+  - [ ] #task Child task
+
+## Can now have logical operators inside placeholders
+
+So we can easily control the query interactively now, via Obsidian's File Properties panel!!!
+
+This search is a proof-of-concept. The `TQ-` prefix was chosen to stand for `Task Query`. It is not yet decided whether recognition of these properties will be built in to Tasks in future.
+
+To try this out:
+
+1. Switch to Reading or Live Preview modes.
+2. Run the `Files: Show file explorer` command.
+3. Modify the query via only editing file properties.
+
+For bonus points, you can copy the placeholder instructions to your Tasks global search, and then you can use these instructions to adjust *all* the searches in your vault that do not use `ignore global query`.
+
+```tasks
+# We ignore the global query just to shorten the `explain` output.
+ignore global query
+path includes {{query.file.path}}
+
+# Instructions are listed in the order that items are displayed in Tasks search results
+# I would like to use the prefix 'tasks-query-' on the names, but it makes the names
+# too wide to be readable in the File Properties panel.
+
+{{const prop = 'TQ-explain';                return query.file.hasProperty(prop) ?  ( query.file.property(prop) ? 'explain' : '') : '';}}
+{{const prop = 'TQ-short-mode';             return query.file.hasProperty(prop) && ( query.file.property(prop) ? 'short mode' : 'full mode') || ''}}
+
+{{const prop = 'TQ-show-tree';              return query.file.hasProperty(prop) && ( query.file.property(prop) ? 'show' : 'hide') + ' tree' || ''}}
+
+{{const prop = 'TQ-show-tags';              return query.file.hasProperty(prop) && ( query.file.property(prop) ? 'show' : 'hide') + ' tags' || ''}}
+{{const prop = 'TQ-show-id';                return query.file.hasProperty(prop) && ( query.file.property(prop) ? 'show' : 'hide') + ' id' || ''}}
+{{const prop = 'TQ-show-depends-on';        return query.file.hasProperty(prop) && ( query.file.property(prop) ? 'show' : 'hide') + ' depends on' || ''}}
+{{const prop = 'TQ-show-priority';          return query.file.hasProperty(prop) && ( query.file.property(prop) ? 'show' : 'hide') + ' priority' || ''}}
+{{const prop = 'TQ-show-recurrence-rule';   return query.file.hasProperty(prop) && ( query.file.property(prop) ? 'show' : 'hide') + ' recurrence rule' || ''}}
+{{const prop = 'TQ-show-on-completion';     return query.file.hasProperty(prop) && ( query.file.property(prop) ? 'show' : 'hide') + ' on completion' || ''}}
+
+{{const prop = 'TQ-show-created-date';      return query.file.hasProperty(prop) && ( query.file.property(prop) ? 'show' : 'hide') + ' created date' || ''}}
+{{const prop = 'TQ-show-start-date';        return query.file.hasProperty(prop) && ( query.file.property(prop) ? 'show' : 'hide') + ' start date' || ''}}
+{{const prop = 'TQ-show-scheduled-date';    return query.file.hasProperty(prop) && ( query.file.property(prop) ? 'show' : 'hide') + ' scheduled date' || ''}}
+{{const prop = 'TQ-show-due-date';          return query.file.hasProperty(prop) && ( query.file.property(prop) ? 'show' : 'hide') + ' due date' || ''}}
+{{const prop = 'TQ-show-cancelled-date';    return query.file.hasProperty(prop) && ( query.file.property(prop) ? 'show' : 'hide') + ' cancelled date' || ''}}
+{{const prop = 'TQ-show-done-date';         return query.file.hasProperty(prop) && ( query.file.property(prop) ? 'show' : 'hide') + ' done date' || ''}}
+
+{{const prop = 'TQ-show-urgency' ;          return query.file.hasProperty(prop) && ( query.file.property(prop) ? 'show' : 'hide') + ' urgency' || ''}}
+{{const prop = 'TQ-show-backlink';          return query.file.hasProperty(prop) && ( query.file.property(prop) ? 'show' : 'hide') + ' backlink' || ''}}
+{{const prop = 'TQ-show-edit-button';       return query.file.hasProperty(prop) && ( query.file.property(prop) ? 'show' : 'hide') + ' edit button' || ''}}
+{{const prop = 'TQ-show-postpone-button';   return query.file.hasProperty(prop) && ( query.file.property(prop) ? 'show' : 'hide') + ' postpone button' || ''}}
+{{const prop = 'TQ-show-task-count';        return query.file.hasProperty(prop) && ( query.file.property(prop) ? 'show' : 'hide') + ' task count' || ''}}
+
+{{const prop = 'TQ-sort-by';                return query.file.hasProperty(prop) &&   query.file.property(prop).map((g) => 'sort by ' + g).join('\n') || ''}}
+{{const prop = 'TQ-group-by';               return query.file.hasProperty(prop) &&   query.file.property(prop).map((g) => 'group by ' + g).join('\n') || ''}}
+
+{{const prop = 'TQ-extra-instructions';     return query.file.hasProperty(prop) ? query.file.property(prop) || '' : '';}}
+```
+
+## Can now call functions inside placeholders
+
+```tasks
+ignore global query
+explain
+path includes {{query.file.path.toUpperCase()}}
+```
+
+## Expands to null, but should be an error
+
+```tasks
+ignore global query
+explain
+path includes {{query.file.path}}
+{{query.file.property('stuff')}}
+```
+
+## Expands to false, but should be an error
+
+```tasks
+ignore global query
+explain
+path includes {{query.file.path}}
+{{query.file.hasProperty('stuff')}}
+```

resources/sample_vaults/Tasks-Demo/Manual Testing/Frontmatter/Placeholder examples to capture in tests and docs.md

@@ -1,5 +1,6 @@
 import Mustache from 'mustache';
 import proxyData from 'mustache-validator';
+import { type ExpressionParameter, evaluateExpression, parseExpression } from './Expression';
 
 // https://github.com/janl/mustache.js
 
@@ -26,11 +27,11 @@ export function expandPlaceholders(template: string, view: any): string {
         return text;
     };
 
-    // Preprocess the template to evaluate any placeholders that involve function calls
-    const evaluatedTemplate = evaluateAnyFunctionCalls(template, view);
-
-    // Render the preprocessed template
     try {
+        // Preprocess the template to evaluate any placeholders that involve function calls
+        const evaluatedTemplate = evaluateAnyFunctionCalls(template, view);
+
+        // Render the preprocessed template
         return Mustache.render(evaluatedTemplate, proxyData(view));
     } catch (error) {
         let message = '';
@@ -50,98 +51,37 @@ The problem is in:
     }
 }
 
-const ARGUMENTS_REGEX = new RegExp(
+// Regex to detect placeholders
+const PLACEHOLDER_REGEX = new RegExp(
     [
-        // Match single-quoted arguments
-        "'((?:\\\\'|[^'])*)'",
+        // Match the opening double braces `{{`
+        '\\{\\{',
 
-        // Match double-quoted arguments
-        '"((?:\\\\"|[^"])*)"',
+        // Lazily capture everything inside (.*?), ensuring it stops at the first `}}`
+        '(.*?)',
 
-        // Match unquoted arguments (non-commas)
-        '([^,]+)',
-    ].join('|'), // Combine all parts with OR (|)
-    'g', // Global flag for multiple matches
-);
-
-function parseArgs(args: string): string[] {
-    const parsedArgs: string[] = [];
-    let match;
-
-    while ((match = ARGUMENTS_REGEX.exec(args)) !== null) {
-        if (match[1] !== undefined) {
-            // Single-quoted argument
-            parsedArgs.push(match[1].replace(/\\'/g, "'"));
-        } else if (match[2] !== undefined) {
-            // Double-quoted argument
-            parsedArgs.push(match[2].replace(/\\"/g, '"'));
-        } else if (match[3] !== undefined) {
-            // Unquoted argument
-            parsedArgs.push(match[3].trim());
-        }
-    }
-
-    return parsedArgs;
-}
-
-// Regex to detect function calls in placeholders
-const FUNCTION_REGEX = new RegExp(
-    [
-        // Match opening double curly braces with optional whitespace
-        '{{\\s*',
-
-        // Match and capture the function path (e.g., "object.path.toFunction")
-        '([\\w.]+)',
-
-        // Match the opening parenthesis and capture arguments inside
-        '\\(([^)]*)\\)',
-
-        // Match optional whitespace followed by closing double curly braces
-        '\\s*}}',
-    ].join(''), // Combine all parts without additional separators
-    'g', // Global flag to match all instances in the template
+        // Match the closing double braces `}}`
+        '\\}\\}',
+    ].join(''), // Combine the parts into a single string
+    'g', // Global flag to find all matches
 );
 
 function evaluateAnyFunctionCalls(template: string, view: any) {
-    return template.replace(FUNCTION_REGEX, (_match, functionPath, args) => {
-        // Split the function path (e.g., "query.file.property") into parts
-        const pathParts = functionPath.split('.');
-
-        // Extract the function name (last part of the path)
-        const functionName = pathParts.pop();
-
-        // Traverse the view object to find the object containing the function.
-        //
-        // This is needed because JavaScript/TypeScript doesn’t provide a direct way
-        // to access view['query']['file']['property'] based on such a dynamic path.
-        //
-        // So we need the loop to "walk" through the view object step by step,
-        // accessing each level as specified by the pathParts.
-        //
-        // Also, if any part of the path is missing (e.g., view.query.file exists,
-        // but view.query.file.property does not), the loop ensures the traversal
-        // stops early, and obj becomes undefined instead of throwing an error.
-        let obj = view; // Start at the root of the view object
-        for (const part of pathParts) {
-            if (obj == null) {
-                // Stop traversal if obj is null or undefined
-                obj = undefined;
-                break;
+    return template.replace(PLACEHOLDER_REGEX, (_match, reconstructed) => {
+        const paramsArgs: ExpressionParameter[] = createExpressionParameters(view);
+        const functionOrError = parseExpression(paramsArgs, reconstructed);
+        if (functionOrError.isValid()) {
+            const result = evaluateExpression(functionOrError.queryComponent!, paramsArgs);
+            if (result !== undefined) {
+                return result;
             }
-            obj = obj[part]; // Move to the next level of the object
         }
-        // At the end of the loop, obj contains the resolved value or undefined if any part of the path was invalid
 
-        // Check if the function exists on the resolved object
-        if (obj && typeof obj[functionName] === 'function') {
-            // Parse the arguments from the placeholder, stripping quotes and trimming whitespace
-            const argValues = parseArgs(args);
-
-            // Call the function with the parsed arguments and return the result
-            return obj[functionName](...argValues);
-        }
-
-        // Throw an error if the function does not exist or is invalid
-        throw new Error(`Unknown property or invalid function: ${functionPath}`);
+        // Fall back on returning the raw string, including {{ and }} - and get Mustache to report the error.
+        return _match;
     });
 }
+
+function createExpressionParameters(view: any): ExpressionParameter[] {
+    return Object.entries(view) as ExpressionParameter[];
+}

src/Scripting/ExpandPlaceholders.ts

@@ -3,6 +3,11 @@ import { errorMessageForException } from '../lib/ExceptionTools';
 
 export class FunctionOrError extends QueryComponentOrError<Function> {}
 
+/**
+ * The name and value of a parameter, as a Tuple, for passing in to {@link parseExpression} and related functions.
+ */
+export type ExpressionParameter = [name: string, value: any];
+
 /**
  * Parse a JavaScript expression, and return either a Function or an error message in a string.
  * @param paramsArgs
@@ -11,16 +16,16 @@ export class FunctionOrError extends QueryComponentOrError<Function> {}
  * @see evaluateExpression
  * @see evaluateExpressionOrCatch
  */
-export function parseExpression(paramsArgs: [string, any][], arg: string): FunctionOrError {
-    const params = paramsArgs.map(([p]) => p);
+export function parseExpression(paramsArgs: ExpressionParameter[], arg: string): FunctionOrError {
     try {
+        const parameterNames = paramsArgs.map(([name]) => name);
         const input = arg.includes('return') ? arg : `return ${arg}`;
-        const expression: '' | null | Function = arg && new Function(...params, input);
+        const expression: '' | null | Function = arg && new Function(...parameterNames, input);
         if (expression instanceof Function) {
             return FunctionOrError.fromObject(arg, expression);
         }
         // I have not managed to write a test that reaches here:
-        return FunctionOrError.fromError(arg, 'Error parsing group function');
+        return FunctionOrError.fromError(arg, `Problem parsing expression "${arg}"`);
     } catch (e) {
         return FunctionOrError.fromError(arg, errorMessageForException(`Failed parsing expression "${arg}"`, e));
     }
@@ -34,9 +39,9 @@ export function parseExpression(paramsArgs: [string, any][], arg: string): Funct
  * @see parseExpression
  * @see evaluateExpressionOrCatch
  */
-export function evaluateExpression(expression: Function, paramsArgs: [string, any][]) {
-    const args = paramsArgs.map(([_, a]) => a);
-    return expression(...args);
+export function evaluateExpression(expression: Function, paramsArgs: ExpressionParameter[]) {
+    const parameterValues = paramsArgs.map(([_, value]) => value);
+    return expression(...parameterValues);
 }
 
 /**
@@ -48,7 +53,7 @@ export function evaluateExpression(expression: Function, paramsArgs: [string, an
  * @see parseExpression
  * @see evaluateExpression
  */
-export function evaluateExpressionOrCatch(expression: Function, paramsArgs: [string, any][], arg: string) {
+export function evaluateExpressionOrCatch(expression: Function, paramsArgs: ExpressionParameter[], arg: string) {
     try {
         return evaluateExpression(expression, paramsArgs);
     } catch (e) {