spec/first-line
First line
txtab
P texttables=0.1 delim=commaLine 1 is P, one space, then a list of key=value tokens. The first token MUST be texttables=<version>. Every character of line 1 MUST be ASCII (first-line-not-ascii, FAIL) — values with non-ASCII text belong in meta-* lines.
Tokens
The first line and every key=value payload (lines.md) use the same tokenizer:
- Tokens are separated by one or more spaces.
- A token is
key=value; it is split on the first=(values may contain=). - A value without spaces MUST NOT be quoted.
- A value with spaces MUST be wrapped in double quotes (
"); a literal"inside is written"". No other escapes exist. - A token without
=, or an unterminated quote, iskv-malformed(FAIL). - Keys are kebab-case (decision 0005). An unknown key MUST be ignored and SHOULD be reported (
key-unknown, WARN). Custom keys SHOULD start withx-. - A key repeated in one line: last wins,
key-duplicate(WARN).
Keys
| Key | Requirement | Default | Meaning |
|---|---|---|---|
texttables |
MUST, first token | — | Format version, e.g. 0.1 |
tables |
MUST if more than one table | 1 |
Number of P table lines in the file |
encoding |
MAY | UTF-8 |
Encoding of the file after line 1 when there is no BOM; default for every table's data (file-structure.md) |
delim |
MAY | comma |
Default delimiter for all tables |
quote |
MAY | none |
Default quote character for all tables |
null |
MAY | — | Default extra null marker for all tables |
delim, quote, null and encoding are defaults: a P table line MAY override each of them for its table (tables.md). name, rows, header, columns, reference, storage, section-size and data-size are table keys; on the first line they are key-misplaced (WARN, ignored). In particular header on the first line has no effect: each table's own header, or its default 1, applies (tables.md).
texttables
- A missing or non-first
texttables=means the file is not Text Tables (file-structure.md). - A version the parser does not implement is
version-unknown(WARN); the parser reads the file best-effort.
tables
- Strict: the number of
P tablelines in the file MUST equaltables(or 1 whentablesis absent). A mismatch istables-mismatch— always FAIL, on read and inverify. A parser MAY return the tables it read, but MUST report the file as incomplete. - More than one
P tableline withouttables=istables-missing(FAIL). tables=0is an empty stub: noP tablelines.
delim
A well-known name or a literal string. Parsers MUST check the name table first; any other value is the literal delimiter.
| Name | Delimiter |
|---|---|
comma |
, |
tab |
TAB (U+0009) |
pipe |
| |
semicolon |
; |
Examples: delim=:: is the two-character sequence ::; delim=| is a literal pipe.
quote
| Name | Quote character |
|---|---|
none |
no quoting (default) |
double |
" |
single |
' |
Any other value is the literal quote character. Inside a quoted value the quote character is doubled.
null
An additional non-empty string that also means null, for example null=NA or null=\N. An empty field is always null.