summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorpukkamustard <pukkamustard@posteo.net>2021-02-28 15:05:41 +0100
committerpukkamustard <pukkamustard@posteo.net>2021-02-28 15:05:41 +0100
commite669f5083d051cb2d19d033a01b493fdd6c53fa6 (patch)
treebd2851d158450f7e66edd6f693dfd04df70707fb
parent52a3dd0989c3b9c965d327696f14e2accf5cf7cb (diff)
info: initial info doc
-rw-r--r--README.org42
-rw-r--r--cbor.scm9
-rw-r--r--doc/cbor.texi76
3 files changed, 114 insertions, 13 deletions
diff --git a/README.org b/README.org
index 3395d15..986394d 100644
--- a/README.org
+++ b/README.org
@@ -5,6 +5,40 @@
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))
+
+(scm->cbor 42)
+#+END_SRC
+
+#+RESULTS:
+: #vu8(24 42)
+
+
+#+BEGIN_SRC scheme
+(use-modules (cbor))
+
+(cbor->scm
+ (scm->cbor 42))
+#+END_SRC
+
+#+RESULTS:
+: 42
+
+#+BEGIN_SRC scheme
+(use-modules (cbor))
+
+(scm->cbor (vector 1 2 3 4))
+#+END_SRC
+
+#+RESULTS:
+: #vu8(132 1 2 3 4)
+
+See also the Info documentation.
+
** Native Scheme Values <-> CBOR data items
| Native Scheme | CBOR | Note |
@@ -33,6 +67,10 @@ Currently not the full "extended generic data model" is supported (only simple v
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.
@@ -41,7 +79,9 @@ Currentlly guile-cbor can not properly encode null and undefined.
Currently no support.
-** TODO texinfo documentation
+** 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
diff --git a/cbor.scm b/cbor.scm
index 5faa619..ff6331b 100644
--- a/cbor.scm
+++ b/cbor.scm
@@ -106,7 +106,8 @@
(put-cbor-initial-byte port 7 31))))
(define (put-cbor-data-item port value)
- "Write CBOR encoding of @var{value} to @var{port}, a binary output port."
+ "Write CBOR encoding of @var{value} to @var{port}"
+
(cond
;; unsigned integer
@@ -164,8 +165,8 @@
;; Decoding
(define (get-uint-network-order port n)
- "Read a unsigned integer of size @code{n} in network order (big endian) from
-@code{port}"
+ "Read a unsigned integer of size @var{n} in network order (big endian) from
+@var{port}"
(bytevector-uint-ref (get-bytevector-n port n)
0 (endianness big) n))
@@ -194,7 +195,7 @@
(else 'not-well-formed)))
(define (get-cbor-data-item port)
- "Read a single CBOR data item from @code{port}"
+ "Read a single CBOR data item from @var{port}"
(let* ((initial-byte (get-u8 port))
;; major type is in the higher-order 3 bits
(major-type (bit-extract initial-byte 5 8))
diff --git a/doc/cbor.texi b/doc/cbor.texi
index 01b1c06..c31a4aa 100644
--- a/doc/cbor.texi
+++ b/doc/cbor.texi
@@ -5,7 +5,7 @@
@c %**start of header
@setfilename guile-cbor.info
@documentencoding UTF-8
-@settitle Guile Cbor Reference Manual
+@settitle guile-cbor Reference Manual
@c %**end of header
@include version.texi
@@ -23,11 +23,11 @@ Documentation License''.
@dircategory The Algorithmic Language Scheme
@direntry
-* Guile Cbor: (guile-cbor).
+* guile-cbor: (guile-cbor).
@end direntry
@titlepage
-@title The Guile Cbor Manual
+@title Guile implementation of the CBOR data format.
@author pukkamustard
@page
@@ -42,20 +42,80 @@ Edition @value{EDITION} @*
@c *********************************************************************
@node Top
-@top Guile Cbor
+@top guile-cbor
-This document describes Guile Cbor version @value{VERSION}.
+This document describes guile-cbor version @value{VERSION}.
@menu
-* Introduction:: Why Guile Cbor?
+* Introduction:: Why CBOR?
+* Encoding and Decoding:: Scheme values to CBOR and back.
@end menu
@c *********************************************************************
@node Introduction
@chapter Introduction
-INTRODUCTION HERE
+The Concise Binary Object Representation (CBOR) as specified by @url{https://www.rfc-editor.org/rfc/rfc8949.html, RFC 8949}, is a binary data format similar to JSON. CBOR is optimized for small code size of, small message size and extensibility.
-This documentation is a stub.
+@code{guile-cbor} is an implementation of CBOR for Guile Scheme that allows encoding and decoding of Scheme values to CBOR and vice-versa.
+
+There are still some pieces missing in order for @code{guile-cbor} to be able to encode all CBOR values (most notably IEEE 754 Half-precission Floats). Contributions, help and bug reports are very welcome! Please email @email{pukkamustard@@posteo.net}.
+
+@node Encoding and Decoding
+@chapter Encoding and Decoding
+
+The @code{(cbor)} module exports procedures for encoding and decoding CBOR.
+
+@deffn {Scheme Procedure} scm->cbor @var{value}
+Returns the CBOR encoding of the Scheme value @var{value} as bytevector.
+@end deffn
+
+@deffn {Scheme Procedure} cbor->scm @var{port-or-bv}
+Returns the Scheme value of CBOR that is read from the port or bytevector @var{port-or-bv}.
+@end deffn
+
+@section Value mapping
+
+TODO the table from the README that describes how Scheme values map to CBOR data items.
+
+@section CBOR tags
+
+In CBOR a data item can be enclosed with a tag to give some additional information. IANA maintains a registry of tags.
+
+In @code{guile-cbor} the @code{<cbor-tag>} record type is used to encode/decode tagged CBOR data items.
+
+@deffn {Scheme Procedure} make-cbor-tag @var{number} @var{content}
+Returns a new CBOR tag with tag number @var{number} and content @var{content}
+@end deffn
+
+@deffn {Scheme Procedure} cbor-tag? @var{obj}
+Returns true if @var{obj} is a @code{<cbor-tag>}.
+@end deffn
+
+@deffn {Scheme Procedure} cbor-tag-number @var{tag}
+Returns the tag number of @var{tag}.
+@end deffn
+
+@deffn {Scheme Procedure} cbor-tag-content @var{tag}
+Returns the content of @var{tag}.
+@end deffn
+
+@section Indefinite length arrays and maps
+
+CBOR supports encoding of indefinite length arrays and maps. This is useful for applications that stream content.
+
+@code{guile-cbor} provides the @code{<cbor-indefinite-length>} record type to encode values as indefinte length arrays or maps. This is however not useful for streaming applications. In the future it would be nice to have an interface that allows encoding of values from an SRFI-158 generator or similar.
+
+TODO document @code{make-cbor-indefinite-length}.
+
+@section Ports
+
+@deffn {Scheme Procedure} put-cbor-data-item @var{port} @var{value}
+Write CBOR encoding of @var{value} to @var{port}.
+@end deffn
+
+@deffn {Scheme Procedure} get-cbor-data-item @var{port}
+Read a single CBOR data item from @var{port}.
+@end deffn
@bye