-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Binary serialization for Cardano
--   
--   This package includes the binary serialization format for Cardano
@package cardano-binary
@version 1.5.0

module Cardano.Binary
class Typeable a => ToCBOR a
toCBOR :: ToCBOR a => a -> Encoding
encodedSizeExpr :: ToCBOR a => (forall t. ToCBOR t => Proxy t -> Size) -> Proxy a -> Size
encodedListSizeExpr :: ToCBOR a => (forall t. ToCBOR t => Proxy t -> Size) -> Proxy [a] -> Size

-- | Compute encoded size of an integer
withWordSize :: (Integral s, Integral a) => s -> a
toCBORMaybe :: (a -> Encoding) -> Maybe a -> Encoding

-- | A range of values. Should satisfy the invariant <tt>forall x. lo x
--   &lt;= hi x</tt>.
data Range b
Range :: b -> b -> Range b
[lo] :: Range b -> b
[hi] :: Range b -> b

-- | Fully evaluate a size expression by applying the given function to any
--   suspended computations. <tt>szEval g</tt> effectively turns each
--   "thunk" of the form <tt>TodoF f x</tt> into <tt>g x</tt>, then
--   evaluates the result.
szEval :: (forall t. ToCBOR t => (Proxy t -> Size) -> Proxy t -> Range Natural) -> Size -> Range Natural

-- | Expressions describing the statically-computed size bounds on a type's
--   possible values.
type Size = Fix SizeF

-- | An individual labeled case.
data Case t
Case :: Text -> t -> Case t

-- | Discard the label on a case.
caseValue :: Case t -> t

-- | A type used to represent the length of a value in <a>Size</a>
--   computations.
newtype LengthOf xs
LengthOf :: xs -> LengthOf xs

-- | Override mechanisms to be used with <a>szWithCtx</a>.
data SizeOverride

-- | Replace with a fixed <tt>Size</tt>.
SizeConstant :: Size -> SizeOverride

-- | Recursively compute the size.
SizeExpression :: ((forall a. ToCBOR a => Proxy a -> Size) -> Size) -> SizeOverride

-- | Select only a specific case from a <tt>CasesF</tt>.
SelectCases :: [Text] -> SizeOverride

-- | Is this expression a thunk?
isTodo :: Size -> Bool

-- | Create a case expression from individual cases.
szCases :: [Case Size] -> Size

-- | Evaluate the expression lazily, by immediately creating a thunk that
--   will evaluate its contents lazily.
--   
--   <pre>
--   ghci&gt; putStrLn $ pretty $ szLazy (Proxy @TxAux)
--   (_ :: TxAux)
--   </pre>
szLazy :: ToCBOR a => Proxy a -> Size

-- | Evaluate an expression greedily. There may still be thunks in the
--   result, for types that did not provide a custom <a>encodedSizeExpr</a>
--   method in their <a>ToCBOR</a> instance.
--   
--   <pre>
--   ghci&gt; putStrLn $ pretty $ szGreedy (Proxy @TxAux)
--   (0 + { TxAux=(2 + ((0 + (((1 + (2 + ((_ :: LengthOf [TxIn]) * (2 + { TxInUtxo=(2 + ((1 + 34) + { minBound=1 maxBound=5 })) })))) + (2 + ((_ :: LengthOf [TxOut]) * (0 + { TxOut=(2 + ((0 + ((2 + ((2 + withWordSize((((1 + 30) + (_ :: Attributes AddrAttributes)) + 1))) + (((1 + 30) + (_ :: Attributes AddrAttributes)) + 1))) + { minBound=1 maxBound=5 })) + { minBound=1 maxBound=9 })) })))) + (_ :: Attributes ()))) + (_ :: Vector TxInWitness))) })
--   </pre>
szGreedy :: ToCBOR a => Proxy a -> Size

-- | Force any thunks in the given <tt>Size</tt> expression.
--   
--   <pre>
--   ghci&gt; putStrLn $ pretty $ szForce $ szLazy (Proxy @TxAux)
--   (0 + { TxAux=(2 + ((0 + (_ :: Tx)) + (_ :: Vector TxInWitness))) })
--   </pre>
szForce :: Size -> Size

-- | Greedily compute the size bounds for a type, using the given context
--   to override sizes for specific types.
szWithCtx :: ToCBOR a => Map TypeRep SizeOverride -> Proxy a -> Size

-- | Simplify the given <tt>Size</tt>, resulting in either the simplified
--   <tt>Size</tt> or, if it was fully simplified, an explicit upper and
--   lower bound.
szSimplify :: Size -> Either Size (Range Natural)

