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.50The 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,30Legacy tools key on the first character, so tell them comment=";".
Blocks
- The file block is everything between the first line and the first
tableline: metadata about the whole file, shared SQL, a note about the file, comments. - A table block starts with
tableand 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
tableor 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.