crystal-cbor v1.0.0
Crystal CBOR
This library implements the RFC7049: Concise Binary Object Representation (CBOR) in Crystal.
Features
- Full RFC 7049
- Tested against all examples in the RFC 7049
- Simple and powerful API inspired by the standard library JSON
- Full support for diagnostic notation
- Support for a wide range of IANA CBOR Tags
- Support custom CBOR Tags
Example
require "cbor"
class Location
include CBOR::Serializable
@[CBOR::Field(key: "lat")]
property latitude : Float64
@[CBOR::Field(key: "lng")]
property longitude : Float64
end
class House
include CBOR::Serializable
property address : String
property location : Location?
end
data = {
"address" => "Crystal Road 1234",
"location" => { "lat" => 12.3, "lng" => 34.5 }
}
cbor = data.to_cbor # => Bytes[...]
CBOR::Diagnostic.to_s(cbor) # => {"address": "Crystal Road 1234", "location": {"lat": 12.3, "lng": 34.5}}
house = House.from_cbor(cbor)
house.address # => "Crystal Road 1234"
house.location # => #<Location:0x10cd93d80 @latitude=12.3, @longitude=34.5>
bytes = house.to_cbor # => Bytes[...]
CBOR::Diagnostic.to_s(bytes) # => {"address": "Crystal Road 1234", "location": {"lat": 12.3, "lng": 34.5}}
data_array = [data]
cbor_array = data_array.to_cbor # => Bytes[...]
CBOR::Diagnostic.to_s(cbor) # => [{"address": "Crystal Road 1234", "location": {"lat": 12.3, "lng": 34.5}}]}
houses = Array(House).from_cbor(cbor_array)
houses.size # => 1
bytes = houses.to_cbor # => Bytes[...]
CBOR::Diagnostic.to_s(bytes) # => [{"address": "Crystal Road 1234", "location": {"lat": 12.3, "lng": 34.5}}]
Installation
-
Add the dependency to your
shard.yml
:dependencies: cbor: git: https://git.sr.ht/~arestifo/crystal-cbor
-
Run
shards install
Usage
Including CBOR::Serializable
will create #to_cbor
and self.from_cbor
methods on the current class, and a constructor which takes a CBOR::Decoder
.
By default, these methods serialize into a cbor map containing the value of every instance variable, the keys being the instance variable name.
Most primitives and collections are supported as instance variable values (string, integer, array, hash, etc.), along with objects which define to_cbor and a constructor taking a CBOR::Decoder
.
Union types are also supported, including unions with nil
. If multiple types in a union parse correctly, it is undefined which one will be chosen.
To change how individual instance variables are parsed and serialized, the annotation CBOR::Field
can be placed on the instance variable. Annotating property, getter and setter macros is also allowed.
require "cbor"
class A
include CBOR::Serializable
@[CBOR::Field(key: "my_key")]
getter a : Int32?
end
CBOR::Field
properties
- ignore: if
true
skip this field in serialization and deserialization (by defaultfalse
) - key: the value of the key in the json object (by default the name of the instance variable)
- converter: specify an alternate type for parsing and generation. The converter must define
from_cbor(CBOR::Decoder)
andto_cbor(value, CBOR::Builder)
as class methods. Examples of converters areTime::Format::RFC_333
andTime::EpochConverter
forTime
. - presence: if
true
, a@{{key}}_present
instance variable will be generated when the key was present (even if it has anull
value),false
by default - emit_null: if
true
, emits anull
value for nilable property (by default nulls are not emitted) - nil_as_undefined: if
true
, when the value isnil
, it is emitted asundefined
(by defaultnil
are encoded asnull
)
Deserialization also respects default values of variables:
require "cbor"
struct A
include CBOR::Serializable
@a : Int32
@b : Float64 = 1.0
end
A.from_cbor({"a" => 1}.to_cbor) # => A(@a=1, @b=1.0)
Extensions: CBOR::Serializable::Unmapped
If the CBOR::Serializable::Unmapped
module is included, unknown properties in the CBOR document will be stored in a Hash(String, CBOR::Type)
.
On serialization, any keys inside cbor_unmapped
will be serialized and appended to the current cbor map.
require "cbor"
struct A
include CBOR::Serializable
include CBOR::Serializable::Unmapped
@a : Int32
end
a = A.from_cbor({"a" => 1, "b" => 2}.to_cbor) # => A(@cbor_unmapped={"b" => 2}, @a=1)
bytes = a.to_cbor # => Bytes[...]
CBOR::Diagnostic.to_s(bytes) # => {"a": 1, "b": 2}
Class annotation CBOR::Serializable::Options
supported properties:
- emit_nulls: if
true
, emits anull
value for all nilable properties (by default nulls are not emitted) - nil_as_undefined: if
true
, emits anil
value as undefined (by default nil emitsnull
)
require "cbor"
@[CBOR::Serializable::Options(emit_nulls: true)]
class A
include CBOR::Serializable
@a : Int32?
end
Supported tags
All the tags specified in section 2.4 of RFC 7049 are supported and the values are encoded in the respective Crystal types:
Time
BigInt
BigDecimal
Limitations
Maximum Array/String array/Bytes array length
The spec allows for the maximum length of arrays, string arrays and bytes array to be a UInt64
.
While this library supports lengths expressed as a UInt64
, it must not exceed Int32::MAX
.
Community
If you're stuck and need help, if you have any questions, or if you simply want to stay up to date with the latest news and developments, you can subscribe to the crystal-cbor mailing list.
If you found an issue, you can open an issue on the ticket tracker.
Contributing
The code is hosted on SourceHut and the development happens over the crystal-cbor mailing list.
-
For issues and feature requests, you can open and issue in the ticket tracker.
-
For code contributions You can send a patch to: ~arestifo/crystal-cbor@lists.sr.ht.
To learn how to use git send-email
, there is a great step-by-step tutorial at git-send-email.io. You might also want to read the mailing list etiquette.
crystal-cbor
- 8
- 2
- 0
- 1
- 0
- over 1 year ago
- June 1, 2020
MIT License
Fri, 22 Nov 2024 12:12:41 GMT