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

guide/first-line

First line

txtab

# texttables=0.1 delim=comma quote=double

The first line says three things: this is Text Tables (version 0.1), the prefix is #, and here's the default CSV dialect for every table in the file.

Everything is key=value, separated by spaces. Values with spaces go in double quotes; a quote inside is written "". The line is plain ASCII.

Key What it says Default
texttables Format version — always first —
tables How many tables the file has — required when there's more than one 1
delim Delimiter: comma, tab, pipe, semicolon, or a literal like :: comma
quote Quote character: none, double, single, or a literal none
null An extra string that also means null, e.g. NA or \N (empty is always null) —
encoding Encoding of the file after the first line when there's no BOM UTF-8

delim, quote, null and encoding are defaults: each table can override them on its own table line.

Whether a table starts with a row of column names is not here: that's header, on each table line, and it defaults to yes.

Why tables= is strict

Each table declares its own row count, so a table cut in the middle is noticed. But a file cut exactly between two tables would look complete. tables=3 closes that gap: a file with two table lines is reported as incomplete, every time.

Your own keys

Unknown keys are left alone. If you invent one, start it with x- (x-team=analytics) so it never collides with a future standard key.

guide/first-line.md on GitHub