cardano-ledger-binary-1.3.3.0: Binary serialization library used throughout ledger
Safe HaskellSafe-Inferred
LanguageHaskell2010

Cardano.Ledger.Binary.Decoding.Decoder

Synopsis

Decoders

data Decoder s a Source #

Instances

Instances details
MonadFail (Decoder s) Source # 
Instance details

Defined in Cardano.Ledger.Binary.Decoding.Decoder

Methods

failStringDecoder s a Source #

Applicative (Decoder s) Source # 
Instance details

Defined in Cardano.Ledger.Binary.Decoding.Decoder

Methods

pure ∷ a → Decoder s a Source #

(<*>)Decoder s (a → b) → Decoder s a → Decoder s b Source #

liftA2 ∷ (a → b → c) → Decoder s a → Decoder s b → Decoder s c Source #

(*>)Decoder s a → Decoder s b → Decoder s b Source #

(<*)Decoder s a → Decoder s b → Decoder s a Source #

Functor (Decoder s) Source # 
Instance details

Defined in Cardano.Ledger.Binary.Decoding.Decoder

Methods

fmap ∷ (a → b) → Decoder s a → Decoder s b Source #

(<$) ∷ a → Decoder s b → Decoder s a Source #

Monad (Decoder s) Source # 
Instance details

Defined in Cardano.Ledger.Binary.Decoding.Decoder

Methods

(>>=)Decoder s a → (a → Decoder s b) → Decoder s b Source #

(>>)Decoder s a → Decoder s b → Decoder s b Source #

return ∷ a → Decoder s a Source #

toPlainDecoderVersionDecoder s a → Decoder s a Source #

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

fromPlainDecoderDecoder s a → Decoder s a Source #

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

withPlainDecoderDecoder s a → (Decoder s a → Decoder s b) → Decoder s b Source #

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

enforceDecoderVersionVersionDecoder s a → Decoder s a Source #

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

type ByteOffset = Int64 Source #

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.

data DecodeAction s a Source #

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

Constructors

