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


-- | Binary deserialisation using strict ByteStrings
--   
@package binary-strict
@version 0.4.7.1

module Data.Binary.Strict.Util

-- | Convert a strict ByteString to a lazy Char8 ByteString, where the
--   format is the same as running hexdump -C on it.
hexDumpString :: ByteString -> ByteString

-- | Performs the same operation as hexDumpString, but also writes it to
--   stdout
hexDump :: ByteString -> IO ()


-- | This module contains a single class which abstracts over Get and
--   IncrementalGet, so that one can write parsers which work in both. If
--   you are using this module, you may find that
--   -fno-monomorphism-restriction is very useful.
module Data.Binary.Strict.Class

-- | This is the generic class for the set of binary parsers. This lets you
--   write parser functions which are agnostic about the pattern of parsing
--   in which they get used (incremental, strict, bitwise etc)
class (Monad m, Alternative m) => BinaryParser m where spanOf1 p = do { result <- spanOf p; if null result then fail "" else return result } string s = do { s' <- getByteString $ length s; if s == s' then return () else fail $ "expecting:" ++ show s } word8 w = do { w' <- getWord8; if w == w' then return () else fail "" } oneOf p = do { w <- getWord8; if p w then return w else fail "" } many p = do { v <- (p >>= return . Just) <|> (return Nothing); case v of { Just x -> do { rest <- many p; return $ x : rest } Nothing -> return [] } } many1 p = do { result <- many p; case result of { [] -> fail "" x -> return x } } optional p = (p >>= return . Just) <|> return Nothing
skip :: BinaryParser m => Int -> m ()
bytesRead :: BinaryParser m => m Int
remaining :: BinaryParser m => m Int
isEmpty :: BinaryParser m => m Bool
spanOf :: BinaryParser m => (Word8 -> Bool) -> m ByteString
spanOf1 :: BinaryParser m => (Word8 -> Bool) -> m ByteString
string :: BinaryParser m => ByteString -> m ()
word8 :: BinaryParser m => Word8 -> m ()
oneOf :: BinaryParser m => (Word8 -> Bool) -> m Word8
many :: BinaryParser m => m a -> m [a]
many1 :: BinaryParser m => m a -> m [a]
optional :: BinaryParser m => m a -> m (Maybe a)
getWord8 :: BinaryParser m => m Word8
getByteString :: BinaryParser m => Int -> m ByteString
getWord16be :: BinaryParser m => m Word16
getWord32be :: BinaryParser m => m Word32
getWord64be :: BinaryParser m => m Word64
getWord16le :: BinaryParser m => m Word16
getWord32le :: BinaryParser m => m Word32
getWord64le :: BinaryParser m => m Word64
getWordhost :: BinaryParser m => m Word
getWord16host :: BinaryParser m => m Word16
getWord32host :: BinaryParser m => m Word32
getWord64host :: BinaryParser m => m Word64


-- | This is a version of the Get monad for incremental parsing. The parser
--   is written as if a single, huge, strict ByteString was to be parsed.
--   It produces results as it parses by calling yield.
--   
--   However, if the parser runs out of data, rather than failing the
--   caller sees a Partial result, which includes the list of yielded
--   values so far and a continuation. By calling the continuation with
--   more data, the parser continues, none the wiser.
--   
--   Take the following example
--   
--   <pre>
--   testParse = do
--     a &lt;- getWord16be
--     b &lt;- getWord16be
--     return $ a + b
--   
--   test = runGet testParse $ B.pack [1,0,0]
--   </pre>
--   
--   Here <tt>testParse</tt> needs to read 4 bytes in order to complete, so
--   test is a Partial, which includes the continuation function, so which
--   you can pass more data until it completes
--   
--   The lookahead functions have been removed from this parser because of
--   their incompatibility with the incremental monad at the moment.
module Data.Binary.Strict.IncrementalGet
data Get r a

-- | The result of a partial parse
data Result a

-- | the parse failed with the given error message
Failed :: String -> Result a

-- | the parse finished and produced the given list of results doing so.
--   Any unparsed data is returned.
Finished :: ByteString -> a -> Result a

-- | the parse ran out of data before finishing, but produced the given
--   list of results before doing so. To continue the parse pass more data
--   to the given continuation
Partial :: (ByteString -> Result a) -> Result a

-- | Start a parser and return the first Result.
runGet :: Get r r -> ByteString -> Result r

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

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

-- | Get the number of remaining unparsed bytes. Useful for checking
--   whether all input has been consumed.
remaining :: Get r Int

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

-- | This is the choice operator. If the first option fails, the second is
--   tried. The failure of the first option must happen within this
--   function otherwise rollback is not attempted.
plus :: Get r a -> Get r a -> Get r a
zero :: Get r a
spanOf :: (Word8 -> Bool) -> Get r ByteString

-- | Yield a partial and get more data
suspend :: Get r ()
getWord8 :: Get r Word8

