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


-- | Binary serialisation for Haskell values using lazy ByteStrings
--   
--   Efficient, pure binary serialisation using lazy ByteStrings. Haskell
--   values may be encoded to and from binary formats, written to disk as
--   binary, or sent over the network. The format used can be automatically
--   generated, or you can choose to implement a custom format if needed.
--   Serialisation speeds of over 1 G/sec have been observed, so this
--   library should be suitable for high performance scenarios.
@package binary
@version 0.7.5.0


-- | A module containing semi-public <a>Builder</a> internals that exposes
--   low level construction functions. Modules which extend the
--   <a>Builder</a> system will need to use this module while ideally most
--   users will be able to make do with the public interface modules.
module Data.Binary.Builder.Internal

-- | Ensure that <tt>n</tt> bytes are available, and then use <tt>f</tt> to
--   write exactly <tt>n</tt> bytes into memory.
writeN :: Int -> (Ptr Word8 -> IO ()) -> Builder

-- | Ensure that <tt>n</tt> bytes are available, and then use <tt>f</tt> to
--   write at most <tt>n</tt> bytes into memory. <tt>f</tt> must return the
--   actual number of bytes written.
writeAtMost :: Int -> (Ptr Word8 -> IO Int) -> Builder

module Data.Binary.Get.Internal
data Get a
runCont :: Get a -> forall r. ByteString -> Success a r -> Decoder r

-- | A decoder produced by running a <a>Get</a> monad.
data Decoder a

-- | The decoder ran into an error. The decoder either used <a>fail</a> or
--   was not provided enough input.
Fail :: !ByteString -> String -> Decoder a

-- | The decoder has consumed the available input and needs more to
--   continue. Provide <a>Just</a> if more input is available and
--   <a>Nothing</a> otherwise, and you will get a new <a>Decoder</a>.
Partial :: (Maybe ByteString -> Decoder a) -> Decoder a

-- | The decoder has successfully finished. Except for the output value you
--   also get the unused input.
Done :: !ByteString -> a -> Decoder a

