[0.1 draft] [guide 15 · spec 15 pages]

spec/lines

System lines and keywords

Grammar

text

system-line = P SP keyword [SP payload]
comment     = P SP "--" [SP text]   |   P
keyword     = [a-z] [a-z0-9-]*
  • The space after P is mandatory. A line that starts with P immediately followed by a non-space character is not a system line: inside a block it starts the table's data section (see file-structure.md), so a header row such as #id,name is data.
  • The keyword is the text up to the next space or end of line. A first token that does not match [a-z][a-z0-9-]* and is not -- is keyword-malformed (FAIL).
  • There are no sigils: every directive is named by a keyword (decision 0001).

Payload types

The keyword decides how the rest of the line is read:

Type Read as Keywords
key-value key=value tokens, tokenized as on the first line (first-line.md) table, column, chart, note, link
row one record in the table's effective dialect, one value per column agg-*
text raw text to end of line, taken as-is; no quoting or escaping meta-*
sql a dialect token, one space, then raw text to end of line sql-pre-data, sql-post-data, sql-dql

Keywords

Keyword Payload File block Table block Spec
table key-value starts a table starts the next table tables.md
column key-value — ✓ columns.md
agg-<name> row — ✓ aggregates.md
meta-<key> text (may be empty) ✓ ✓ metadata.md
sql-pre-data, sql-post-data, sql-dql sql ✓ ✓ sql.md
note key-value ✓ (no address) ✓ notes.md
link key-value — ✓ notes.md
chart, chart-<engine> key-value / text — ✓ charts.md
-- comment ✓ ✓, and after a data section below

A keyword in a block where it is not allowed is a FAIL with a code of the form <keyword>-in-file-block (for example column-in-file-block, link-in-file-block, chart-in-file-block).

Comments

  • A system line whose first token is -- is a comment. The rest of the line is free text.
  • A line that is exactly P is an empty comment.
  • Comments MAY appear anywhere after the first line, including between a data section and the next P table.
  • Parsers MUST ignore comments. Tools MAY drop them when rewriting a file. A remark that must survive belongs in a note (notes.md).

Unknown keywords and extensions

  • A keyword that matches the grammar but is not defined here MUST be ignored and SHOULD be reported (keyword-unknown, WARN). Writers that round-trip a file SHOULD preserve such lines in place.
  • Custom keywords SHOULD start with x- (for example x-ui-widget) so they never collide with future standard keywords.
  • Keys inside key-value payloads follow the same rule: unknown keys are ignored (key-unknown, WARN); custom keys use x-.

Order

  • Inside a block, directives MAY appear in any order. The only order with meaning is the execution order of sql-pre-data and sql-post-data (sql.md) and the position of directives relative to P table lines (which table they belong to).
  • Recommended order inside a table block: table, meta-*, column, chart, note/link, sql-*, agg-*.

spec/lines.md on GitHub