Codec.CBOR.Decoding

High level API for decoding values that were encoded with the Codec.CBOR.Encoding module, using a Monad based interface.

Decode primitive operations

data Decoder s a

A continuation-based decoder, used for decoding values that were previously encoded using the Codec.CBOR.Encoding module. As Decoder has a Monad instance, you can easily write Decoders monadically for building your deserialisation logic.

Since: 0.2.0.0

Instances

Monad (Decoder s)

Since: 0.2.0.0

Defined in Codec.CBOR.Decoding

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

fail :: String -> Decoder s a

Functor (Decoder s)

Since: 0.2.0.0

Defined in Codec.CBOR.Decoding

Methods

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

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

MonadFail (Decoder s)

Since: 0.2.0.0

Defined in Codec.CBOR.Decoding

Methods

fail :: String -> Decoder s a

Applicative (Decoder s)

Since: 0.2.0.0

Defined in Codec.CBOR.Decoding

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

data DecodeAction s a

An action, representing a step for a decoder to taken and a continuation to invoke with the expected value.

Since: 0.2.0.0

Constructors

ConsumeWord (Word# -> ST s (DecodeAction s a))

ConsumeWord8 (Word# -> ST s (DecodeAction s a))

ConsumeWord16 (Word# -> ST s (DecodeAction s a))

ConsumeWord32 (Word# -> ST s (DecodeAction s a))

ConsumeNegWord (Word# -> ST s (DecodeAction s a))

ConsumeInt (Int# -> ST s (DecodeAction s a))

ConsumeInt8 (Int# -> ST s (DecodeAction s a))

ConsumeInt16 (Int# -> ST s (DecodeAction s a))

ConsumeInt32 (Int# -> ST s (DecodeAction s a))

ConsumeListLen (Int# -> ST s (DecodeAction s a))

ConsumeMapLen (Int# -> ST s (DecodeAction s a))

ConsumeTag (Word# -> ST s (DecodeAction s a))

ConsumeInteger (Integer -> ST s (DecodeAction s a))

ConsumeFloat (Float# -> ST s (DecodeAction s a))

ConsumeDouble (Double# -> ST s (DecodeAction s a))

ConsumeBytes (ByteString -> ST s (DecodeAction s a))

ConsumeByteArray (ByteArray -> ST s (DecodeAction s a))

ConsumeString (Text -> ST s (DecodeAction s a))

ConsumeUtf8ByteArray (ByteArray -> ST s (DecodeAction s a))

ConsumeBool (Bool -> ST s (DecodeAction s a))

ConsumeSimple (Word# -> ST s (DecodeAction s a))

ConsumeBytesIndef (ST s (DecodeAction s a))

ConsumeStringIndef (ST s (DecodeAction s a))

ConsumeListLenIndef (ST s (DecodeAction s a))

ConsumeMapLenIndef (ST s (DecodeAction s a))

ConsumeNull (ST s (DecodeAction s a))

ConsumeListLenOrIndef (Int# -> ST s (DecodeAction s a))

ConsumeMapLenOrIndef (Int# -> ST s (DecodeAction s a))

ConsumeBreakOr (Bool -> ST s (DecodeAction s a))

PeekTokenType (TokenType -> ST s (DecodeAction s a))

PeekAvailable (Int# -> ST s (DecodeAction s a))

PeekByteOffset (Int# -> ST s (DecodeAction s a))

ConsumeWordCanonical (Word# -> ST s (DecodeAction s a))

ConsumeWord8Canonical (Word# -> ST s (DecodeAction s a))

ConsumeWord16Canonical (Word# -> ST s (DecodeAction s a))

ConsumeWord32Canonical (Word# -> ST s (DecodeAction s a))

ConsumeNegWordCanonical (Word# -> ST s (DecodeAction s a))

ConsumeIntCanonical (Int# -> ST s (DecodeAction s a))

ConsumeInt8Canonical (Int# -> ST s (DecodeAction s a))

ConsumeInt16Canonical (Int# -> ST s (DecodeAction s a))

ConsumeInt32Canonical (Int# -> ST s (DecodeAction s a))

ConsumeListLenCanonical (Int# -> ST s (DecodeAction s a))

ConsumeMapLenCanonical (Int# -> ST s (DecodeAction s a))

ConsumeTagCanonical (Word# -> ST s (DecodeAction s a))

ConsumeIntegerCanonical (Integer -> ST s (DecodeAction s a))

ConsumeFloat16Canonical (Float# -> ST s (DecodeAction s a))

ConsumeFloatCanonical (Float# -> ST s (DecodeAction s a))

ConsumeDoubleCanonical (Double# -> ST s (DecodeAction s a))

ConsumeBytesCanonical (ByteString -> ST s (DecodeAction s a))

ConsumeByteArrayCanonical (ByteArray -> ST s (DecodeAction s a))

ConsumeStringCanonical (Text -> ST s (DecodeAction s a))

ConsumeUtf8ByteArrayCanonical (ByteArray -> ST s (DecodeAction s a))

ConsumeSimpleCanonical (Word# -> ST s (DecodeAction s a))

Fail String

Done a

liftST :: ST s a -> Decoder s a

Lift an ST action into a Decoder. Useful for, e.g., leveraging in-place mutation to efficiently build a deserialised value.

Since: 0.2.0.0

getDecodeAction :: Decoder s a -> ST s (DecodeAction s a)

Given a Decoder, give us the DecodeAction

Since: 0.2.0.0

Read input tokens

decodeWord :: Decoder s Word

Decode a Word.

Since: 0.2.0.0

decodeWord8 :: Decoder s Word8

Decode a Word8.

Since: 0.2.0.0

decodeWord16 :: Decoder s Word16

Decode a Word16.

Since: 0.2.0.0

decodeWord32 :: Decoder s Word32

Decode a Word32.

Since: 0.2.0.0

decodeWord64 :: Decoder s Word64

Decode a Word64.

Since: 0.2.0.0

decodeNegWord :: Decoder s Word

Decode a negative Word.

Since: 0.2.0.0

decodeNegWord64 :: Decoder s Word64

Decode a negative Word64.

Since: 0.2.0.0

decodeInt :: Decoder s Int

Decode an Int.

Since: 0.2.0.0

decodeInt8 :: Decoder s Int8

Decode an Int8.

Since: 0.2.0.0

decodeInt16 :: Decoder s Int16

Decode an Int16.

Since: 0.2.0.0

decodeInt32 :: Decoder s Int32

Decode an Int32.

Since: 0.2.0.0

decodeInt64 :: Decoder s Int64

Decode an Int64.

Since: 0.2.0.0

decodeInteger :: Decoder s Integer

Decode an Integer.

Since: 0.2.0.0

decodeFloat :: Decoder s Float

Decode a Float.

Since: 0.2.0.0

decodeDouble :: Decoder s Double

Decode a Double.

Since: 0.2.0.0

decodeBytes :: Decoder s ByteString

Decode a string of bytes as a ByteString.

Since: 0.2.0.0

decodeBytesIndef :: Decoder s ()

Decode a token marking the beginning of an indefinite length set of bytes.

Since: 0.2.0.0

decodeByteArray :: Decoder s ByteArray

Decode a string of bytes as a ByteArray.

Also note that this will eagerly copy the content out of the input to ensure that the input does not leak in the event that the ByteArray is live but not forced.

Since: 0.2.0.0

decodeString :: Decoder s Text

Decode a textual string as a piece of Text.

Since: 0.2.0.0

decodeStringIndef :: Decoder s ()

Decode a token marking the beginning of an indefinite length string.

Since: 0.2.0.0

decodeUtf8ByteArray :: Decoder s ByteArray

Decode a textual string as UTF-8 encoded ByteArray. Note that the result is not validated to be well-formed UTF-8.

Also note that this will eagerly copy the content out of the input to ensure that the input does not leak in the event that the ByteArray is live but not forced.

Since: 0.2.0.0

decodeListLen :: Decoder s Int

Decode the length of a list.

Since: 0.2.0.0

decodeListLenIndef :: Decoder s ()

Decode a token marking the beginning of a list of indefinite length.

Since: 0.2.0.0

decodeMapLen :: Decoder s Int

Decode the length of a map.

Since: 0.2.0.0

decodeMapLenIndef :: Decoder s ()

Decode a token marking the beginning of a map of indefinite length.

Since: 0.2.0.0

decodeTag :: Decoder s Word

Decode an arbitrary tag and return it as a Word.

Since: 0.2.0.0

decodeTag64 :: Decoder s Word64

Decode an arbitrary 64-bit tag and return it as a Word64.

Since: 0.2.0.0

decodeBool :: Decoder s Bool

Decode a bool.

Since: 0.2.0.0

decodeNull :: Decoder s ()

Decode a nullary value, and return a unit value.

Since: 0.2.0.0

decodeSimple :: Decoder s Word8

Decode a simple CBOR value and give back a Word8. You probably don't ever need to use this.

Since: 0.2.0.0

Specialised Read input token operations

decodeWordOf

Arguments

:: Word

Expected value of the decoded word

-> Decoder s ()

Attempt to decode a word with decodeWord, and ensure the word is exactly as expected, or fail.

Since: 0.2.0.0

decodeListLenOf :: Int -> Decoder s ()

Attempt to decode a list length using decodeListLen, and ensure it is exactly the specified length, or fail.

Since: 0.2.0.0

Branching operations

decodeListLenOrIndef :: Decoder s (Maybe Int)

Attempt to decode a token for the length of a finite, known list, or an indefinite list. If Nothing is returned, then an indefinite length list occurs afterwords. If Just x is returned, then a list of length x is encoded.

Since: 0.2.0.0

decodeMapLenOrIndef :: Decoder s (Maybe Int)

Attempt to decode a token for the length of a finite, known map, or an indefinite map. If Nothing is returned, then an indefinite length map occurs afterwords. If Just x is returned, then a map of length x is encoded.

Since: 0.2.0.0

decodeBreakOr :: Decoder s Bool

Attempt to decode a Break token, and if that was successful, return True. If the token was of any other type, return False.

Since: 0.2.0.0

Inspecting the token type

peekTokenType :: Decoder s TokenType

Peek at the current token we're about to decode, and return a TokenType specifying what it is.

Since: 0.2.0.0

data TokenType

The type of a token, which a decoder can ask for at an arbitrary time.

Since: 0.2.0.0

Constructors

TypeUInt

TypeUInt64

TypeNInt

TypeNInt64

TypeInteger

TypeFloat16

TypeFloat32

TypeFloat64

TypeBytes

TypeBytesIndef

TypeString

TypeStringIndef

TypeListLen

TypeListLen64

TypeListLenIndef

TypeMapLen

TypeMapLen64

TypeMapLenIndef

TypeTag

TypeTag64

TypeBool

TypeNull

TypeSimple

TypeBreak

TypeInvalid

Instances

Bounded TokenType

Defined in Codec.CBOR.Decoding

Methods

minBound :: TokenType

maxBound :: TokenType

Enum TokenType

Defined in Codec.CBOR.Decoding

Methods

succ :: TokenType -> TokenType

pred :: TokenType -> TokenType

toEnum :: Int -> TokenType

fromEnum :: TokenType -> Int

enumFrom :: TokenType -> [TokenType]

enumFromThen :: TokenType -> TokenType -> [TokenType]

enumFromTo :: TokenType -> TokenType -> [TokenType]

enumFromThenTo :: TokenType -> TokenType -> TokenType -> [TokenType]

Eq TokenType

Defined in Codec.CBOR.Decoding

Methods

(==) :: TokenType -> TokenType -> Bool

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

Ord TokenType

Defined in Codec.CBOR.Decoding

Methods

compare :: TokenType -> TokenType -> Ordering

(<) :: TokenType -> TokenType -> Bool

(<=) :: TokenType -> TokenType -> Bool

(>) :: TokenType -> TokenType -> Bool

(>=) :: TokenType -> TokenType -> Bool

max :: TokenType -> TokenType -> TokenType

min :: TokenType -> TokenType -> TokenType

Show TokenType

Defined in Codec.CBOR.Decoding

Methods

showsPrec :: Int -> TokenType -> ShowS

show :: TokenType -> String

showList :: [TokenType] -> ShowS

Special operations

peekAvailable :: Decoder s Int

Peek and return the length of the current buffer that we're running our decoder on.

Since: 0.2.0.0

type ByteOffset = Int64

A 0-based offset within the overall byte sequence that makes up the input to the Decoder.

This is an Int64 since Decoder is incremental and can decode more data than fits in memory at once. This is also compatible with the result type of length.

peekByteOffset :: Decoder s ByteOffset

Get the current ByteOffset in the input byte sequence of the Decoder.

The Decoder does not provide any facility to get at the input data directly (since that is tricky with an incremental decoder). The next best is this primitive which can be used to keep track of the offset within the input bytes that makes up the encoded form of a term.

By keeping track of the byte offsets before and after decoding a subterm (a pattern captured by decodeWithByteSpan) and if the overall input data is retained then this is enables later retrieving the span of bytes for the subterm.

Since: 0.2.2.0

decodeWithByteSpan :: Decoder s a -> Decoder s (a, ByteOffset, ByteOffset)

This captures the pattern of getting the byte offsets before and after decoding a subterm.

!before <- peekByteOffset
x <- decode
!after  <- peekByteOffset

Canonical CBOR

https://tools.ietf.org/html/rfc7049#section-3.9

In general in CBOR there can be multiple representations for the same value, for example the integer 0 can be represented in 8, 16, 32 or 64 bits. This library always encoded values in the shortest representation but on decoding allows any valid encoding. For some applications it is useful or important to only decode the canonical encoding. The decoder primitives here are to allow applications to implement canonical decoding.

It is important to note that achieving a canonical representation is not simply about using these primitives. For example consider a typical CBOR encoding of a Haskell Set data type. This will be encoded as a CBOR list of the set elements. A typical implementation might be:

encodeSet = encodeList . Set.toList
decodeSet = fmap Set.fromList . decodeList

This does not enforce a canonical encoding. The decoder above will allow set elements in any order. The use of Set.fromList forgets the order. To enforce that the decoder only accepts the canonical encoding it will have to check that the elements in the list are strictly increasing. Similar issues arise in many other data types, wherever there is redundancy in the external representation.

The decoder primitives in this section are not much more expensive than their normal counterparts. If checking the canonical encoding property is critical then a technique that is more expensive but easier to implement and test is to decode normally, re-encode and check the serialised bytes are the same.

decodeWordCanonical :: Decoder s Word

Decode canonical representation of a Word.

Since: 0.2.0.0

decodeWord8Canonical :: Decoder s Word8

Decode canonical representation of a Word8.

Since: 0.2.0.0

decodeWord16Canonical :: Decoder s Word16

Decode canonical representation of a Word16.

Since: 0.2.0.0

decodeWord32Canonical :: Decoder s Word32

Decode canonical representation of a Word32.

Since: 0.2.0.0

decodeWord64Canonical :: Decoder s Word64

Decode canonical representation of a Word64.

Since: 0.2.0.0

decodeNegWordCanonical :: Decoder s Word

Decode canonical representation of a negative Word.

Since: 0.2.0.0

decodeNegWord64Canonical :: Decoder s Word64

Decode canonical representation of a negative Word64.

Since: 0.2.0.0

decodeIntCanonical :: Decoder s Int

Decode canonical representation of an Int.

Since: 0.2.0.0

decodeInt8Canonical :: Decoder s Int8

Decode canonical representation of an Int8.

Since: 0.2.0.0

decodeInt16Canonical :: Decoder s Int16

Decode canonical representation of an Int16.

Since: 0.2.0.0

decodeInt32Canonical :: Decoder s Int32

Decode canonical representation of an Int32.

Since: 0.2.0.0

decodeInt64Canonical :: Decoder s Int64

Decode canonical representation of an Int64.

Since: 0.2.0.0

decodeBytesCanonical :: Decoder s ByteString

Decode canonical representation of a string of bytes as a ByteString.

Since: 0.2.1.0

decodeByteArrayCanonical :: Decoder s ByteArray

Decode canonical representation of a string of bytes as a ByteArray.

Also note that this will eagerly copy the content out of the input to ensure that the input does not leak in the event that the ByteArray is live but not forced.

Since: 0.2.1.0

decodeStringCanonical :: Decoder s Text

Decode canonical representation of a textual string as a piece of Text.

Since: 0.2.1.0

decodeUtf8ByteArrayCanonical :: Decoder s ByteArray

Decode canonical representation of a textual string as UTF-8 encoded ByteArray. Note that the result is not validated to be well-formed UTF-8.

Also note that this will eagerly copy the content out of the input to ensure that the input does not leak in the event that the ByteArray is live but not forced.

Since: 0.2.1.0

decodeListLenCanonical :: Decoder s Int

Decode canonical representation of the length of a list.

Since: 0.2.0.0

decodeMapLenCanonical :: Decoder s Int

Decode canonical representation of the length of a map.

Since: 0.2.0.0

decodeTagCanonical :: Decoder s Word

Decode canonical representation of an arbitrary tag and return it as a Word.

Since: 0.2.0.0

decodeTag64Canonical :: Decoder s Word64

Decode canonical representation of an arbitrary 64-bit tag and return it as a Word64.

Since: 0.2.0.0

decodeIntegerCanonical :: Decoder s Integer

Decode canonical representation of an Integer.

Since: 0.2.0.0

decodeFloat16Canonical :: Decoder s Float

Decode canonical representation of a half-precision Float.

Since: 0.2.0.0

decodeFloatCanonical :: Decoder s Float

Decode canonical representation of a Float.

Since: 0.2.0.0

decodeDoubleCanonical :: Decoder s Double

Decode canonical representation of a Double.

Since: 0.2.0.0

decodeSimpleCanonical :: Decoder s Word8

Decode canonical representation of a simple CBOR value and give back a Word8. You probably don't ever need to use this.

Since: 0.2.0.0

decodeWordCanonicalOf

Arguments

:: Word

Expected value of the decoded word

-> Decoder s ()

Attempt to decode canonical representation of a word with decodeWordCanonical, and ensure the word is exactly as expected, or fail.

Since: 0.2.0.0

decodeListLenCanonicalOf :: Int -> Decoder s ()

Attempt to decode canonical representation of a list length using decodeListLenCanonical, and ensure it is exactly the specified length, or fail.

Since: 0.2.0.0

Sequence operations

decodeSequenceLenIndef :: (r -> a -> r) -> r -> (r -> r') -> Decoder s a -> Decoder s r'

Decode an indefinite sequence length.

Since: 0.2.0.0

decodeSequenceLenN :: (r -> a -> r) -> r -> (r -> r') -> Int -> Decoder s a -> Decoder s r'

Decode a sequence length.

Since: 0.2.0.0