-*- mode: org; coding: utf-8; -*-
#+PROPERTY: header-args:scheme :session *guile-cbor-repl* :eval never-export

#+TITLE: guile-cbor

guile-cbor is a Guile implementation of CBOR (Concise Binary Object Representation) as specified by [[https://www.rfc-editor.org/rfc/rfc8949.html][RFC8949]].

* Usage

The ~(cbor)~ module provides ~scm->cbor~ and ~cbor->scm~ that can be used to encode native Scheme values to CBOR and vice-versa:

#+BEGIN_SRC scheme
(use-modules (cbor)
             (rnrs bytevectors))

(scm->cbor 42)
#+END_SRC

#+RESULTS:
: #vu8(24 42)


#+BEGIN_SRC scheme
(cbor->scm
 (scm->cbor 42))
#+END_SRC

#+RESULTS:
: 42

A more complete example of all the things that can be encoded:

#+BEGIN_SRC scheme
(define cbor-encoded
  (scm->cbor
   (vector 1 2 3
           '((1 . "a") (2 . "b") (3 . 3.141))
           (string->utf8 "Hello CBOR!")
           (make-cbor-tag 32 "https://example.com")
           (vector 2.1 3.2 "Hi" #t #f))))

cbor-encoded
#+END_SRC

#+RESULTS:
: #vu8(135 1 2 3 163 1 97 97 2 97 98 3 251 64 9 32 196 155 165 227 84 75 72 101 108 108 111 32 67 66 79 82 33 216 32 115 104 116 116 112 115 58 47 47 101 120 97 109 112 108 101 46 99 111 109 133 251 64 0 204 204 204 204 204 205 251 64 9 153 153 153 153 153 154 98 72 105 245 244)

#+BEGIN_SRC scheme
(cbor->scm cbor-encoded)
#+END_SRC

#+RESULTS:
: #(1 2 3 ((1 . "a") (2 . "b") (3 . 3.141)) #vu8(72 101 108 108 111 32 67 66 79 82 33) #<<cbor-tag> number: 32 content: "https://example.com"> #(2.1 3.2 "Hi" #t #f))

~guile-cbor~ also provides procedures for directly reading and writing CBOR from and to ports. See the info documentation.

** Native Scheme Values <-> CBOR data items

| Native Scheme            | CBOR                                           | Note                                                                                                                                              |
|--------------------------+------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------|
| positive integer         | unsigned integer (major type 0)                |                                                                                                                                                   |
| negative integer         | negative integer (major type 0)                |                                                                                                                                                   |
| bytevector               | byte string (major type 2)                     |                                                                                                                                                   |
| string                   | text string (major type 3)                     |                                                                                                                                                   |
| vector                   | array (major type 4)                           | See also how [[https://github.com/aconchillo/guile-json#usage][guile-json]] maps arrays                                                                                                               |
| alist                    | map (major type 5)                             |                                                                                                                                                   |
| <cbor-tag>               | tagged data item (major type 6)                | A Scheme record is used for CBOR tags                                                                                                             |
| -                        | IEEE 754 Half-Precision Float (major type 7)   | Can not be parsed (FIXME)                                                                                                                         |
| real                     | IEEE 754 Double-Precision Float (major type 7) | Scheme reals are always encoded as CBOR double precision floats                                                                                   |
| real                     | IEEE 754 Single-Precision Float (major type 7) | CBOR single precision floats are parsed as Scheme real numbers                                                                                    |
| #f                       | false (major type 7, simple value 20)          |                                                                                                                                                   |
| #t                       | true (major type 7, simple value 21)           |                                                                                                                                                   |
| #nil                     | empty array (major type 4)                     | This should be encoded to null (major type 7, simple value 22) (FIXME)                                                                            |
| <cbor-indefinite-length> | Indefinite-Length Arrays and Maps              | A Scheme record is used to encode indefinite-length arrays and maps. Arrays or maps of indefinite length are decoded to simple vectors or alists. |

Note that IEEE 754 Half-Precision Floats can currently not be parsed as there is no native Guile support.

* Todos
** TODO Extended Generic Data Models

Currently not the full "extended generic data model" is supported (only simple values ~#f~, ~#t~ are supported).

It might be nice to support the full extended generic data model (bignums, decimal fractions, bigfloats and date/time tags).

** TODO IEEE 754 Half-Precision Floats

Currenlty there is no support for encoding or decoding IEEE 754 Half-precision floats. This is due to the fact that there is no support for half-precision floats in Guile.

** TODO null and undefined

Currentlly guile-cbor can not properly encode null and undefined.

** TODO Indefinite Length Byte Strings and Text Strings

Currently no support.

** TODO Indefinite Length Arrays and Maps with streaming support

Currently guile-cbor uses the ~<cbor-indefnite-length>~ record type to encode arrays/maps as indefinite length CBOR values. This does not enable encoding streams of CBOR values. It would be nice to have an interface to SRFI-158 generators.

* License

GPL-3.0-or-later see [[./COPYING]].