pkgs/profpatsch/encode: change number format and defined records

Change the number format to be more concise, working in steps of 2^n,
going from 2^1 (1 bit) to 2^9 (512 bits), though implementations are
free to define the biggest numbers they want to support.

Records get the marker `{` and are closed by `}`, so parens match up
nicely, similar to lists.

1 files changed, 26 insertions, 19 deletions

diff --git a/pkgs/profpatsch/encode/spec.md b/pkgs/profpatsch/encode/spec.md
index 11222de9..163ad414 100644
--- a/pkgs/profpatsch/encode/spec.md
+++ b/pkgs/profpatsch/encode/spec.md
@@ -7,6 +7,8 @@
 
 Scalars have the format `[type prefix][size]:[value],`.
 
+where size is a natural number without leading zeroes.
+
 ### unit
 
 The unit (`u`) has only one value.
@@ -17,13 +19,17 @@ The unit is: `u,`
 
 Naturals (`n`) and Integers (`i`), with a maximum size in bits.
 
-The allowed bit sizes are: 8, 16, 32, 64, 128. (TODO: does that make sense?)
+Bit sizes are specified in 2^n increments, 1 to 9 (`n1`..`n9`, `i1`..`n9`).
+
+Natural `1234` that fits in 32 bits (2^5): `n5:1234,`
+Integer `-42` that fits in 8 bits (2^3): `i3:-42,`
+Integer `23` that fits in 64 bits (2^6): `i64:23,`
+Integer `-1` that fits in 512 bits (2^9): `i9:-1,`
+Natural `0` that fits in 1 bit (2^1): `n1:0,`
 
-Natural `1234` that fits in 32 bits: `n32:1234,`
-Integer `-42` that fits in 8 bits: `i8:-42,`
-Integer `23` that fits in 64 bits: `i64:23,`
+An implementation can define the biggest numbers it supports, and has to throw an error for anything bigger. It has to support everything smaller, so for example if you support up to i6/n6, you have to support 1–6 as well. An implementation could support up to the current architecture’s wordsize for example.
 
-Floats elided by choice.
+Floats are not supported, you can implement fixed-size decimals or ratios using integers.
 
 ### text
 
@@ -32,10 +38,9 @@ Text (`t`) that *must* be encoded as UTF-8, starting with its length in bytes:
 The string `hello world` (11 bytes): `t11:hello world,`
 The string `今日は` (9 bytes): `t9:今日は,`
 The string `:,` (2 bytes): `t2::,,`
-The empty sting `` (0 bytes): t0:,`
-
-Binary data elided by choice.
+The empty sting `` (0 bytes): `t0:,`
 
+Binary data is not supported, it hinders human readability. Try to use structured data, or use a different format.
 
 ## tagged values
 
@@ -44,33 +49,35 @@ Binary data elided by choice.
 A tag (`<`) gives a value a name. The tag is UTF-8 encoded, starting with its length in bytes and proceeding with the value.
 
 The tag `foo` (3 bytes) tagging the text `hello` (5 bytes): `<3:foo|t5:hello,`
-The tag `` (0 bytes) tagging the 8-bit integer 0: `<0:|i8:0,`
+The tag `` (0 bytes) tagging the 8-bit integer 0: `<0:|i3:0,`
 
-### products (dicts/records), also maps
+### records (products/records), also maps
 
-Multiple tags concatenated, if tag names repeat the later ones should be ignored. (TODO: should there be a marker indicating products, and should maps get a different marker? We don’t have a concept of types here, so probably not.)
-Ordering does not matter.
+A record (`{`) is a concatenation of tags (`<`). It needs to be closed with `}`.
+If tag names repeat the later ones should be ignored. Ordering does not matter.
 
-### sums (tagged unions)
+There is no empty record. (TODO: make the empty record the unit type, remove `u,`?)
+A record with one empty field, `foo`: `{<3:foo|u,}`
+A record with two fields, `foo` and `x`: `{<3:foo|u,<1:x|t3:baz,}`
+The same record: `{<1:x|t3:baz,<3:foo|u,}`
+The same record (later occurences of fields are ignored): `{<1:x|t3:baz,<3:foo|u,<1:x|u,}`
 
-Simply a tagged value (TODO: should there be a marker?).
+### sums (tagged unions)
 
+Simply a tagged value. The tag marker `<` indicates it is a sum if it appears outside of a record.
 
 ## lists
 
-TODO: necessary?
-
 A list (`[`) imposes an ordering on a sequence of values. It needs to be closed with `]`. Values in it are simply concatenated.
 
 The empty list: `[]`
 The list with one element, the string `foo`: `[t3:foo,]`
-The list with text `foo` followed by i8 `-42`: `[t3:foo,i8:-42,]`
+The list with text `foo` followed by i3 `-42`: `[t3:foo,i3:-42,]`
 The list with `Some` and `None` tags: `[<4:Some|t3:foo,<4None|u,<4None|u,]`
 
-
 ## motivation
 
-Using
+TODO
 
 ## guarantees