.. _library_cbor:

``cbor``
========

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

- https://www.rfc-editor.org/rfc/rfc8949.html
- http://cbor.io/

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
`../../apis/library_index.html#cbor <../../apis/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)).
