-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Binary serialisation for Haskell values using lazy ByteStrings
--
@package binary
@version 0.7.6.1
-- | A module containing semi-public Builder internals that exposes
-- low level construction functions. Modules which extend the
-- Builder 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 n bytes are available, and then use f to
-- write exactly n bytes into memory.
writeN :: Int -> (Ptr Word8 -> IO ()) -> Builder
-- | Ensure that n bytes are available, and then use f to
-- write at most n bytes into memory. f 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 Get monad.
data Decoder a
-- | The decoder ran into an error. The decoder either used fail or
-- was not provided enough input.
Fail :: !ByteString -> String -> Decoder a
-- | The decoder has consumed the available input and needs more to
-- continue. Provide Just if more input is available and
-- Nothing otherwise, and you will get a new Decoder.
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 Get monad. See Decoder 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 n bytes, maybe more. If not enough data is
-- available the computation will escape with Partial.
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, isolate will also fail.
-- Offset from bytesRead will be relative to the start of
-- isolate, 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 n bytes available. If not, the
-- computation will escape with Partial.
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.
-- | Deprecated: This will force all remaining input, don't use it.
remaining :: Get Int64
-- | DEPRECATED. Same as getByteString.
-- | Deprecated: Use getByteString instead of
-- getBytes.
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
-- Just. If Nothing 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
-- Right. If Left 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
-- n bytes are left in the input. If n <= 0 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 MonadPlus Get
instance Applicative Get
instance Monad Get
-- | Efficient construction of lazy bytestrings.
module Data.Binary.Builder
-- | A Builder is an efficient way to build lazy ByteStrings.
-- There are several functions for constructing Builders, but only
-- one to inspect them: to extract any data, you have to turn them into
-- lazy ByteStrings using toLazyByteString.
--
-- Internally, a Builder constructs a lazy Bytestring 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
-- ByteString. All this is hidden from the user of the
-- Builder.
data Builder
-- | O(n). Extract a lazy ByteString from a Builder.
-- The construction work takes place if and when the relevant part of the
-- lazy ByteString is demanded.
toLazyByteString :: Builder -> ByteString
-- | O(1). The empty Builder, satisfying
--
--
empty :: Builder
-- | O(1). A Builder taking a single byte, satisfying
--
--
singleton :: Word8 -> Builder
-- | O(1). The concatenation of two Builders, an associative
-- operation with identity empty, satisfying
--
--
append :: Builder -> Builder -> Builder
-- | O(1). A Builder taking a ByteString, satisfying
--
--
fromByteString :: ByteString -> Builder
-- | O(1). A Builder taking a lazy ByteString, satisfying
--
--
fromLazyByteString :: ByteString -> Builder
-- | O(1). Pop the ByteString we have constructed so far, if
-- any, yielding a new chunk in the result lazy ByteString.
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
-- | O(1). 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.
--
-- 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.
--
--
-- +------------------+--------------+-----------------+
-- | 32 bit timestamp | 32 bit price | 16 bit quantity |
-- +------------------+--------------+-----------------+
--
--
-- A corresponding Haskell value looks like this:
--
--
-- data Trade = Trade
-- { timestamp :: !Word32
-- , price :: !Word32
-- , qty :: !Word16
-- } deriving (Show)
--
--
--
-- The fields in Trade are marked as strict (using !)
-- since we don't need laziness here. In practise, you would probably
-- consider using the UNPACK pragma as well.
-- http://www.haskell.org/ghc/docs/latest/html/users_guide/pragmas.html#unpack-pragma
--
-- Now, let's have a look at a decoder for this format.
--
--
-- getTrade :: Get Trade
-- getTrade = do
-- timestamp <- getWord32le
-- price <- getWord32le
-- quantity <- getWord16le
-- return $! Trade timestamp price quantity
--
--
--
-- Or even simpler using applicative style:
--
--
-- getTrade' :: Get Trade
-- getTrade' = Trade <$> getWord32le <*> getWord32le <*> getWord16le
--
--
--
-- The applicative style can sometimes result in faster code, as
-- binary 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 Trades.
--
--
-- getTrades :: Get [Trade]
-- getTrades = do
-- empty <- isEmpty
-- if empty
-- then return []
-- else do trade <- getTrade
-- trades <- getTrades
-- return (trade:trades)
--
--
--
-- Finally, we run the decoder:
--
--
-- lazyIOExample :: IO [Trade]
-- lazyIOExample = do
-- input <- BL.readFile "trades.bin"
-- return (runGet getTrades input)
--
--
--
-- 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.
--
--
-- incrementalExample :: BL.ByteString -> [Trade]
-- incrementalExample input0 = go decoder input0
-- where
-- decoder = runGetIncremental getTrade
-- go :: Decoder Trade -> BL.ByteString -> [Trade]
-- go (Done leftover _consumed trade) input =
-- trade : go decoder (BL.chunk leftover input)
-- go (Partial k) input =
-- go (k . takeHeadChunk $ input) (dropHeadChunk input)
-- go (Fail _leftover _consumed msg) _input =
-- error msg
--
-- takeHeadChunk :: BL.ByteString -> Maybe BS.ByteString
-- takeHeadChunk lbs =
-- case lbs of
-- (BL.Chunk bs _) -> Just bs
-- _ -> Nothing
--
-- dropHeadChunk :: BL.ByteString -> BL.ByteString
-- dropHeadChunk lbs =
-- case lbs of
-- (BL.Chunk _ lbs') -> lbs'
-- _ -> BL.Empty
--
--
--
-- The lazyIOExample 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
-- incrementalExample. For an example of how to read
-- incrementally from a Handle, see the implementation of
-- decodeFileOrFail in Data.Binary.
module Data.Binary.Get
data Get a
-- | The simplest interface to run a Get decoder. If the decoder
-- runs into an error, calls fail, or runs out of input, it will
-- call error.
runGet :: Get a -> ByteString -> a
-- | Run a Get monad and return Left on failure and
-- Right 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 Get monad.
data Decoder a
-- | The decoder ran into an error. The decoder either used fail 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 Just if more input is available and
-- Nothing otherwise, and you will get a new Decoder.
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 Get monad. See Decoder for what to do next, like
-- providing input, handling decoder errors and to get the output value.
-- Hint: Use the helper functions pushChunk, pushChunks and
-- pushEndOfInput.
runGetIncremental :: Get a -> Decoder a
-- | Feed a Decoder with more input. If the Decoder is
-- Done or Fail it will add the input to ByteString
-- of unconsumed input.
--
--
-- runGetIncremental myParser `pushChunk` myInput1 `pushChunk` myInput2
--
pushChunk :: Decoder a -> ByteString -> Decoder a
-- | Feed a Decoder with more input. If the Decoder is
-- Done or Fail it will add the input to
-- ByteString of unconsumed input.
--
--
-- runGetIncremental myParser `pushChunks` myLazyByteString
--
pushChunks :: Decoder a -> ByteString -> Decoder a
-- | Tell a Decoder that there is no more input. This passes
-- Nothing to a Partial decoder, otherwise returns the
-- decoder unchanged.
pushEndOfInput :: Decoder a -> Decoder a
-- | Skip ahead n bytes. Fails if fewer than n 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, isolate will also fail.
-- Offset from bytesRead will be relative to the start of
-- isolate, 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
-- Just. If Nothing 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
-- Right. If Left 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
-- n bytes are left in the input. If n <= 0 then the
-- empty string is returned.
getByteString :: Int -> Get ByteString
-- | An efficient get method for lazy ByteStrings. Fails if fewer than
-- n 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
-- | O(1). 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
-- | O(1). Read a 2 byte Word16 in native host order and host
-- endianness.
getWord16host :: Get Word16
-- | O(1). Read a Word32 in native host order and host endianness.
getWord32host :: Get Word32
-- | O(1). Read a Word64 in native host order and host endianess.
getWord64host :: Get Word64
-- | DEPRECATED. Provides compatibility with previous versions of this
-- library. Run a Get 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.
-- | Deprecated: Use runGetIncremental instead. This function will be
-- removed.
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.
-- | Deprecated: This will force all remaining input, don't use it.
remaining :: Get Int64
-- | DEPRECATED. Same as getByteString.
-- | Deprecated: Use getByteString instead of
-- getBytes.
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 Put monad with a serialiser
runPut :: Put -> ByteString
-- | Run the Put monad with a serialiser and get its result
runPutM :: PutM a -> (a, ByteString)
putBuilder :: Builder -> Put
-- | Run the Put 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
-- | O(1). 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
-- | O(1). Write a Word16 in native host order and host endianness.
-- For portability issues see putWordhost.
putWord16host :: Word16 -> Put
-- | O(1). Write a Word32 in native host order and host endianness.
-- For portability issues see putWordhost.
putWord32host :: Word32 -> Put
-- | O(1). 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 putWordhost.
putWord64host :: Word64 -> Put
instance [safe] Monad PutM
instance [safe] Applicative PutM
instance [safe] Functor PutM
-- | Binary serialisation of Haskell values to and from lazy
-- ByteStrings. The Binary library provides methods for encoding
-- Haskell values as streams of bytes directly in memory. The resulting
-- ByteString can then be written to disk, sent over the network,
-- or further processed (for example, compressed with gzip).
--
-- The binary package is notable in that it provides both pure,
-- and high performance serialisation.
--
-- Values encoded using the Binary 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 Binary 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
-- Binary instances using the generic support. See GBinary.
--
-- If you have specific requirements about the encoding format, you can
-- use the encoding and decoding primitives directly, see the modules
-- Data.Binary.Get and Data.Binary.Put.
module Data.Binary
-- | The Binary class provides put and get, methods to
-- encode and decode a Haskell value to a lazy ByteString. It
-- mirrors the Read and Show 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 Put and Get
-- primitives directly.
--
-- Instances of Binary should satisfy the following property:
--
--
-- decode . encode == id
--
--
-- That is, the get and put 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
-- | Decode a value from a lazy ByteString. Returning Left on
-- failure and Right 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:
--
--
-- encodeFile f = B.writeFile f . encode
--
--
-- So for example if you wanted to compress as well, you could use:
--
--
-- B.writeFile f . compress . encode
--
encodeFile :: Binary a => FilePath -> a -> IO ()
-- | Decode a value from a file. In case of errors, error 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 Right. 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)