Skip to content

grammar.md

Latest commit

 

History

History
143 lines (106 loc) · 3.46 KB

grammar.md

File metadata and controls

143 lines (106 loc) · 3.46 KB
Raw

Grammar

Structure

start: line*
line: heading | task | _SKIP_LINE

Headings

heading: HEADING_MARKER content_item* _NL
HEADING_MARKER: /#{1,6} /
Example Level
# TODO 1
## Sprint 2
### Backend 3

Tasks

task: INDENT? LIST_MARKER checkbox content_item* _NL
LIST_MARKER: /[-*] /
INDENT: /[ \t]+/

Indented tasks become subtasks of the previous less-indented task.

Checkboxes

Terminal Pattern State
CHECKBOX_OPEN [ ] open
CHECKBOX_DONE [x] or [X] done
CHECKBOX_CANCELLED [-] cancelled
CHECKBOX_BLOCKED [!] blocked

Content Items

Terminal Pattern Example
PROJECT \+[\w\/.-]+ +work, +parent/child, +v2.1
TAG #[\w-]+ #urgent
ASSIGNEE @[\w-]+ @alice
PRIORITY \([\w]+\) (A)
DURATION ~\d+[hmd] ~2h
KEYVALUE_QUOTED \w+:"[^"]+" desc:"with spaces"
KEYVALUE \w+:\S+ due:2025-01-01
DATE_POSITION \d{4}-\d{2}-\d{2} 2024-03-15
ESCAPED \S*\\[@#+]\S* john\@example.com
WORD [^\s@#+~:\\]+ Fix

Duration Conversion

Unit Multiplier Example
h 60 ~2h → 120 min
m 1 ~30m → 30 min
d configurable (default 480) ~1d → 480 min

Use ParseConfig(minutes_per_day=N) to customize.

Built-in Key-Value Fields

Key Field Type
due due_date String
created created_date String
started started_date String
done done_date String
planned planned_date String
paused paused_date String
recur recurrence String
repeat recurrence String (alias)
Other custom_fields[key] String

Positional Dates

ISO dates at the start of a task line are parsed as:

  • First date → planned_date
  • Second date → done_date

Example: - [x] 2024-03-01 2024-03-05 Task → planned: 2024-03-01, done: 2024-03-05

Escaping

Use backslash to escape metadata markers:

  • \@ → literal @ (not assignee)
  • \# → literal # (not tag)
  • \+ → literal + (not project)

Frontmatter

YAML front matter at the start of a file provides file-level metadata:

---
timezone: America/New_York
locale: en_US
---

# Tasks
- [ ] My task
Field Purpose
timezone IANA timezone for date interpretation
locale Locale for formatting (future use)

Accessed via store.frontmatter.timezone and store.frontmatter.locale.

Recurrence Patterns

The repeat: field supports various patterns:

Pattern Example Next Occurrence
Simple daily, weekly, monthly, yearly +1 unit
Multiplied 2weeks, 3days, 2d, 3w +N units
Day of month 15th, 1st, 31st Next occurrence (clamps to month end)
Nth weekday 2nd-tuesday, last-friday Next Nth weekday of month
Natural language "every other week" Via recurrent library (requires quotes)

When a recurring task is marked done, a new open task is created for the next occurrence.

Parser Configuration

Setting Value
Parser Earley
propagate_positions True

Related

  • ARCHITECTURE.md - System design
  • TYPES.md - Output types