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

spec/first-line

First line

txtab

P texttables=0.1 delim=comma

Line 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, is kv-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 with x-.
  • 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 table lines in the file MUST equal tables (or 1 when tables is absent). A mismatch is tables-mismatch — always FAIL, on read and in verify. A parser MAY return the tables it read, but MUST report the file as incomplete.
  • More than one P table line without tables= is tables-missing (FAIL).
  • tables=0 is an empty stub: no P table lines.

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.

spec/first-line.md on GitHub