-- | Apply a monotonically increasing function to the expression. There are
--   three cases when applying <tt>f</tt> to a <tt>Size</tt> expression: *
--   When applied to a value <tt>x</tt>, compute <tt>f x</tt>. * When
--   applied to cases, apply to each case individually. * In all other
--   cases, create a deferred application of <tt>f</tt>.
apMono :: Text -> (Natural -> Natural) -> Size -> Size
szBounds :: ToCBOR a => a -> Either Size (Range Natural)

-- | Serialize a Haskell value with a <a>ToCBOR</a> instance to an external
--   binary representation.
--   
--   The output is represented as a lazy <a>LByteString</a> and is
--   constructed incrementally.
serialize :: ToCBOR a => a -> LByteString

-- | Serialize a Haskell value to an external binary representation.
--   
--   The output is represented as a strict <a>ByteString</a>.
serialize' :: ToCBOR a => a -> ByteString

-- | Serialize into a Builder. Useful if you want to throw other
--   ByteStrings around it.
serializeBuilder :: ToCBOR a => a -> Builder

-- | Serialize a Haskell value to an external binary representation using
--   the provided CBOR <a>Encoding</a>
--   
--   The output is represented as an <a>LByteString</a> and is constructed
--   incrementally.
serializeEncoding :: Encoding -> LByteString

-- | A strict version of <a>serializeEncoding</a>
serializeEncoding' :: Encoding -> ByteString

-- | Encode and serialise the given <tt>a</tt> and sorround it with the
--   semantic tag 24 In CBOR diagnostic notation: &gt;&gt;&gt;
--   24(h<tt>DEADBEEF</tt>)
encodeNestedCbor :: ToCBOR a => a -> Encoding

-- | Like <a>encodeNestedCbor</a>, but assumes nothing about the shape of
--   input object, so that it must be passed as a binary <a>ByteString</a>
--   blob. It's the caller responsibility to ensure the input
--   <a>ByteString</a> correspond indeed to valid, previously-serialised
--   CBOR data.
encodeNestedCborBytes :: LByteString -> Encoding
nestedCborSizeExpr :: Size -> Size
nestedCborBytesSizeExpr :: Size -> Size

-- | A wrapper over <a>ByteString</a> for signalling that a bytestring
--   should be processed as a sequence of bytes, not as a separate entity.
--   It's used in crypto and binary code.
newtype Raw
Raw :: ByteString -> Raw
class Typeable a => FromCBOR a
fromCBOR :: FromCBOR a => Decoder s a
label :: FromCBOR a => Proxy a -> Text
data DecoderError
DecoderErrorCanonicityViolation :: Text -> DecoderError

-- | Custom decoding error, usually due to some validation failure
DecoderErrorCustom :: Text -> Text -> DecoderError
DecoderErrorDeserialiseFailure :: Text -> DeserialiseFailure -> DecoderError
DecoderErrorEmptyList :: Text -> DecoderError
DecoderErrorLeftover :: Text -> ByteString -> DecoderError

-- | A size mismatch <tt>DecoderErrorSizeMismatch label expectedSize
--   actualSize</tt>
DecoderErrorSizeMismatch :: Text -> Int -> Int -> DecoderError
DecoderErrorUnknownTag :: Text -> Word8 -> DecoderError
DecoderErrorVoid :: DecoderError

-- | Enforces that the input size is the same as the decoded one, failing
--   in case it's not
enforceSize :: Text -> Int -> Decoder s ()

-- | Compare two sizes, failing if they are not equal
matchSize :: Text -> Int -> Int -> Decoder s ()
fromCBORMaybe :: Decoder s a -> Decoder s (Maybe a)

-- | <tt><a>Decoder</a></tt> for list.
decodeListWith :: Decoder s a -> Decoder s [a]

-- | Checks canonicity by comparing the new key being decoded with the
--   previous one, to enfore these are sorted the correct way. See:
--   <a>https://tools.ietf.org/html/rfc7049#section-3.9</a> "[..]The keys
--   in every map must be sorted lowest value to highest.[...]"
decodeMapSkel :: (Ord k, FromCBOR k, FromCBOR v) => ([(k, v)] -> m) -> Decoder s m
type Dropper s = Decoder s ()
dropBytes :: Dropper s
dropInt32 :: Dropper s

-- | Drop a list of values using the supplied <a>Dropper</a> for each
--   element
dropList :: Dropper s -> Dropper s
dropMap :: Dropper s -> Dropper s -> Dropper s
dropSet :: Dropper s -> Dropper s
dropTuple :: Dropper s -> Dropper s -> Dropper s
dropTriple :: Dropper s -> Dropper s -> Dropper s -> Dropper s
dropWord8 :: Dropper s
dropWord64 :: Dropper s

