# Text Tables line syntax (0.1, reading view)

What a reader needs to parse a file by hand. The normative source is `spec/` in the repository.

## Layout

```
# texttables=0.1 delim=comma tables=2   ← line 1: prefix, version, file defaults (ASCII only)
# meta-source shop_db                             ← file block: before the first table
# table name=orders rows=2                        ← table block starts
# column name=id type=long role=id
# agg-sum ,250.00
id,amount                                         ← data: header row + exactly rows records
1,100.00
2,150.00
# -- comments may sit between tables
# table name=customers rows=1                     ← next table
id
7
```

- **Prefix `P`**: line 1 up to its first space. 1–8 printable ASCII characters, first not a letter/digit (`#`, `;;`, `/***/`). One per file.
- **System line**: `P` + space + keyword + payload. A line that is exactly `P` is an empty comment. A line starting with `P` without a space (e.g. `#id,name`) is data.
- **Comment**: `P -- text`. Ignored.
- After a table's data come only the next `table` line or comments. There is no footer.
- Records are single-line. A file may start with a BOM (UTF-8/16/32); lines end in LF or CRLF.

## `key=value` payloads

Line 1, `table`, `column`, `chart`, `note`, `link` use one grammar: tokens separated by spaces, split on the first `=`; a value with spaces is double-quoted and `""` inside is `"`. Unknown keys are ignored; custom keys start with `x-`.

## Line 1 and `table`

| Key | Where | Meaning |
| --- | --- | --- |
| `texttables` | line 1, first | Version |
| `tables` | line 1 | Number of `table` lines; required when more than one; strict |
| `delim` | line 1 default, `table` override | `comma` (default) `tab` `pipe` `semicolon` or a literal |
| `quote` | same | `none` (default) `double` `single` or a literal |
| `null` | same | Extra null marker (`NA`, `\N`); empty is always null |
| `encoding` | same | Without a BOM: encoding after line 1 (default UTF-8); on `table`: of that table's data |
| `rows` | `table`, required | Data records, header row not counted |
| `header` | `table` only | `1` (default) header row present, `0` absent; ignored on line 1 |
| `name` | `table` | `[A-Za-z_][A-Za-z0-9_]*`, unique |
| `columns` | `table` | Physical column count |
| `reference` | `table` | External data: `file.csv` or `dir/` |
| `storage` | `table` | `rows` (default) or `columns` (with `reference=dir/`) |
| `section-size` | `table` | Records per `.col` section (column storage) |
| `data-size` | `table` | Approximate unpacked bytes of the table's data |

## Keywords

| Keyword | Payload | Meaning |
| --- | --- | --- |
| `table` | key=value | Starts a table |
| `column` | key=value | One column's schema |
| `agg-<name>` | a row in the table's dialect | Aggregate, one value per physical column |
| `meta-<key>` | raw text (empty = flag) | Metadata: `source`, `author`, `comment`, `grain`, `created`, `exported`, `as-of`, `license`, `tool`, `tags`, any other |
| `sql-pre-data` / `sql-post-data` | `<dialect>[-<version>] <statement>` | DDL before / after loading data; one statement per line; file order |
| `sql-dql` | same | Query for provenance; never run |
| `note` | key=value | Remark: `text=` + optional `col`/`row`/`key` |
| `link` | key=value | URL for one cell: `href=`, `col=`, `row=`/`key=` |
| `chart` / `chart-vega` | key=value / raw JSON | Suggested chart |
| `--` | text | Comment |

## `column` attributes

| Attribute | Meaning |
| --- | --- |
| `name` | `[A-Za-z_][A-Za-z0-9_]*`; binds to the header cell (unless `title=` is set) |
| `title` | Any text; the header cell's actual text when it isn't an identifier (`title="Сумма (руб.)"`) |
| `index` | Zero-based position; required with `header=0` |
| `type` | `string` `int` `long` `float` `double` `decimal` `boolean` `date` `time` `datetime` `uuid` `binary` |
| `format`, `description`, `example` | Display hint, description, made-up example value |
| `unit` | `kg`, `USD` (ISO 4217 = money), `EUR/kg`, `@column` (per row) |
| `required`, `default` | Not null; database default (never filled on read) |
| `min` `max` `len-min` `len-max` `enum` `pattern` `regexp-dialect` `unique` | Constraints (descriptive) |
| `role`, `agg` | `id` `dimension` `measure` `time`; `sum` `avg` `min` `max` `none` |
| `references` | `<table>.<column>` foreign key, informational |
| `order`, `separator`, `link` | Sort order, multi-value separator, URL template |
| `formula`, `materialized` | Computed column; `materialized=1` stores the values |

## SQL dialects

`ansi`, `mysql`, `mariadb`, `postgres` (aliases `postgresql`, `pg`), `mssql` (`sqlserver`), `sqlite`, `oracle`, `db2`, `clickhouse`, `snowflake`, `bigquery`, `duckdb`; any other lowercase name is accepted. Version after a hyphen: `postgres-17`, `mysql-8.4`. For a target, take lines of the same dialect; unversioned and versioned lines of one dialect both match.
