binary-strict-0.4.5: Binary deserialisation using strict ByteStringsSource codeContentsIndex
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
plus :: Get r a -> Get r a -> Get r a
zero :: Get r a
spanOf :: (Word8 -> Bool) -> Get r ByteString
suspend :: Get r ()
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 Source
show/hide Instances
data Result a Source
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 rSource
Start a parser and return the first Result.
Utility
skip :: Int -> Get r ()Source
Skip ahead n bytes. Fails if fewer than n bytes are available.
bytesRead :: Get r IntSource
Get the total number of bytes read to this point.
remaining :: Get r IntSource
Get the number of remaining unparsed bytes. Useful for checking whether all input has been consumed.
isEmpty :: Get r BoolSource
Test whether all input has been consumed, i.e. there are no remaining unparsed bytes.
plus :: Get r a -> Get r a -> Get r aSource
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.
zero :: Get r aSource
spanOf :: (Word8 -> Bool) -> Get r ByteStringSource
suspend :: Get r ()Source
Yield a partial and get more data
Parsing particular types
getWord8 :: Get r Word8Source
ByteStrings
getByteString :: Int -> Get r ByteStringSource
An efficient get method for strict ByteStrings. Fails if fewer than n bytes are left in the input.
Big-endian reads
getWord16be :: Get r Word16Source
getWord32be :: Get r Word32Source
getWord64be :: Get r Word64Source
Little-endian reads
getWord16le :: Get r Word16Source
getWord32le :: Get r Word32Source
getWord64le :: Get r Word64Source
Host-endian, unaligned reads
getWordhost :: Get r WordSource
getWord16host :: Get r Word16Source
getWord32host :: Get r Word32Source
getWord64host :: Get r Word64Source
Produced by Haddock version 2.4.2