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 | Safe-Inferred |
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 #
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 #
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 #
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: cborg-0.2.0.0
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 #
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.
Since: 0.2.0.0
deserialiseIncremental :: Serialise a => ST s (IDecode s a) #
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
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
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 #
Definition of a given
for a type.Decoder
Since: 0.2.0.0
default decode :: (Generic a, GSerialiseDecode (Rep a)) => Decoder s a #
encodeList :: [a] -> Encoding #
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] #
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 # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise Any # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise SomeTypeRep # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise Version # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CChar # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CClock # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CDouble # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CFloat # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CInt # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CIntMax # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CIntPtr # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CLLong # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CLong # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CPtrdiff # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CSChar # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CSUSeconds # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CShort # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CSigAtomic # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CSize # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CTime # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CUChar # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CUInt # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CUIntMax # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CUIntPtr # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CULLong # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CULong # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CUSeconds # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CUShort # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise CWchar # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise Void # | Since: 0.2.4.0 |
Defined in Codec.Serialise.Class | |
Serialise Fingerprint # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise ExitCode # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise Int16 # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise Int32 # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise Int64 # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise Int8 # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise Word16 # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise Word32 # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise Word64 # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise Word8 # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise ByteString # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise ByteString # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise ShortByteString # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise Term # | Since: 0.2.0.0 |
Serialise IntSet # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise KindRep # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise Ordering # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise TyCon # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise TypeLitSort # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise Half # | Since: 0.2.0.0 |
Serialise Text # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise Text # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise UTCTime # |
Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise Integer # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise Natural # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise () # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise Bool # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise Char # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise Double # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise Float # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise Int # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise Levity # | Since: 0.2.6.0 |
Defined in Codec.Serialise.Class | |
Serialise RuntimeRep # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise VecCount # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise VecElem # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise Word # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise a => Serialise (ZipList a) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise a => Serialise (Complex a) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise a => Serialise (Identity a) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise a => Serialise (First a) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise a => Serialise (Last a) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise a => Serialise (Down a) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise a => Serialise (First a) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise a => Serialise (Last a) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise a => Serialise (Max a) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise a => Serialise (Min a) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise a => Serialise (WrappedMonoid a) # | |
Defined in Codec.Serialise.Class | |
Serialise a => Serialise (Dual a) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise a => Serialise (Product a) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise a => Serialise (Sum a) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise a => Serialise (NonEmpty a) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
(Serialise a, Integral a) => Serialise (Ratio a) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise a => Serialise (IntMap a) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise a => Serialise (Seq a) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
(Ord a, Serialise a) => Serialise (Set a) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise a => Serialise (Tree a) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise a => Serialise (Maybe a) # | Since: 0.2.4.0 |
(Serialise a, Hashable a, Eq a) => Serialise (HashSet a) # | Since: 0.2.0.0 |
Serialise a => Serialise (Vector a) # | Since: 0.2.0.0 |
(Serialise a, Prim a) => Serialise (Vector a) # | Since: 0.2.0.0 |
(Serialise a, Storable a) => Serialise (Vector a) # | Since: 0.2.0.0 |
(Serialise a, Unbox a) => Serialise (Vector a) # | Since: 0.2.0.0 |
Serialise a => Serialise (Maybe a) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise a => Serialise [a] # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
(Serialise a, Serialise b) => Serialise (Either a b) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise (Fixed e) # | Values are serialised in units of least precision represented as
Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise (Proxy a) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Typeable a => Serialise (TypeRep a) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
(Ord k, Serialise k, Serialise v) => Serialise (Map k v) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
(Serialise a, Serialise b) => Serialise (Either a b) # | Since: 0.2.4.0 |
(Serialise a, Serialise b) => Serialise (These a b) # | Since: 0.2.4.0 |
(Serialise a, Serialise b) => Serialise (Pair a b) # | Since: 0.2.4.0 |
(Serialise a, Serialise b) => Serialise (These a b) # | Since: 0.2.4.0 |
(Serialise k, Hashable k, Eq k, Serialise v) => Serialise (HashMap k v) # | Since: 0.2.0.0 |
(Serialise a, Serialise b) => Serialise (a, b) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise a => Serialise (Const a b) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
Serialise (f a) => Serialise (Alt f a) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
(Serialise a, Serialise b, Serialise c) => Serialise (a, b, c) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
(Serialise a, Serialise b, Serialise c, Serialise d) => Serialise (a, b, c, d) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
(Serialise a, Serialise b, Serialise c, Serialise d, Serialise e) => Serialise (a, b, c, d, e) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class | |
(Serialise a, Serialise b, Serialise c, Serialise d, Serialise e, Serialise f) => Serialise (a, b, c, d, e, f) # | Since: 0.2.0.0 |
Defined in 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) # | Since: 0.2.0.0 |
Defined in 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) # | Since: 0.2.0.0 |
Defined in 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) # | Since: 0.2.0.0 |
Defined in Codec.Serialise.Class |
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