Codec.Borsh.Incremental

Constructing decoders

newtype Decoder s a

Decoder

A decoder describes how to match against a single chunk of the input.

Constructors

Decoder

Fields

• matchChunk :: LocatedChunk -> ST s (LocatedChunk, DecodeResult s a)

Instances

MonadFail (Decoder s)

Defined in Codec.Borsh.Incremental.Decoder

Methods

fail :: String -> Decoder s a

Applicative (Decoder s)

Defined in Codec.Borsh.Incremental.Decoder

Methods

pure :: a -> Decoder s a

(<*>) :: Decoder s (a -> b) -> Decoder s a -> Decoder s b

liftA2 :: (a -> b -> c) -> Decoder s a -> Decoder s b -> Decoder s c

(*>) :: Decoder s a -> Decoder s b -> Decoder s b

(<*) :: Decoder s a -> Decoder s b -> Decoder s a

Functor (Decoder s)

Defined in Codec.Borsh.Incremental.Decoder

Methods

fmap :: (a -> b) -> Decoder s a -> Decoder s b

(<$) :: a -> Decoder s b -> Decoder s a

Monad (Decoder s)

Defined in Codec.Borsh.Incremental.Decoder

Methods

(>>=) :: Decoder s a -> (a -> Decoder s b) -> Decoder s b

(>>) :: Decoder s a -> Decoder s b -> Decoder s b

return :: a -> Decoder s a

data DecodeResult s a where

Constructors

DecodeDone :: a -> DecodeResult s a

The decoder terminated successfully: we can stop decoding

DecodeFail :: String -> DecodeResult s a

The decoder failed: we should abort

DecodeNeedsData :: Decoder s a -> DecodeResult s a

The decoder needs more data before it can continue

NOTE: The decoder that is waiting for more data may not be (and typically will not be) the decoder we started with in matchChunk: in the typical case, a bunch of values will have been decoded successfully before we get to a (continuation) decoder that requires data beyond the current chunk.

DecodeLargeToken

Large token of known length that spans multiple chunks

This is NOT incremental: all chunks will be read into memory before the function is applied. Primarily useful for large types that are not easily split into (valid) chunks, such as UTF8-encoded text (if were wanted to split that, we'd have to split it at UTF8 boundaries).

The continuation will be called with a lazy bytestring of precisely the requested length (provided enough input is available, of course), along with the remaining input token to be provided to the continuation decoder.

Fields

• :: Word32

  Required number of bytes

• -> (ByteString -> Decoder s a)
• -> DecodeResult s a

DecodeIncremental

Incremental interface

When decoding large objects such as lists, we do not want to bring all required chunks into memory before decoding the list. Instead, we want to decode the list elements as we go. In this case, DecodeIncremental can be used to repeatedly decode a value using decoder for the elements; when all elements have been processed, the continuation decoder is called.

NOTE: This interface is incremental in the sense that the input chunks are read one at a time. It is NOT incremental in the generated output.

Fields

• :: Word32

  How often to repeat the smaller decoder

• -> Decoder s a

  Decoder to repeat

• -> ([a] -> Decoder s b)

  Process all elements

• -> DecodeResult s b

DecodeIncremental_

Variation on DecodeIncremental, where we do not accumulate results

This is useful for example for datatypes that we can update imperatively, such as mutable arrays. It could also be used to skip over unused parts of the input.

Fields

• :: Word32

  How often to repeat the smaller decoder

• -> Decoder s ()

  Decoder to repeat (imperatively handling each element)

• -> Decoder s a

  Continuation

• -> DecodeResult s a

liftDecoder :: ST s a -> Decoder s a

Running decoders

data DeserialiseFailure

Error type for deserialisation.

Constructors

DeserialiseFailure

Fields

• ByteOffset

  The position of the decoder when the failure occurred

• String

  Message explaining the failure

Instances

Exception DeserialiseFailure

Defined in Codec.Borsh.Incremental.Monad

Methods

toException :: DeserialiseFailure -> SomeException

fromException :: SomeException -> Maybe DeserialiseFailure

displayException :: DeserialiseFailure -> String

Show DeserialiseFailure

Defined in Codec.Borsh.Incremental.Monad

Methods

showsPrec :: Int -> DeserialiseFailure -> ShowS

show :: DeserialiseFailure -> String

showList :: [DeserialiseFailure] -> ShowS

Eq DeserialiseFailure

Defined in Codec.Borsh.Incremental.Monad

Methods

(==) :: DeserialiseFailure -> DeserialiseFailure -> Bool

(/=) :: DeserialiseFailure -> DeserialiseFailure -> Bool

deserialiseByteString :: (forall s. Decoder s a) -> ByteString -> Either DeserialiseFailure (ByteString, ByteOffset, a)

Specialised decoders

These functions comprise a low-level decoder interface which will not be necessary for most applications. Most applications should simply use deserialiseBorsh

decodeLittleEndian :: forall s a. ByteSwap a => Decoder s a

decodeLargeToken :: Word32 -> Decoder s ByteString

decodeIncremental :: Word32 -> Decoder s a -> Decoder s [a]

decodeIncremental_ :: Word32 -> Decoder s () -> Decoder s ()

Located values

data Located a

Value at a particular point in the input

Constructors

L !a !ByteOffset

type ByteOffset = Word32

Offset in bytes within the input

type LocatedChunk = Located ByteString

The most common case: chunk of the input at a particular point