8.9
Christopher Lemmer Webber
and Jérôme Martin
Canonical s-expressions (csexp) are a way to format s-expressions into data packets
suitable for transmission over a network.
1 Overview
Consider the following expression:
‘(bag “Inventory” (content cookie caramel aligator))
To get a canonical s-exp, it must first be changed into a tree of bytestrings:
(list #”bag” #””Inventory”” (list #”content” #”cookie” #”caramel” #”aligator”))
Which can then be transmitted as:
#”(3:bag11:”Inventory”(7:content6:cookie7:caramel8:aligator))”
Spaces are removed and all strings are suffixed by their size and a colon : separator.
This makes it easy to read the expression in a stream, and gives a unique (canonical) way
of writing a given s-expression.
2 Hinted csexp
Canonical s-expressions can have an optional “hint”, which is a bytestring attached to the front of a
csexp atom, inside square brackets:
#”(6:animal(4:name[13:charset=utf-8]7:The Cat)(5:noise4:meow))”
Here the hint is attached to the atom The Cat and has the value charset=utf-8.
When parsing a csexp, hints are rendered by default as hinted structures.
Example:
> (bytes->csexp #”(6:animal(4:name[13:charset=utf-8]7:The Cat)(5:noise4:meow))”)
(list
#”animal”
(list #”name” (hinted #”The Cat” #”charset=utf-8″))
‘(#”noise” #”meow”))
3 Reference
Transform a csexp into a string of bytes.
Reads a string of bytes and parse it as a csexp.
If hinting is ‘if-present, it generates a hinted instance every time a hint
is found.
If hinting is ‘always, it generates hinted instances for each atom, with #f as the default hint value.
If hinting is ‘never, it ignores any hint and just returns bytestrings.
Read a csexp from a port, byte by byte.
Write a csexp to a port.
A structure which contains hints. See Hinted csexp.
Check if a given value is a canonical s-expression.
Examples:
