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 #
Constructors
DeserialiseFailure ByteOffset String |
Instances
Exception DeserialiseFailure | |
Defined in Codec.CBOR.Read Methods toException :: DeserialiseFailure -> SomeException fromException :: SomeException -> Maybe DeserialiseFailure displayException :: DeserialiseFailure -> String | |
Show DeserialiseFailure | |
Defined in Codec.CBOR.Read Methods showsPrec :: Int -> DeserialiseFailure -> ShowS show :: DeserialiseFailure -> String showList :: [DeserialiseFailure] -> ShowS | |
NFData DeserialiseFailure | |
Defined in Codec.CBOR.Read Methods rnf :: DeserialiseFailure -> () | |
Eq DeserialiseFailure | |
Defined in Codec.CBOR.Read Methods (==) :: DeserialiseFailure -> DeserialiseFailure -> Bool (/=) :: DeserialiseFailure -> DeserialiseFailure -> Bool |
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
Constructors
Partial (Maybe ByteString -> ST s (IDecode s a)) | |
Done !ByteString !ByteOffset a | |
Fail !ByteString !ByteOffset DeserialiseFailure |
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
default encode :: (Generic a, GSerialiseEncode (Rep a)) => a -> Encoding Source #
decode :: Decoder s a Source #
Definition of a given
for a type.Decoder
Since: 0.2.0.0
default decode :: (Generic a, GSerialiseDecode (Rep a)) => Decoder s a Source #
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 #
Utility to support specialised decoding for some list type -
used for
/Char
instances in this package.String
Since: 0.2.0.0
Instances
Serialise All Source # | Since: 0.2.0.0 |
Serialise Any Source # | Since: 0.2.0.0 |
Serialise SomeTypeRep Source # | Since: 0.2.0.0 |
Serialise Version Source # | Since: 0.2.0.0 |
Serialise CChar Source # | Since: 0.2.0.0 |
Serialise CClock Source # | Since: 0.2.0.0 |
Serialise CDouble Source # | Since: 0.2.0.0 |
Serialise CFloat Source # | Since: 0.2.0.0 |
Serialise CInt Source # | Since: 0.2.0.0 |
Serialise CIntMax Source # | Since: 0.2.0.0 |
Serialise CIntPtr Source # | Since: 0.2.0.0 |
Serialise CLLong Source # | Since: 0.2.0.0 |
Serialise CLong Source # | Since: 0.2.0.0 |
Serialise CPtrdiff Source # | Since: 0.2.0.0 |
Serialise CSChar Source # | Since: 0.2.0.0 |
Serialise CSUSeconds Source # | Since: 0.2.0.0 |
Serialise CShort Source # | Since: 0.2.0.0 |
Serialise CSigAtomic Source # | Since: 0.2.0.0 |
Serialise CSize Source # | Since: 0.2.0.0 |
Serialise CTime Source # | Since: 0.2.0.0 |
Serialise CUChar Source # | Since: 0.2.0.0 |
Serialise CUInt Source # | Since: 0.2.0.0 |
Serialise CUIntMax Source # | Since: 0.2.0.0 |
Serialise CUIntPtr Source # | Since: 0.2.0.0 |
Serialise CULLong Source # | Since: 0.2.0.0 |
Serialise CULong Source # | Since: 0.2.0.0 |
Serialise CUSeconds Source # | Since: 0.2.0.0 |
Serialise CUShort Source # | Since: 0.2.0.0 |
Serialise CWchar Source # | Since: 0.2.0.0 |
Serialise Void Source # | Since: 0.2.4.0 |
Serialise Fingerprint Source # | Since: 0.2.0.0 |
Serialise ExitCode Source # | Since: 0.2.0.0 |
Serialise Int16 Source # | Since: 0.2.0.0 |
Serialise Int32 Source # | Since: 0.2.0.0 |
Serialise Int64 Source # | Since: 0.2.0.0 |
Serialise Int8 Source # | Since: 0.2.0.0 |
Serialise Word16 Source # | Since: 0.2.0.0 |
Serialise Word32 Source # | Since: 0.2.0.0 |
Serialise Word64 Source # | Since: 0.2.0.0 |
Serialise Word8 Source # | Since: 0.2.0.0 |
Serialise ByteString Source # | Since: 0.2.0.0 |
Serialise ByteString Source # | Since: 0.2.0.0 |
Serialise ShortByteString Source # | Since: 0.2.0.0 |
Serialise Term Source # | Since: 0.2.0.0 |
Serialise IntSet Source # | Since: 0.2.0.0 |
Serialise KindRep Source # | Since: 0.2.0.0 |
Serialise Ordering Source # | Since: 0.2.0.0 |
Serialise TyCon Source # | Since: 0.2.0.0 |
Serialise TypeLitSort Source # | Since: 0.2.0.0 |
Serialise Half Source # | Since: 0.2.0.0 |
Serialise Text Source # | Since: 0.2.0.0 |
Serialise Text Source # | Since: 0.2.0.0 |
Serialise UTCTime Source # |
Since: 0.2.0.0 |
Serialise Integer Source # | Since: 0.2.0.0 |
Serialise Natural Source # | Since: 0.2.0.0 |
Serialise () Source # | Since: 0.2.0.0 |
Serialise Bool Source # | Since: 0.2.0.0 |
Serialise Char Source # | Since: 0.2.0.0 |
Serialise Double Source # | Since: 0.2.0.0 |
Serialise Float Source # | Since: 0.2.0.0 |
Serialise Int Source # | Since: 0.2.0.0 |
Serialise Levity Source # | Since: 0.2.6.0 |
Serialise RuntimeRep Source # | Since: 0.2.0.0 |
Serialise VecCount Source # | Since: 0.2.0.0 |
Serialise VecElem Source # | Since: 0.2.0.0 |
Serialise Word Source # | Since: 0.2.0.0 |
Serialise a => Serialise (ZipList a) Source # | Since: 0.2.0.0 |
Serialise a => Serialise (Complex a) Source # | Since: 0.2.0.0 |
Serialise a => Serialise (Identity a) Source # | Since: 0.2.0.0 |
Serialise a => Serialise (First a) Source # | Since: 0.2.0.0 |
Serialise a => Serialise (Last a) Source # | Since: 0.2.0.0 |
Serialise a => Serialise (Down a) Source # | Since: 0.2.0.0 |
Serialise a => Serialise (First a) Source # | Since: 0.2.0.0 |
Serialise a => Serialise (Last a) Source # | Since: 0.2.0.0 |
Serialise a => Serialise (Max a) Source # | Since: 0.2.0.0 |
Serialise a => Serialise (Min a) Source # | Since: 0.2.0.0 |
Serialise a => Serialise (WrappedMonoid a) Source # | |
Serialise a => Serialise (Dual a) Source # | Since: 0.2.0.0 |
Serialise a => Serialise (Product a) Source # | Since: 0.2.0.0 |
Serialise a => Serialise (Sum a) Source # | Since: 0.2.0.0 |
Serialise a => Serialise (NonEmpty a) Source # | Since: 0.2.0.0 |
(Serialise a, Integral a) => Serialise (Ratio a) Source # | Since: 0.2.0.0 |
Serialise a => Serialise (IntMap a) Source # | Since: 0.2.0.0 |
Serialise a => Serialise (Seq a) Source # | Since: 0.2.0.0 |
(Ord a, Serialise a) => Serialise (Set a) Source # | Since: 0.2.0.0 |
Serialise a => Serialise (Tree a) Source # | Since: 0.2.0.0 |
Serialise a => Serialise (Maybe a) Source # | Since: 0.2.4.0 |
(Serialise a, Hashable a, Eq a) => Serialise (HashSet a) Source # | Since: 0.2.0.0 |
Serialise a => Serialise (Vector a) Source # | Since: 0.2.0.0 |
(Serialise a, Prim a) => Serialise (Vector a) Source # | Since: 0.2.0.0 |
(Serialise a, Storable a) => Serialise (Vector a) Source # | Since: 0.2.0.0 |
(Serialise a, Unbox a) => Serialise (Vector a) Source # | Since: 0.2.0.0 |
Serialise a => Serialise (Maybe a) Source # | Since: 0.2.0.0 |
Serialise a => Serialise [a] Source # | Since: 0.2.0.0 |
(Serialise a, Serialise b) => Serialise (Either a b) Source # | Since: 0.2.0.0 |
Serialise (Fixed e) Source # | Values are serialised in units of least precision represented as
Since: 0.2.0.0 |
Serialise (Proxy a) Source # | Since: 0.2.0.0 |
Typeable a => Serialise (TypeRep a) Source # | Since: 0.2.0.0 |
(Ord k, Serialise k, Serialise v) => Serialise (Map k v) Source # | Since: 0.2.0.0 |
(Serialise a, Serialise b) => Serialise (Either a b) Source # | Since: 0.2.4.0 |
(Serialise a, Serialise b) => Serialise (These a b) Source # | Since: 0.2.4.0 |
(Serialise a, Serialise b) => Serialise (Pair a b) Source # | Since: 0.2.4.0 |
(Serialise a, Serialise b) => Serialise (These a b) Source # | Since: 0.2.4.0 |
(Serialise k, Hashable k, Eq k, Serialise v) => Serialise (HashMap k v) Source # | Since: 0.2.0.0 |
(Serialise a, Serialise b) => Serialise (a, b) Source # | Since: 0.2.0.0 |
Serialise a => Serialise (Const a b) Source # | Since: 0.2.0.0 |
Serialise (f a) => Serialise (Alt f a) Source # | Since: 0.2.0.0 |
(Serialise a, Serialise b, Serialise c) => Serialise (a, b, c) Source # | Since: 0.2.0.0 |
(Serialise a, Serialise b, Serialise c, Serialise d) => Serialise (a, b, c, d) Source # | Since: 0.2.0.0 |
(Serialise a, Serialise b, Serialise c, Serialise d, Serialise e) => Serialise (a, b, c, d, e) Source # | Since: 0.2.0.0 |
(Serialise a, Serialise b, Serialise c, Serialise d, Serialise e, Serialise f) => Serialise (a, b, c, d, e, f) Source # | Since: 0.2.0.0 |
(Serialise a, Serialise b, Serialise c, Serialise d, Serialise e, Serialise f, Serialise g) => Serialise (a, b, c, d, e, f, g) Source # | Since: 0.2.0.0 |
(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) Source # | Since: 0.2.0.0 |
(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) Source # | Since: 0.2.0.0 |
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
Arguments
:: Serialise a | |
=> FilePath | The file to read from. |
-> IO a | The deserialised value. |
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
Arguments
:: Serialise a | |
=> Handle | The |
-> a | The value to be serialised and written. |
-> IO () |
Serialise a
(via ByteString
) and write it directly
to the specified serialise
.Handle
Since: 0.2.0.0