-- | Deserialize a Haskell value from the external binary representation
--   (which must have been made using <tt>serialize</tt> or related
--   function).
--   
--   <i>Throws</i>: <tt><a>DeserialiseFailure</a></tt> if the given
--   external representation is invalid or does not correspond to a value
--   of the expected type.
unsafeDeserialize :: FromCBOR a => LByteString -> a

-- | Strict variant of <tt>deserialize</tt>.
unsafeDeserialize' :: FromCBOR a => ByteString -> a

-- | Turn an <a>Encoding</a> into a strict <a>ByteString</a> in CBOR binary
--   format.
toStrictByteString :: Encoding -> ByteString

-- | Deserialize a Haskell value from the external binary representation,
--   failing if there are leftovers. In a nutshell, the <tt>full</tt> here
--   implies the contract of this function is that what you feed as input
--   needs to be consumed entirely.
decodeFull :: forall a. FromCBOR a => LByteString -> Either DecoderError a
decodeFull' :: forall a. FromCBOR a => ByteString -> Either DecoderError a
decodeFullDecoder :: Text -> (forall s. Decoder s a) -> LByteString -> Either DecoderError a

-- | Remove the the semantic tag 24 from the enclosed CBOR data item,
--   decoding back the inner <a>ByteString</a> as a proper Haskell type.
--   Consume its input in full.
decodeNestedCbor :: FromCBOR a => Decoder s a

-- | Like <tt>decodeKnownCborDataItem</tt>, but assumes nothing about the
--   Haskell type we want to deserialise back, therefore it yields the
--   <a>ByteString</a> Tag 24 surrounded (stripping such tag away).
--   
--   In CBOR notation, if the data was serialised as:
--   
--   <pre>
--   &gt;&gt;&gt; 24(h'DEADBEEF')
--   </pre>
--   
--   then <a>decodeNestedCborBytes</a> yields the inner <tt>DEADBEEF</tt>,
--   unchanged.
decodeNestedCborBytes :: Decoder s ByteString
data Annotated b a
Annotated :: !b -> !a -> Annotated b a
[unAnnotated] :: Annotated b a -> !b
[annotation] :: Annotated b a -> !a

-- | A pair of offsets delimiting the beginning and end of a substring of a
--   ByteString
data ByteSpan
ByteSpan :: !ByteOffset -> !ByteOffset -> ByteSpan
class Decoded t where {
    type family BaseType t :: Type;
}
recoverBytes :: Decoded t => t -> ByteString
annotationBytes :: Functor f => LByteString -> f ByteSpan -> f ByteString

-- | A decoder for a value paired with an annotation specifying the start
--   and end of the consumed bytes.
annotatedDecoder :: Decoder s a -> Decoder s (Annotated a ByteSpan)

-- | Extract a substring of a given ByteString corresponding to the
--   offsets.
slice :: ByteString -> ByteSpan -> LByteString

-- | A decoder for a value paired with an annotation specifying the start
--   and end of the consumed bytes.
fromCBORAnnotated :: FromCBOR a => Decoder s (Annotated a ByteSpan)

-- | Decodes a value from a ByteString, requiring that the full ByteString
--   is consumed, and replaces ByteSpan annotations with the corresponding
--   substrings of the input string.
decodeFullAnnotatedBytes :: Functor f => Text -> (forall s. Decoder s (f ByteSpan)) -> LByteString -> Either DecoderError (f ByteString)

-- | Reconstruct an annotation by re-serialising the payload to a
--   ByteString.
reAnnotate :: ToCBOR a => Annotated a b -> Annotated a ByteString

-- | A value of type `Annotator a` is one that needs access to the entire |
--   bytestring used during decoding to finish construction.
newtype Annotator a
Annotator :: (FullByteString -> a) -> Annotator a
[runAnnotator] :: Annotator a -> FullByteString -> a

-- | 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.
annotatorSlice :: Decoder s (Annotator (LByteString -> a)) -> Decoder s (Annotator a)

-- | Supplies the bytestring argument to both the decoder and the produced
--   annotator.
decodeAnnotator :: Text -> (forall s. Decoder s (Annotator a)) -> LByteString -> Either DecoderError a

-- | Pairs the decoder result with an annotator.
withSlice :: Decoder s a -> Decoder s (a, Annotator LByteString)

-- | This marks the entire bytestring used during decoding, rather than the
--   | piece we need to finish constructing our value.
newtype FullByteString
Full :: LByteString -> FullByteString
