cbor

The cbor library implements predicates for importing and exporting data in the Concise Binary Object Representation (CBOR) format:

This library is a work-in-progress. Currently it requires a backend supporting unbounded integer arithmetic.

Representation

  • Maps are represented using curly-bracketed terms, {Pairs}, where each pair uses the representation Key-Value.

  • Arrays are represented using lists.

  • Byte strings uses bytes(List) compound terms.

  • Text strings can be represented as atoms, chars(List), or codes(List). The default when decoding is to use atoms when using the cbor object. To decode text strings into lists of chars or code, use the cbor/1 with the parameter bound to chars or codes. For example:

    | ?- cbor::parse([0x65,0x68,0x65,0x6c,0x6c,0x6f], Term).
Term = hello
yes

| ?- cbor(atom)::parse([0x65,0x68,0x65,0x6c,0x6c,0x6f], Term).
Term = hello
yes

| ?- cbor(chars)::parse([0x65,0x68,0x65,0x6c,0x6c,0x6f], Term).
Term = chars([h,e,l,l,o])
yes

| ?- cbor(codes)::parse([0x65,0x68,0x65,0x6c,0x6c,0x6f], Term).
Term = codes([104,101,108,108,111])
yes

  • Tagged data uses tag(Tag, Data) compound terms.

  • Simple values can be represented using simple(Simple) compound terms.

  • The CBOR elements false, true, null, and undefined are represented by, respectively, the @false, @true, @null, and @undefined compound terms.

  • The compound terms @infinity, @negative_infinity, and @not_a_number are used to represent the corresponding CBOR elements.

  • Only some backends distinguish between positive zero and negative zero. The compound terms @zero and @negative_zero can be used as an alternative for encoding. The decoder, however, produces the 0.0 and -0.0 floats.

Encoding

Encoding is accomplished using the generate/2 predicate. For example:

| ?- cbor::generate([a,{b-c}], Encoding).
Encoding = [0x9f,0x61,0x61,0xbf,0x61,0x62,0x61,0x63,0xff,0xff]
yes

The encoding of arrays and maps uses indefinite-length encoding. All floats are currently encoded using decimal fractions. Encoding indicators and big floats are not currently supported.

Decoding

Decoding is accomplished using the parse/2 predicate. For example:

| ?- cbor::parse([0x9f,0x61,0x61,0xbf,0x61,0x62,0x61,0x63,0xff,0xff], Term).
Term = [a,{b-c}]
yes

API documentation

Open the ../../docs/library_index.html#cbor link in a web browser.

Loading

To load all entities in this library, load the loader.lgt file:

| ?- logtalk_load(cbor(loader)).

Testing

To test this library predicates, load the tester.lgt file:

| ?- logtalk_load(cbor(tester)).