Moduleserialise-0.2.6.1Haskell2010

Codec.Serialise

This module provides functions to serialise and deserialise Haskell values for storage or transmission, to and from lazy ByteStrings. It also provides a type class and utilities to help you make your types serialisable.

For a full tutorial on using this module, see Codec.Serialise.Tutorial.

Contents

High level, one-shot API
Deserialisation exceptions
Incremental encoding interface
The Serialise class
IO operations
FilePath API
Handle API

Synopsis

value serialise
value deserialise
value deserialiseOrFail
data DeserialiseFailure
value serialiseIncremental
value deserialiseIncremental
data IDecode
class Serialise
value writeFileSerialise
value readFileDeserialise
value hPutSerialise

Packageserialise-0.2.6.1
Exports11
LanguageHaskell2010
LicenceBSD-3-Clause
SourceSerialise.hs

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 Serialise) and lazy ByteStrings.

valueserialise :: 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.

valuedeserialise :: 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 if the given external representation is invalid or does not correspond to a value of the expected type.

valuedeserialiseOrFail

Source#

Deserialise a Haskell value from the external binary representation, or get back a DeserialiseFailure.

Deserialisation exceptions

datadata DeserialiseFailure

Source#

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

Constructors

DeserialiseFailure ByteOffset String

Instances4Eq, Show, Exception, NFData

Eq DeserialiseFailureDefined in cborg-0.2.10.0 · Codec.CBOR.Read
Show DeserialiseFailureDefined in cborg-0.2.10.0 · Codec.CBOR.Read
Exception DeserialiseFailureDefined in cborg-0.2.10.0 · Codec.CBOR.Read
NFData DeserialiseFailureDefined in cborg-0.2.10.0 · Codec.CBOR.Read

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.

valueserialiseIncremental :: Serialise a => a -> Builder

Source#

Serialise a Haskell value to an external binary representation.

The output is represented as a Builder and is constructed incrementally. The representation as a Builder allows efficient concatenation with other data.

valuedeserialiseIncremental :: 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.

datadata IDecode s a

Source#

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.

The `Serialise` class

classclass Serialise a where

Source#

Types that are instances of the Serialise class allow values to be quickly encoded or decoded directly to a CBOR representation, for object transmission or storage.

Methods

encode :: a -> Encoding
Definition for encoding a given type into a binary representation, using the Encoding Monoid.
decode :: Decoder s a
Definition of a given Decoder for a type.
encodeList :: [a] -> Encoding
Utility to support specialised encoding for some list type - used for Char/String instances in this package.
decodeList :: Decoder s [a]
Utility to support specialised decoding for some list type - used for Char/String instances in this package.

Instances114Serialise, …

Serialise ByteStringDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise ByteStringDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise ShortByteStringDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise TermDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise IntSetDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise VoidDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise IntegerDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise NaturalDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise AllDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise AnyDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise SomeTypeRepDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise VersionDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise FingerprintDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CCharDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CClockDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CDoubleDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CFloatDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CIntDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CIntMaxDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CIntPtrDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CLLongDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CLongDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CPtrdiffDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CSCharDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CSUSecondsDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CShortDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CSigAtomicDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CSizeDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CTimeDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CUCharDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CUIntDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CUIntMaxDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CUIntPtrDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CULLongDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CULongDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CUSecondsDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CUShortDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CWcharDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise ExitCodeDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise Int16Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise Int32Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise Int64Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise Int8Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise BoolDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise CharDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise DoubleDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise FloatDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise IntDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise KindRepDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise LevityDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise OrderingDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise RuntimeRepDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise TyConDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise TypeLitSortDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise VecCountDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise VecElemDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise WordDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise Word16Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise Word32Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise Word64Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise Word8Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise HalfDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise TextDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise TextDefined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise UTCTimeDefined in serialise-0.2.6.1 · Codec.Serialise.Class
UTCTime is encoded using the extended time format which is currently in Internet Draft state, https://tools.ietf.org/html/draft-bormann-cbor-time-tag-00.
Serialise ()Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise a => Serialise (Complex a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise a => Serialise (First a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise a => Serialise (Last a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise a => Serialise (Max a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise a => Serialise (Min a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise a => Serialise (WrappedMonoid a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise a => Serialise (IntMap a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise a => Serialise (Seq a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise a => Serialise (Tree a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise a => Serialise (NonEmpty a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise a => Serialise (Identity a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise a => Serialise (First a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise a => Serialise (Last a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise a => Serialise (Down a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise a => Serialise (Dual a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise a => Serialise (Product a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise a => Serialise (Sum a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise a => Serialise (ZipList a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise a => Serialise (Maybe a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise a => Serialise (Maybe a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise a => Serialise (Vector a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise a => Serialise [a]Defined in serialise-0.2.6.1 · Codec.Serialise.Class
(Ord a, Serialise a) => Serialise (Set a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
(Serialise a, Storable a) => Serialise (Vector a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
(Serialise a, Integral a) => Serialise (Ratio a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
(Serialise a, Hashable a, Eq a) => Serialise (HashSet a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
(Serialise a, Prim a) => Serialise (Vector a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
(Serialise a, Unbox a) => Serialise (Vector a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Typeable a => Serialise (TypeRep a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise (Fixed e)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Values are serialised in units of least precision represented as Integer.
Serialise (Proxy a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
(Ord k, Serialise k, Serialise v) => Serialise (Map k v)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
(Serialise a, Serialise b) => Serialise (Either a b)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
(Serialise a, Serialise b) => Serialise (Either a b)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
(Serialise a, Serialise b) => Serialise (These a b)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
(Serialise a, Serialise b) => Serialise (Pair a b)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
(Serialise a, Serialise b) => Serialise (These a b)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
(Serialise a, Serialise b) => Serialise (a, b)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
(Serialise k, Hashable k, Eq k, Serialise v) => Serialise (HashMap k v)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise (f a) => Serialise (Alt f a)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
Serialise a => Serialise (Const a b)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
(Serialise a, Serialise b, Serialise c) => Serialise (a, b, c)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
(Serialise a, Serialise b, Serialise c, Serialise d) => Serialise (a, b, c, d)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
(Serialise a, Serialise b, Serialise c, Serialise d, Serialise e) => Serialise (a, b, c, d, e)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
(Serialise a, Serialise b, Serialise c, Serialise d, Serialise e, Serialise f) => Serialise (a, b, c, d, e, f)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
(Serialise a, Serialise b, Serialise c, Serialise d, Serialise e, Serialise f, Serialise g) => Serialise (a, b, c, d, e, f, g)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
(Serialise a, Serialise b, Serialise c, Serialise d, Serialise e, Serialise f, Serialise g, Serialise h) => Serialise (a, b, c, d, e, f, g, h)Defined in serialise-0.2.6.1 · Codec.Serialise.Class
(Serialise a, Serialise b, Serialise c, Serialise d, Serialise e, Serialise f, Serialise g, Serialise h, Serialise i) => Serialise (a, b, c, d, e, f, g, h, i)Defined in serialise-0.2.6.1 · Codec.Serialise.Class

IO operations

Convenient utilities for basic IO operations.

`FilePath` API

valuewriteFileSerialise

:: Serialise a
=> FilePath
The file to write to.
-> a
The value to be serialised and written.
-> IO ()

Source#

Serialise a ByteString and write it directly to the specified file.

valuereadFileDeserialise

:: Serialise a
=> FilePath
The file to read from.
-> IO a
The deserialised value.

Source#

Read the specified file (internally, by reading a ByteString) and attempt to decode it into a Haskell value using deserialise (the type of which is determined by the choice of the result type).

Throws: DeserialiseFailure if the file fails to deserialise properly.

`Handle` API

valuehPutSerialise

:: Serialise a
=> Handle
The Handle to write to.
-> a
The value to be serialised and written.
-> IO ()

Source#

Serialise a ByteString (via serialise) and write it directly to the specified Handle.

High level, one-shot API

Deserialisation exceptions

Constructors

Incremental encoding interface

Constructors

The Serialise class

Methods

IO operations

FilePath API

Handle API

The `Serialise` class

`FilePath` API

`Handle` API