csexp:   S-expressions over the network
1 Overview
2 Hinted csexp
3 Reference
csexp->bytes
bytes->csexp
read-csexp
write-csexp
hinted
csexp?
7.4

csexp: S-expressions over the network

Christopher Lemmer Webber
and Jérôme Martin

 (require csexp) package: csexp

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

procedure

(csexp->bytes csexp)  bytes?

  csexp : csexp?
Transform a csexp into a string of bytes.

procedure

(bytes->csexp bytes [#:hinting hinting])  csexp?

  bytes : bytes?
  hinting : (or/c 'if-present 'never 'always) = 'if-present
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.

procedure

(read-csexp port [#:hinting hinting])  csexp?

  port : input-port?
  hinting : (or/c 'if-present 'never 'always) = 'if-present
Read a csexp from a port, byte by byte.

procedure

(write-csexp csexp port)  void

  csexp : csexp?
  port : output-port?
Write a csexp to a port.

struct

(struct hinted (bytestring hint)
    #:transparent)
  bytestring : bytes?
  hint : bytes?
A structure which contains hints. See Hinted csexp.

procedure

(csexp? v)  boolean?

  v : any
Check if a given value is a canonical s-expression.

Examples:
> (csexp? '(#"animal" (#"name" #"cat") (#"noise" #"meow")))

#t

> (csexp? (list #"animal"
          (list (hinted #"name" #"foo") #"cat")
          '(#"noise" #"meow")))

#t

> (csexp? '())

#t

> (csexp? #"aligator")

#f

> (csexp? (list "aligator"))

#f

> (csexp? (list 'aligator))

#f