| 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
Description
This module provides functions to serialise and deserialise Haskell
values for storage or transmission, to and from lazy
s. It also provides a type class
and utilities to help you make your types serialisable.
ByteString
For a full tutorial on using this module, see Codec.Serialise.Tutorial .
Synopsis
- 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
- encode :: a -> Encoding
- decode :: Decoder s a
- encodeList :: [a] -> Encoding
- decodeList :: Decoder s [a]
- 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
) and lazy
Serialise
s.
ByteString
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
:
if the given external
representation is invalid or does not correspond to a value of the
expected type.
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 Source #
An exception type that may be returned (by pure functions) or thrown (by IO actions) that fail to deserialise a given input.
Since: cborg-0.2.0.0
Constructors
| DeserialiseFailure ByteOffset String |
Instances
| Eq DeserialiseFailure | |
|
Defined in Codec.CBOR.Read Methods (==) :: DeserialiseFailure -> DeserialiseFailure -> Bool Source # (/=) :: DeserialiseFailure -> DeserialiseFailure -> Bool Source # |
|
| Show DeserialiseFailure | |
|
Defined in Codec.CBOR.Read |
|
| Exception DeserialiseFailure | |
|
Defined in Codec.CBOR.Read Methods toException :: DeserialiseFailure -> SomeException Source # fromException :: SomeException -> Maybe DeserialiseFailure Source # |
|
| NFData DeserialiseFailure | |
|
Defined in Codec.CBOR.Read Methods rnf :: DeserialiseFailure -> () Source # |
|
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
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
class
Serialise
class Serialise a where Source #
Types that are instances of the
class allow values
to be quickly encoded or decoded directly to a CBOR representation,
for object transmission or storage.
Serialise
Since: 0.2.0.0
Minimal complete definition
Nothing
Methods
encode :: a -> Encoding Source #
Definition for encoding a given type into a binary
representation, using the
Encoding
.
Monoid
Since: 0.2.0.0
decode :: Decoder s a Source #
Definition of a given
for a type.
Decoder
Since: 0.2.0.0
encodeList :: [a] -> Encoding Source #
Utility to support specialised encoding for some list type -
used for
/
Char
instances in this package.
String
Since: 0.2.0.0
decodeList :: Decoder s [a] Source #
Instances
IO operations
Convenient utilities for basic
operations.
IO
FilePath
API
FilePath
Arguments
| :: Serialise a | |
| => FilePath |
The file to write to. |
| -> a |
The value to be serialised and written. |
| -> IO () |
Serialise a
and write it directly to the
specified file.
ByteString
Since: 0.2.0.0
Read the specified file (internally, by reading a
)
and attempt to decode it into a Haskell value using
ByteString
(the type of which is determined by the choice of the result type).
deserialise
Throws
:
if the file fails to
deserialise properly.
DeserialiseFailure
Since: 0.2.0.0
Handle
API
Handle