cell/docs/wota.md

title, description, weight, type

title	description	weight	type
Wota Format	Word Object Transfer Arrangement	86	docs

Wota is a binary message format for local inter-process communication. It is similar to Nota but works at word granularity (64-bit words) rather than byte granularity. Wota arrangements are less compact than Nota but faster to arrange and consume.

Wota stands for Word Object Transfer Arrangement.

Type Summary

Byte	Type
00	Integer
01	Floating Point
02	Array
03	Record
04	Blob
05	Text
07	Symbol

Preambles

Every Wota value starts with a preamble word. The least significant byte contains the type. The remaining 56 bits contain type-specific data.

Blob

A blob is a string of bits. The remaining field contains the number of bits. The number of words that follow: floor((number_of_bits + 63) / 64). The first bit of the blob goes into the most significant bit of the first word. The final word is padded with 0.

Example: A blob containing 25 bits 111100001110001100100001:

0000000000001904    # preamble: 25 bits, type blob
F0E3208000000000    # data (padded to 64 bits)

Text

The text is a string of UTF-32 characters packed 2 per word. The remaining field contains the number of characters. The number of words that follow: floor((number_of_characters + 1) / 2). The final word is padded with 0.

Example: "cat":

0000000000000305    # preamble: 3 characters, type text
0000006300000061    # 'c' and 'a'
0000007400000000    # 't' and padding

Array

An array is an ordered sequence of values. The remaining field contains the number of elements. Following the preamble are the elements, each beginning with its own preamble. Nesting is encouraged. Cyclic structures are not allowed.

Example: ["duck", "dragon"]:

0000000000000202    # preamble: 2 elements, type array
0000000000000405    # text "duck": 4 chars
0000006400000074    # 'd' 't' (reversed pair order)
000000630000006B    # 'c' 'k'
0000000000000605    # text "dragon": 6 chars
0000006400000072    # 'd' 'r'
0000006100000067    # 'a' 'g'
0000006F0000006E    # 'o' 'n'

Record

A record is a set of key/value pairs. Keys must be text. The remaining field contains the number of pairs.

Example: {"ox": ["O", "X"]}:

0000000000000103    # preamble: 1 pair, type record
0000000000000205    # key "ox": 2 chars
0000006F00000078    # 'o' 'x'
0000000000000202    # value: array of 2
0000000000000105    # "O": 1 char
0000004F00000000    # 'O'
0000000000000105    # "X": 1 char
0000005800000000    # 'X'

Number

Numbers are represented as DEC64. To arrange an integer, shift the integer up 8 bits. The number is incorporated directly into the preamble.

Example: 7:

0000000000000700    # integer 7 as DEC64

To arrange a floating point number, place the number in the word following the floating point preamble.

Example: 4.25:

0000000000000001    # preamble: type floating point
000000000001A9FE    # DEC64 encoding of 4.25

Care must be taken when decoding that the least significant byte of the number is not 80 (the null exponent).

Symbol

The remaining field contains the symbol.

Example: [null, false, true, private, system]:

0000000000000502    # array of 5
0000000000000007    # null
0000000000000207    # false
0000000000000307    # true
0000000000000807    # private
0000000000000907    # system