-- 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. Serialisation speeds of over 1 G/sec
--   have been observed, so this library should be suitable for high
--   performance scenarios.
@package binary
@version 0.6.3.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 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.
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

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

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

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

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

-- | Demand more input. If none available, fail.
demandInput :: 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 'getByteString' instead of 'getBytes'.</i>
getBytes :: Int -> Get ByteString

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

-- | 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 Alternative Get
instance Show a => Show (Decoder a)
instance Functor Decoder
instance Functor Get
instance Applicative Get
instance Monad 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 Get monad. A monad for efficiently building structures from
--   encoded lazy ByteStrings.
module Data.Binary.Get
data Get a

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

-- | DEPRECATED. Provides compatibility with previous versions of this
--   library. Run a <a>Get</a> monad and return a tuple with thee 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 runGetPartial instead. This function will be
--   removed.</i>
runGetState :: Get a -> ByteString -> Int64 -> (a, ByteString, 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.
Fail :: !ByteString -> {-# UNPACK #-} !Int64 -> 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 as well as the count of used bytes.
Done :: !ByteString -> {-# UNPACK #-} !Int64 -> 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>
--   <tt>runGetPartial</tt> 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>
--   <tt>runGetPartial</tt> 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

-- | 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. 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.
remaining :: Get Int64

-- | DEPRECATED. Same as <a>getByteString</a>.
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 Monad PutM
instance Applicative PutM
instance Functor 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 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 from GHC, and read back in Hugs.
--   
--   You can either provide a hand written implementation of the
--   <a>Binary</a> class, or derive one using the generic support. See
--   <a>GBinary</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
put :: Binary t => t -> Put
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

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

-- | Lazily reconstruct a value previously written to a file.
--   
--   This is just a convenience function, it's defined simply as:
--   
--   <pre>
--   decodeFile f = return . decode =&lt;&lt; B.readFile f
--   </pre>
--   
--   So for example if you wanted to decompress as well, you could use:
--   
--   <pre>
--   return . decode . decompress =&lt;&lt; B.readFile f
--   </pre>
--   
--   After contructing the data from the input file, <a>decodeFile</a>
--   checks if the file is empty, and in doing so will force the associated
--   file handle closed, if it is indeed empty. If the file is not empty,
--   it is up to the decoding instance to consume the rest of the data, or
--   otherwise finalise the resource.
decodeFile :: Binary a => FilePath -> IO a