ConsumeWord (Word#ST s (DecodeAction s a)) 
ConsumeWord8 (Word#ST s (DecodeAction s a)) 
ConsumeWord16 (Word#ST s (DecodeAction s a)) 
ConsumeWord32 (Word#ST s (DecodeAction s a)) 
ConsumeNegWord (Word#ST s (DecodeAction s a)) 
ConsumeInt (Int#ST s (DecodeAction s a)) 
ConsumeInt8 (Int#ST s (DecodeAction s a)) 
ConsumeInt16 (Int#ST s (DecodeAction s a)) 
ConsumeInt32 (Int#ST s (DecodeAction s a)) 
ConsumeListLen (Int#ST s (DecodeAction s a)) 
ConsumeMapLen (Int#ST s (DecodeAction s a)) 
ConsumeTag (Word#ST s (DecodeAction s a)) 
ConsumeInteger (IntegerST s (DecodeAction s a)) 
ConsumeFloat (Float#ST s (DecodeAction s a)) 
ConsumeDouble (Double#ST s (DecodeAction s a)) 
ConsumeBytes (ByteStringST s (DecodeAction s a)) 
ConsumeByteArray (ByteArrayST s (DecodeAction s a)) 
ConsumeString (TextST s (DecodeAction s a)) 
ConsumeUtf8ByteArray (ByteArrayST s (DecodeAction s a)) 
ConsumeBool (BoolST s (DecodeAction s a)) 
ConsumeSimple (Word#ST s (DecodeAction s a)) 
ConsumeBytesIndef (ST s (DecodeAction s a)) 
ConsumeStringIndef (ST s (DecodeAction s a)) 
ConsumeListLenIndef (ST s (DecodeAction s a)) 
ConsumeMapLenIndef (ST s (DecodeAction s a)) 
ConsumeNull (ST s (DecodeAction s a)) 
ConsumeListLenOrIndef (Int#ST s (DecodeAction s a)) 
ConsumeMapLenOrIndef (Int#ST s (DecodeAction s a)) 
ConsumeBreakOr (BoolST s (DecodeAction s a)) 
PeekTokenType (TokenTypeST s (DecodeAction s a)) 
PeekAvailable (Int#ST s (DecodeAction s a)) 
PeekByteOffset (Int#ST s (DecodeAction s a)) 
ConsumeWordCanonical (Word#ST s (DecodeAction s a)) 
ConsumeWord8Canonical (Word#ST s (DecodeAction s a)) 
ConsumeWord16Canonical (Word#ST s (DecodeAction s a)) 
ConsumeWord32Canonical (Word#ST s (DecodeAction s a)) 
ConsumeNegWordCanonical (Word#ST s (DecodeAction s a)) 
ConsumeIntCanonical (Int#ST s (DecodeAction s a)) 
ConsumeInt8Canonical (Int#ST s (DecodeAction s a)) 
ConsumeInt16Canonical (Int#ST s (DecodeAction s a)) 
ConsumeInt32Canonical (Int#ST s (DecodeAction s a)) 
ConsumeListLenCanonical (Int#ST s (DecodeAction s a)) 
ConsumeMapLenCanonical (Int#ST s (DecodeAction s a)) 
ConsumeTagCanonical (Word#ST s (DecodeAction s a)) 
ConsumeIntegerCanonical (IntegerST s (DecodeAction s a)) 
ConsumeFloat16Canonical (Float#ST s (DecodeAction s a)) 
ConsumeFloatCanonical (Float#ST s (DecodeAction s a)) 
ConsumeDoubleCanonical (Double#ST s (DecodeAction s a)) 
ConsumeBytesCanonical (ByteStringST s (DecodeAction s a)) 
ConsumeByteArrayCanonical (ByteArrayST s (DecodeAction s a)) 
ConsumeStringCanonical (TextST s (DecodeAction s a)) 
ConsumeUtf8ByteArrayCanonical (ByteArrayST s (DecodeAction s a)) 
ConsumeSimpleCanonical (Word#ST s (DecodeAction s a)) 
Fail String 
Done a 

data TokenType Source #

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

Since: cborg-0.2.0.0

Versioning

getDecoderVersionDecoder s Version Source #

Extract current version of the decoder

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

ifDecoderVersionAtLeast Source #

Arguments

Version 
Decoder s a

Use this decoder if current decoder version is larger or equal to the supplied Version

Decoder s a

Use this decoder if current decoder version is lower than the supplied Version

Decoder s a 

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
Expand

Let's say prior to the version 2 some type Foo was backed by Word16, but at the 2nd version onwards it was switched to Word32 instead. In order to support both versions, we change the type, but we also use this condition to keep backwards compatibility of the decoder:

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

whenDecoderVersionAtLeast Source #

Arguments

Version 
Decoder s a

Run this decoder whenever current decoder version is larger or equal to the supplied Version

Decoder s () 

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

unlessDecoderVersionAtLeast Source #

Arguments

Version 
Decoder s a

Run this decoder whenever current decoder version is smaller to the supplied Version

Decoder s () 

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

Error reporting

cborError ∷ (MonadFail m, Buildable e) ⇒ e → m a Source #

Convert a Buildable error message into a MonadFail failure.

toCborError ∷ (MonadFail m, Buildable e) ⇒ Either e a → m a Source #

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

invalidKeyMonadFail m ⇒ Word → m a Source #

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

enforceSizeTextIntDecoder s () Source #

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

matchSizeTextIntIntDecoder s () Source #

Compare two sizes, failing if they are not equal

Compatibility tools

binaryGetDecoder Source #

Arguments

Bool

Flag to allow left over at the end or not

Text

Name of the function or type for error reporting

Get a

Deserializer for the binary package

Decoder s a 

Convert a Get monad from binary package into a Decoder

Custom decoders

decodeRationalDecoder s Rational Source #

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.

decodeRecordNamedText → (a → Int) → Decoder s a → Decoder s a Source #

decodeRecordNamedT ∷ (MonadTrans m, Monad (m (Decoder s))) ⇒ Text → (a → Int) → m (Decoder s) a → m (Decoder s) a Source #

decodeRecordSumText → (WordDecoder s (Int, a)) → Decoder s a Source #

decodeListLike Source #

Arguments

Text

Name for error reporting

Decoder s a

Decoder for the datastructure itself

→ (a → IntDecoder s ())

In case when length was encoded, act upon it.

Decoder s a 

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

decodeListLikeT Source #

Arguments

∷ (MonadTrans m, Monad (m (Decoder s))) 
Text

Name for error reporting

→ m (Decoder s) a

Decoder for the datastructure itself

→ (a → Int → m (Decoder s) ())

In case when length was encoded, act upon it.

→ m (Decoder s) a 

decodeEnumBounded ∷ ∀ a s. (Enum a, Bounded a, Typeable a) ⇒ Decoder s a Source #

Containers

decodeMaybeDecoder s a → Decoder s (Maybe a) Source #

Decoder for Maybe. Versions variance:

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

decodeNullMaybeDecoder s a → Decoder s (Maybe a) Source #

Alternative way to decode a Maybe type.

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

decodeStrictMaybeDecoder s a → Decoder s (StrictMaybe a) Source #

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

decodeNullStrictMaybeDecoder s a → Decoder s (StrictMaybe a) Source #

Alternative way to decode a StrictMaybe type.

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

decodeEitherDecoder s a → Decoder s b → Decoder s (Either a b) Source #

decodeListDecoder s a → Decoder s [a] Source #

Decoder for list.

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

decodeVectorVector vec a ⇒ Decoder s a → Decoder s (vec a) Source #

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

decodeSetOrd a ⇒ Decoder s a → Decoder s (Set a) Source #

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

setTagWord Source #

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

decodeMapOrd k ⇒ Decoder s k → Decoder s v → Decoder s (Map k v) Source #

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")])

decodeMapByKeyOrd k ⇒ Decoder s k → (k → Decoder s v) → Decoder s (Map k v) Source #

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

decodeMapLikeEnforceNoDuplicatesOrd k ⇒ Decoder s (Maybe Int) → Decoder s (k, v) → Decoder s (Map k v) Source #

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

decodeVMap ∷ (Vector kv k, Vector vv v, Ord k) ⇒ Decoder s k → Decoder s v → Decoder s (VMap kv vv k v) Source #

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

decodeSeqDecoder s a → Decoder s (Seq a) Source #

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

decodeStrictSeqDecoder s a → Decoder s (StrictSeq a) Source #

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

decodeListLikeWithCount Source #

Arguments

∷ ∀ s a b. Monoid b 
Decoder s (Maybe Int)

Length decoder that produces the expected number of elements. When Nothing is decoded the decodeBreakOr will be used as termination indicator.

→ (a → b → b)

Add an element into the decoded List like data structure

→ (b → Decoder s a)

Decoder for the values. Current accumulator is supplied as an argument

Decoder s (Int, b) 

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

decodeSetLikeEnforceNoDuplicates Source #

Arguments

∷ ∀ s a b c. Monoid b 
⇒ (a → b → b)

Add an element into the decoded Set like data structure

→ (b → (Int, c))

Get the final data structure from the decoded sequence of values and the number of elements it contains. This is useful when a sequence on the wire is represented by a set, namely no duplicates are allowed, while the Haskell representation uses some other data structure that enforces no duplicates by some other means. For example a Map, where keys are hashes of the values encoded on the wire. The size of the final data structure will be used to enforce the invariant that the number of elements decoded matches the final size of the Set like data structure, thus ensuring no duplicates were encountered.

Decoder s a 
Decoder s c 

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

decodeListLikeEnforceNoDuplicates Source #

Arguments

∷ ∀ s a b c. Monoid b 
Decoder s (Maybe Int) 
→ (a → b → b)

Add an element into the decoded List like data structure

→ (b → (Int, c))

Get the final data structure and the number of elements it has.

Decoder s a 
Decoder s c 

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

Applicaitve

decodeMapTraverse ∷ (Ord a, Applicative t) ⇒ Decoder s (t a) → Decoder s (t b) → Decoder s (t (Map a b)) Source #

decodeMapContentsTraverseApplicative t ⇒ Decoder s (t a) → Decoder s (t b) → Decoder s (t [(a, b)]) Source #

Time

decodeUTCTimeDecoder s UTCTime Source #

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

Network

Lifted cborg decoders

decodeSequenceLenIndef ∷ (r → a → r) → r → (r → b) → Decoder s a → Decoder s b Source #

decodeSequenceLenN ∷ (r → a → r) → r → (r → b) → IntDecoder s a → Decoder s b Source #