Iced Quinn’s Concise Binary Object Notator

A module for reading and writing in Concise Binary Object Representation.

Encoding

Object encoding works by calling a series of write primitives which in turn encode data and pass them down to a supplied writing backend.

Decoding

Object decoding works by reading over a stream of bytes and outputting events a la SAX. There are some complexities (ex. semantic tags, indefinite elements) which are parsed and returned as events but not handled inside the reader itself.

Safety

Encoding does not have any safety mechanisms. Whatever you pass in to a write function is encoded and passed to a writer which you also supply. It is assumed what you are outputting you have done any application specific checks on. Yes it is also possible to write outputs that are canonically invalid CBOR. Although maybe you want to do this on purpose.

Decoding has two safety checks:

• Ranges are checked to make sure no more bytes will be read than are available in the input buffer. Objects are read whole or not at all: if a part of an object is available then reading will return rrMoreData and the caller must deal with it (this is why icedband exists).

• A maximum object size may be passed when setting up the reader. Any text or binary strings which are larger than this amount will return an rrLengthViolation instead of being allocated.

The test suite is also generated from a set of objects defined by gsl/cases.xml, which is interpreted via src/cases.gsl to create the testing suite. Test objects are defined only once and both encoding and decoding testers are manufactured from it.

Encoding tests ensure that the objects are encoded without crashing. If valgrind is run it also ensures no memory corruption ocurred during the encoding proces.

Decoding tests first encode objects (same as the encoding test) but then immediately decode the objects and assert the same input is read via the SAX interface.

Efficiency

icedcbor is, regrettably, not a zero-copy decoder. It will read bytes from a buffer you supply but values are copied from this buffer to the event objects returned by the reader.

A zero-copy reader is possible but would have a more complicated implementation.

Not Implemented

16-bit floats are not implemented. icedcbor will interpret them as a malformed object.

Dependencies

For use the module in your own project:

• None!

For developing the module:

• iMatix GSL

Much of the code depends on a model of CBOR which is stored in gsl/model.xml. This model defines the overall types of items which might appear in a CBOR document and the sizes of headers which appear. That model is converted to Nim with the help of gsl/model.gsl which ultimately produces src/icedcbor.nim.

A mkfile is provided (usable via plan9port's mk) to deal with repo developer tasks like regenerating Nim code or running the test suite.

Testing uses TAP and the suite is typically run with Perl's prove. Any TAP compatible harness and reporter is sufficient.

License

• Mozilla Public License, version 2 (MPL-2.)

Short version: you may use the modules for non-commercial and commercial purposes but any changes in the code must be returned to the repository.