binary-strict-0.2: 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
   getWord16be >>= yield
   testParse

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

Here, testParse never completes, but yields Word16 values forever. It's started with a 3 byte ByteString and will yield a single value before running out of data. Thus, test = Partial cont [256]. Calling cont with a single extra byte will yield another Word16 value etc.

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) [a]
runGet :: Get r a -> ByteString -> Result r
skip :: Int -> Get r ()
yield :: r -> 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 [a]the parse finished and produced the given list of results doing so. Any unparsed data is returned.
Partial (ByteString -> Result a) [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 a -> 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.
yield :: r -> Get r ()
Return a value from the parse
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
Read a Word16 in big endian format
getWord32be :: Get r Word32
Read a Word32 in big endian format
getWord64be :: Get r Word64
Read a Word64 in big endian format
Little-endian reads
getWord16le :: Get r Word16
Read a Word16 in little endian format
getWord32le :: Get r Word32
Read a Word32 in little endian format
getWord64le :: Get r Word64
Read a Word64 in little endian format
Host-endian, unaligned reads
getWordhost :: Get r Word
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.
getWord16host :: Get r Word16
O(1). Read a 2 byte Word16 in native host order and host endianness.
getWord32host :: Get r Word32
O(1). Read a Word32 in native host order and host endianness.
getWord64host :: Get r Word64
O(1). Read a Word64 in native host order and host endianess.
Produced by Haddock version 0.8