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

guide/file-structure

File structure

A Text Tables file reads top to bottom:

text

┌──────────────────────────────┐
│ First line                   │  # texttables=0.1 …
├──────────────────────────────┤
│ File block                   │  lines about the whole file
├──────────────────────────────┤
│ Table                        │  # table …, then lines about this table,
│                              │  then its rows (if they're in this file)
├──────────────────────────────┤
│ More tables …                │
└──────────────────────────────┘

The smallest useful file has a first line, one table line and its rows:

txtab

# texttables=0.1
# table rows=2
id,amount
1,500.00
2,550.50

The prefix

Everything before the first space on the first line is the file's prefix — here #. Every system line starts with the prefix and a space. Lines without it are data.

# is the right choice almost always: pandas (comment="#"), R (comment.char = "#") and DuckDB (comment='#') can skip such lines, so a one-table file opens as ordinary CSV.

Pick another prefix when your data itself has lines starting with # — hashtags, issue numbers. Any 1–8 printable ASCII characters work, as long as the first isn't a letter or a digit:

txtab

;; texttables=0.1
;; table rows=2
;; column name=tag type=string
tag,count
# release,12
# bugfix,30

Legacy tools key on the first character, so tell them comment=";".

Blocks

  • The file block is everything between the first line and the first table line: metadata about the whole file, shared SQL, a note about the file, comments.
  • A table block starts with table and runs until the table's rows begin. Its columns, aggregates, SQL, notes and charts are listed there.
  • After a table's rows come only the next table or comments.

Rows are read by count: a table that says rows=2 has exactly two data rows (plus a header row if header=1). So a data row may start with anything, and a cut-off file is noticed.

Comments

txtab

# -- generated by the nightly export job

-- right after the prefix makes a comment. Tools ignore it and may drop it when they rewrite a file; if a remark must survive, write a note.

Encoding

  • No BOM: the file is UTF-8 unless the first line says otherwise (encoding=windows-1251). The first line itself is always plain ASCII.
  • With a BOM, the BOM decides — UTF-8, UTF-16 or UTF-32. That covers Excel's "CSV UTF-8" (UTF-8 with a BOM) and "Unicode Text" (UTF-16 with tabs).
  • A table can say encoding= too — handy when one file describes CSV exports from different systems.

Line endings can be LF or CRLF.

Plain CSV tools and several tables

A file with one table is a valid CSV for any tool that skips comment lines. With several tables, the same tool would glue all their rows together — the second table's header row turning into a data row. Keep that in mind when a file is meant to be opened by tools that don't know Text Tables.

guide/file-structure.md on GitHub