| 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.Serialise
Contents
Description
This module provides functions to serialise and deserialise Haskell
values for storage or transmission, to and from lazy
ByteString
For a full tutorial on using this module, see Codec.CBOR.Tutorial.
- serialise :: Serialise a => a -> ByteString
- deserialise :: Serialise a => ByteString -> a
- deserialiseOrFail :: Serialise a => ByteString -> Either DeserialiseFailure a
- data DeserialiseFailure :: * = DeserialiseFailure ByteOffset String
- serialiseIncremental :: Serialise a => a -> Builder
- deserialiseIncremental :: Serialise a => ST s (IDecode s a)
- data IDecode s a :: * -> * -> *
- = Partial (Maybe ByteString -> ST s (IDecode s a))
- | Done !ByteString !ByteOffset a
- | Fail !ByteString !ByteOffset DeserialiseFailure
- class Serialise a where
- writeFileSerialise :: Serialise a => FilePath -> a -> IO ()
- readFileDeserialise :: Serialise a => FilePath -> IO a
- hPutSerialise :: Serialise a => Handle -> a -> IO ()
High level, one-shot API
The following API exposes a high level interface allowing you to quickly
convert between arbitrary Haskell values (which are an instance of
SerialiseByteString
serialise :: Serialise a => a -> ByteString Source #
Serialise a Haskell value to an external binary representation.
The output is represented as a lazy ByteString and is constructed
incrementally.
Since: 0.2.0.0
deserialise :: Serialise a => ByteString -> a Source #
Deserialise a Haskell value from the external binary representation
(which must have been made using serialise or related function).
Throws: DeserialiseFailure
Since: 0.2.0.0
deserialiseOrFail :: Serialise a => ByteString -> Either DeserialiseFailure a Source #
Deserialise a Haskell value from the external binary representation,
or get back a DeserialiseFailure
Since: 0.2.0.0
Deserialisation exceptions
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
Incremental encoding interface
The following API allows you to encode or decode CBOR values incrementally, which is useful for large structures that require you to stream values in over time.
serialiseIncremental :: Serialise a => a -> Builder Source #
deserialiseIncremental :: Serialise a => ST s (IDecode s a) Source #
Deserialise a Haskell value from the external binary representation.
This allows input data to be provided incrementally, rather than all in one go. It also gives an explicit representation of deserialisation errors.
Note that the incremental behaviour is only for the input data, not the output value: the final deserialised value is constructed and returned as a whole, not incrementally.
Since: 0.2.0.0
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 |
| 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
|
The Serialise
Serialiseclass Serialise a where Source #
Types that are instances of the Serialise
Since: 0.2.0.0
Methods
encode :: a -> Encoding Source #
Definition for encoding a given type into a binary
representation, using the EncodingMonoid
Since: 0.2.0.0
encode :: (Generic a, GSerialiseEncode (Rep a)) => a -> Encoding Source #
Definition for encoding a given type into a binary
representation, using the EncodingMonoid
Since: 0.2.0.0
decode :: Decoder s a Source #
Definition of a given Decoder
Since: 0.2.0.0
decode :: (Generic a, GSerialiseDecode (Rep a)) => Decoder s a Source #
Definition of a given Decoder
Since: 0.2.0.0
encodeList :: [a] -> Encoding Source #
Utility to support specialised encoding for some list type -
used for CharString
Since: 0.2.0.0
decodeList :: Decoder s [a] Source #
Instances
IO operations
Convenient utilities for basic IO
FilePath
FilePathArguments
| :: Serialise a | |
| => FilePath | The file to write to. |
| -> a | The value to be serialised and written. |
| -> IO () |
Serialise a ByteString
Since: 0.2.0.0
Read the specified file (internally, by reading a ByteStringdeserialise
Throws: DeserialiseFailure
Since: 0.2.0.0
Handle
Handle