-- 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 replaces the asynchronous
--   errors with a user-handleable Either type. Similar to binary in
--   performance, but uses a strict ByteString instead of a lazy
--   ByteString, thus restricting it to operating on finite inputs.
@package cereal
@version 0.3.5.2


-- | Efficient construction of lazy bytestrings.
module Data.Serialize.Builder

-- | A <a>Builder</a> is an efficient way to build lazy <a>ByteString</a>s.
--   There are several functions for constructing <a>Builder</a>s, but only
--   one to inspect them: to extract any data, you have to turn them into
--   lazy <a>ByteString</a>s using <a>toLazyByteString</a>.
--   
--   Internally, a <a>Builder</a> constructs a lazy <a>Bytestring</a> by
--   filling byte arrays piece by piece. As each buffer is filled, it is
--   'popped' off, to become a new chunk of the resulting lazy
--   <a>ByteString</a>. All this is hidden from the user of the
--   <a>Builder</a>.
data Builder
toByteString :: Builder -> ByteString

-- | <i>O(n).</i> Extract a lazy <a>ByteString</a> from a <a>Builder</a>.
--   The construction work takes place if and when the relevant part of the
--   lazy <a>ByteString</a> is demanded.
toLazyByteString :: Builder -> ByteString

-- | <i>O(1).</i> The empty Builder, satisfying
--   
--   <ul>
--   <li><pre><a>toLazyByteString</a> <a>empty</a> =
--   <a>empty</a></pre></li>
--   </ul>
empty :: Builder

-- | <i>O(1).</i> A Builder taking a single byte, satisfying
--   
--   <ul>
--   <li><pre><a>toLazyByteString</a> (<a>singleton</a> b) =
--   <a>singleton</a> b</pre></li>
--   </ul>
singleton :: Word8 -> Builder

-- | <i>O(1).</i> The concatenation of two Builders, an associative
--   operation with identity <a>empty</a>, satisfying
--   
--   <ul>
--   <li><pre><a>toLazyByteString</a> (<a>append</a> x y) = <a>append</a>
--   (<a>toLazyByteString</a> x) (<a>toLazyByteString</a> y)</pre></li>
--   </ul>
append :: Builder -> Builder -> Builder

-- | <i>O(1).</i> A Builder taking a <a>ByteString</a>, satisfying
--   
--   <ul>
--   <li><pre><a>toLazyByteString</a> (<a>fromByteString</a> bs) =
--   <a>fromChunks</a> [bs]</pre></li>
--   </ul>
fromByteString :: ByteString -> Builder

-- | <i>O(1).</i> A Builder taking a lazy <a>ByteString</a>, satisfying
--   
--   <ul>
--   <li><pre><a>toLazyByteString</a> (<a>fromLazyByteString</a> bs) =
--   bs</pre></li>
--   </ul>
fromLazyByteString :: ByteString -> Builder

-- | <i>O(1).</i> Pop the <a>ByteString</a> we have constructed so far, if
--   any, yielding a new chunk in the result lazy <a>ByteString</a>.
flush :: Builder

-- | Write a Word16 in big endian format
putWord16be :: Word16 -> Builder

-- | Write a Word32 in big endian format
putWord32be :: Word32 -> Builder

-- | Write a Word64 in big endian format
putWord64be :: Word64 -> Builder

-- | Write a Word16 in little endian format
putWord16le :: Word16 -> Builder

-- | Write a Word32 in little endian format
putWord32le :: Word32 -> Builder

-- | Write a Word64 in little endian format
putWord64le :: Word64 -> Builder

-- | <i>O(1).</i> A Builder taking 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 :: Word -> Builder

-- | Write a Word16 in native host order and host endianness. 2 bytes will
--   be written, unaligned.
putWord16host :: Word16 -> Builder

-- | Write a Word32 in native host order and host endianness. 4 bytes will
--   be written, unaligned.
putWord32host :: Word32 -> Builder

-- | Write a Word64 in native host order. On a 32 bit machine we write two
--   host order Word32s, in big endian form. 8 bytes will be written,
--   unaligned.
putWord64host :: Word64 -> Builder
instance Monoid Builder


-- | 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

