Docs / Packages / cbor

cbor

Kindffi-zig
Categoriesparser data-format encoding
Keywordscbor binary serialization data-format rfc8949

CBOR (Concise Binary Object Representation) encoding and decoding for Kit

Files

FileDescription
kit.tomlPackage manifest with metadata and dependencies
src/cbor.kitCBOR encoding, decoding, and JSON interoperability
src/cddl.kitCDDL schema parsing and validation (RFC 8610)
zig/cbor.zigZig FFI for CBOR encode/decode operations
zig/cddl_parser.zigZig FFI for CDDL token parsing
tests/test-cbor.kitTests for encoding, decoding, and round-trips
tests/test-cddl-debug.kitDebug script for CDDL parsing
tests/test-cddl.kitTests for CDDL schema validation
examples/basic.kitEncode values and use Show/BinaryEncode traits
examples/cddl-validation.kitValidate CBOR data against CDDL schemas
LICENSEMIT license file

Dependencies

No Kit package dependencies.

Installation

kit add gitlab.com/kit-lang/packages/kit-cbor.git

Usage

import Kit.Cbor

License

MIT License - see LICENSE for details.

Exported Functions & Types

parse-schema

Parses a CDDL schema string into a CDDLSchema.

Parameters:

Returns:

String -> Result CDDLSchema CDDLParseError

match CDDL.parse-schema "person = { name: tstr, age: uint }"
  | Ok schema -> println "Parsed successfully"
  | Err e -> println (show e)

validate

Validates a CBOR value against a CDDL schema.

Parameters:

Returns: 

match CDDL.validate schema value
  | Ok no-op -> println "Valid!"
  | Err e -> println (show e)

validate-as

Validates a CBOR value against a specific named type in the schema.

Parameters:

Returns: 

match CDDL.validate-as schema "address" addr-value
  | Ok no-op -> println "Valid address!"
  | Err e -> println (show e)

is-valid?

Checks if a CBOR value is valid against a schema.

Parameters:

Returns: 

if CDDL.is-valid? schema value then
  println "Valid!"
else
  println "Invalid!"

empty-schema

Creates an empty CDDL schema.

single-rule

Creates a schema with a single rule.

add-rule

Adds a rule to a schema.

set-root

Sets the root type of a schema.

find-rule

Looks up a rule by name.

prim

Creates a primitive type.

lit-int

Creates a literal integer type.

lit-str

Creates a literal string type.

lit-bool

Creates a literal bool type.

arr

Creates an array type with default occurrence.

arr-plus

Creates an array type with one-or-more occurrence.

arr-occ

Creates an array type with specific occurrence.

map-type

Creates a map type.

member

Creates a map member.

optional-member

Creates an optional map member.

choice

Creates a choice type.

ref

Creates a type reference.

range

Creates a range type.

tagged

Creates a tagged type.

CBORValue

CBOR value types for typed access.

Variants

CBORInt {Int}
Integer value (positive or negative)
CBORBytes {_0}
Byte string (list of bytes 0-255)
CBORString {String}
UTF-8 text string
CBORArray {_0}
Array of CBOR values
CBORMap {_0}
Map with any CBOR keys and values
CBORTag {Int, CBORValue}
Tagged value with tag number and content
CBORBool {Bool}
Boolean value (true/false)
CBORNull
Null value
CBORUndefined
Undefined value (CBOR-specific, not in JSON)
CBORFloat {Float}
Floating-point value

CBORDecodeError

CBOR decode error type.

match CBOR.decode bytes
  | Ok value -> process value
  | Err (CBORDecodeError { message }) ->
      println "Decode error: ${message}"

Variants

CBORDecodeError {message}

CBOR

Marker type for the CBOR format. Used with BinaryEncode/BinaryDecode traits to distinguish CBOR serialization.

Variants

CBOR

Result of decoding a single CBOR value at an offset.

CBOR header information for peeking.

encode-canonical

Encodes a CBORValue using canonical (deterministic) encoding.

