Decoders

Extract the underlying Decoder by specifying the concrete version to be used.

Promote a regular Decoder to a versioned one. Which means it will work for all versions.

Use the supplied decoder as a plain decoder with current version.

Ignore the current version of the decoder and enforce the supplied one instead.

A 0-based offset within the overall byte sequence that makes up the input to the Decoder.

This is an Int64 since Decoder is incremental and can decode more data than fits in memory at once. This is also compatible with the result type of length.

An action, representing a step for a decoder to taken and a continuation to invoke with the expected value.

Since: cborg-0.2.0.0

The type of a token, which a decoder can ask for at an arbitrary time.

Since: cborg-0.2.0.0

Extract current version of the decoder

>>> import Cardano.Ledger.Decoding
>>> decodeFullDecoder 3 "Version" getDecoderVersion ""
Right 3

Conditionally choose the newer or older decoder, depending on the current version. Version in the context of encoders/decoders is the major protocol version. Supplied version acts as a pivot.

Example

>>> newtype Foo = Foo Word32
>>> decFoo = Foo <$> ifDecoderVersionAtLeast 2 decodeWord32 (fromIntegral <$> decodeWord16)

Optionally run a decoder depending on the current version and the supplied one.

Optionally run a decoder depending on the current version and the supplied one.

Convert a Buildable error message into a MonadFail failure.

Convert an Either-encoded failure to a MonadFail failure using the Buildable insatance

Report an error when a numeric key of the type constructor doesn't match.

Enforces that the input size is the same as the decoded one, failing in case it's not

Compare two sizes, failing if they are not equal

Convert a Get monad from binary package into a Decoder

Decoder for Rational. Versions variance:

• [>= 9] - Allows variable as well as exact list length encoding. Consumes tag 30 if one is present, but does not enforce it.
• [>= 2] - Allows variable as well as exact list length encoding.
• [== 1] - Expects exact list length encoding.

Enforces tag 30 to indicate a rational number, as per tag assignment: https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml

https://peteroupc.github.io/CBOR/rational.html

Use this decoder for any list like structure that accepts fixed or variable list length encoding.

Decoder for Maybe. Versions variance:

• [>= 2] - Allows variable as well as exact list length encoding.
• [< 2] - Expects exact list length encoding

Alternative way to decode a Maybe type.

Note - this is not the default method for decoding Maybe, use decodeMaybe instead.

Unlike decodeMaybe this allows variable as well as exact list length encoding for all versions, because Byron never used StrictMaybe type.

Alternative way to decode a StrictMaybe type.

Note - this is not the default method for decoding StrictMaybe, use decodeStrictMaybe instead.

Decoder for list.

• [>= 2] - Allows variable as well as exact list length encoding.
• [< 2] - Expects variable list length encoding

Generic decoder for vectors. Its intended use is to allow easy definition of Serialise instances for custom vector

Decoder for Set. Versions variance:

• [>= 9] - Allows variable as well as exact list length encoding. Duplicates are not allowed. Set tag 258 is permitted, but not enforced.
• [>= 2, < 9] - Allows variable as well as exact list length encoding. Duplicates are silently ignored, set tag 258 is not permitted.
• [< 2] - Expects exact list length encoding and enforces strict order without any duplicates. Also enforces special set tag 258, which was abandoned starting with version 2

We stitch a `258` in from of a (Hash)Set, so that tools which programmatically check for canonicity can recognise it from a normal array. Why 258? This will be formalised pretty soon, but IANA allocated 256...18446744073709551615 to "First come, first served": https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml Currently `258` is the first unassigned tag and as it requires 2 bytes to be encoded, it sounds like the best fit.

https://github.com/input-output-hk/cbor-sets-spec/blob/master/CBOR_SETS.md

Decoder for Map. Versions variance:

• [>= 9] - Allows variable as well as exact list length encoding. Duplicate keys will result in a deserialization failure
• [>= 2] - Allows variable as well as exact list length encoding. Duplicate keys are silently ignored
• [< 2] - Expects exact list length encoding and enforces strict order without any duplicates.

An example of how to use versioning

>>> :set -XOverloadedStrings
>>> import Codec.CBOR.FlatTerm
>>> fromFlatTerm (toPlainDecoder 1 (decodeMap decodeInt decodeBytes)) [TkMapLen 2,TkInt 1,TkBytes "Foo",TkInt 2,TkBytes "Bar"]
Right (fromList [(1,"Foo"),(2,"Bar")])
>>> fromFlatTerm (toPlainDecoder 1 (decodeMap decodeInt decodeBytes)) [TkMapBegin,TkInt 1,TkBytes "Foo",TkInt 2,TkBytes "Bar"]
Left "decodeMapLen: unexpected token TkMapBegin"
>>> fromFlatTerm (toPlainDecoder 2 (decodeMap decodeInt decodeBytes)) [TkMapBegin,TkInt 1,TkBytes "Foo",TkInt 2,TkBytes "Bar",TkBreak]
Right (fromList [(1,"Foo"),(2,"Bar")])

Just like decodeMap, but also gives access to the key for the value decoder.

Similar to decodeMapByKey, except it gives access to the key value decoder as a pair and allows for different type of length encoding

Decode VMap. Unlike decodeMap it does not behavee differently for version prior to 2.

Decoder for Seq. Same behavior for all versions, allows variable as well as exact list length encoding

Decoder for StrictSeq. Same behavior for all versions, allows variable as well as exact list length encoding.

Decode a collection of values with ability to supply length decoder. Number of decoded elements will be returned together with the data structure

Decode a Set as a either a definite or indefinite list. Duplicates are not allowed. Set tag 258 is permitted, but not enforced.

Decode a collection of values with ability to supply length decoder. Duplicates are not allowed.

Decoder for UTCTime. Versions variance:

• [>= 2] - Allows variable list length encoding, but still expects number of elements to be 3.
• [< 2] - Expects exact list length encoding to be 3