-- | The decoder needs to know the current position in the input. Given the
--   number of bytes remaning in the decoder, the outer decoder runner
--   needs to calculate the position and resume the decoding.
BytesRead :: {-# UNPACK #-} !Int64 -> (Int64 -> Decoder a) -> Decoder a

-- | Run a <a>Get</a> monad. See <a>Decoder</a> for what to do next, like
--   providing input, handling decoding errors and to get the output value.
runGetIncremental :: Get a -> Decoder a

-- | Return at least <tt>n</tt> bytes, maybe more. If not enough data is
--   available the computation will escape with <a>Partial</a>.
readN :: Int -> (ByteString -> a) -> Get a
readNWith :: Int -> (Ptr a -> IO a) -> Get a

-- | Get the total number of bytes read to this point.
bytesRead :: Get Int64

-- | Isolate a decoder to operate with a fixed number of bytes, and fail if
--   fewer bytes were consumed, or more bytes were attempted to be
--   consumed. If the given decoder fails, <a>isolate</a> will also fail.
--   Offset from <a>bytesRead</a> will be relative to the start of
--   <a>isolate</a>, not the absolute of the input.
isolate :: Int -> Get a -> Get a
withInputChunks :: s -> Consume s -> ([ByteString] -> b) -> ([ByteString] -> Get b) -> Get b
type Consume s = s -> ByteString -> Either s (ByteString, ByteString)
failOnEOF :: [ByteString] -> Get a

-- | Get the current chunk.
get :: Get ByteString

-- | Replace the current chunk.
put :: ByteString -> Get ()

-- | Ensure that there are at least <tt>n</tt> bytes available. If not, the
--   computation will escape with <a>Partial</a>.
ensureN :: Int -> Get ()

-- | DEPRECATED. Get the number of bytes of remaining input. Note that this
--   is an expensive function to use as in order to calculate how much
--   input remains, all input has to be read and kept in-memory. The
--   decoder keeps the input as a strict bytestring, so you are likely
--   better off by calculating the remaining input in another way.

-- | <i>Deprecated: This will force all remaining input, don't use it.</i>
remaining :: Get Int64

-- | DEPRECATED. Same as <a>getByteString</a>.

-- | <i>Deprecated: Use <a>getByteString</a> instead of
--   <a>getBytes</a>.</i>
getBytes :: Int -> Get ByteString

-- | Test whether all input has been consumed, i.e. there are no remaining
--   undecoded bytes.
isEmpty :: Get Bool

-- | Run the given decoder, but without consuming its input. If the given
--   decoder fails, then so will this function.
lookAhead :: Get a -> Get a

-- | Run the given decoder, and only consume its input if it returns
--   <a>Just</a>. If <a>Nothing</a> is returned, the input will be
--   unconsumed. If the given decoder fails, then so will this function.
lookAheadM :: Get (Maybe a) -> Get (Maybe a)

-- | Run the given decoder, and only consume its input if it returns
--   <a>Right</a>. If <a>Left</a> is returned, the input will be
--   unconsumed. If the given decoder fails, then so will this function.
lookAheadE :: Get (Either a b) -> Get (Either a b)
label :: String -> Get a -> Get a

-- | An efficient get method for strict ByteStrings. Fails if fewer than
--   <tt>n</tt> bytes are left in the input. If <tt>n &lt;= 0</tt> then the
--   empty string is returned.
getByteString :: Int -> Get ByteString
instance GHC.Base.Monad Data.Binary.Get.Internal.Get
instance GHC.Base.Applicative Data.Binary.Get.Internal.Get
instance GHC.Base.MonadPlus Data.Binary.Get.Internal.Get
instance GHC.Base.Functor Data.Binary.Get.Internal.Get
instance GHC.Base.Functor Data.Binary.Get.Internal.Decoder
instance GHC.Show.Show a => GHC.Show.Show (Data.Binary.Get.Internal.Decoder a)
instance GHC.Base.Alternative Data.Binary.Get.Internal.Get


-- | Efficient construction of lazy bytestrings.
module Data.Binary.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

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

-- | Write a character using UTF-8 encoding.
putCharUtf8 :: Char -> Builder


-- | The <a>Get</a> monad. A monad for efficiently building structures from
--   encoded lazy ByteStrings.
--   
--   Primitives are available to decode words of various sizes, both big
--   and little endian.
--   
--   Let's decode binary data representing illustrated here. In this
--   example the values are in little endian.
--   
--   <pre>
--   +------------------+--------------+-----------------+
--   | 32 bit timestamp | 32 bit price | 16 bit quantity |
--   +------------------+--------------+-----------------+
--   </pre>
--   
--   A corresponding Haskell value looks like this:
--   
--   <pre>
--   data Trade = Trade
--     { timestamp :: !<a>Word32</a>
--     , price     :: !<a>Word32</a>
--     , qty       :: !<a>Word16</a>
--     } deriving (<a>Show</a>)
--    
--   </pre>
--   
--   The fields in <tt>Trade</tt> are marked as strict (using <tt>!</tt>)
--   since we don't need laziness here. In practise, you would probably
--   consider using the UNPACK pragma as well.
--   <a>http://www.haskell.org/ghc/docs/latest/html/users_guide/pragmas.html#unpack-pragma</a>
--   
--   Now, let's have a look at a decoder for this format.
--   
--   <pre>
--   getTrade :: <a>Get</a> Trade
--   getTrade = do
--     timestamp &lt;- <a>getWord32le</a>
--     price     &lt;- <a>getWord32le</a>
--     quantity  &lt;- <a>getWord16le</a>
--     return <a>$!</a> Trade timestamp price quantity
--    
--   </pre>
--   
--   Or even simpler using applicative style:
--   
--   <pre>
--   getTrade' :: <a>Get</a> Trade
--   getTrade' = Trade <a>&lt;$&gt;</a> <a>getWord32le</a> <a>&lt;*&gt;</a> <a>getWord32le</a> <a>&lt;*&gt;</a> <a>getWord16le</a>
--    
--   </pre>
--   
--   The applicative style can sometimes result in faster code, as
--   <tt>binary</tt> will try to optimize the code by grouping the reads
--   together.
--   
--   There are two kinds of ways to execute this decoder, the lazy input
--   method and the incremental input method. Here we will use the lazy
--   input method.
--   
--   Let's first define a function that decodes many <tt>Trade</tt>s.
--   
--   <pre>
--   getTrades :: Get [Trade]
--   getTrades = do
--     empty &lt;- <a>isEmpty</a>
--     if empty
--       then return []
--       else do trade &lt;- getTrade
--               trades &lt;- getTrades
--               return (trade:trades)
--    
--   </pre>
--   
--   Finally, we run the decoder:
--   
--   <pre>
--   lazyIOExample :: IO [Trade]
--   lazyIOExample = do
--     input &lt;- BL.readFile "trades.bin"
--     return (<a>runGet</a> getTrades input)
--    
--   </pre>
--   
--   This decoder has the downside that it will need to read all the input
--   before it can return. On the other hand, it will not return anything
--   until it knows it could decode without any decoder errors.
--   
--   You could also refactor to a left-fold, to decode in a more streaming
--   fashion, and get the following decoder. It will start to return data
--   without knowing that it can decode all input.
--   
--   <pre>
--   incrementalExample :: BL.ByteString -&gt; [Trade]
--   incrementalExample input0 = go decoder input0
--     where
--       decoder = <a>runGetIncremental</a> getTrade
--       go :: <a>Decoder</a> Trade -&gt; BL.ByteString -&gt; [Trade]
--       go (<a>Done</a> leftover _consumed trade) input =
--         trade : go decoder (BL.chunk leftover input)
--       go (<a>Partial</a> k) input                     =
--         go (k . takeHeadChunk $ input) (dropHeadChunk input)
--       go (<a>Fail</a> _leftover _consumed msg) _input =
--         error msg
--   
--   takeHeadChunk :: BL.ByteString -&gt; Maybe BS.ByteString
--   takeHeadChunk lbs =
--     case lbs of
--       (BL.Chunk bs _) -&gt; Just bs
--       _ -&gt; Nothing
--   
--   dropHeadChunk :: BL.ByteString -&gt; BL.ByteString
--   dropHeadChunk lbs =
--     case lbs of
--       (BL.Chunk _ lbs') -&gt; lbs'
--       _ -&gt; BL.Empty
--    
--   </pre>
--   
--   The <tt>lazyIOExample</tt> uses lazy I/O to read the file from the
--   disk, which is not suitable in all applications, and certainly not if
--   you need to read from a socket which has higher likelihood to fail. To
--   address these needs, use the incremental input method like in
--   <tt>incrementalExample</tt>. For an example of how to read
--   incrementally from a Handle, see the implementation of
--   <tt>decodeFileOrFail</tt> in <a>Data.Binary</a>.
module Data.Binary.Get
data Get a

-- | The simplest interface to run a <a>Get</a> decoder. If the decoder
--   runs into an error, calls <a>fail</a>, or runs out of input, it will
--   call <a>error</a>.
runGet :: Get a -> ByteString -> a

-- | Run a <a>Get</a> monad and return <a>Left</a> on failure and
--   <a>Right</a> on success. In both cases any unconsumed input and the
--   number of bytes consumed is returned. In the case of failure, a
--   human-readable error message is included as well.
runGetOrFail :: Get a -> ByteString -> Either (ByteString, ByteOffset, String) (ByteString, ByteOffset, a)

-- | An offset, counted in bytes.
type ByteOffset = Int64

-- | A decoder procuced by running a <a>Get</a> monad.
data Decoder a

-- | The decoder ran into an error. The decoder either used <a>fail</a> or
--   was not provided enough input. Contains any unconsumed input and the
--   number of bytes consumed.
Fail :: !ByteString -> {-# UNPACK #-} !ByteOffset -> String -> Decoder a

-- | The decoder has consumed the available input and needs more to
--   continue. Provide <a>Just</a> if more input is available and
--   <a>Nothing</a> otherwise, and you will get a new <a>Decoder</a>.
Partial :: (Maybe ByteString -> Decoder a) -> Decoder 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.
Done :: !ByteString -> {-# UNPACK #-} !ByteOffset -> a -> Decoder a

-- | Run a <a>Get</a> monad. See <a>Decoder</a> for what to do next, like
--   providing input, handling decoder errors and to get the output value.
--   Hint: Use the helper functions <a>pushChunk</a>, <a>pushChunks</a> and
--   <a>pushEndOfInput</a>.
runGetIncremental :: Get a -> Decoder a

-- | Feed a <a>Decoder</a> with more input. If the <a>Decoder</a> is
--   <a>Done</a> or <a>Fail</a> it will add the input to <a>ByteString</a>
--   of unconsumed input.
--   
--   <pre>
--   <a>runGetIncremental</a> myParser `pushChunk` myInput1 `pushChunk` myInput2
--   </pre>
pushChunk :: Decoder a -> ByteString -> Decoder a

-- | Feed a <a>Decoder</a> with more input. If the <a>Decoder</a> is
--   <a>Done</a> or <a>Fail</a> it will add the input to
--   <tt>ByteString</tt> of unconsumed input.
--   
--   <pre>
--   <a>runGetIncremental</a> myParser `pushChunks` myLazyByteString
--   </pre>
pushChunks :: Decoder a -> ByteString -> Decoder a

-- | Tell a <a>Decoder</a> that there is no more input. This passes
--   <a>Nothing</a> to a <a>Partial</a> decoder, otherwise returns the
--   decoder unchanged.
pushEndOfInput :: Decoder a -> Decoder a

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

-- | Test whether all input has been consumed, i.e. there are no remaining
--   undecoded bytes.
isEmpty :: Get Bool

-- | Get the total number of bytes read to this point.
bytesRead :: Get Int64

-- | Isolate a decoder to operate with a fixed number of bytes, and fail if
--   fewer bytes were consumed, or more bytes were attempted to be
--   consumed. If the given decoder fails, <a>isolate</a> will also fail.
--   Offset from <a>bytesRead</a> will be relative to the start of
--   <a>isolate</a>, not the absolute of the input.
isolate :: Int -> Get a -> Get a

-- | Run the given decoder, but without consuming its input. If the given
--   decoder fails, then so will this function.
lookAhead :: Get a -> Get a

-- | Run the given decoder, and only consume its input if it returns
--   <a>Just</a>. If <a>Nothing</a> is returned, the input will be
--   unconsumed. If the given decoder fails, then so will this function.
lookAheadM :: Get (Maybe a) -> Get (Maybe a)

-- | Run the given decoder, and only consume its input if it returns
--   <a>Right</a>. If <a>Left</a> is returned, the input will be
--   unconsumed. If the given decoder fails, then so will this function.
lookAheadE :: Get (Either a b) -> Get (Either a b)
label :: String -> Get a -> Get a

-- | An efficient get method for strict ByteStrings. Fails if fewer than
--   <tt>n</tt> bytes are left in the input. If <tt>n &lt;= 0</tt> then the
--   empty string is returned.
getByteString :: Int -> Get ByteString

-- | An efficient get method for lazy ByteStrings. Fails if fewer than
--   <tt>n</tt> bytes are left in the input.
getLazyByteString :: Int64 -> Get ByteString

-- | Get a lazy ByteString that is terminated with a NUL byte. The returned
--   string does not contain the NUL byte. Fails if it reaches the end of
--   input without finding a NUL.
getLazyByteStringNul :: Get ByteString

-- | Get the remaining bytes as a lazy ByteString. Note that this can be an
--   expensive function to use as it forces reading all input and keeping
--   the string in-memory.
getRemainingLazyByteString :: Get ByteString

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

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

-- | DEPRECATED. Provides compatibility with previous versions of this
--   library. Run a <a>Get</a> monad and return a tuple with three values.
--   The first value is the result of the decoder. The second and third are
--   the unused input, and the number of consumed bytes.

-- | <i>Deprecated: Use runGetIncremental instead. This function will be
--   removed.</i>
runGetState :: Get a -> ByteString -> ByteOffset -> (a, ByteString, ByteOffset)

-- | DEPRECATED. Get the number of bytes of remaining input. Note that this
--   is an expensive function to use as in order to calculate how much
--   input remains, all input has to be read and kept in-memory. The
--   decoder keeps the input as a strict bytestring, so you are likely
--   better off by calculating the remaining input in another way.

-- | <i>Deprecated: This will force all remaining input, don't use it.</i>
remaining :: Get Int64

-- | DEPRECATED. Same as <a>getByteString</a>.

-- | <i>Deprecated: Use <a>getByteString</a> instead of
--   <a>getBytes</a>.</i>
getBytes :: Int -> Get ByteString


-- | The Put monad. A monad for efficiently constructing lazy bytestrings.
module Data.Binary.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

-- | 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)
putBuilder :: Builder -> Put

-- | 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 :: Word8 -> Put

-- | 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 :: ByteString -> Put

-- | Write a lazy ByteString efficiently, simply appending the lazy
--   ByteString chunks to the output buffer
putLazyByteString :: ByteString -> Put

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

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

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

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

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

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

-- | <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 :: Word -> Put

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

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

-- | <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 :: Word64 -> Put
instance GHC.Base.Functor Data.Binary.Put.PutM
instance GHC.Base.Applicative Data.Binary.Put.PutM
instance GHC.Base.Monad Data.Binary.Put.PutM


-- | Binary serialisation of Haskell values to and from lazy
--   <a>ByteString</a>s. The Binary library provides methods for encoding
--   Haskell values as streams of bytes directly in memory. The resulting
--   <a>ByteString</a> can then be written to disk, sent over the network,
--   or further processed (for example, compressed with gzip).
--   
--   The <tt>binary</tt> package is notable in that it provides both pure,
--   and high performance serialisation.
--   
--   Values encoded using the <a>Binary</a> class are always encoded in
--   network order (big endian) form, and encoded data should be portable
--   across machine endianness, word size, or compiler version. For
--   example, data encoded using the <a>Binary</a> class could be written
--   on any machine, and read back on any another.
--   
--   If the specifics of the data format is not important to you, for
--   example, you are more interested in serializing and deserializing
--   values than in which format will be used, it is possible to derive
--   <a>Binary</a> instances using the generic support. See <a>GBinary</a>.
--   
--   If you have specific requirements about the encoding format, you can
--   use the encoding and decoding primitives directly, see the modules
--   <a>Data.Binary.Get</a> and <a>Data.Binary.Put</a>.
module Data.Binary

-- | The <a>Binary</a> class provides <a>put</a> and <a>get</a>, methods to
--   encode and decode a Haskell value to a lazy <a>ByteString</a>. It
--   mirrors the <a>Read</a> and <a>Show</a> classes for textual
--   representation of Haskell types, and is suitable for serialising
--   Haskell values to disk, over the network.
--   
--   For decoding and generating simple external binary formats (e.g. C
--   structures), Binary may be used, but in general is not suitable for
--   complex protocols. Instead use the <a>Put</a> and <a>Get</a>
--   primitives directly.
--   
--   Instances of Binary should satisfy the following property:
--   
--   <pre>
--   decode . encode == id
--   </pre>
--   
--   That is, the <a>get</a> and <a>put</a> methods should be the inverse
--   of each other. A range of instances are provided for basic Haskell
--   types.
class Binary t where put = gput . from get = to `fmap` gget

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

-- | Decode a value in the Get monad
get :: Binary t => Get t
class GBinary f
gput :: GBinary f => f t -> Put
gget :: GBinary f => Get (f t)
data Get a

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

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

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

-- | Encode a value using binary serialisation to a lazy ByteString.
encode :: Binary a => a -> ByteString

-- | Decode a value from a lazy ByteString, reconstructing the original
--   structure.
decode :: Binary a => ByteString -> a

-- | Decode a value from a lazy ByteString. Returning <a>Left</a> on
--   failure and <a>Right</a> on success. In both cases the unconsumed
--   input and the number of consumed bytes is returned. In case of
--   failure, a human-readable error message will be returned as well.
decodeOrFail :: Binary a => ByteString -> Either (ByteString, ByteOffset, String) (ByteString, ByteOffset, a)

-- | Lazily serialise a value to a file.
--   
--   This is just a convenience function, it's defined simply as:
--   
--   <pre>
--   encodeFile f = B.writeFile f . encode
--   </pre>
--   
--   So for example if you wanted to compress as well, you could use:
--   
--   <pre>
--   B.writeFile f . compress . encode
--   </pre>
encodeFile :: Binary a => FilePath -> a -> IO ()

-- | Decode a value from a file. In case of errors, <a>error</a> will be
--   called with the error message.
decodeFile :: Binary a => FilePath -> IO a

-- | Decode a value from a file. In case of success, the value will be
--   returned in <a>Right</a>. In case of decoder errors, the error message
--   together with the byte offset will be returned.
decodeFileOrFail :: Binary a => FilePath -> IO (Either (ByteOffset, String) a)
