#janet-bare

Binary Application Record Encoding library for Janet. Mostly conformant to draft-devault-bare-07.

#Usage

# bare/encode encodes a value, according to the provided type.
(bare/encode :uint 1024) # => @"\x80\x08"
(bare/encode [:list :uint] [1 2 3]) # => @"\x03\x01\x02\x03"

# Optionally, an existing buffer can be provided.
(bare/encode :uint 1024 @"a") # => @"a\x80\x08"

# The type specification uses a tuple-based format: the first element is the
# primitive type, and further arguments follow:
(bare/encode [:optional :uint] nil)
(bare/encode [:optional :uint] 42)
(bare/encode [:list 2 :uint] [10 20]) # 2 = length
(bare/encode [:data 2] @"ab") # 2 = length
(bare/encode [:map :str :uint] {"one" 1 "two" 2})
(bare/encode [:enum :ZERO :ONE [10 :TEN] :ELEVEN] :TEN)
(bare/encode [:struct [:a :uint] [:b :str]] {:a 1 :b "a"})

# Union values are specified with explicit tags to disambiguate.
(bare/encode [:union :uint :str] {::tag 0 ::value 1})
(bare/encode [:union :uint :str] {::tag 1 ::value "a"})

# Similarly, bare/decode parses a BARE message and returns an equivalent Janet
# representation.
(bare/decode :uint @"\x80\x08")
(bare/decode [:optional :uint] @"\x00")
(bare/decode [:optional :uint] @"\x01\x2a")
(bare/decode [:list :uint] @"\x03\x01\x02\x03")
(bare/decode [:list 2 :uint] @"\x01\x02")
(bare/decode [:data 2] @"ab")
(bare/decode [:map :str :uint] @"\x02\x03one\x01\x03two\x02")
(bare/decode [:enum :ZERO :ONE [10 :TEN] :ELEVEN] "\x0a")
(bare/decode [:struct [:a :uint] [:b :str]] @"\x01\x01a")
(bare/decode [:union :uint :str] @"\x00\x01")
(bare/decode [:union :uint :str] @"\x01\x01a")

# bare/decode* returns a tuple [value consumed], indicating how many bytes of
# the buffer were consumed. Given that BARE messages are self-delimiting, a
# buffer could contain more than just the message.
(bare/decode* :uint @"\x0a\x14\x1e") # => [10 1]

# bare/compile-schema parses a BARE schema document and returns a registry of
# parsed types. Named references are preserved, so that types with particular
# given names are distinguished when decoded as structs or parts of unions.
(def schema
  (bare/compile-schema
    ``
    type A uint
    type B str
    type C struct { x: uint y: str }
    type Union union {A | B | C}
    ``))
(bare/encode (schema "A") 42)
(bare/encode (schema "B") "hello")
(bare/encode (schema "C") {:x 42 :y "hello"})
# If an explicit tag value is not provided, the tag can also be resolved by
# using the type name.
(bare/encode (schema "Union") {::type "A" ::value 42})
(bare/encode (schema "Union") {::type "B" ::value "hello"})
# For structs, the table/struct value can contain both the type annotation along
# with the struct keyvalue entries.
(bare/encode (schema "Union") {::type "C" :x 42 :y "hello"})

#Contributing

Thank you for your interest! For questions, please contact the author. For patches, email them to the author directly, or to ~paulsnar/misc@lists.sr.ht.

For announcements, subscribe to ~paulsnar/announce@lists.sr.ht.

#License

0BSD