Concise Binary Object Representation
1 Usage
cbor-write
cbor-read
2 Configuration Options
cbor-config
cbor-empty-config
with-cbor-tag-deserializer
with-cbor-null-value
with-sorted-map-keys
gen:  cbor-custom-write
3 Auxiliary Items
cbor-valid-tag-number?
cbor-unassigned-simple-value?
cbor-tag
cbor-simple-value
4 Bugs
8.12

Concise Binary Object Representation🔗ℹ

 (require cbor) package: cbor

This library implements serialization and deserialization routines for Concise Binary Object Representation (CBOR), as defined in RFC 8949. The library takes in raw data in the form of Racket data structures, outputting a serialized binary stream, and vice versa.

1 Usage🔗ℹ

procedure

(cbor-write config v [out])  void?

  config : cbor-config?
  v : any/c
  out : output-port? = (current-output-port)
Writes the value v to out. The following v are accepted:

procedure

(cbor-read config [in])  any/c

  config : cbor-config?
  in : input-port? = (current-input-port)
Reads a binary-serialized CBOR value from in. Major types are decoded as follows:
  • Major type 0 (unsigned integer) and 1 (negative integer) are decoded as standard Racket integers

  • Major type 2 (byte string) and 3 (string) are decoded as Racket bytes? and string?, respectively

  • Major type 4 (list) is decoded as a Racket list? of the contained values

  • Major type 5 (map) is decoded as a Racket hash-equal? of the contained key-value pairs

  • Major type 6 (tag) is decoded according to the registered tag deserializers (see cbor-config). If no deserializer is registered, the contents are stored in cbor-tag.

  • Major type 7, additional data 20, 21, and 23 (false, true, and undefined) are decoded as #f, #t, and undefined, respectively

  • Major type 7, additional data 22 is decoded as the value of (cbor-config-null-value config)

  • Major type 7, additional data 25, 26, and 27 (half float, single float, and double float, respectively), are all decoded as Racket flonum?. Note that this library decodes all of these three types to Racket’s double-width floating point type.

  • Any other item with major type 7 and additional data matching cbor-unassigned-simple-value? is decoded as a cbor-simple-value

2 Configuration Options🔗ℹ

struct

(struct cbor-config (tag-deserializers null-value sorted-map-keys)
    #:extra-constructor-name make-cbor-config)
  tag-deserializers : (hash/c cbor-valid-tag-number? (-> cbor-valid-tag-number? any/c any/c))
  null-value : any/c
  sorted-map-keys : boolean?
Configuration object for CBOR encoding and decoding. Note that this struct is only exposed opaquely, and must be manipulated with the provided functions and values.

tag-deserializers is a hash from CBOR tag numbers to a procedure that takes the CBOR tag number and a raw data value and produces the meaningful interpretation of that value.

null-value is the value that CBOR null will be encoded and decoded as.

sorted-map-keys determines whether or not map keys should be serialized in sorted order. This only affects encoding; unsorted map keys will still be decoded identically.

Base configuration object, with no tag deserializers registered and null value set to 'null.

procedure

(with-cbor-tag-deserializer config    
  id    
  deserializer)  cbor-config?
  config : cbor-config?
  id : cbor-valid-tag-number?
  deserializer : (-> cbor-valid-tag-number? any/c any/c)
Registers a tag deserializer to the given config, returning a new config.

procedure

(with-cbor-null-value config v)  cbor-config?

  config : cbor-config?
  v : any/c
Registers a null value to the given config, returning a new config.

procedure

(with-sorted-map-keys config v)  cbor-config?

  config : cbor-config?
  v : boolean?
Set whether map keys should be serialized in sorted order.

A generic interface that supplies a method, cbor-write-proc that can serialize arbitrary values to CBOR. Implementations of the method should accept a value to be serialized and return it in serialized form as a cbor-tag?.

3 Auxiliary Items🔗ℹ

procedure

(cbor-valid-tag-number? v)  boolean?

  v : any/c
Equivalent to (integer-in 0 18446744073709551616).

procedure

(cbor-unassigned-simple-value? v)  boolean?

  v : any/c
Equivalent to (or/c (integer-in 0 19) (integer-in 32 255)).

struct

(struct cbor-tag (number content)
    #:extra-constructor-name make-cbor-tag)
  number : cbor-valid-tag-number?
  content : any/c
Raw representation of a CBOR tag with tag number number and tag content content. content must be serializable by cbor-write.

struct

(struct cbor-simple-value (inner)
    #:extra-constructor-name make-cbor-simple-value)
  inner : cbor-unassigned-simple-value?
Represents a CBOR Simple Value. Only simple values that have not been assigned a meaning via RFC can be represented as this struct. Simple Values with predefined meaning such as #f are always serialized and deserialized directly as their meaningful forms.

4 Bugs🔗ℹ

Patches to improve these issues are welcome! Email patches to ~williewillus/public-inbox (at) lists.sr.ht.
  • Some functions are currently too lax (indefinite-length objects can be nested in nonconforming ways).

  • There should be a config or parameter to specify maximum lengths for indefinite-length objects

  • More correctness-testing is needed.

  • Some recommended tag and simple values from the RFC are not supported yet.