# Short Syntax

Super Productivity supports four main short syntax forms for quickly adding metadata to tasks: tags (`#`), projects (`+`), time estimates (`m`/`h`/`d`), and due dates (`@`). Each form can be enabled or disabled individually 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), `d` (days). 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`, `d`. 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`, `2d`. Time estimate (after `/`): e.g. `1h`, `90m`, `0.5d`. 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"`, `"1h 30m / 1d 12h"`.
- **Defaults:** `h` = 60 minutes, `d` = 8 hours (work day).

### 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).

## Formal Grammar and Regex Patterns

The parser uses regular expressions for each syntax form. Time: optional `t` prefix, digits and decimal with `m`/`h`/`d`, 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. 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`).

## Default Values and Behavior

- **Time units:** `m` = minutes, `h` = 60 minutes, `d` = 8 hours (work day).
- **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:** Each syntax type (tag, project, time, due) can be turned off in [[3.02-Settings-and-Preferences#global-settings.Short-Syntax]]; disabled forms are ignored.
- **Archived or hidden projects:** Project syntax does not match archived or hidden projects.

## Parsing and Evaluation Rules

1. **Order of processing:** Due → Project → Tag (time is processed together with due).
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.
- All four syntax forms are configurable in the global Short Syntax section in [[3.02-Settings-and-Preferences]].
