Raku Land

CBOR::Simple

zef:japhb

Actions Status

NAME

CBOR::Simple - Simple codec for the CBOR serialization format

SYNOPSIS

use CBOR::Simple;

# Encode a Raku value to CBOR, or vice-versa
my $cbor = cbor-encode($value);
my $val1 = cbor-decode($cbor);               # Fails if more data past first decoded value
my $val2 = cbor-decode($cbor, my $pos = 0);  # Updates $pos after decoding first value

# By default, cbor-decode() marks partially corrupt parsed structures with
# Failure nodes at the point of corruption
my $bad  = cbor-decode(buf8.new(0x81 xx 3));  # [[[Failure]]]

# Callers can instead force throwing exceptions on any error
my $*CBOR_SIMPLE_FATAL_ERRORS = True;
my $bad  = cbor-decode(buf8.new(0x81 xx 3));  # BOOM!

# Decode CBOR into diagnostic text, used for checking encodings and complex structures
my $diag = cbor-diagnostic($cbor);

# Force the encoder to tag a value with a particular tag number
my $tagged = CBOR::Simple::Tagged.new(:$tag-number, :$value);
my $cbor   = cbor-encode($tagged);

DESCRIPTION

CBOR::Simple is an easy-to-use implementation of the core functionality of the CBOR serialization format, implementing the standard as of RFC 8949, plus a collection of common tag extensions as described below in TAG IMPLEMENTATION STATUS.

PERFORMANCE

CBOR::Simple is one of the fastest data structure serialization codecs available for Raku. It is comparable in round-trip speed to JSON::Fast for data structures that are the most JSON-friendly. For all other cases tested, CBOR::Simple produces smaller, higher fidelity encodings, faster. For more detail, and comparison with other Raku serialization codecs, see serializer-perf.

NYI

Currently known NOT to work:

TAG CONTENT STRICTNESS

When encoding, CBOR::Simple makes every attempt to encode tagged content strictly within the tag standards as written, always producing spec-compliant encoded values.

When decoding, CBOR::Simple will often slightly relax the allowed content types in tagged content, especially when later tag proposals made no change other than to extend the allowed content types and allocate a new tag number for that. In the extension case CBOR::Simple is likely to allow both the old and new tag to accept the same content domain when decoding.

For example, when encoding CBOR::Simple will always encode Instant or DateTime as a CBOR epoch-based date/time (tag 1), using standard integer or floating point content data. But when decoding, CBOR::Simple will accept any content that decodes properly as a Raku Real value -- and in particular will handle a CBOR Rational (tag 30) as another valid content type.

DATE, DATETIME, INSTANT

Raku's builtin time handling is richer than the default CBOR data model (though certain tag extensions improve this), so the following mappings apply:

UNDEFINED VALUES

OTHER SPECIAL CASES

TAG IMPLEMENTATION STATUS

Note that unrecognized tags will decode to their contents wrapped with a CBOR::Simple::Tagged object that records its tag-number; check marks in the details table indicate conversion to/from an appropriate native Raku type rather than this default behavior.

