super-productivity/docs/wiki/3.04-Short-Syntax.md

Short Syntax

Super Productivity supports five main short syntax forms for quickly adding metadata to tasks: tags (#), projects (+), time estimates (m/h), due dates (@), and deadlines (!). The project, tag, and due/deadline/time forms can be enabled or disabled in 3.02-Settings-and-Preferences#global-settings.Short-Syntax.

Supported Syntax Forms

Tag Syntax (#)

• Symbol: #
• Purpose: Add tags to the task.
• Grammar: #<tag-name>. A space is required before #.
• Parameters: Tag name (case-insensitive).
• Valid: "Task #urgent", "Meeting #work #important". Multiple tags allowed.
• Invalid: "Task#urgent" (no space before #) — the whole short-syntax run returns no changes. If other tokens are valid (e.g. "Task#urgent #other"), only the valid tag is applied and the invalid token is left in the title.

Project Syntax (+)

• Symbol: +
• Purpose: Assign the task to a project.
• Grammar: +<project-name>. A space is required before +.
• Parameters: Project title or partial title; minimum 3 characters. Matching is prefix-based, case-insensitive, with spaces removed for comparison. The shortest matching project title is preferred when several match.
• Valid: "Task +Important Project", "Task +Project" (partial match). Project names containing +, #, @, or similar are supported; the parser uses lookahead so these characters inside the name do not end the token.
• Invalid: "Task+Project" (no space before +) — no project is applied.

Time Estimate Syntax

• Symbols: m (minutes), h (hours). Optional prefix t. Optional / to separate time spent from time estimate.
• Purpose: Set time spent and/or time estimate.
• Grammar: [t]<number><unit>[ <number><unit>...][/ <number><unit>...]. Units: m, h. Decimal numbers allowed (e.g. 1.5h). Before /: time spent on the current day. After /: time estimate. Clusters like 1h 30m are supported.
• Parameters: Time spent (before /): e.g. 30m, 1.5h. Time estimate (after /): e.g. 1h, 90m. One side can be omitted: 30m/ sets only time spent; 1h sets only estimate.
• Valid: "Task 10m", "Task 1h/2h", "Task 30m/", "Task t1.5h", "Task 1h 30m / 2h".
• Defaults: h = 60 minutes.

Due Date Syntax (@)

• Symbol: @
• Purpose: Set due date/time for the task.
• Grammar: @<date-time-expression>. No space is allowed between @ and the expression.
• Parameters: Date/time expressions supported by the Chrono-based parser (e.g. 4pm, friday, tomorrow 19:00, 2030-10-12T13:37).
• Valid: "Task @4pm", "Task @friday", "Task @tomorrow 19:00", "Task @2030-10-12T13:37".
• Invalid: "Task @ tomorrow" (space after @) — due date is not applied and the expression is stripped from the title. Two-digit years 50–99 are corrected to the current or next calendar year to avoid Chrono interpreting them as years (e.g. 90m in a date context).

Deadline Syntax (!)

• Symbol: !
• Purpose: Set a deadline date/time for the task.
• Grammar: !<date-time-expression>. A space is required before ! when it is not at the start of the title.
• Parameters: Date/time expressions supported by the Chrono-based parser (e.g. 14:30, friday, next month).
• Valid: "Task !14:30", "Task !friday", "Task @monday !friday".
• Invalid: "Done!" (no space before !) — the exclamation mark is treated as punctuation and no deadline is applied.

Formal Grammar and Regex Patterns

The parser uses regular expressions for each syntax form. Time: optional t prefix, digits and decimal with m/h, optional / for spent/estimate. Project: + with lookahead so delimiters (#, @, time-like tokens) inside the project name do not terminate the match. Tag: # followed by characters until a special character or whitespace. Due: @ followed by characters until a special character. Deadline: ! followed by characters until a special character. Exact patterns are defined in short-syntax.ts (e.g. SHORT_SYNTAX_TIME_REG_EX, SHORT_SYNTAX_PROJECT_REG_EX, SHORT_SYNTAX_TAGS_REG_EX, SHORT_SYNTAX_DUE_REG_EX, SHORT_SYNTAX_DEADLINE_REG_EX).

Default Values and Behavior

• Time units: m = minutes, h = 60 minutes.
• Time spent only: e.g. 30m/ sets time spent on the current day and no estimate.
• Time estimate only: e.g. 1h sets estimate without time spent.
• Date parsing: Uses a custom Chrono-based parser with year correction for two-digit years 50–99 (current/next year).
• Project matching: Prefix-based, case-insensitive, spaces removed; shortest matching project title wins.
• Tag mode: combine (default) or replace; configurable in settings.

Where Short Syntax Is Supported

Supported:

• Add Task Bar (primary place for creating tasks with short syntax).
• Task creation when adding new tasks (e.g. via the shared add-task action).
• Task title updates when the only change is the title (syntax is re-parsed).

Unsupported or disabled:

• Issue-linked tasks: Tasks linked to external issues cannot use project syntax (see 2.07-Manage-Task-Integrations).
• When disabled: Short syntax has three settings groups in 3.02-Settings-and-Preferences#global-settings.Short-Syntax: project, tag, and due/deadline/time. Disabled groups are ignored.
• Archived or hidden projects: Project syntax does not match archived or hidden projects.

Parsing and Evaluation Rules

1. Order of processing: Due/deadline/time → Project → Tag.
2. Title cleanup: Parsed syntax is removed from the task title after processing.
3. Tag creation: Tags that do not exist yet are collected in a newTagTitles array for creation.
4. Return value: The shortSyntax() function returns an object with task changes (and newTagTitles, remindAt, projectId) or undefined if nothing was parsed or syntax is disabled.

Error Handling

Malformed syntax:

• Invalid syntax is ignored; the function may return undefined or only apply valid parts.
• No exception is thrown; invalid tokens are skipped or left in the title as appropriate.
• If a syntax type is disabled in settings, that form is not processed.

Edge cases:

• Project names containing +, #, @, or time-like patterns are handled so that the project token is parsed correctly.
• Two-digit years 50–99 in date expressions are corrected to the current or next year.
• Time estimate tokens (e.g. 90m) in the same title as date expressions are parsed separately so Chrono date parsing does not consume the time estimate.

Add Task Bar Behavior

• Toggle new task position: A toggle in the Add Task Bar controls whether the new task is added at the top or the bottom of the list.
• Autocomplete: The Add Task Bar can suggest tags, projects, and date expressions while typing.

Notes

• Short syntax is processed by the shortSyntax() function; it returns task changes or undefined when no changes are needed.
• The five syntax forms are controlled by the global Short Syntax settings for project, tag, and due/deadline/time in 3.02-Settings-and-Preferences.