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

Cardano.Ledger.Binary.Decoding

Synopsis

Running decoders

decodeFull ∷ ∀ a. DecCBOR a ⇒ Version → ByteString → Either DecoderError a Source #

Deserialize a Haskell value from a binary CBOR representation, failing if there are leftovers. In other words, the Full here implies the contract on this function that the input must be consumed in its entirety by the decoder specified in DecCBOR.

decodeFull' ∷ ∀ a. DecCBOR a ⇒ Version → ByteString → Either DecoderError a Source #

Same as decodeFull, except accepts a strict ByteString as input instead of the lazy one.

decodeFullDecoder Source #

Arguments

∷ Version

Protocol version to be used during decoding.

→ Text

Label for error reporting

→ (∀ s. Decoder s a)

The parser for the ByteString to decode. It should decode the given ByteString into a value of type a

→ ByteString

The ByteString to decode

→ Either DecoderError a 

Same as decodeFull, except instead of relying on the DecCBOR instance the Decoder must be suplied manually.

decodeFullDecoder' ∷ Version → Text → (∀ s. Decoder s a) → ByteString → Either DecoderError a Source #

Same as decodeFullDecoder, except works on strict ByteString

decodeFullAnnotator ∷ Version → Text → (∀ s. Decoder s (Annotator a)) → ByteString → Either DecoderError a Source #

Same as decodeFullDecoder, except it provdes the means of passing portion or all of the ByteString input argument to the decoding Annotator.

decodeFullAnnotatedBytes ∷ Functor f ⇒ Version → Text → (∀ s. Decoder s (f ByteSpan)) → ByteString → Either DecoderError (f ByteString) Source #

Same as decodeFullDecoder, decodes a Haskell value from a lazy ByteString, requiring that the full ByteString is consumed, and replaces ByteSpan annotations with the corresponding slice of the input as a strict ByteString.

decodeFullAnnotatorFromHexText ∷ Version → Text → (∀ s. Decoder s (Annotator a)) → Text → Either DecoderError a Source #

module Cardano.Ledger.Binary.Version

module Cardano.Ledger.Binary.Decoding.DecCBOR

module Cardano.Ledger.Binary.Decoding.Sharing

module Cardano.Ledger.Binary.Decoding.Decoder

module Cardano.Ledger.Binary.Decoding.Sized

module Cardano.Ledger.Binary.Decoding.Drop

Annotated

The regular CBOR Decoder does not support access to the original ByteString that is being read during deserialization. The Annotator and Annotated recover this ability.

  1. ByteSpan A pair of indexes into a bytestring, indicating a substring.
  2. Annotated Used in practice to pair a value with a ByteSpan. Mostly used in Byron codebase.
  3. FullByteString A newtype (around a bytestring) used to store the original bytestring being deserialized.
  4. Annotator An explict reader monad whose environment is a FullByteString

The basic idea is, for a given type t, where we need the original ByteString, either

  1. To complete the deserialization, or
  2. To combine the deserialized answer with the original ByteString.

We should proceed as follows: Define instances (DecCBOR (Annotator t)) instead of (DecCBOR t). When making this instance we may freely use that both Decoder and Annotator are both monads, and that functions withSlice and annotatorSlice provide access to the original bytes, or portions thereof, inside of decoders. Then, to actually decode a value of type t, we use something similar to the following code fragment.

howToUseFullBytes bytes = do
  Annotator f <- decodeFullDecoder "DecodingAnnotator" (decCBOR :: forall s. Decoder s (Annotator t)) bytes
  pure (f (Full bytes))

Decode the bytes to get an (Annotator f) where f is a function that when given original bytes produces a value of type t, then apply f to (Full bytes) to get the answer.

module Cardano.Ledger.Binary.Decoding.Annotated

Nested CBOR in CBOR

decodeNestedCbor ∷ DecCBOR a ⇒ Decoder s a Source #

Remove the the semantic tag 24 from the enclosed CBOR data item, decoding back the inner ByteString as a proper Haskell type. Consume its input in full.

decodeNestedCborBytes ∷ Decoder s ByteString Source #

Like decodeKnownCborDataItem, but assumes nothing about the Haskell type we want to deserialise back, therefore it yields the ByteString Tag 24 surrounded (stripping such tag away).

In CBOR notation, if the data was serialised as:

>>> 24(h'DEADBEEF')

then decodeNestedCborBytes yields the inner DEADBEEF, unchanged.

Unsafe deserialization

unsafeDeserialize ∷ DecCBOR a ⇒ Version → ByteString → a Source #

Deserialize a Haskell value from the external binary representation, which have been made using serialize or a matching serialization functionilty in another language that uses CBOR format. Accepts lazy ByteString as input, for strict variant use unsafeDeserialize` instead.

This deserializaer is not safe for these reasons:

  • Throws: DeserialiseFailure if the given external representation is invalid or does not correspond to a value of the expected type.
  • Decoding will not fail when the binary input is not consumed in full.

unsafeDeserialize' ∷ DecCBOR a ⇒ Version → ByteString → a Source #

Variant of unsafeDeserialize that accepts a strict ByteString as input.

Helpers

toStrictByteString Source #

Arguments

∷ Encoding

The Encoding of a CBOR value.

→ ByteString

The encoded value.

Turn an Encoding into a strict ByteString in CBOR binary format.

Since: cborg-0.2.0.0

Deprecated

decodeAnnotator ∷ Version → Text → (∀ s. Decoder s (Annotator a)) → ByteString → Either DecoderError a Source #

Deprecated: In favor of decodeFullAnnotator

decCBORMaybe ∷ Decoder s a → Decoder s (Maybe a) Source #

Deprecated: In favor of decodeMaybe