-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | High-performance parsing from strict bytestrings
--
-- Flatparse is a high-performance parsing library, focusing on
-- programming languages and human-readable data formats. See the README
-- for more information:
-- https://github.com/AndrasKovacs/flatparse.
@package flatparse
@version 0.1.1.1
-- | This module implements a Parser supporting a reader environment
-- and custom error types. If you need efficient indentation parsing, use
-- FlatParse.Stateful instead.
module FlatParse.Basic
-- | Parser r e a has a reader environment r, an error
-- type e and a return type a.
newtype Parser r e a
Parser :: (ForeignPtrContents -> r -> Addr# -> Addr# -> Res# e a) -> Parser r e a
[runParser#] :: Parser r e a -> ForeignPtrContents -> r -> Addr# -> Addr# -> Res# e a
-- | Primitive result of a parser. Possible results are given by
-- OK#, Err# and Fail# pattern synonyms.
type Res# e a = (# (# a, Addr# #) | (# #) | (# e #) #)
-- | Contains return value and a pointer to the rest of the input buffer.
pattern OK# :: a -> Addr# -> Res# e a
-- | Constructor for recoverable failure.
pattern Fail# :: Res# e a
-- | Constructor for errors which are by default non-recoverable.
pattern Err# :: e -> Res# e a
-- | Higher-level boxed data type for parsing results.
data Result e a
-- | Contains return value and unconsumed input.
OK :: a -> !ByteString -> Result e a
-- | Recoverable-by-default failure.
Fail :: Result e a
-- | Unrecoverble-by-default error.
Err :: !e -> Result e a
-- | Run a parser.
runParser :: Parser r e a -> r -> ByteString -> Result e a
-- | Run a parser on a String input. Reminder:
-- OverloadedStrings for ByteString does not yield a
-- valid UTF-8 encoding! For non-ASCII ByteString literal input,
-- use runParserS or packUTF8 for testing.
runParserS :: Parser r e a -> r -> String -> Result e a
-- | Query the read-only environment.
ask :: Parser r e r
-- | Run a parser in a modified environment.
local :: (r' -> r) -> Parser r e a -> Parser r' e a
-- | The failing parser. By default, parser choice (<|>)
-- arbitrarily backtracks on parser failure.
empty :: Parser r e a
-- | Throw a parsing error. By default, parser choice (<|>)
-- can't backtrack on parser error. Use try to convert an error to
-- a recoverable failure.
err :: e -> Parser r e a
-- | Save the parsing state, then run a parser, then restore the state.
lookahead :: Parser r e a -> Parser r e a
-- | Convert a parsing failure to a success.
fails :: Parser r e a -> Parser r e ()
-- | Convert a parsing error into failure.
try :: Parser r e a -> Parser r e a
-- | Convert a parsing failure to a Maybe. If possible, use
-- optioned instead.
optional :: Parser r e a -> Parser r e (Maybe a)
-- | Convert a parsing failure to a ().
optional_ :: Parser r e a -> Parser r e ()
-- | CPS'd version of optional. This is usually more efficient,
-- since it gets rid of the extra Maybe allocation.
optioned :: Parser r e a -> (a -> Parser r e b) -> Parser r e b -> Parser r e b
-- | Convert a parsing failure to an error.
cut :: Parser r e a -> e -> Parser r e a
-- | Run the parser, if we get a failure, throw the given error, but if we
-- get an error, merge the inner and the newly given errors using the
-- e -> e -> e function. This can be useful for
-- implementing parsing errors which may propagate hints or accummulate
-- contextual information.
cutting :: Parser r e a -> e -> (e -> e -> e) -> Parser r e a
-- | Succeed if the input is empty.
eof :: Parser r e ()
-- | Parse a UTF-8 character literal. This is a template function, you can
-- use it as $(char 'x'), for example, and the splice in this
-- case has type Parser r e ().
char :: Char -> Q Exp
-- | Read a Word8.
byte :: Word8 -> Parser r e ()
-- | Read a sequence of bytes. This is a template function, you can use it
-- as $(bytes [3, 4, 5]), for example, and the splice has type
-- Parser r e ().
bytes :: [Word8] -> Q Exp
-- | Parse a UTF-8 string literal. This is a template function, you can use
-- it as $(string "foo"), for example, and the splice has type
-- Parser r e ().
string :: String -> Q Exp
-- | This is a template function which makes it possible to branch on a
-- collection of string literals in an efficient way. By using
-- switch, such branching is compiled to a trie of primitive
-- parsing operations, which has optimized control flow, vectorized reads
-- and grouped checking for needed input bytes.
--
-- The syntax is slightly magical, it overloads the usual case
-- expression. An example:
--
--
-- $(switch [| case _ of
-- "foo" -> pure True
-- "bar" -> pure False |])
--
--
-- The underscore is mandatory in case _ of. Each branch must be
-- a string literal, but optionally we may have a default case, like in
--
--
-- $(switch [| case _ of
-- "foo" -> pure 10
-- "bar" -> pure 20
-- _ -> pure 30 |])
--
--
-- All case right hand sides must be parsers with the same type. That
-- type is also the type of the whole switch expression.
--
-- A switch has longest match semantics, and the order of cases
-- does not matter, except for the default case, which may only appear as
-- the last case.
--
-- If a switch does not have a default case, and no case matches
-- the input, then it returns with failure, without having consumed any
-- input. A fallthrough to the default case also does not consume any
-- input.
switch :: Q Exp -> Q Exp
-- | Switch expression with an optional first argument for performing a
-- post-processing action after every successful branch matching. For
-- example, if we have ws :: Parser r e () for a whitespace
-- parser, we might want to consume whitespace after matching on any of
-- the switch cases. For that case, we can define a "lexeme" version of
-- switch as follows.
--
--
-- switch' :: Q Exp -> Q Exp
-- switch' = switchWithPost (Just [| ws |])
--
--
-- Note that this switch' function cannot be used in the same
-- module it's defined in, because of the stage restriction of Template
-- Haskell.
switchWithPost :: Maybe (Q Exp) -> Q Exp -> Q Exp
-- | Version of switchWithPost without syntactic sugar. The second
-- argument is the list of cases, the third is the default case.
rawSwitchWithPost :: Maybe (Q Exp) -> [(String, Q Exp)] -> Maybe (Q Exp) -> Q Exp
-- | Parse a UTF-8 Char for which a predicate holds.
satisfy :: (Char -> Bool) -> Parser r e Char
-- | Parse an ASCII Char for which a predicate holds. Assumption:
-- the predicate must only return True for ASCII-range characters.
-- Otherwise this function might read a 128-255 range byte, thereby
-- breaking UTF-8 decoding.
satisfyASCII :: (Char -> Bool) -> Parser r e Char
-- | Parse an ASCII Char for which a predicate holds.
satisfyASCII_ :: (Char -> Bool) -> Parser r e ()
-- | This is a variant of satisfy which allows more optimization. We
-- can pick four testing functions for the four cases for the possible
-- number of bytes in the UTF-8 character. So in fusedSatisfy f1 f2
-- f3 f4, if we read a one-byte character, the result is scrutinized
-- with f1, for two-bytes, with f2, and so on. This can
-- result in dramatic lexing speedups.
--
-- For example, if we want to accept any letter, the naive solution would
-- be to use isLetter, but this accesses a large lookup table of
-- Unicode character classes. We can do better with fusedSatisfy
-- isLatinLetter isLetter isLetter isLetter, since here the
-- isLatinLetter is inlined into the UTF-8 decoding, and it
-- probably handles a great majority of all cases without accessing the
-- character table.
fusedSatisfy :: (Char -> Bool) -> (Char -> Bool) -> (Char -> Bool) -> (Char -> Bool) -> Parser r e Char
-- | Parse any Word8.
anyWord8 :: Parser r e Word8
-- | Parse any Word16.
anyWord16 :: Parser r e Word16
-- | Parse any Word32.
anyWord32 :: Parser r e Word32
-- | Parse any Word.
anyWord :: Parser r e Word
-- | Parse any UTF-8-encoded Char.
anyChar :: Parser r e Char
-- | Skip any UTF-8-encoded Char.
anyChar_ :: Parser r e ()
-- | Parse any Char in the ASCII range, fail if the next input
-- character is not in the range. This is more efficient than
-- anyChar if we are only working with ASCII.
anyCharASCII :: Parser r e Char
-- | Skip any Char in the ASCII range. More efficient than
-- anyChar_ if we're working only with ASCII.
anyCharASCII_ :: Parser r e ()
-- |
-- isDigit c = '0' <= c && c <= '9'
--
isDigit :: Char -> Bool
-- |
-- isGreekLetter c = ('Α' <= c && c <= 'Ω') || ('α' <= c && c <= 'ω')
--
isGreekLetter :: Char -> Bool
-- |
-- isLatinLetter c = ('A' <= c && c <= 'Z') || ('a' <= c && c <= 'z')
--
isLatinLetter :: Char -> Bool
-- | Choose between two parsers. If the first parser fails, try the second
-- one, but if the first one throws an error, propagate the error.
(<|>) :: Parser r e a -> Parser r e a -> Parser r e a
infixr 6 <|>
-- | Branch on a parser: if the first argument fails, continue with the
-- second, else with the third. This can produce slightly more efficient
-- code than (<|>). Moreover, ḃranch does not
-- backtrack from the true/false cases.
branch :: Parser r e a -> Parser r e b -> Parser r e b -> Parser r e b
-- | An analogue of the list foldl function: first parse a
-- b, then parse zero or more a-s, and combine the
-- results in a left-nested way by the b -> a -> b
-- function. Note: this is not the usual chainl function from the
-- parsec libraries!
chainl :: (b -> a -> b) -> Parser r e b -> Parser r e a -> Parser r e b
-- | An analogue of the list foldr function: parse zero or more
-- a-s, terminated by a b, and combine the results in a
-- right-nested way using the a -> b -> b function. Note:
-- this is not the usual chainr function from the parsec
-- libraries!
chainr :: (a -> b -> b) -> Parser r e a -> Parser r e b -> Parser r e b
-- | Run a parser zero or more times, collect the results in a list. Note:
-- for optimal performance, try to avoid this. Often it is possible to
-- get rid of the intermediate list by using a combinator or a custom
-- parser.
many :: Parser r e a -> Parser r e [a]
-- | Skip a parser zero or more times.
many_ :: Parser r e a -> Parser r e ()
-- | Run a parser one or more times, collect the results in a list. Note:
-- for optimal performance, try to avoid this. Often it is possible to
-- get rid of the intermediate list by using a combinator or a custom
-- parser.
some :: Parser r e a -> Parser r e [a]
-- | Skip a parser one or more times.
some_ :: Parser r e a -> Parser r e ()
-- | Succeed if the first parser succeeds and the second one fails.
notFollowedBy :: Parser r e a -> Parser r e b -> Parser r e a
-- | Byte offset counted backwards from the end of the buffer.
newtype Pos
Pos :: Int -> Pos
-- | A pair of positions.
data Span
Span :: !Pos -> !Pos -> Span
-- | Get the current position in the input.
getPos :: Parser r e Pos
-- | Set the input position. Warning: this can result in crashes if the
-- position points outside the current buffer. It is always safe to
-- setPos values which came from getPos with the current
-- input.
setPos :: Pos -> Parser r e ()
-- | The end of the input.
endPos :: Pos
-- | Return the consumed span of a parser.
spanOf :: Parser r e a -> Parser r e Span
-- | Bind the result together with the span of the result. CPS'd version of
-- spanOf for better unboxing.
spanned :: Parser r e a -> (a -> Span -> Parser r e b) -> Parser r e b
-- | Return the ByteString consumed by a parser. Note: it's more
-- efficient to use spanOf and spanned instead.
byteStringOf :: Parser r e a -> Parser r e ByteString
-- | CPS'd version of byteStringOf. Can be more efficient, because
-- the result is more eagerly unboxed by GHC. It's more efficient to use
-- spanOf or spanned instead.
byteStringed :: Parser r e a -> (a -> ByteString -> Parser r e b) -> Parser r e b
-- | Run a parser in a given input span. The input position and the
-- Int state is restored after the parser is finished, so
-- inSpan does not consume input and has no side effect. Warning:
-- this operation may crash if the given span points outside the current
-- parsing buffer. It's always safe to use inSpan if the span
-- comes from a previous spanned or spanOf call on the
-- current input.
inSpan :: Span -> Parser r e a -> Parser r e a
-- | Check whether a Pos points into a ByteString.
validPos :: ByteString -> Pos -> Bool
-- | Compute corresponding line and column numbers for each Pos in a
-- list. Throw an error on invalid positions. Note: computing lines and
-- columns may traverse the ByteString, but it traverses it only
-- once regardless of the length of the position list.
posLineCols :: ByteString -> [Pos] -> [(Int, Int)]
-- | Create a ByteString from a Span. The result is invalid
-- is the Span points outside the current buffer, or if the
-- Span start is greater than the end position.
unsafeSpanToByteString :: Span -> Parser r e ByteString
-- | Create a Pos from a line and column number. Throws an error on
-- out-of-bounds line and column numbers.
mkPos :: ByteString -> (Int, Int) -> Pos
-- | Break an UTF-8-coded ByteString to lines. Throws an error on
-- invalid input. This is mostly useful for grabbing specific source
-- lines for displaying error messages.
lines :: ByteString -> [String]
-- | Parse the rest of the current line as a String. Assumes UTF-8
-- encoding, throws an error if the encoding is invalid.
takeLine :: Parser r e String
-- | Parse the rest of the current line as a String, but restore the
-- parsing state. Assumes UTF-8 encoding. This can be used for debugging.
traceLine :: Parser r e String
-- | Take the rest of the input as a String. Assumes UTF-8 encoding.
takeRest :: Parser r e String
-- | Get the rest of the input as a String, but restore the parsing
-- state. Assumes UTF-8 encoding. This can be used for debugging.
traceRest :: Parser r e String
-- | Check that the input has at least the given number of bytes.
ensureBytes# :: Int -> Parser r e ()
-- | Unsafely read a concrete byte from the input. It's not checked that
-- the input has enough bytes.
scan8# :: Word -> Parser r e ()
-- | Unsafely read two concrete bytes from the input. It's not checked that
-- the input has enough bytes.
scan16# :: Word -> Parser r e ()
-- | Unsafely read four concrete bytes from the input. It's not checked
-- that the input has enough bytes.
scan32# :: Word -> Parser r e ()
-- | Unsafely read eight concrete bytes from the input. It's not checked
-- that the input has enough bytes.
scan64# :: Word -> Parser r e ()
-- | Unsafely read and return a byte from the input. It's not checked that
-- the input is non-empty.
scanAny8# :: Parser r e Word8
-- | Template function, creates a Parser r e () which unsafely
-- scans a given sequence of bytes.
scanBytes# :: [Word8] -> Q Exp
-- | Decrease the current input position by the given number of bytes.
setBack# :: Int -> Parser r e ()
-- | Convert a String to an UTF-8-coded ByteString.
packUTF8 :: String -> ByteString
instance (GHC.Show.Show a, GHC.Show.Show e) => GHC.Show.Show (FlatParse.Basic.Result e a)
instance GHC.Show.Show FlatParse.Basic.Pos
instance GHC.Classes.Eq FlatParse.Basic.Pos
instance GHC.Show.Show FlatParse.Basic.Span
instance GHC.Classes.Eq FlatParse.Basic.Span
instance GHC.Classes.Ord FlatParse.Basic.Pos
instance GHC.Base.Functor (FlatParse.Basic.Result e)
instance GHC.Base.Functor (FlatParse.Basic.Parser r e)
instance GHC.Base.Applicative (FlatParse.Basic.Parser r e)
instance GHC.Base.Monad (FlatParse.Basic.Parser r e)
-- | This module contains lexer and error message primitives for a simple
-- lambda calculus parser. It demonstrates a simple but decently
-- informative implementation of error message propagation.
module FlatParse.Examples.BasicLambda.Lexer
-- | An expected item which is displayed in error messages.
data Expected
-- | An expected literal string.
Lit :: String -> Expected
-- | A description of what's expected.
Msg :: String -> Expected
-- | A parsing error, without source position.
data Error'
-- | A precisely known error, like leaving out "in" from "let".
Precise :: Expected -> Error'
-- | An imprecise error, when we expect a number of different things, but
-- parse something else.
Imprecise :: [Expected] -> Error'
-- | A source-annotated error.
data Error
Error :: !Pos -> !Error' -> Error
-- | Merge two errors. Imprecise errors are merged by appending lists of
-- expected items. If we have a precise and an imprecise error, we throw
-- away the imprecise one. If we have two precise errors, we choose the
-- left one, which is by convention the one throw by an inner parser.
--
-- The point of prioritizing inner and precise errors is to suppress the
-- deluge of "expected" items, and instead try to point to a concrete
-- issue to fix.
merge :: Error -> Error -> Error
type Parser = Parser () Error
-- | Pretty print an error. The ByteString input is the source file.
-- The offending line from the source is displayed in the output.
prettyError :: ByteString -> Error -> String
-- | Imprecise cut: we slap a list of expected things on inner errors.
cut :: Parser a -> [Expected] -> Parser a
-- | Precise cut: we propagate at most a single expected thing.
cut' :: Parser a -> Expected -> Parser a
runParser :: Parser a -> ByteString -> Result Error a
-- | Run parser, print pretty error on failure.
testParser :: Show a => Parser a -> String -> IO ()
-- | Parse a line comment.
lineComment :: Parser ()
-- | Parse a potentially nested multiline comment.
multilineComment :: Parser ()
-- | Consume whitespace.
ws :: Parser ()
-- | Consume whitespace after running a parser.
token :: Parser a -> Parser a
-- | Read a starting character of an identifier.
identStartChar :: Parser Char
-- | Read a non-starting character of an identifier.
identChar :: Parser Char
-- | Check whether a Span contains exactly a keyword. Does not
-- change parsing state.
isKeyword :: Span -> Parser ()
-- | Parse a non-keyword string.
symbol :: String -> Q Exp
-- | Parser a non-keyword string, throw precise error on failure.
cutSymbol :: String -> Q Exp
-- | Parse a keyword string.
keyword :: String -> Q Exp
-- | Parse a keyword string, throw precise error on failure.
cutKeyword :: String -> Q Exp
instance GHC.Classes.Ord FlatParse.Examples.BasicLambda.Lexer.Expected
instance GHC.Show.Show FlatParse.Examples.BasicLambda.Lexer.Expected
instance GHC.Classes.Eq FlatParse.Examples.BasicLambda.Lexer.Expected
instance GHC.Show.Show FlatParse.Examples.BasicLambda.Lexer.Error'
instance GHC.Show.Show FlatParse.Examples.BasicLambda.Lexer.Error
-- | This module contains a simple lambda calculus parser. This parser is
-- not optimized for maximum performance; instead it's written in a style
-- which emulates the look and feel of conventional monadic parsers. An
-- optimized implementation would use low-level switch expressions
-- more often.
module FlatParse.Examples.BasicLambda.Parser
type Name = ByteString
-- | A term in the language. The precedences of different constructs are
-- the following, in decreasing order of strength:
--
--
-- - Identifiers, literals and parenthesized expressions
-- - Function application (left assoc)
-- - Multiplication (left assoc)
-- - Addition (left assoc)
-- - Equality, less-than (non-assoc)
-- - lam, let, if (right assoc)
--
data Tm
-- |
-- x
--
Var :: Name -> Tm
-- |
-- t u
--
App :: Tm -> Tm -> Tm
-- |
-- lam x. t
--
Lam :: Name -> Tm -> Tm
-- |
-- let x = t in u
--
Let :: Name -> Tm -> Tm -> Tm
-- | true or false.
BoolLit :: Bool -> Tm
-- | A positive Int literal.
IntLit :: Int -> Tm
-- |
-- if t then u else v
--
If :: Tm -> Tm -> Tm -> Tm
-- |
-- t + u
--
Add :: Tm -> Tm -> Tm
-- |
-- t * u
--
Mul :: Tm -> Tm -> Tm
-- |
-- t == u
--
Eq :: Tm -> Tm -> Tm
-- |
-- t < u
--
Lt :: Tm -> Tm -> Tm
-- | Parse an identifier. This parser uses isKeyword to check that
-- an identifier is not a keyword.
ident :: Parser Name
-- | Parse an identifier, throw a precise error on failure.
cutIdent :: Parser Name
digit :: Parser Int
int :: Parser Int
-- | Parse a literal, identifier or parenthesized expression.
atom :: Parser Tm
expectAtom :: [Expected]
-- | Parse an App-level expression.
app :: Parser Tm
-- | Parse a Mul-level expression.
mul :: Parser Tm
-- | Parse an Add-level expression.
add :: Parser Tm
-- | Parse an Eq or Lt-level expression.
eqLt :: Parser Tm
-- | Parse a Let.
pLet :: Parser Tm
-- | Parse a Lam.
lam :: Parser Tm
-- | Parse an If.
pIf :: Parser Tm
-- | Parse any Tm.
tm :: Parser Tm
-- | Parse a complete source file.
src :: Parser Tm
p1 :: String
instance GHC.Show.Show FlatParse.Examples.BasicLambda.Parser.Tm
-- | This module implements a Parser supporting a reader
-- environment, custom error types, and an Int state.
module FlatParse.Stateful
-- | Parser r e a has a reader environment r, an error
-- type e and a return type a.
newtype Parser r e a
Parser :: (ForeignPtrContents -> r -> Addr# -> Addr# -> Int# -> Res# e a) -> Parser r e a
[runParser#] :: Parser r e a -> ForeignPtrContents -> r -> Addr# -> Addr# -> Int# -> Res# e a
-- | Primitive result of a parser. Possible results are given by
-- OK#, Err# and Fail# pattern synonyms.
type Res# e a = (# (# a, Addr#, Int# #) | (# #) | (# e #) #)
-- | Contains return value, pointer to the rest of the input buffer and the
-- nex Int state.
pattern OK# :: a -> Addr# -> Int# -> Res# e a
-- | Constructor for recoverable failure.
pattern Fail# :: Res# e a
-- | Constructor for errors which are by default non-recoverable.
pattern Err# :: e -> Res# e a
-- | Higher-level boxed data type for parsing results.
data Result e a
-- | Contains return value, last Int state, unconsumed input.
OK :: a -> Int -> !ByteString -> Result e a
-- | Recoverable-by-default failure.
Fail :: Result e a
-- | Unrecoverble-by-default error.
Err :: !e -> Result e a
-- | Run a parser.
runParser :: Parser r e a -> r -> Int -> ByteString -> Result e a
-- | Run a parser on a String input. Reminder:
-- OverloadedStrings for ByteString does not yield a
-- valid UTF-8 encoding! For non-ASCII ByteString literal input,
-- use runParserS or packUTF8 for testing.
runParserS :: Parser r e a -> r -> Int -> String -> Result e a
-- | Query the Int state.
get :: Parser r e Int
-- | Write the Int state.
put :: Int -> Parser r e ()
-- | Modify the Int state.
modify :: (Int -> Int) -> Parser r e ()
-- | Query the read-only environment.
ask :: Parser r e r
-- | Run a parser in a modified environment.
local :: (r' -> r) -> Parser r e a -> Parser r' e a
-- | The failing parser. By default, parser choice (<|>)
-- arbitrarily backtracks on parser failure.
empty :: Parser r e a
-- | Throw a parsing error. By default, parser choice (<|>)
-- can't backtrack on parser error. Use try to convert an error to
-- a recoverable failure.
err :: e -> Parser r e a
-- | Save the parsing state, then run a parser, then restore the state.
lookahead :: Parser r e a -> Parser r e a
-- | Convert a parsing failure to a success.
fails :: Parser r e a -> Parser r e ()
-- | Convert a parsing error into failure.
try :: Parser r e a -> Parser r e a
-- | Convert a parsing failure to a Maybe. If possible, use
-- optioned instead.
optional :: Parser r e a -> Parser r e (Maybe a)
-- | Convert a parsing failure to a ().
optional_ :: Parser r e a -> Parser r e ()
-- | CPS'd version of optional. This is usually more efficient,
-- since it gets rid of the extra Maybe allocation.
optioned :: Parser r e a -> (a -> Parser r e b) -> Parser r e b -> Parser r e b
-- | Convert a parsing failure to an error.
cut :: Parser r e a -> e -> Parser r e a
-- | Run the parser, if we get a failure, throw the given error, but if we
-- get an error, merge the inner and the newly given errors using the
-- e -> e -> e function. This can be useful for
-- implementing parsing errors which may propagate hints or accummulate
-- contextual information.
cutting :: Parser r e a -> e -> (e -> e -> e) -> Parser r e a
-- | Succeed if the input is empty.
eof :: Parser r e ()
-- | Parse a UTF-8 character literal. This is a template function, you can
-- use it as $(char 'x'), for example, and the splice in this
-- case has type Parser r e ().
char :: Char -> Q Exp
-- | Read a Word8.
byte :: Word8 -> Parser r e ()
-- | Read a sequence of bytes. This is a template function, you can use it
-- as $(bytes [3, 4, 5]), for example, and the splice has type
-- Parser r e ().
bytes :: [Word8] -> Q Exp
-- | Parse a UTF-8 string literal. This is a template function, you can use
-- it as $(string "foo"), for example, and the splice has type
-- Parser r e ().
string :: String -> Q Exp
-- | This is a template function which makes it possible to branch on a
-- collection of string literals in an efficient way. By using
-- switch, such branching is compiled to a trie of primitive
-- parsing operations, which has optimized control flow, vectorized reads
-- and grouped checking for needed input bytes.
--
-- The syntax is slightly magical, it overloads the usual case
-- expression. An example:
--
--
-- $(switch [| case _ of
-- "foo" -> pure True
-- "bar" -> pure False |])
--
--
-- The underscore is mandatory in case _ of. Each branch must be
-- a string literal, but optionally we may have a default case, like in
--
--
-- $(switch [| case _ of
-- "foo" -> pure 10
-- "bar" -> pure 20
-- _ -> pure 30 |])
--
--
-- All case right hand sides must be parsers with the same type. That
-- type is also the type of the whole switch expression.
--
-- A switch has longest match semantics, and the order of cases
-- does not matter, except for the default case, which may only appear as
-- the last case.
--
-- If a switch does not have a default case, and no case matches
-- the input, then it returns with failure, without having consumed any
-- input. A fallthrough to the default case also does not consume any
-- input.
switch :: Q Exp -> Q Exp
-- | Switch expression with an optional first argument for performing a
-- post-processing action after every successful branch matching. For
-- example, if we have ws :: Parser r e () for a whitespace
-- parser, we might want to consume whitespace after matching on any of
-- the switch cases. For that case, we can define a "lexeme" version of
-- switch as follows.
--
--
-- switch' :: Q Exp -> Q Exp
-- switch' = switchWithPost (Just [| ws |])
--
--
-- Note that this switch' function cannot be used in the same
-- module it's defined in, because of the stage restriction of Template
-- Haskell.
switchWithPost :: Maybe (Q Exp) -> Q Exp -> Q Exp
-- | Version of switchWithPost without syntactic sugar. The second
-- argument is the list of cases, the third is the default case.
rawSwitchWithPost :: Maybe (Q Exp) -> [(String, Q Exp)] -> Maybe (Q Exp) -> Q Exp
-- | Parse a UTF-8 Char for which a predicate holds.
satisfy :: (Char -> Bool) -> Parser r e Char
-- | Parse an ASCII Char for which a predicate holds. Assumption:
-- the predicate must only return True for ASCII-range characters.
-- Otherwise this function might read a 128-255 range byte, thereby
-- breaking UTF-8 decoding.
satisfyASCII :: (Char -> Bool) -> Parser r e Char
-- | Parse an ASCII Char for which a predicate holds.
satisfyASCII_ :: (Char -> Bool) -> Parser r e ()
-- | This is a variant of satisfy which allows more optimization. We
-- can pick four testing functions for the four cases for the possible
-- number of bytes in the UTF-8 character. So in fusedSatisfy f1 f2
-- f3 f4, if we read a one-byte character, the result is scrutinized
-- with f1, for two-bytes, with f2, and so on. This can
-- result in dramatic lexing speedups.
--
-- For example, if we want to accept any letter, the naive solution would
-- be to use isLetter, but this accesses a large lookup table of
-- Unicode character classes. We can do better with fusedSatisfy
-- isLatinLetter isLetter isLetter isLetter, since here the
-- isLatinLetter is inlined into the UTF-8 decoding, and it
-- probably handles a great majority of all cases without accessing the
-- character table.
fusedSatisfy :: (Char -> Bool) -> (Char -> Bool) -> (Char -> Bool) -> (Char -> Bool) -> Parser r e Char
-- | Parse any Word8.
anyWord8 :: Parser r e Word8
-- | Parse any Word16.
anyWord16 :: Parser r e Word16
-- | Parse any Word32.
anyWord32 :: Parser r e Word32
-- | Parse any Word.
anyWord :: Parser r e Word
-- | Parse any UTF-8-encoded Char.
anyChar :: Parser r e Char
-- | Skip any UTF-8-encoded Char.
anyChar_ :: Parser r e ()
-- | Parse any Char in the ASCII range, fail if the next input
-- character is not in the range. This is more efficient than
-- anyChar if we are only working with ASCII.
anyCharASCII :: Parser r e Char
-- | Skip any Char in the ASCII range. More efficient than
-- anyChar_ if we're working only with ASCII.
anyCharASCII_ :: Parser r e ()
-- |
-- isDigit c = '0' <= c && c <= '9'
--
isDigit :: Char -> Bool
-- |
-- isGreekLetter c = ('Α' <= c && c <= 'Ω') || ('α' <= c && c <= 'ω')
--
isGreekLetter :: Char -> Bool
-- |
-- isLatinLetter c = ('A' <= c && c <= 'Z') || ('a' <= c && c <= 'z')
--
isLatinLetter :: Char -> Bool
-- | Choose between two parsers. If the first parser fails, try the second
-- one, but if the first one throws an error, propagate the error.
(<|>) :: Parser r e a -> Parser r e a -> Parser r e a
infixr 6 <|>
-- | Branch on a parser: if the first argument fails, continue with the
-- second, else with the third. This can produce slightly more efficient
-- code than (<|>). Moreover, ḃranch does not
-- backtrack from the true/false cases.
branch :: Parser r e a -> Parser r e b -> Parser r e b -> Parser r e b
-- | An analogue of the list foldl function: first parse a
-- b, then parse zero or more a-s, and combine the
-- results in a left-nested way by the b -> a -> b
-- function. Note: this is not the usual chainl function from the
-- parsec libraries!
chainl :: (b -> a -> b) -> Parser r e b -> Parser r e a -> Parser r e b
-- | An analogue of the list foldr function: parse zero or more
-- a-s, terminated by a b, and combine the results in a
-- right-nested way using the a -> b -> b function. Note:
-- this is not the usual chainr function from the parsec
-- libraries!
chainr :: (a -> b -> b) -> Parser r e a -> Parser r e b -> Parser r e b
-- | Run a parser zero or more times, collect the results in a list. Note:
-- for optimal performance, try to avoid this. Often it is possible to
-- get rid of the intermediate list by using a combinator or a custom
-- parser.
many :: Parser r e a -> Parser r e [a]
-- | Skip a parser zero or more times.
many_ :: Parser r e a -> Parser r e ()
-- | Run a parser one or more times, collect the results in a list. Note:
-- for optimal performance, try to avoid this. Often it is possible to
-- get rid of the intermediate list by using a combinator or a custom
-- parser.
some :: Parser r e a -> Parser r e [a]
-- | Skip a parser one or more times.
some_ :: Parser r e a -> Parser r e ()
-- | Succeed if the first parser succeeds and the second one fails. The
-- parsing state is restored to the point of the first argument's
-- success.
notFollowedBy :: Parser r e a -> Parser r e b -> Parser r e a
-- | Byte offset counted backwards from the end of the buffer.
newtype Pos
Pos :: Int -> Pos
-- | A pair of positions.
data Span
Span :: !Pos -> !Pos -> Span
-- | Get the current position in the input.
getPos :: Parser r e Pos
-- | Set the input position. Warning: this can result in crashes if the
-- position points outside the current buffer. It is always safe to
-- setPos values which came from getPos with the current
-- input.
setPos :: Pos -> Parser r e ()
-- | The end of the input.
endPos :: Pos
-- | Return the consumed span of a parser. Use spanned if possible
-- for better efficiency.
spanOf :: Parser r e a -> Parser r e Span
-- | Bind the result together with the span of the result. CPS'd version of
-- spanOf for better unboxing.
spanned :: Parser r e a -> (a -> Span -> Parser r e b) -> Parser r e b
-- | Return the ByteString consumed by a parser. Note: it's more
-- efficient to use spanOf and spanned instead.
byteStringOf :: Parser r e a -> Parser r e ByteString
-- | CPS'd version of byteStringOf. Can be more efficient, because
-- the result is more eagerly unboxed by GHC. It's more efficient to use
-- spanOf or spanned instead.
byteStringed :: Parser r e a -> (a -> ByteString -> Parser r e b) -> Parser r e b
-- | Run a parser in a given input span. The input position and the
-- Int state is restored after the parser is finished, so
-- inSpan does not consume input and has no side effect. Warning:
-- this operation may crash if the given span points outside the current
-- parsing buffer. It's always safe to use inSpan if the span
-- comes from a previous spanned or spanOf call on the
-- current input.
inSpan :: Span -> Parser r e a -> Parser r e a
-- | Check whether a Pos points into a ByteString.
validPos :: ByteString -> Pos -> Bool
-- | Compute corresponding line and column numbers for each Pos in a
-- list. Throw an error on invalid positions. Note: computing lines and
-- columns may traverse the ByteString, but it traverses it only
-- once regardless of the length of the position list.
posLineCols :: ByteString -> [Pos] -> [(Int, Int)]
-- | Create a ByteString from a Span. The result is invalid
-- is the Span points outside the current buffer, or if the
-- Span start is greater than the end position.
unsafeSpanToByteString :: Span -> Parser r e ByteString
-- | Create a Pos from a line and column number. Throws an error on
-- out-of-bounds line and column numbers.
mkPos :: ByteString -> (Int, Int) -> Pos
-- | Break an UTF-8-coded ByteString to lines. Throws an error on
-- invalid input. This is mostly useful for grabbing specific source
-- lines for displaying error messages.
lines :: ByteString -> [String]
-- | Parse the rest of the current line as a String. Assumes UTF-8
-- encoding, throws an error if the encoding is invalid.
takeLine :: Parser r e String
-- | Parse the rest of the current line as a String, but restore the
-- parsing state. Assumes UTF-8 encoding. This can be used for debugging.
traceLine :: Parser r e String
-- | Take the rest of the input as a String. Assumes UTF-8 encoding.
takeRest :: Parser r e String
-- | Get the rest of the input as a String, but restore the parsing
-- state. Assumes UTF-8 encoding. This can be used for debugging.
traceRest :: Parser r e String
-- | Check that the input has at least the given number of bytes.
ensureBytes# :: Int -> Parser r e ()
-- | Unsafely read a concrete byte from the input. It's not checked that
-- the input has enough bytes.
scan8# :: Word -> Parser r e ()
-- | Unsafely read two concrete bytes from the input. It's not checked that
-- the input has enough bytes.
scan16# :: Word -> Parser r e ()
-- | Unsafely read four concrete bytes from the input. It's not checked
-- that the input has enough bytes.
scan32# :: Word -> Parser r e ()
-- | Unsafely read eight concrete bytes from the input. It's not checked
-- that the input has enough bytes.
scan64# :: Word -> Parser r e ()
-- | Unsafely read and return a byte from the input. It's not checked that
-- the input is non-empty.
scanAny8# :: Parser r e Word8
-- | Template function, creates a Parser r e () which unsafely
-- scans a given sequence of bytes.
scanBytes# :: [Word8] -> Q Exp
-- | Decrease the current input position by the given number of bytes.
setBack# :: Int -> Parser r e ()
-- | Convert a String to an UTF-8-coded ByteString.
packUTF8 :: String -> ByteString
instance (GHC.Show.Show a, GHC.Show.Show e) => GHC.Show.Show (FlatParse.Stateful.Result e a)
instance GHC.Show.Show FlatParse.Stateful.Pos
instance GHC.Classes.Eq FlatParse.Stateful.Pos
instance GHC.Show.Show FlatParse.Stateful.Span
instance GHC.Classes.Eq FlatParse.Stateful.Span
instance GHC.Classes.Ord FlatParse.Stateful.Pos
instance GHC.Base.Functor (FlatParse.Stateful.Result e)
instance GHC.Base.Functor (FlatParse.Stateful.Parser r e)
instance GHC.Base.Applicative (FlatParse.Stateful.Parser r e)
instance GHC.Base.Monad (FlatParse.Stateful.Parser r e)