| Safe Haskell | Safe-Inferred |
|---|---|
| Language | GHC2021 |
Plutus.Codec.CBOR.Encoding
Description
An on-chain implementation of RFC 8949: Concise Binary Object Representation (CBOR).
This is generally something one would want to avoid as the memory and CPU budgets on-chain are heavily limited. However, there are scenarios when one needs to serialise some higher level data-type into binary. This library provides an efficient way of doing it.
How to use
Let's start with some relatively simple type:
data Foo = Foo
{ bar :: Bool
, baz :: Integer
}
From there, one can define an Encoding for the Foo data-type. This is a
simple record of unary constructors, so using a 2-tuple should do. Note that
Encoding is a Semigroup, and thus, they are easily composed using the
concatenation operator (<>).
encodeFoo :: Foo -> Encoding
encodeFoo Foo{bar,baz} =
encodeListLen 2
<> encodeBool bar
<> encodeInteger baz
Then, any Encoding can be turned into a BuiltinByteString using: encodingToBuiltinByteString.
For instance, one could define:
serialiseFoo :: Foo -> BuiltinByteString serialiseFoo = encodingToBuiltinByteString . encodeFoo
Synopsis
- data Encoding
- encodingToBuiltinByteString :: Encoding -> BuiltinByteString
- encodeBool :: Bool -> Encoding
- encodeInteger :: Integer -> Encoding
- encodeByteString :: BuiltinByteString -> Encoding
- encodeString :: BuiltinString -> Encoding
- encodeNull :: Encoding
- encodeMaybe :: (a -> Encoding) -> Maybe a -> Encoding
- encodeListLen :: Integer -> Encoding
- encodeList :: (a -> Encoding) -> [a] -> Encoding
- encodeMapLen :: Integer -> Encoding
- encodeMap :: (k -> Encoding) -> (v -> Encoding) -> Map k v -> Encoding
- encodeBreak :: Encoding
- encodeBeginList :: Encoding
- encodeListIndef :: (a -> Encoding) -> [a] -> Encoding
- encodeBeginMap :: Encoding
- encodeMapIndef :: (k -> Encoding) -> (v -> Encoding) -> Map k v -> Encoding
- encodeTag :: Integer -> Encoding
- unsafeEncodeRaw :: BuiltinByteString -> Encoding
Encoding
An opaque Encoding type. See also encodingToBuiltinByteString.
encodingToBuiltinByteString :: Encoding -> BuiltinByteString Source #
Runs an encoder and produce a BuiltinByteString.
Basic Types
encodeInteger :: Integer -> Encoding Source #
encodeByteString :: BuiltinByteString -> Encoding Source #
Encode a BuiltinByteString as a CBOR type-02 major type.
encodeString :: BuiltinString -> Encoding Source #
Encode a BuiltinString as a CBOR type-03 major type.
encodeNull :: Encoding Source #
Encode a null character, useful to encode optional values.
Data-Structures
Finite Structures
encodeMaybe :: (a -> Encoding) -> Maybe a -> Encoding Source #
Helper for optionally encoding a type. Note that in the Nothing case,
this is a no-op.
encodeListLen :: Integer -> Encoding Source #
Declare a list of fixed size. Each element of the list must then be
separately provided via appending them (Encoding is a Semigroup).
This is useful to construct non-uniform arrays where elements may have
different types. For uniform list, see encodeList.
-- Encoding (14, 42) as a finite list... encodeListLen 2 <> encodeInteger 14 <> encodeInteger 42
encodeList :: (a -> Encoding) -> [a] -> Encoding Source #
Shorthand for encoding a uniform list. Note that CBOR supports non-uniform
lists (i.e. n-tuples) for which one should use encodeListLen or
encodeBeginList / encodeBreak.
encodeMapLen :: Integer -> Encoding Source #
Declare a map of fixed size. Each key/value pair of the map must then
be separately provided via appending them (Encoding is a Semigroup).
This is useful to construct non-uniform maps where keys and values may have
different types. For uniform maps, see encodeMap.
-- Encoding { 14: b'1abc', 42: b'0000' } as a finite map...
encodeMapLen 2
<> encodeInteger 14 <> encodeByteString "1abc"
<> encodeInteger 42 <> encodeByteString "0000"
encodeMap :: (k -> Encoding) -> (v -> Encoding) -> Map k v -> Encoding Source #
Shorthand for encoding a uniform map of fixed size.
see also: encodeMapLen / encodeBreak for non-uniform maps.
Indefinite Structures
encodeBreak :: Encoding Source #
Encode a indefinite list or map termination. This must come (not
necessarily immediately) after an encodeListIndef or encodeMapIndef
encodeBeginList :: Encoding Source #
Declare a list of indefinite size. Each element of the list must then be
separately provided via appending them (Encoding is a Semigroup).
This is useful to construct non-uniform arrays where elements may have
different types. For uniform list, see encodeListIndef.
-- Encoding (14, 42) as an indefinite list... encodeBeginList <> encodeInteger 14 <> encodeInteger 42 <> encodeBreak
encodeListIndef :: (a -> Encoding) -> [a] -> Encoding Source #
Shorthand for encoding uniform list of indefinite sizes. Note that CBOR
supports non-uniform indefinite list (i.e. n-tuples) for which one should use
encodeListLen or encodeBeginList / encodeBreak.
encodeBeginMap :: Encoding Source #
Declare a map of indefinite size. Each key/value pair of the map must then
be separately provided via appending them (Encoding is a Semigroup).
This is useful to construct non-uniform maps where keys and values may have
different types. For uniform maps, see encodeMap.
-- Encoding { 14: b'1abc', 42: b'0000' } as a finite map...
encodeBeginMap
<> encodeInteger 14 <> encodeByteString "1abc"
<> encodeInteger 42 <> encodeByteString "0000"
<> encodeBreak
encodeMapIndef :: (k -> Encoding) -> (v -> Encoding) -> Map k v -> Encoding Source #
Shorthand for encoding a uniform map of indefinite size.
see also: encodeBeginMap / encodeBreak for non-uniform maps.
Tags
encodeTag :: Integer -> Encoding Source #
Encode a CBOR-tag as a major type-06.
Well known tags:
| Tag | Description | Type |
| 0 | Standard date/time string | text string |
| 1 | Epoch-based date/time | number |
| 2 | Positive bignum | byte string |
| 3 | Negative bignum | byte string |
| 4 | Decimal fraction | array |
| 24 | Encoded CBOR data item | byte string |
For more tags, have a look at iana's Concise Binary Object Representation (CBOR) Tags list.