File formats for tables, documents and diagrams that stay correct when several people edit them in git.
Two people add a row to a spreadsheet saved as CSV. git merge reports no
conflict, and the total comes out 480 when the truth is 660. A formula pointed
at a position, the rows moved, and nothing warned anyone.
Every format follows three rules:
- Names, not positions. A formula says
qty * unit, neverB2 * C2. - Correct or refused. A file that can't be read correctly is rejected, with the reason.
- Plain git is enough. No merge driver, no plugin.
Each format is a written spec plus a test suite. The suite merges real branches with real git, computes the result and checks the numbers. Then it breaks the implementation on purpose, to prove the tests can fail.
Save this as parts.mdtbl:
| id | item | qty | unit | total = qty * unit |
| ------ | ------ | --: | ----: | -----------------: |
| r_0001 | widget | 10 | 12.00 | |
key := id
grand := sum(total)
Then:
pip install rowspec
rowspec check . # will it survive merging?
rowspec eval . # what do the totals come to?| what it is | status | |
|---|---|---|
| rowspec | tables | released, on PyPI |
| blockspec | documents | released, on PyPI |
| nodespec | diagrams | draft spec and checker |
| kindkit | the shared test runner | released, on PyPI |
| research | the measurements the specs cite | ongoing record |
Issues and pull requests are welcome; see rowspec's CONTRIBUTING. Commits need a DCO sign-off. Specs are CC-BY-4.0, test fixtures CC0, code MIT or Apache-2.0.