https://docs.racket-lang.org/csexp/index.html

>  csexp:   S-expressions over the network
1  Overview
2  Hinted csexp
3  Reference
csexp:   S-expressions over the network
1 Overview
2 Hinted csexp
3 Reference
csexp->bytes
bytes->csexp
read-csexp
write-csexp
hinted
csexp?
8.9
[                    ]
  top  contents  - prev  up  next - 

csexp: S-expressions over the network

Christopher Lemmer Webber
and Jerome 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


[                    ]
  top  contents  - prev  up  next -