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
Pimmediately 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,nameis 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--iskeyword-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
Pis 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 examplex-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 usex-.
Order
- Inside a block, directives MAY appear in any order. The only order with meaning is the execution order of
sql-pre-dataandsql-post-data(sql.md) and the position of directives relative toP tablelines (which table they belong to). - Recommended order inside a table block:
table,meta-*,column,chart,note/link,sql-*,agg-*.