libghc-cereal-doc 0.5.4.0-1 / usr / share / doc / libghc-cereal-doc / html / cereal.txt

-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A binary serialization library
--   
--   A binary serialization library, similar to binary, that introduces an
--   isolate primitive for parser isolation, and labeled blocks for better
--   error messages.
@package cereal
@version 0.5.4.0


-- | The Put monad. A monad for efficiently constructing bytestrings.
module Data.Serialize.Put

-- | Put merely lifts Builder into a Writer monad, applied to ().
type Put = PutM ()

-- | The PutM type. A Writer monad over the efficient Builder monoid.
newtype PutM a
Put :: PairS a -> PutM a
[unPut] :: PutM a -> PairS a
type Putter a = a -> Put

-- | Run the <a>Put</a> monad with a serialiser
runPut :: Put -> ByteString

-- | Run the <a>Put</a> monad with a serialiser and get its result
runPutM :: PutM a -> (a, ByteString)

-- | Run the <a>Put</a> monad with a serialiser
runPutLazy :: Put -> ByteString

-- | Run the <a>Put</a> monad with a serialiser
runPutMLazy :: PutM a -> (a, ByteString)
putBuilder :: Putter Builder

-- | Run the <a>Put</a> monad
execPut :: PutM a -> Builder

-- | Pop the ByteString we have constructed so far, if any, yielding a new
--   chunk in the result ByteString.
flush :: Put

-- | Efficiently write a byte into the output buffer
putWord8 :: Putter Word8

-- | Efficiently write an int into the output buffer
putInt8 :: Putter Int8

-- | An efficient primitive to write a strict ByteString into the output
--   buffer. It flushes the current buffer, and writes the argument into a
--   new chunk.
putByteString :: Putter ByteString

-- | Write a lazy ByteString efficiently, simply appending the lazy
--   ByteString chunks to the output buffer
putLazyByteString :: Putter ByteString
putShortByteString :: Putter ShortByteString

-- | Write a Word16 in big endian format
putWord16be :: Putter Word16

-- | Write a Word32 in big endian format
putWord32be :: Putter Word32

-- | Write a Word64 in big endian format
putWord64be :: Putter Word64

-- | Write a Int16 in big endian format
putInt16be :: Putter Int16

-- | Write a Int32 in big endian format
putInt32be :: Putter Int32

-- | Write a Int64 in big endian format
putInt64be :: Putter Int64

-- | Write a Word16 in little endian format
putWord16le :: Putter Word16

-- | Write a Word32 in little endian format
putWord32le :: Putter Word32

-- | Write a Word64 in little endian format
putWord64le :: Putter Word64

-- | Write a Int16 in little endian format
putInt16le :: Putter Int16

-- | Write a Int32 in little endian format
putInt32le :: Putter Int32

-- | Write a Int64 in little endian format
putInt64le :: Putter Int64

-- | <i>O(1).</i> Write a single native machine word. The word is written
--   in host order, host endian form, for the machine you're on. On a 64
--   bit machine the Word is an 8 byte value, on a 32 bit machine, 4 bytes.
--   Values written this way are not portable to different endian or word
--   sized machines, without conversion.
putWordhost :: Putter Word

-- | <i>O(1).</i> Write a Word16 in native host order and host endianness.
--   For portability issues see <tt>putWordhost</tt>.
putWord16host :: Putter Word16

-- | <i>O(1).</i> Write a Word32 in native host order and host endianness.
--   For portability issues see <tt>putWordhost</tt>.
putWord32host :: Putter Word32

-- | <i>O(1).</i> Write a Word64 in native host order On a 32 bit machine
--   we write two host order Word32s, in big endian form. For portability
--   issues see <tt>putWordhost</tt>.
putWord64host :: Putter Word64

-- | <i>O(1).</i> Write a single native machine int. The int is written in
--   host order, host endian form, for the machine you're on. On a 64 bit
--   machine the Int is an 8 byte value, on a 32 bit machine, 4 bytes.
--   Values written this way are not portable to different endian or int
--   sized machines, without conversion.
putInthost :: Putter Int

-- | <i>O(1).</i> Write a Int16 in native host order and host endianness.
--   For portability issues see <tt>putInthost</tt>.
putInt16host :: Putter Int16

-- | <i>O(1).</i> Write a Int32 in native host order and host endianness.
--   For portability issues see <tt>putInthost</tt>.
putInt32host :: Putter Int32

-- | <i>O(1).</i> Write a Int64 in native host order On a 32 bit machine we
--   write two host order Int32s, in big endian form. For portability
--   issues see <tt>putInthost</tt>.
putInt64host :: Putter Int64
putTwoOf :: Putter a -> Putter b -> Putter (a, b)
putListOf :: Putter a -> Putter [a]
putIArrayOf :: (Ix i, IArray a e) => Putter i -> Putter e -> Putter (a i e)
putSeqOf :: Putter a -> Putter (Seq a)
putTreeOf :: Putter a -> Putter (Tree a)
putMapOf :: Putter k -> Putter a -> Putter (Map k a)
putIntMapOf :: Putter Int -> Putter a -> Putter (IntMap a)
putSetOf :: Putter a -> Putter (Set a)
putIntSetOf :: Putter Int -> Putter IntSet
putMaybeOf :: Putter a -> Putter (Maybe a)
putEitherOf :: Putter a -> Putter b -> Putter (Either a b)

-- | Put a nested structure by first putting a length field and then
--   putting the encoded value.
putNested :: Putter Int -> Put -> Put
instance GHC.Base.Functor Data.Serialize.Put.PutM
instance GHC.Base.Applicative Data.Serialize.Put.PutM
instance GHC.Base.Monad Data.Serialize.Put.PutM
instance GHC.Base.Monoid (Data.Serialize.Put.PutM ())


-- | The Get monad. A monad for efficiently building structures from strict
--   ByteStrings
module Data.Serialize.Get

-- | The Get monad is an Exception and State monad.
data Get a

-- | Run the Get monad applies a <a>get</a>-based parser on the input
--   ByteString
runGet :: Get a -> ByteString -> Either String a

-- | Run the Get monad over a Lazy ByteString. Note that this will not run
--   the Get parser lazily, but will operate on lazy ByteStrings.
runGetLazy :: Get a -> ByteString -> Either String a

-- | Run the Get monad applies a <a>get</a>-based parser on the input
--   ByteString. Additional to the result of get it returns the number of
--   consumed bytes and the rest of the input.
runGetState :: Get a -> ByteString -> Int -> Either String (a, ByteString)

-- | Run the Get monad over a Lazy ByteString. Note that this does not run
--   the Get parser lazily, but will operate on lazy ByteStrings.
runGetLazyState :: Get a -> ByteString -> Either String (a, ByteString)

-- | The result of a parse.
data Result r

-- | The parse failed. The <a>String</a> is the message describing the
--   error, if any.
Fail :: String -> ByteString -> Result r

-- | Supply this continuation with more input so that the parser can
--   resume. To indicate that no more input is available, use an
--   <a>empty</a> string.
Partial :: (ByteString -> Result r) -> Result r

-- | The parse succeeded. The <a>ByteString</a> is the input that had not
--   yet been consumed (if any) when the parse succeeded.
Done :: r -> ByteString -> Result r

-- | Run the Get monad applies a <a>get</a>-based parser on the input
--   ByteString
runGetPartial :: Get a -> ByteString -> Result a

-- | Run the get monad on a single chunk, providing an optional length for
--   the remaining, unseen input, with Nothing indicating that it's not
--   clear how much input is left. For example, with a lazy ByteString, the
--   optional length represents the sum of the lengths of all remaining
--   chunks.
runGetChunk :: Get a -> Maybe Int -> ByteString -> Result a

-- | If at least <tt>n</tt> bytes of input are available, return the
--   current input, otherwise fail.
ensure :: Int -> Get ByteString

-- | Isolate an action to operating within a fixed block of bytes. The
--   action is required to consume all the bytes that it is isolated to.
isolate :: Int -> Get a -> Get a
label :: String -> Get a -> Get a

-- | Skip ahead <tt>n</tt> bytes. Fails if fewer than <tt>n</tt> bytes are
--   available.
skip :: Int -> Get ()

-- | Skip ahead up to <tt>n</tt> bytes in the current chunk. No error if
--   there aren't enough bytes, or if less than <tt>n</tt> bytes are
--   skipped.
uncheckedSkip :: Int -> Get ()

-- | Run <tt>ga</tt>, but return without consuming its input. Fails if
--   <tt>ga</tt> fails.
lookAhead :: Get a -> Get a

-- | Like <a>lookAhead</a>, but consume the input if <tt>gma</tt> returns
--   'Just _'. Fails if <tt>gma</tt> fails.
lookAheadM :: Get (Maybe a) -> Get (Maybe a)

-- | Like <a>lookAhead</a>, but consume the input if <tt>gea</tt> returns
--   'Right _'. Fails if <tt>gea</tt> fails.
lookAheadE :: Get (Either a b) -> Get (Either a b)

-- | Get the next up to <tt>n</tt> bytes as a ByteString until end of this
--   chunk, without consuming them.
uncheckedLookAhead :: Int -> Get ByteString

-- | Pull <tt>n</tt> bytes from the input, as a strict ByteString.
getBytes :: Int -> Get ByteString

-- | Get the number of remaining unparsed bytes. Useful for checking
--   whether all input has been consumed.
--   
--   WARNING: when run with <tt>runGetPartial</tt>, remaining will only
--   return the number of bytes that are remaining in the current input.
remaining :: Get Int

-- | Test whether all input has been consumed.
--   
--   WARNING: when run with <tt>runGetPartial</tt>, isEmpty will only tell
--   you if you're at the end of the current chunk.
isEmpty :: Get Bool

-- | Read a Word8 from the monad state
getWord8 :: Get Word8

-- | Read a Int8 from the monad state
getInt8 :: Get Int8

-- | An efficient <a>get</a> method for strict ByteStrings. Fails if fewer
--   than <tt>n</tt> bytes are left in the input. This function creates a
--   fresh copy of the underlying bytes.
getByteString :: Int -> Get ByteString
getLazyByteString :: Int64 -> Get ByteString
getShortByteString :: Int -> Get ShortByteString

-- | Read a Word16 in big endian format
getWord16be :: Get Word16

-- | Read a Word32 in big endian format
getWord32be :: Get Word32

-- | Read a Word64 in big endian format
getWord64be :: Get Word64

-- | Read a Int16 in big endian format
getInt16be :: Get Int16

-- | Read a Int32 in big endian format
getInt32be :: Get Int32

-- | Read a Int64 in big endian format
getInt64be :: Get Int64

-- | Read a Word16 in little endian format
getWord16le :: Get Word16

-- | Read a Word32 in little endian format
getWord32le :: Get Word32

-- | Read a Word64 in little endian format
getWord64le :: Get Word64

-- | Read a Int16 in little endian format
getInt16le :: Get Int16

-- | Read a Int32 in little endian format
getInt32le :: Get Int32

-- | Read a Int64 in little endian format
getInt64le :: Get Int64

-- | <i>O(1).</i> Read a single native machine word. The word is read in
--   host order, host endian form, for the machine you're on. On a 64 bit
--   machine the Word is an 8 byte value, on a 32 bit machine, 4 bytes.
getWordhost :: Get Word

-- | <i>O(1).</i> Read a 2 byte Word16 in native host order and host
--   endianness.
getWord16host :: Get Word16

-- | <i>O(1).</i> Read a Word32 in native host order and host endianness.
getWord32host :: Get Word32

-- | <i>O(1).</i> Read a Word64 in native host order and host endianess.
getWord64host :: Get Word64
getTwoOf :: Get a -> Get b -> Get (a, b)

-- | Get a list in the following format: Word64 (big endian format) element
--   1 ... element n
getListOf :: Get a -> Get [a]

-- | Get an IArray in the following format: index (lower bound) index
--   (upper bound) Word64 (big endian format) element 1 ... element n
getIArrayOf :: (Ix i, IArray a e) => Get i -> Get e -> Get (a i e)

-- | Read as a list of lists.
getTreeOf :: Get a -> Get (Tree a)

-- | Get a sequence in the following format: Word64 (big endian format)
--   element 1 ... element n
getSeqOf :: Get a -> Get (Seq a)

-- | Read as a list of pairs of key and element.
getMapOf :: Ord k => Get k -> Get a -> Get (Map k a)

