Copyright | Lennart Kolmodin |
---|---|
License | BSD3-style (see LICENSE) |
Maintainer | Adam Langley <agl@imperialviolet.org> |
Stability | experimental |
Portability | portable to Hugs and GHC. |
Safe Haskell | None |
Language | Haskell98 |
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.
- 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
Alternative (Get r) | |
Monad (Get r) | |
Functor (Get r) | |
MonadPlus (Get r) | |
Applicative (Get r) | |
BinaryParser (Get r) |
The result of a partial parse
Failed String | the 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) | 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 |
runGet :: Get r r -> ByteString -> Result r Source
Start a parser and return the first Result.
Utility
Get the number of remaining unparsed bytes. Useful for checking whether all input has been consumed.
Test whether all input has been consumed, i.e. there are no remaining unparsed bytes.
plus :: Get r a -> Get r a -> Get r a Source
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.
Parsing particular types
ByteStrings
getByteString :: Int -> Get r ByteString Source
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 Source
getWord32be :: Get r Word32 Source
getWord64be :: Get r Word64 Source
Little-endian reads
getWord16le :: Get r Word16 Source
getWord32le :: Get r Word32 Source
getWord64le :: Get r Word64 Source
Host-endian, unaligned reads
getWordhost :: Get r Word Source
getWord16host :: Get r Word16 Source
getWord32host :: Get r Word32 Source
getWord64host :: Get r Word64 Source