Z.Data.Parser.Base

This module provide internal data types for a simple resumable Parser, which is suitable for binary protocol and simple textual protocol parsing. Parser extensively works on on Bytes, which is same to Text representation.

Parser types

data Result a

Simple parsing result, that represent respectively:

• Success: the remaining unparsed data and the parsed value
• Failure: the remaining unparsed data and the error message
• Partial: that need for more input data, supply empty bytes to indicate endOfInput

Constructors

Success a !Bytes

Failure ParseError !Bytes

Partial (ParseStep a)

Instances

Functor Result

Defined in Z.Data.Parser.Base

Methods

fmap :: (a -> b) -> Result a -> Result b

(<$) :: a -> Result b -> Result a

Show a => Show (Result a)

Defined in Z.Data.Parser.Base

Methods

showsPrec :: Int -> Result a -> ShowS

show :: Result a -> String

showList :: [Result a] -> ShowS

type ParseError = [Text]

Type alias for error message

type ParseStep r = Bytes -> Result r

A parse step consumes Bytes and produce Result.

newtype Parser a

Simple CPSed parser

A parser takes a failure continuation, and a success one, while the success continuation is usually composed by Monad instance, the failure one is more like a reader part, which can be modified via <?>. If you build parsers from ground, a pattern like this can be used:

   xxParser = do
     ensureN errMsg ...            -- make sure we have some bytes
     Parser $  kf k inp ->        -- fail continuation, success continuation and input
       ...
       ... kf errMsg (if input not OK)
       ... k ... (if we get something useful for next parser)
 

Constructors

Parser

Fields

• runParser :: forall r. (ParseError -> ParseStep r) -> (a -> ParseStep r) -> ParseStep r

Instances

Monad Parser

Defined in Z.Data.Parser.Base

Methods

(>>=) :: Parser a -> (a -> Parser b) -> Parser b

(>>) :: Parser a -> Parser b -> Parser b

return :: a -> Parser a

Functor Parser

Defined in Z.Data.Parser.Base

Methods

fmap :: (a -> b) -> Parser a -> Parser b

(<$) :: a -> Parser b -> Parser a

MonadFail Parser

Defined in Z.Data.Parser.Base

Methods

fail :: String -> Parser a

Applicative Parser

Defined in Z.Data.Parser.Base

Methods

pure :: a -> Parser a

(<*>) :: Parser (a -> b) -> Parser a -> Parser b

liftA2 :: (a -> b -> c) -> Parser a -> Parser b -> Parser c

(*>) :: Parser a -> Parser b -> Parser b

(<*) :: Parser a -> Parser b -> Parser a

Alternative Parser

Defined in Z.Data.Parser.Base

Methods

empty :: Parser a

(<|>) :: Parser a -> Parser a -> Parser a

some :: Parser a -> Parser [a]

many :: Parser a -> Parser [a]

MonadPlus Parser

Defined in Z.Data.Parser.Base

Methods

mzero :: Parser a

mplus :: Parser a -> Parser a -> Parser a

(<?>) :: Text -> Parser a -> Parser a infixr 0

Running a parser

parse :: Parser a -> Bytes -> (Bytes, Either ParseError a)

Parse the complete input, without resupplying, return the rest bytes

parse' :: Parser a -> Bytes -> Either ParseError a

Parse the complete input, without resupplying

parseChunk :: Parser a -> Bytes -> Result a

Parse an input chunk

type ParseChunks m chunk err x = m chunk -> chunk -> m (chunk, Either err x)

Type alias for a streaming parser, draw chunk from Monad m (with a initial chunk), return result in Either err x.

parseChunks :: Monad m => Parser a -> ParseChunks m Bytes ParseError a

Run a parser with an initial input string, and a monadic action that can supply more input if needed.

Note, once the monadic action return empty bytes, parsers will stop drawing more bytes (take it as endOfInput).

finishParsing :: Result a -> (Bytes, Either ParseError a)

Finish parsing and fetch result, feed empty bytes if it's Partial result.

runAndKeepTrack :: Parser a -> Parser (Result a, [Bytes])

Run a parser and keep track of all the input chunks it consumes. Once it's finished, return the final result (always Success or Failure) and all consumed chunks.