-- | 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

-- | 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 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

-- | <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
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 :: Ord k => 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)
instance Monad PutM
instance Applicative PutM
instance Functor 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 -> 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

-- | 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 <tt>n</tt> bytes. No error if there isn't enough bytes.
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, 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

-- | 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

-- | 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 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

-- | <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)
instance Eq More
instance MonadPlus Get
instance Monad Get
instance Alternative Get
instance Applicative Get
instance Functor Get
instance Functor Result
instance Show r => Show (Result r)


-- | IEEE-754 parsing, as described in this stack-overflow article:
--   
--   
--   http:<i></i>stackoverflow.com<i>questions</i>6976684<i>converting-ieee-754-floating-point-in-haskell-word32-64-to-and-from-haskell-float</i>7002812#7002812
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
put :: Serialize t => Putter t
get :: Serialize 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
instance SumSize (C1 c a)
instance (SumSize a, SumSize b) => SumSize (a :+: b)
instance GSerialize a => GetSum (C1 c a)
instance (GetSum a, GetSum b, GSerialize a, GSerialize b) => GetSum (a :+: b)
instance GSerialize a => PutSum (C1 c a)
instance (PutSum a, PutSum b, GSerialize a, GSerialize b) => PutSum (a :+: b)
instance (PutSum a, PutSum b, GetSum a, GetSum b, GSerialize a, GSerialize b, SumSize a, SumSize b) => GSerialize (a :+: b)
instance (GSerialize a, GSerialize b) => GSerialize (a :*: b)
instance GSerialize U1
instance Serialize a => GSerialize (K1 i a)
instance GSerialize a => GSerialize (M1 i c a)
instance (Serialize i, Ix i, Serialize e, IArray UArray e) => Serialize (UArray i e)
instance (Serialize i, Ix i, Serialize e) => Serialize (Array i e)
instance Serialize e => Serialize (Tree e)
instance Serialize Float
instance Serialize Double
instance Serialize e => Serialize (Seq e)
instance Serialize e => Serialize (IntMap e)
instance Serialize IntSet
instance (Ord k, Serialize k, Serialize e) => Serialize (Map k e)
instance (Ord a, Serialize a) => Serialize (Set a)
instance Serialize ByteString
instance Serialize ByteString
instance (Serialize a, Serialize b) => Serialize (Either a b)
instance Serialize a => Serialize (Maybe a)
instance Serialize a => Serialize [a]
instance (Serialize a, Serialize b, Serialize c, Serialize d, Serialize e, Serialize f, Serialize g, Serialize h, Serialize i, Serialize j) => Serialize (a, b, c, d, e, f, g, h, i, j)
instance (Serialize a, Serialize b, Serialize c, Serialize d, Serialize e, Serialize f, Serialize g, Serialize h, Serialize i) => Serialize (a, b, c, d, e, f, g, h, i)
instance (Serialize a, Serialize b, Serialize c, Serialize d, Serialize e, Serialize f, Serialize g, Serialize h) => Serialize (a, b, c, d, e, f, g, h)
instance (Serialize a, Serialize b, Serialize c, Serialize d, Serialize e, Serialize f, Serialize g) => Serialize (a, b, c, d, e, f, g)
instance (Serialize a, Serialize b, Serialize c, Serialize d, Serialize e, Serialize f) => Serialize (a, b, c, d, e, f)
instance (Serialize a, Serialize b, Serialize c, Serialize d, Serialize e) => Serialize (a, b, c, d, e)
instance (Serialize a, Serialize b, Serialize c, Serialize d) => Serialize (a, b, c, d)
instance (Serialize a, Serialize b, Serialize c) => Serialize (a, b, c)
instance (Serialize a, Serialize b) => Serialize (a, b)
instance Serialize Char
instance (Serialize a, Integral a) => Serialize (Ratio a)
instance Serialize Integer
instance Serialize Int
instance Serialize Word
instance Serialize Int64
instance Serialize Int32
instance Serialize Int16
instance Serialize Int8
instance Serialize Word64
instance Serialize Word32
instance Serialize Word16
instance Serialize Word8
instance Serialize Ordering
instance Serialize Bool
instance Serialize ()