-- | An efficient <a>get</a> method for strict ByteStrings. Fails if fewer
--   than <tt>n</tt> bytes are left in the input.
getByteString :: Int -> Get r ByteString
getWord16be :: Get r Word16
getWord32be :: Get r Word32
getWord64be :: Get r Word64
getWord16le :: Get r Word16
getWord32le :: Get r Word32
getWord64le :: Get r Word64
getWordhost :: Get r Word
getWord16host :: Get r Word16
getWord32host :: Get r Word32
getWord64host :: Get r Word64
instance BinaryParser (Get r)
instance Alternative (Get r)
instance Applicative (Get r)
instance MonadPlus (Get r)
instance Monad (Get r)
instance Functor (Get r)
instance Show a => Show (Result a)
instance Show (IResult a)


-- | This is a strict version of the Get monad from the binary package.
--   It's pretty much just a copy and paste job from the original source
--   code. The binary team are currently unsure about their future plans
--   w.r.t. strictness, so this is a stop gap measure.
--   
--   To use, write a function in the Get monad:
--   
--   <pre>
--   import Data.Binary.Strict.Get as BinStrict
--   import Data.ByteString as BS
--   parse :: BinStrict.Get
--   parse = getWord16be
--   main = print $ runGet parse $ BS.pack [1, 1]
--   </pre>
--   
--   This results in a tuple of (Right 257, "") (where the second element
--   is just the remaining data after the parser has run)
module Data.Binary.Strict.Get
data Get a

-- | Run a parser on the given input and return the result (either an error
--   string from a call to <tt>fail</tt>, or the parsing result) and the
--   remainder of of the input.
runGet :: Get a -> ByteString -> (Either String a, ByteString)

-- | 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)
zero :: Get a
plus :: Get a -> Get a -> Get a
spanOf :: (Word8 -> Bool) -> Get ByteString

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

-- | Get the number of remaining unparsed bytes. Useful for checking
--   whether all input has been consumed.
remaining :: Get Int

-- | Test whether all input has been consumed, i.e. there are no remaining
--   unparsed bytes.
isEmpty :: Get Bool
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.
getByteString :: Int -> Get ByteString
getWord16be :: Get Word16
getWord32be :: Get Word32
getWord64be :: Get Word64
getWord16le :: Get Word16
getWord32le :: Get Word32
getWord64le :: Get Word64
getWordhost :: Get Word
getWord16host :: Get Word16
getWord32host :: Get Word32
getWord64host :: Get Word64
getFloat32host :: Get Float
getFloat64host :: Get Double
instance BinaryParser Get
instance Alternative Get
instance Applicative Get
instance MonadPlus Get
instance Monad Get
instance Functor Get

module Data.Binary.Strict.BitUtil

-- | This is used for masking the last byte of a ByteString so that extra
--   bits don't leak in
topNBits :: Int -> Word8

-- | Return a Word8 with the bottom n bits set
bottomNBits :: Int -> Word8

-- | Shift the whole ByteString some number of bits left where 0 &lt;=
--   <tt>n</tt> &lt; 8
leftShift :: Int -> ByteString -> ByteString

-- | Shift the whole ByteString some number of bits right where 0 &lt;=
--   <tt>n</tt> &lt; 8
rightShift :: Int -> ByteString -> ByteString

-- | Truncate a ByteString to a given number of bits (counting from the
--   left) by masking out extra bits in the last byte
leftTruncateBits :: Int -> ByteString -> ByteString

-- | Truncate a ByteString to a given number of bits (counting from the
--   right) by masking out extra bits in the first byte
rightTruncateBits :: Int -> ByteString -> ByteString


-- | This is a reader monad for parsing bit-aligned data. The usual Get
--   monad handles byte aligned data well.
--   
--   In this monad, the current offset into the input is a number of bits,
--   and fetching n bits from the current position will shift everything
--   correctly. Bit vectors are represented as ByteStrings here either the
--   first <tt>n</tt> bits are valid (left aligned) or the last <tt>n</tt>
--   bits are (right aligned).
--   
--   If one is looking to parse integers etc, right alignment is the easist
--   to work with, however left alignment makes more sense in some
--   situations.
module Data.Binary.Strict.BitGet
data BitGet a

-- | Run a BitGet on a ByteString
runBitGet :: ByteString -> BitGet a -> Either String a

-- | Skip <tt>n</tt> bits of the input. Fails if less then <tt>n</tt> bits
--   remain
skip :: Int -> BitGet ()

-- | Return the number of bits remaining to be parsed
remaining :: BitGet Int

-- | Return true if there are no more bits to parse
isEmpty :: BitGet Bool

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

-- | Get a single bit from the input
getBit :: BitGet Bool

-- | Get a ByteString with the given number of bits, left aligned.
getLeftByteString :: Int -> BitGet ByteString

-- | Get a ByteString with the given number of bits in, right aligned.
getRightByteString :: Int -> BitGet ByteString
getAsWord8 :: Int -> BitGet Word8

