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

Plain text tables
that describe themselves.

CSV rows, plus a few lines that say what they mean: types, units, totals, where the data came from, how tables join. Any CSV tool still reads it.

txtab peek orders.txtab 1 table · 3 rows · 9 lines

¹sourceorders.txtab

id,status,amount
1001,paid,500.00
1002,paid,300.50
1003,refunded,250.00

²tableorders

source
shop_db.orders
grain
one row per order
rows
3 declared · 3 read ✓ · header row
idstatusamount
long · idstring · enumdecimal · USD · sum
1001paid500.00
1002paid300.50
1003refunded●250.00
Σ 1050.50

³inspectline 7

# column · column

Exact decimals, in US dollars, meant to be summed.

name=amounttype=decimalunit=USDrole=measureagg=sum

hoverselect a line ↑ ↓move tabnext line highlighted cells are what the selected line describes

Reads with anything

A one-table file is ordinary CSV to any tool that skips comment lines. Several tables in one file? Read them with a Text Tables tool, or slice by the declared row counts.

⁴read with

$ pd.read_csv("orders.txtab", comment="#")

⁵table

Several tables, one file

Orders and customers side by side, joined by references=. Or one small file describing CSVs that stay untouched next to it.

read more →
⁶agg-sum

Totals that survive a preview

Sums and counts are written down for all rows. Paste the first fifty into a chat and the total is still right.

read more →
⁷meta-grain

Context for agents

What a row is, which column is money, what never to sum — read in a few lines, before touching the data.

read more →
⁸sql-pre-data

SQL that comes along

The CREATE TABLE, the keys and a query, per database dialect, in the same file as the rows they load.

read more →
⁹note

Remarks on cells

Pin a note to a cell, row, column or the whole file. Keyed by the row id, it stays put when the table is sorted.

read more →
¹⁰.txtab.zip

Big and wide

Zip it; the schema rides in the archive comment, readable without unzipping. Wide tables can be stored column by column.

read more →