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

guide/introduction

Introduction

You open a CSV someone sent you. Which column is the amount? Is 01720 a ZIP code or the number 1720? Is 2026-01-02 the 2nd of January or the 1st of February? Are these all the rows, or just the first thousand your viewer loaded? What's the total — do you trust it, or add the column up yourself? And what about the other three files that came with it — how do they connect?

The answers usually live somewhere else: a README, a chat thread, someone's memory. Text Tables puts them back in the file. Column types and units, what one row means, pre-computed totals, where the data came from, the CREATE TABLE that would recreate it — written as lines that start with a prefix (usually #) which CSV tools already know how to skip.

txtab

# texttables=0.1 delim=comma
# meta-source crm export
# table name=orders rows=2
# column name=id type=long role=id
# column name=amount type=decimal unit=USD role=measure agg=sum
# agg-sum ,1050.50
id,amount
1,500.00
2,550.50

Below the system lines it's ordinary CSV. Tell pandas, R or DuckDB that # starts a comment and they read it as before.

It describes; it never changes your data

Reading a Text Tables file never rewrites a value, never fills a blank, never "corrects" anything. What's in the rows is what's there. A few explicit commands do write data — materializing a computed column, slicing a table — but they are deliberate edits, never a side effect of opening a file.

What you can add

Every layer is optional. Start with the first line, then name your tables, then add types, then totals, then SQL — and stop wherever it's useful enough.

  • The first line — names the format and the CSV dialect: delimiter, quote, header row, encoding.
  • Tables (table) — each table declares how many rows it has, optionally a name, and where its data is.
  • Columns (column) — types, units and currencies, formats, allowed values, analytical roles (id, measure, time), relations to other tables, computed columns.
  • Aggregates (agg-*) — sum, average, min, max, counts — written down, so the total is a fact in the file.
  • Metadata (meta-*) — source, author, license, the date the data is current as of, and what one row is.
  • SQL (sql-*) — the DDL to recreate the tables, split like pg_dump into before-data and after-data, and queries for provenance.
  • Notes, links and charts — remarks on cells and rows, clickable values, suggested views.

One file, many tables

A file can hold several tables, each starting with its own table line. Their data can sit right in the file, in ordinary CSV/TSV files next to it (which stay untouched), or column by column inside a .txtab.zip. One .txtab can describe a whole folder of exports.

A new take on ExCSV

Text Tables grew out of ExCSV 0.6. It keeps ExCSV's idea — CSV that describes itself — and reworks the syntax: a configurable prefix, keywords instead of sigils, several tables per file, one archive form. It is a new format: Text Tables tools don't read ExCSV files.

guide/introduction.md on GitHub