-- | Read a Word16 in big endian format
getAsWord16 :: Int -> BitGet Word16

-- | Read a Word32 in big endian format
getAsWord32 :: Int -> BitGet Word32

-- | Read a Word64 in big endian format
getAsWord64 :: Int -> BitGet Word64
getWord8 :: BitGet Word8
getWord16le :: BitGet Word16
getWord16be :: BitGet Word16
getWord16host :: BitGet Word16
getWord32le :: BitGet Word32
getWord32be :: BitGet Word32
getWord32host :: BitGet Word32
getWord64le :: BitGet Word64
getWord64be :: BitGet Word64
getWord64host :: BitGet Word64
getWordhost :: BitGet Word
instance Show Direction
instance Monad BitGet


-- | A ByteSet is a fast Set object for Word8's. The construction of these
--   objects isn't terribly quick, but the member function should be about
--   as good as you can get. Thus, you should use this when <tt>member</tt>
--   is the most common operation
--   
--   This object is designed to be imported qualified:
--   
--   <pre>
--   import qualified Data.Binary.Strict.ByteSet as BSet
--   </pre>
module Data.Binary.Strict.ByteSet
data ByteSet

-- | An empty set
empty :: ByteSet

-- | The set contained all elements
full :: ByteSet

-- | A set with a single element
singleton :: Word8 -> ByteSet
fromList :: [Word8] -> ByteSet

-- | Construct a ByteSet containing all the elements from a to b,
--   inclusive.
range :: Word8 -> Word8 -> ByteSet
union :: ByteSet -> ByteSet -> ByteSet
intersection :: ByteSet -> ByteSet -> ByteSet
difference :: ByteSet -> ByteSet -> ByteSet
complement :: ByteSet -> ByteSet
toList :: ByteSet -> [Word8]
member :: ByteSet -> Word8 -> Bool
instance Show ByteSet


-- | Efficient construction of lazy bytestrings, bit by bit.
module Data.Binary.BitBuilder

-- | A <a>BitBuilder</a> is an efficient way to build lazy
--   <a>ByteString</a>s. There are several functions for constructing
--   <a>BitBuilder</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>BitBuilder</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>BitBuilder</a>.
--   
--   This is closely based on the Builder monad, but this one deals with
--   single bits at a time.
data BitBuilder

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

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

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

-- | <i>O(1).</i> The concatenation of two BitBuilders, 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 :: BitBuilder -> BitBuilder -> BitBuilder
fromByteString :: (ByteString, Int) -> BitBuilder

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

-- | Construct a BitBuilder by taking the bottom n bits of a Bits instance.
--   If the instance has less than n bits, this acts as if there was an
--   infinite zero filled prefix
fromBits :: (Integral a, Bits a) => Int -> a -> BitBuilder

-- | <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 :: BitBuilder
instance Monoid BitBuilder
instance Show BitBuilder


-- | This is the writer dual to BitGet. It allows one to append bits in a
--   monad and get a strict ByteString as a result. Bits are appended from
--   the MSB of the first byte towards the LSB of the last byte.
--   
--   This is best suited to small bit-fields because it accumulates bytes
--   using snoc, so large results will cause a lot of copying. It would be
--   possible to switch to using something similar to the Builder monad if
--   need arises. However, since most protocols only have small bit fields,
--   this should suffice for many cases.
module Data.Binary.BitPut
type BitPut = BitPutM ()
data BitPutM a
data BitPutT m a
runBitPut :: BitPut -> ByteString
runBitPutM :: BitPutM a -> (a, ByteString)
runBitPutT :: Monad m => BitPutT m a -> m (a, ByteString)

-- | Append a single bit
putBit :: Bool -> BitPut
putBitT :: Monad m => Bool -> BitPutT m ()

-- | Append the bottom n bits of the given bits value. In the case that
--   more bits are requested than the value provides, this acts as if the
--   value has as unlimited number of leading 0 bits.
putNBits :: (Integral a, Bits a) => Int -> a -> BitPut
putNBitsT :: (Monad m, Integral a, Bits a) => Int -> a -> BitPutT m ()

-- | Append a value. Note that this function is undefined for instances of
--   Bits which have no fixed bitsize (like Integer)
putBits :: (Integral a, Bits a) => a -> BitPut

-- | Append a ByteString
putByteString :: ByteString -> BitPut

-- | Append a left aligned ByteString where ByteString has a partial byte
--   with the given number of valid bits, from the MSB downwards. The
--   number of such bits must be 0..7. (A normal ByteString, which all
--   bytes full would use 0)
putLeftByteString :: (ByteString, Int) -> BitPut
instance MonadError e m => MonadError e (BitPutT m)
instance MonadTrans BitPutT
instance Monad m => Monad (BitPutT m)
instance Monad m => Functor (BitPutT m)
instance Monad BitPutM
instance Functor BitPutM