CBORValue -> [Int]

encode-minimal

Encodes a CBORValue using minimal encoding (smallest size).

CBORValue -> [Int]

encode-int

Directly encode an integer to CBOR bytes.

Int -> [Int]

encode-string

Directly encode a string to CBOR bytes.

String -> [Int]

encode-bytes

Directly encode bytes to CBOR bytes.

[Int] -> [Int]

encode-bool

Directly encode a boolean to CBOR bytes.

Bool -> [Int]

encode-null

Directly encode null to CBOR bytes.

Unit -> [Int]

encode-float

Directly encode a float to CBOR bytes (double precision).

Float -> [Int]

encode-float-minimal

Directly encode a float using minimal precision.

Float -> [Int]

is-int?

Checks if value is an integer.

CBORValue -> Bool

is-bytes?

Checks if value is a byte string.

CBORValue -> Bool

is-string?

Checks if value is a text string.

CBORValue -> Bool

is-array?

Checks if value is an array.

CBORValue -> Bool

is-map?

Checks if value is a map.

CBORValue -> Bool

is-tagged?

Checks if value is a tagged value.

CBORValue -> Bool

is-bool?

Checks if value is a boolean.

CBORValue -> Bool

is-null?

Checks if value is null.

CBORValue -> Bool

is-undefined?

Checks if value is undefined.

CBORValue -> Bool

is-float?

Checks if value is a float.

CBORValue -> Bool

int

Creates an integer value.

Int -> CBORValue

bytes

Creates a byte string value.

[Int] -> CBORValue

string

Creates a text string value.

String -> CBORValue

array

Creates an array value.

[CBORValue] -> CBORValue

map

Creates a map value.

[(CBORValue, CBORValue)] -> CBORValue

tag

Creates a tagged value.

Int -> CBORValue -> CBORValue

bool

Creates a boolean value.

Bool -> CBORValue

null

Creates a null value.

CBORValue

undefined

Creates an undefined value.

CBORValue

float

Creates a float value.

Float -> CBORValue

get

Gets a value from a CBOR map by string key.

Parameters:

Returns:

CBORValue -> String -> Option CBORValue

match CBOR.get value "name"
  | Some val -> println "Found"
  | None -> println "Not found"

get-string

Gets a string value from a CBOR map.

Parameters:

Returns:

CBORValue -> String -> Option String

get-int

Gets an integer value from a CBOR map.

Parameters:

Returns:

CBORValue -> String -> Option Int

get-float

Gets a float value from a CBOR map.

Parameters:

Returns:

CBORValue -> String -> Option Float

get-bool

Gets a boolean value from a CBOR map.

Parameters:

Returns:

CBORValue -> String -> Option Bool

get-bytes

Gets a bytes value from a CBOR map.

Parameters:

Returns:

CBORValue -> String -> Option [Int]

get-array

Gets an array value from a CBOR map.

Parameters:

Returns:

CBORValue -> String -> Option [CBORValue]

get-map

Gets a map value from a CBOR map.

Parameters:

Returns:

CBORValue -> String -> Option [(CBORValue, CBORValue)]

at

Gets an element from a CBOR array by index.

Parameters:

Returns:

CBORValue -> Int -> Option CBORValue

unwrap-tag

Unwraps a tagged value, returning the inner value.

Parameters:

Returns:

CBORValue -> CBORValue

get-tag

Gets the tag number from a tagged value.

Parameters:

Returns:

CBORValue -> Option Int

tag-datetime-string

Standard date/time string (tag 0)

Int

tag-epoch-datetime

Epoch-based date/time (tag 1)

Int

tag-unsigned-bignum

Unsigned bignum (tag 2)

Int

tag-negative-bignum

Negative bignum (tag 3)

Int

tag-decimal-fraction

Decimal fraction (tag 4)

Int

tag-bigfloat

Bigfloat (tag 5)

Int

tag-base64url

Base64url encoding (tag 21)

