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

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.

A pair of offsets delimiting the beginning and end of a substring of a ByteString

A decoder for a value paired with an annotation specifying the start and end of the consumed bytes.

Extract a substring of a given ByteString corresponding to the offsets.

A decoder for a value paired with an annotation specifying the start and end of the consumed bytes.

Reconstruct an annotation by re-serialising the payload to a ByteString.

A value of type (Annotator a) is one that needs access to the entire bytestring used during decoding to finish construction of a vaue of type a. A typical use is some type that stores the bytes that were used to deserialize it. For example the type Inner below is constructed using the helper function makeInner which serializes and stores its bytes (using serialize). Note how we build the Annotator by abstracting over the full bytes, and using those original bytes to fill the bytes field of the constructor Inner. The EncCBOR instance just reuses the stored bytes to produce an encoding (using encodePreEncoded).

data Inner = Inner Int Bool LByteString

makeInner :: Int -> Bool -> Inner
makeInner i b = Inner i b (serialize (encCBOR i <> encCBOR b))

instance EncCBOR Inner where
  encCBOR (Inner _ _ bytes) = encodePreEncoded bytes

instance DecCBOR (Annotator Inner) where
  decCBOR = do
     int <- decCBOR
     trueOrFalse <- decCBOR
     pure (Annotator ((Full bytes) -> Inner int trueOrFalse bytes))

if an Outer type has a field of type Inner, with a (EncCBOR (Annotator Inner)) instance, the Outer type must also have a (EncCBOR (Annotator Outer)) instance. The key to writing that instance is to use the operation withSlice which returns a pair. The first component is an Annotator that can build Inner, the second is an Annotator that given the full bytes, extracts just the bytes needed to decode Inner.

data Outer = Outer Text Inner

instance EncCBOR Outer where
  encCBOR (Outer t i) = encCBOR t <> encCBOR i

instance DecCBOR (Annotator Outer) where
  decCBOR = do
    t <- decCBOR
    (Annotator mkInner, Annotator extractInnerBytes) <- withSlice decCBOR
    pure (Annotator ( full -> Outer t (mkInner (Full (extractInnerBytes full)))))

The argument is a decoder for a annotator that needs access to the bytes that | were decoded. This function constructs and supplies the relevant piece.

Pairs the decoder result with an annotator that can be used to construct the exact bytes used to decode the result.

This marks the entire bytestring used during decoding, rather than the piece we need to finish constructing our value.

Translation function between values through a related binary representation. This function allows you to translate one type into another (or the same one) through their common binary format. It is possible for the source type to be encoded with a different version than the version that will be used for decoding. This is useful for types that build upon one another and are "upgradeable" through their binary representation. It is important to note that the deserialization will happen with Annotator, since that is usually the way we deserialize upgradeable types that live on chain. Moreover, encoding does not require a version, because memoized types that were decoded with annotation will have the bytes retained and thus will have the ToCBOR instance.