binary-strict-0.2.4: Binary deserialisation using strict ByteStringsContentsIndex
Data.Binary.Strict.IncrementalGet
Portabilityportable to Hugs and GHC.
Stabilityexperimental
MaintainerAdam Langley <agl@imperialviolet.org>
Contents
The Get type
Utility
Parsing particular types
ByteStrings
Big-endian reads
Little-endian reads
Host-endian, unaligned reads
Description

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

 testParse = do
   a <- getWord16be
   b <- getWord16be
   return $ a + b

 test = runGet testParse $ B.pack [1,0,0]

Here testParse 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.

Synopsis
data Get r a
data Result a
= Failed String
| Finished ByteString a
| Partial (ByteString -> Result a)
runGet :: Get r r -> ByteString -> Result r
skip :: Int -> Get r ()
bytesRead :: Get r Int
remaining :: Get r Int
isEmpty :: Get r Bool
getWord8 :: Get r Word8
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
The Get type
data Get r a
show/hide Instances
data Result a
The result of a partial parse
Constructors
Failed Stringthe parse failed with the given error message
Finished ByteString athe parse finished and produced the given list of results doing so. Any unparsed data is returned.
Partial (ByteString -> 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
show/hide Instances
Show a => Show (Result a)
runGet :: Get r r -> ByteString -> Result r
Start a parser and return the first Result.
Utility
skip :: Int -> Get r ()
Skip ahead n bytes. Fails if fewer than n bytes are available.
bytesRead :: Get r Int
Get the total number of bytes read to this point.
remaining :: Get r Int
Get the number of remaining unparsed bytes. Useful for checking whether all input has been consumed.
isEmpty :: Get r Bool
Test whether all input has been consumed, i.e. there are no remaining unparsed bytes.
Parsing particular types
getWord8 :: Get r Word8
ByteStrings
getByteString :: Int -> Get r ByteString
An efficient get method for strict ByteStrings. Fails if fewer than n bytes are left in the input.
Big-endian reads
getWord16be :: Get r Word16
getWord32be :: Get r Word32
getWord64be :: Get r Word64
Little-endian reads
getWord16le :: Get r Word16
getWord32le :: Get r Word32
getWord64le :: Get r Word64
Host-endian, unaligned reads
getWordhost :: Get r Word
getWord16host :: Get r Word16
getWord32host :: Get r Word32
getWord64host :: Get r Word64
Produced by Haddock version 0.8