-- | Read as a list of pairs of int and element.
getIntMapOf :: Get Int -> Get a -> Get (IntMap a)

-- | Read as a list of elements.
getSetOf :: Ord a => Get a -> Get (Set a)

-- | Read as a list of ints.
getIntSetOf :: Get Int -> Get IntSet

-- | Read in a Maybe in the following format: Word8 (0 for Nothing,
--   anything else for Just) element (when Just)
getMaybeOf :: Get a -> Get (Maybe a)

-- | Read an Either, in the following format: Word8 (0 for Left, anything
--   else for Right) element a when 0, element b otherwise
getEitherOf :: Get a -> Get b -> Get (Either a b)

-- | Read in a length and then read a nested structure of that length.
getNested :: Get Int -> Get a -> Get a
instance GHC.Classes.Eq Data.Serialize.Get.More
instance GHC.Show.Show r => GHC.Show.Show (Data.Serialize.Get.Result r)
instance GHC.Base.Functor Data.Serialize.Get.Result
instance GHC.Base.Functor Data.Serialize.Get.Get
instance GHC.Base.Applicative Data.Serialize.Get.Get
instance GHC.Base.Alternative Data.Serialize.Get.Get
instance GHC.Base.Monad Data.Serialize.Get.Get
instance Control.Monad.Fail.MonadFail Data.Serialize.Get.Get
instance GHC.Base.MonadPlus Data.Serialize.Get.Get


-- | IEEE-754 parsing, as described in this stack-overflow article:
--   
--   
--   <a>http://stackoverflow.com/questions/6976684/converting-ieee-754-floating-point-in-haskell-word32-64-to-and-from-haskell-float/7002812#7002812</a>
module Data.Serialize.IEEE754

-- | Read a Float in little endian IEEE-754 format
getFloat32le :: Get Float

-- | Read a Float in big endian IEEE-754 format
getFloat32be :: Get Float

-- | Read a Double in little endian IEEE-754 format
getFloat64le :: Get Double

-- | Read a Double in big endian IEEE-754 format
getFloat64be :: Get Double

-- | Write a Float in little endian IEEE-754 format
putFloat32le :: Float -> Put

-- | Write a Float in big endian IEEE-754 format
putFloat32be :: Float -> Put

-- | Write a Double in little endian IEEE-754 format
putFloat64le :: Double -> Put

-- | Write a Double in big endian IEEE-754 format
putFloat64be :: Double -> Put


module Data.Serialize

-- | If your compiler has support for the <tt>DeriveGeneric</tt> and
--   <tt>DefaultSignatures</tt> language extensions (<tt>ghc &gt;=
--   7.2.1</tt>), the <a>put</a> and <a>get</a> methods will have default
--   generic implementations.
--   
--   To use this option, simply add a <tt>deriving <a>Generic</a></tt>
--   clause to your datatype and declare a <a>Serialize</a> instance for it
--   without giving a definition for <a>put</a> and <a>get</a>.
class Serialize t where put = gPut . from get = to <$> gGet

-- | Encode a value in the Put monad.
put :: Serialize t => Putter t

-- | Decode a value in the Get monad
get :: Serialize t => Get t

-- | Encode a value in the Put monad.
put :: (Serialize t, Generic t, GSerializePut (Rep t)) => Putter t

-- | Decode a value in the Get monad
get :: (Serialize t, Generic t, GSerializeGet (Rep t)) => Get t

-- | Encode a value using binary serialization to a strict ByteString.
encode :: Serialize a => a -> ByteString

-- | Encode a value using binary serialization to a lazy ByteString.
encodeLazy :: Serialize a => a -> ByteString

-- | Decode a value from a strict ByteString, reconstructing the original
--   structure.
decode :: Serialize a => ByteString -> Either String a

-- | Decode a value from a lazy ByteString, reconstructing the original
--   structure.
decodeLazy :: Serialize a => ByteString -> Either String a

