Documentation

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.