Int

tag-base64

Base64 encoding (tag 22)

Int

tag-base16

Base16 (hex) encoding (tag 23)

Int

tag-encoded-cbor

Encoded CBOR data item (tag 24)

Int

tag-uri

URI (tag 32)

Int

tag-base64url-no-pad

Base64url without padding (tag 33)

Int

tag-base64-encoding

Base64 (tag 34)

Int

tag-regexp

Regular expression (tag 35)

Int

tag-mime

MIME message (tag 36)

Int

tag-self-described

Self-described CBOR (tag 55799)

Int

from-json

Converts a JSONValue to a CBORValue.

Parameters:

Returns:

Conversion rules: - JSONNull -> CBORNull - JSONBool b -> CBORBool b - JSONInt n -> CBORInt n - JSONFloat f -> CBORFloat f - JSONString s -> CBORString s - JSONArray items -> CBORArray (with converted items) - JSONObject pairs -> CBORMap (with string keys converted to CBORString)

JSONValue -> CBORValue

json = JSONObject [("name", JSONString "Kit"), ("version", JSONInt 1)]
cbor = CBOR.from-json json
# => CBORMap [(CBORString "name", CBORString "Kit"), (CBORString "version", CBORInt 1)]

to-json

Converts a CBORValue to a JSONValue.

Parameters:

Returns:

Conversion rules: - CBORNull -> JSONNull - CBORUndefined -> JSONNull (no JSON equivalent) - CBORBool b -> JSONBool b - CBORInt n -> JSONInt n - CBORFloat f -> JSONFloat f - CBORString s -> JSONString s - CBORBytes bytes -> JSONArray (bytes as integers) - CBORArray items -> JSONArray (with converted items) - CBORMap pairs -> JSONObject (keys converted to strings) - CBORTag _ value -> converts inner value (tag is stripped)

Note: CBOR has richer types than JSON, so some information may be lost: - CBORUndefined becomes JSONNull - CBORBytes become an array of integers - CBORTag information is discarded - Non-string map keys are converted to their string representation

CBORValue -> JSONValue

cbor = CBORMap [(CBORString "name", CBORString "Kit")]
json = CBOR.to-json cbor
# => JSONObject [("name", JSONString "Kit")]

datetime-to-cbor

Converts a DateTime to a CBOR tagged value.

Uses tag 1 (epoch-based date/time) with the Unix timestamp.

Parameters:

Returns:

DateTime -> CBORValue

dt = DateTime.now ()
cbor = CBOR.datetime-to-cbor dt
# => CBORTag 1 (CBORInt timestamp)

cbor-to-datetime

Converts a CBOR tagged datetime value back to a DateTime.

Supports: - Tag 0: Standard date/time string (RFC 3339) - parses the string - Tag 1: Epoch-based date/time (integer or float timestamp)

Parameters:

Returns:

CBORValue -> Option DateTime

cbor = CBORTag 1 (CBORInt 1700000000)
match CBOR.cbor-to-datetime cbor
  | Some dt -> println (DateTime.format dt "%Y-%m-%d")
  | None -> println "Invalid datetime"

uri-to-cbor

Converts a URI string to a CBOR tagged value.

Uses tag 32 (URI) per RFC 8949.

Parameters:

Returns:

String -> CBORValue

cbor = CBOR.uri-to-cbor "https://example.com"
# => CBORTag 32 (CBORString "https://example.com")

cbor-to-uri

Extracts a URI string from a CBOR tagged URI value.

Parameters:

Returns:

CBORValue -> Option String

cbor = CBORTag 32 (CBORString "https://example.com")
match CBOR.cbor-to-uri cbor
  | Some uri -> println uri
  | None -> println "Not a URI"

bigint-to-cbor

Converts a BigInt to a CBOR tagged value.

BigInt -> CBORValue

cbor-to-bigint

Converts a CBOR bignum (tag 2 or 3) back to a BigInt.

CBORValue -> Option BigInt