cborg-0.2.10.0: Concise Binary Object Representation (CBOR)

Copyright | (c) Duncan Coutts 2015-2017
License | BSD3-style (see LICENSE.txt)
Maintainer | duncan@community.haskell.org
Stability | experimental
Portability | non-portable (GHC extensions)
Safe Haskell | None
Language | Haskell2010

Codec.CBOR.Read

Description

Tools for reading values in a CBOR-encoded format back into ordinary values.

Synopsis

- deserialiseFromBytes :: (forall s. Decoder s a) -> ByteString -> Either DeserialiseFailure (ByteString, a)
- deserialiseFromBytesWithSize :: (forall s. Decoder s a) -> ByteString -> Either DeserialiseFailure (ByteString, ByteOffset, a)
- deserialiseIncremental :: Decoder s a -> ST s (IDecode s a)
- data DeserialiseFailure = DeserialiseFailure ByteOffset String
- data IDecode s a
  - = Partial (Maybe ByteString -> ST s (IDecode s a))
  - | Done !ByteString !ByteOffset a
  - | Fail !ByteString !ByteOffset DeserialiseFailure
- type ByteOffset = Int64

# Documentation

deserialiseFromBytes :: (forall s. Decoder s a) -> ByteString -> Either DeserialiseFailure (ByteString, a) #

Given a `Decoder` and some `ByteString` representing an encoded CBOR value, return `Either` the decoded CBOR value or an error. In addition to the decoded value return any remaining input content.

Since: 0.2.0.0

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

Given a `Decoder` and some `ByteString` representing an encoded CBOR value, return `Either` the decoded CBOR value or an error. In addition to the decoded value return any remaining input content and the number of bytes consumed.

Since: 0.2.0.0

deserialiseIncremental :: Decoder s a -> ST s (IDecode s a) #

Run a `Decoder` incrementally, returning a continuation representing the result of the incremental decode.

Since: 0.2.0.0

data DeserialiseFailure #

An exception type that may be returned (by pure functions) or thrown (by IO actions) that fail to deserialise a given input.

Since: 0.2.0.0

Constructors

DeserialiseFailure ByteOffset String |

#### Instances

Instances details

NFData DeserialiseFailure # |
Instance details Defined in Codec.CBOR.Read Methods rnf :: DeserialiseFailure -> () #
Exception DeserialiseFailure # |
Instance details Defined in Codec.CBOR.Read Methods toException :: DeserialiseFailure -> SomeException # fromException :: SomeException -> Maybe DeserialiseFailure # displayException :: DeserialiseFailure -> String # backtraceDesired :: DeserialiseFailure -> Bool #
Show DeserialiseFailure # |
Instance details Defined in Codec.CBOR.Read Methods showsPrec :: Int -> DeserialiseFailure -> ShowS # show :: DeserialiseFailure -> String # showList :: [DeserialiseFailure] -> ShowS #
Eq DeserialiseFailure # |
Instance details Defined in Codec.CBOR.Read Methods (==) :: DeserialiseFailure -> DeserialiseFailure -> Bool # (/=) :: DeserialiseFailure -> DeserialiseFailure -> Bool #

data IDecode s a #

An Incremental decoder, used to represent the result of attempting to run a decoder over a given input, and return a value of type `a`.

Constructors

Partial (Maybe ByteString -> ST s (IDecode s a)) | The decoder has consumed the available input and needs more to continue. Provide `Just` if more input is available and `Nothing` otherwise, and you will get a new `IDecode`.
Done !ByteString !ByteOffset a | The decoder has successfully finished. Except for the output value you also get any unused input as well as the number of bytes consumed.
Fail !ByteString !ByteOffset DeserialiseFailure | The decoder ran into an error. The decoder either used `fail` or was not provided enough input. Contains any unconsumed input, the number of bytes consumed, and a `DeserialiseFailure` exception describing the reason why the failure occurred.

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`.