|
4 weeks ago | |
---|---|---|
gsl | 4 weeks ago | |
src | 4 weeks ago | |
DOCS.md | 4 weeks ago | |
README.md | 1 month ago | |
mkfile | 1 month ago |
A module for reading and writing in Concise Binary Object Representation.
Object encoding works by calling a series of write
primitives which
in turn encode data and pass them down to a supplied writing backend.
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.
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.
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.
16-bit floats are not implemented. icedcbor
will interpret them as a
malformed object.
For use the module in your own project:
For developing the module:
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.
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.