-- | Perform an action, failing if the read result does not match the
--   argument provided.
expect :: (Eq a, Serialize a) => a -> Get a
class GSerializePut f
gPut :: GSerializePut f => Putter (f a)
class GSerializeGet f
gGet :: GSerializeGet f => Get (f a)
instance Data.Serialize.Serialize ()
instance Data.Serialize.Serialize GHC.Types.Bool
instance Data.Serialize.Serialize GHC.Types.Ordering
instance Data.Serialize.Serialize GHC.Word.Word8
instance Data.Serialize.Serialize GHC.Word.Word16
instance Data.Serialize.Serialize GHC.Word.Word32
instance Data.Serialize.Serialize GHC.Word.Word64
instance Data.Serialize.Serialize GHC.Int.Int8
instance Data.Serialize.Serialize GHC.Int.Int16
instance Data.Serialize.Serialize GHC.Int.Int32
instance Data.Serialize.Serialize GHC.Int.Int64
instance Data.Serialize.Serialize GHC.Types.Word
instance Data.Serialize.Serialize GHC.Types.Int
instance Data.Serialize.Serialize GHC.Integer.Type.Integer
instance (Data.Serialize.Serialize a, GHC.Real.Integral a) => Data.Serialize.Serialize (GHC.Real.Ratio a)
instance Data.Serialize.Serialize GHC.Natural.Natural
instance Data.Serialize.Serialize GHC.Types.Char
instance (Data.Serialize.Serialize a, Data.Serialize.Serialize b) => Data.Serialize.Serialize (a, b)
instance (Data.Serialize.Serialize a, Data.Serialize.Serialize b, Data.Serialize.Serialize c) => Data.Serialize.Serialize (a, b, c)
instance (Data.Serialize.Serialize a, Data.Serialize.Serialize b, Data.Serialize.Serialize c, Data.Serialize.Serialize d) => Data.Serialize.Serialize (a, b, c, d)
instance (Data.Serialize.Serialize a, Data.Serialize.Serialize b, Data.Serialize.Serialize c, Data.Serialize.Serialize d, Data.Serialize.Serialize e) => Data.Serialize.Serialize (a, b, c, d, e)
instance (Data.Serialize.Serialize a, Data.Serialize.Serialize b, Data.Serialize.Serialize c, Data.Serialize.Serialize d, Data.Serialize.Serialize e, Data.Serialize.Serialize f) => Data.Serialize.Serialize (a, b, c, d, e, f)
instance (Data.Serialize.Serialize a, Data.Serialize.Serialize b, Data.Serialize.Serialize c, Data.Serialize.Serialize d, Data.Serialize.Serialize e, Data.Serialize.Serialize f, Data.Serialize.Serialize g) => Data.Serialize.Serialize (a, b, c, d, e, f, g)
instance (Data.Serialize.Serialize a, Data.Serialize.Serialize b, Data.Serialize.Serialize c, Data.Serialize.Serialize d, Data.Serialize.Serialize e, Data.Serialize.Serialize f, Data.Serialize.Serialize g, Data.Serialize.Serialize h) => Data.Serialize.Serialize (a, b, c, d, e, f, g, h)
instance (Data.Serialize.Serialize a, Data.Serialize.Serialize b, Data.Serialize.Serialize c, Data.Serialize.Serialize d, Data.Serialize.Serialize e, Data.Serialize.Serialize f, Data.Serialize.Serialize g, Data.Serialize.Serialize h, Data.Serialize.Serialize i) => Data.Serialize.Serialize (a, b, c, d, e, f, g, h, i)
instance (Data.Serialize.Serialize a, Data.Serialize.Serialize b, Data.Serialize.Serialize c, Data.Serialize.Serialize d, Data.Serialize.Serialize e, Data.Serialize.Serialize f, Data.Serialize.Serialize g, Data.Serialize.Serialize h, Data.Serialize.Serialize i, Data.Serialize.Serialize j) => Data.Serialize.Serialize (a, b, c, d, e, f, g, h, i, j)
instance Data.Serialize.Serialize a => Data.Serialize.Serialize (Data.Monoid.Dual a)
instance Data.Serialize.Serialize Data.Monoid.All
instance Data.Serialize.Serialize Data.Monoid.Any
instance Data.Serialize.Serialize a => Data.Serialize.Serialize (Data.Monoid.Sum a)
instance Data.Serialize.Serialize a => Data.Serialize.Serialize (Data.Monoid.Product a)
instance Data.Serialize.Serialize a => Data.Serialize.Serialize (Data.Monoid.First a)
instance Data.Serialize.Serialize a => Data.Serialize.Serialize (Data.Monoid.Last a)
instance Data.Serialize.Serialize a => Data.Serialize.Serialize [a]
instance Data.Serialize.Serialize a => Data.Serialize.Serialize (GHC.Base.Maybe a)
instance (Data.Serialize.Serialize a, Data.Serialize.Serialize b) => Data.Serialize.Serialize (Data.Either.Either a b)
instance Data.Serialize.Serialize Data.ByteString.Internal.ByteString
instance Data.Serialize.Serialize Data.ByteString.Lazy.Internal.ByteString
instance (GHC.Classes.Ord a, Data.Serialize.Serialize a) => Data.Serialize.Serialize (Data.Set.Base.Set a)
instance (GHC.Classes.Ord k, Data.Serialize.Serialize k, Data.Serialize.Serialize e) => Data.Serialize.Serialize (Data.Map.Base.Map k e)
instance Data.Serialize.Serialize Data.IntSet.Base.IntSet
instance Data.Serialize.Serialize e => Data.Serialize.Serialize (Data.IntMap.Base.IntMap e)
instance Data.Serialize.Serialize e => Data.Serialize.Serialize (Data.Sequence.Seq e)
instance Data.Serialize.Serialize GHC.Types.Double
instance Data.Serialize.Serialize GHC.Types.Float
instance Data.Serialize.Serialize e => Data.Serialize.Serialize (Data.Tree.Tree e)
instance (Data.Serialize.Serialize i, GHC.Arr.Ix i, Data.Serialize.Serialize e) => Data.Serialize.Serialize (GHC.Arr.Array i e)
instance (Data.Serialize.Serialize i, GHC.Arr.Ix i, Data.Serialize.Serialize e, Data.Array.Base.IArray Data.Array.Base.UArray e) => Data.Serialize.Serialize (Data.Array.Base.UArray i e)
instance Data.Serialize.GSerializePut a => Data.Serialize.GSerializePut (GHC.Generics.M1 i c a)
instance Data.Serialize.GSerializeGet a => Data.Serialize.GSerializeGet (GHC.Generics.M1 i c a)
instance Data.Serialize.Serialize a => Data.Serialize.GSerializePut (GHC.Generics.K1 i a)
instance Data.Serialize.Serialize a => Data.Serialize.GSerializeGet (GHC.Generics.K1 i a)
instance Data.Serialize.GSerializePut GHC.Generics.U1
instance Data.Serialize.GSerializeGet GHC.Generics.U1
instance (Data.Serialize.GSerializePut a, Data.Serialize.GSerializePut b) => Data.Serialize.GSerializePut (a GHC.Generics.:*: b)
instance (Data.Serialize.GSerializeGet a, Data.Serialize.GSerializeGet b) => Data.Serialize.GSerializeGet (a GHC.Generics.:*: b)
instance (Data.Serialize.PutSum a, Data.Serialize.PutSum b, Data.Serialize.SumSize a, Data.Serialize.SumSize b) => Data.Serialize.GSerializePut (a GHC.Generics.:+: b)
instance (Data.Serialize.GetSum a, Data.Serialize.GetSum b, Data.Serialize.SumSize a, Data.Serialize.SumSize b) => Data.Serialize.GSerializeGet (a GHC.Generics.:+: b)
instance (Data.Serialize.PutSum a, Data.Serialize.PutSum b) => Data.Serialize.PutSum (a GHC.Generics.:+: b)
instance Data.Serialize.GSerializePut a => Data.Serialize.PutSum (GHC.Generics.C1 c a)
instance (Data.Serialize.GetSum a, Data.Serialize.GetSum b) => Data.Serialize.GetSum (a GHC.Generics.:+: b)
instance Data.Serialize.GSerializeGet a => Data.Serialize.GetSum (GHC.Generics.C1 c a)
instance (Data.Serialize.SumSize a, Data.Serialize.SumSize b) => Data.Serialize.SumSize (a GHC.Generics.:+: b)
instance Data.Serialize.SumSize (GHC.Generics.C1 c a)