match :: Parser a -> Parser (Bytes, a)

Return both the result of a parse and the portion of the input that was consumed while it was being parsed.

Basic parsers

ensureN :: Int -> ParseError -> Parser ()

Ensure that there are at least n bytes available. If not, the computation will escape with Partial.

Since this parser is used in many other parsers, an extra error param is provide to attach custom error info.

endOfInput :: Parser ()

Test whether all input has been consumed, i.e. there are no remaining undecoded bytes. Fail if not atEnd.

atEnd :: Parser Bool

Test whether all input has been consumed, i.e. there are no remaining undecoded bytes.

Primitive decoders

decodePrim :: forall a. Unaligned a => Parser a

decodePrimLE :: forall a. Unaligned (LE a) => Parser a

decodePrimBE :: forall a. Unaligned (BE a) => Parser a

More parsers

scan :: s -> (s -> Word8 -> Maybe s) -> Parser (Bytes, s)

A stateful scanner. The predicate consumes and transforms a state argument, and each transformed state is passed to successive invocations of the predicate on each byte of the input until one returns Nothing or the input ends.

This parser does not fail. It will return an empty string if the predicate returns Nothing on the first byte of input.

scanChunks :: forall s. s -> (s -> Bytes -> Either s (Bytes, Bytes, s)) -> Parser (Bytes, s)

Similar to scan, but working on Bytes chunks, The predicate consumes a Bytes chunk and transforms a state argument, and each transformed state is passed to successive invocations of the predicate on each chunk of the input until one chunk got splited to Right (V.Bytes, V.Bytes) or the input ends.

peekMaybe :: Parser (Maybe Word8)

Match any byte, to perform lookahead. Returns Nothing if end of input has been reached. Does not consume any input.

peek :: Parser Word8

Match any byte, to perform lookahead. Does not consume any input, but will fail if end of input has been reached.

satisfy :: (Word8 -> Bool) -> Parser Word8

The parser satisfy p succeeds for any byte for which the predicate p returns True. Returns the byte that is actually parsed.

digit = satisfy isDigit
    where isDigit w = w >= 48 && w <= 57

satisfyWith :: (Word8 -> a) -> (a -> Bool) -> Parser a

The parser satisfyWith f p transforms a byte, and succeeds if the predicate p returns True on the transformed value. The parser returns the transformed byte that was parsed.

anyWord8 :: Parser Word8

Return a byte, this is an alias to decodePrim Word8@.

word8 :: Word8 -> Parser ()

Match a specific byte.

anyChar8 :: Parser Char

Take a byte and return as a 8bit char.

char8 :: Char -> Parser ()

Match a specific 8bit char.

skipWord8 :: Parser ()

Skip a byte.

endOfLine :: Parser ()

Match either a single newline byte '\n', or a carriage return followed by a newline byte "\r\n".

skip :: Int -> Parser ()

skip N bytes.

skipWhile :: (Word8 -> Bool) -> Parser ()

Skip past input for as long as the predicate returns True.

skipSpaces :: Parser ()

Skip over white space using isSpace.

take :: Int -> Parser Bytes

takeN :: (Word8 -> Bool) -> Int -> Parser Bytes

Similar to take, but requires the predicate to succeed on next N bytes of input, and take N bytes(no matter if N+1 byte satisfy predicate or not).

takeTill :: (Word8 -> Bool) -> Parser Bytes

Consume input as long as the predicate returns False or reach the end of input, and return the consumed input.

takeWhile :: (Word8 -> Bool) -> Parser Bytes

Consume input as long as the predicate returns True or reach the end of input, and return the consumed input.

takeWhile1 :: (Word8 -> Bool) -> Parser Bytes

Similar to takeWhile, but requires the predicate to succeed on at least one byte of input: it will fail if the predicate never returns True or reach the end of input

takeRemaining :: Parser Bytes

Take all the remaining input chunks and return as Bytes.

bytes :: Bytes -> Parser ()

bytes s parses a sequence of bytes that identically match s.

bytesCI :: Bytes -> Parser ()

Same as bytes but ignoring case.

text :: Text -> Parser ()

text s parses a sequence of UTF8 bytes that identically match s.

Misc

fail' :: Text -> Parser a

Text version of fail.