3 files changed, 83 insertions(+), 0 deletions(-)

M .gitignore
M info.rkt
A scribblings/manual.scrbl

@@ 1,1 1,3 @@
 compiled/
+coverage/
+doc/

@@ 5,3 5,4 @@
 (define build-deps '("racket-doc"
                      "rackunit-lib"
                      "scribble-lib"))
+(define scribblings '(("scribblings/manual.scrbl" ())))

@@ 0,0 1,80 @@
+#lang scribble/manual
+@(require (for-label racket))
+@(require (for-label racket/undefined))
+@(require (for-label "../main.rkt"))
+
+@title{Concise Binary Object Representation}
+
+@defmodule[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.
+
+@section{Usage}
+@defproc[(cbor-write [config cbor-config?]
+                     [v any/c]
+                     [out output-port?])
+         void?]{
+Writes the value @racket[v] to @racket[out].
+The following @racket[v] are accepted:
+@itemlist[
+@item{Integers between -2@superscript{64} and 2@superscript{64} - 1, inclusive}
+@item{@racket[#f] and @racket[#t]}
+@item{Values @racket[equal?] to the value of @racket[(cbor-config-null-value config)]}
+@item{@racket[undefined]}
+@item{@racket[flonum?]s}
+@item{@racket[bytes?] and @racket[string?]s}
+@item{Lists and vectors of any item accepted by @racket[cbor-write]}
+@item{Sequences of any item accepted by @racket[cbor-write]}
+@item{Hashes of items accepted by @racket[cbor-write] (both the key and value)}
+@item{Instances of @racket[cbor-tag]}
+@item{Instances of @racket[cbor-simple-value]}
+@item{TODO: Any value for which a tag serializer procedure is registered in @racket[config]}
+]
+}
+
+@defproc[(cbor-read [config cbor-config?]
+                    [in input-port?])
+         any/c]{
+Reads a binary-serialized CBOR value from @racket[in].
+Major types are decoded as follows:
+@itemlist[
+@item{Major type 0 (unsigned integer) and 1 (negative integer) are decoded as standard Racket integers}
+@item{Major type 2 (byte string) and 3 (string) are decoded as Racket @racket[bytes?] and @racket[string?], respectively}
+@item{Major type 4 (list) is decoded as a Racket @racket[list?] of the contained values}
+@item{Major type 5 (map) is decoded as a Racket @racket[hash-equal?] of the contained key-value pairs}
+@item{Major type 6 (tag) is decoded as a @racket[cbor-tag]. TODO detail custom deserializers}
+@item{Major type 7, additional data 20, 21, and 23 (false, true, and undefined) are decoded as @racket[#f], @racket[#t], and @racket[undefined], respectively}
+@item{Major type 7, additional data 22 is decoded as the value of @racket[(cbor-config-null-value config)]}
+@item{Major type 7, additional data 25, 26, and 27 (half float, single float, and double float, respectively), are all decoded as Racket @racket[flonum?]. Note that this library decodes all of these three types to Racket's double-width floating point type.}
+@item{Any other item with major type 7 and additional data matching @racket[cbor-unassigned-simple-value?] is decoded as a @racket[cbor-simple-value]}
+]
+}
+
+@section{Configuration Options}
+
+@section{Auxiliary Items}
+
+@defproc[(cbor-valid-tag-number? [v any/c])
+         boolean?]{
+Equivalent to @racket[(integer-in 0 18446744073709551616)].
+}
+
+@defproc[(cbor-unassigned-simple-value? [v any/c])
+         boolean?]{
+Equivalent to @racket[(or/c (integer-in 0 19) (integer-in 32 255))].
+}
+
+@defstruct[cbor-tag ([number cbor-valid-tag-number?] [content any/c])]{
+Raw representation of a CBOR tag with tag number @racket[number] and tag content
+@racket[content].
+}
+
+@defstruct[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 @racket[#f] are always serialized and deserialized directly as their meaningful forms.
+}
+
+@section{Notes}