Tag Status Overview: Native Raku Types
GROUPSUPPORTNOTES
CoreGoodCore RFC 8949 CBOR data model and syntax
CollectionsGoodSets, maps with only object or only string keys
GraphNONECyclic, indirected, and self-referential structures
NumbersGoodRational/BigInt/BigFloat support except non-finite triplets
Packed ArraysPartialPacked num16/32/64 arrays supported; packed int arrays not
Special ArraysNONEExplicit multi-dim/homogenous arrays
Tag FallbacksGoodRound tripping of unknown tagged content
Date/TimePartialAll but tagged time (tags 1001-1003) supported
Tag Status Overview: Specialty Types
GROUPSUPPORTNOTES
EncodingsNONEbaseN, MIME, YANG, BER, non-UTF-8 strings
GeoNONEGeographic coordinates and shapes
IdentifiersNONEURI, IRI, UUID, IPLD CID, general identifiers
NetworkingNONEIPv4/IPv6 addresses, subnets, and masks
SecurityNONECOSE and CWT
SpecialtyNONEIoT data, Openswan, PlatformV, DOTS, ERIS, RAINS
String HintsNONEJSON conversions, language tags, regex
Tag Status Details
SPECTAGSENCODEDECODENOTES
RFC 89490DateTime strings → Encoded as tag 1
RFC 89491DateTime/Instant
RFC 89492,3(Big) Int
RFC 89494,5Big fractions → Encoded as tag 30
unassigned6-15
COSE16-18MAC/Signatures
unassigned19-20
RFC 894921-23Expected JSON conversion to baseN
RFC 894924TEncoded CBOR data item
[Lehmann]25String backrefs
[Lehmann]26,27General serialized objects
[Lehmann]28,29Shareable referenced values
[Occil]30Rational numbers
[Vaarala]31*Absent values
RFC 894932-34URIs and base64 encoding
RFC 709435DDPCRE/ECMA 262 regex (DEPRECATED)
RFC 894936Text-based MIME message
[Clemente]37Binary UUID
[Occil]38Language-tagged string
[Clemente]39Identifier semantics
RFC 874640Row-major multidim array
RFC 874641Homogenous array
[Mische]42IPLD content identifier
[YANG]43-47YANG datatypes
unassigned48-51
draft52DDIPv4 address/network (DEPRECATED)
unassigned53
draft54DDIPv6 address/network (DEPRECATED)
unassigned55-60
RFC 839261CBOR Web Token (CWT)
unassigned62
[Bormann]63TEncoded CBOR Sequence
RFC 874664-79✘!✘!Packed int arrays
RFC 874680-87Packed num arrays (except 128-bit)
unassigned88-95
COSE96-98Encryption/MAC/Signatures
unassigned99
RFC 8943100Date
unassigned101-102
[Vidovic]103Geo coords
[Clarke]104Geo coords ref system WKT/EPSG
unassigned105-109
RFC 9090110-112BER-encoded object ID
unassigned113-119
[Vidovic]120IoT data point
unassigned121-255
[Lehmann]256String backrefs (see tag 25)
[Occil]257Binary MIME message
[Napoli]258Set
[Holloway]259TMap with object keys
[Raju]260-261IPv4/IPv6/MAC address/network
[Raju]262-263Embedded JSON/hex strings
[Occil]264-265*Extended fractions -> Encoded as tag 30
[Occil]266-267IRI/IRI reference
[Occil]268-270✘✘✘✘Triplet non-finite numerics
RFC 9132271✘✘✘✘DDoS Open Threat Signaling (DOTS)
[Vaarala]272-274Non-UTF-8 strings
[Cormier]275TMap with only string keys
[ERIS]276ERIS binary read capability
[Meins]277-278Geo area shape/velocity
unassigned279-1000
[Bormann]1001-1003Extended time representations
RFC 89431004→ Encoded as tag 100
unassigned1005-1039
RFC 87461040Column-major multidim array
unassigned1041-22097
[Lehmann]22098Hint for additional indirection
unassigned22099-49999
[Tongzhou]50000-50011✘✘✘✘PlatformV
unassigned50012-55798
RFC 894955799Self-described CBOR
[Richardson]55800Self-described CBOR Sequence
unassigned55801-65534
invalid65535Invalid tag detected
unassigned65536-15309735
[Trammell]15309736✘✘✘✘RAINS message
unassigned15309737-1330664269
[Hussain]1330664270✘✘✘✘CBOR-encoded Openswan config file
unassigned1330664271-4294967294
invalid4294967295Invalid tag detected
unassigned...
invalid18446744073709551615Invalid tag detected
Tag Table Symbol Key
SYMBOLMEANING
Fully supported
*Supported, but see notes below
TEncoding supported by explicitly tagging contents
Raku values will be encoded using a different tag
DDeprecated and unsupported tag spec; may eventually be decodable
Not yet implemented
✘!Not yet implemented, but already requested
✘?Not yet implemented, but may be easy to add
✘✘Probably won't be implemented in CBOR::Simple

AUTHOR

Geoffrey Broadwell gjb@sonic.net

COPYRIGHT AND LICENSE

Copyright 2021 Geoffrey Broadwell

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.