-- 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.2.1.0
-- | This module implements a Parser supporting custom error types.
-- If you need efficient indentation parsing, use
-- FlatParse.Stateful instead.
module FlatParse.Basic
-- | Parser e a has an error type e and a return type
-- a.
newtype Parser e a
Parser :: (ForeignPtrContents -> Addr# -> Addr# -> Res# e a) -> Parser e a
[runParser#] :: Parser e a -> ForeignPtrContents -> 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 e a -> 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 e a -> String -> Result e a
-- | The failing parser. By default, parser choice (<|>)
-- arbitrarily backtracks on parser failure.
empty :: Parser 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 e a
-- | Save the parsing state, then run a parser, then restore the state.
lookahead :: Parser e a -> Parser e a
-- | Convert a parsing failure to a success.
fails :: Parser e a -> Parser e ()
-- | Convert a parsing error into failure.
try :: Parser e a -> Parser e a
-- | Convert a parsing failure to a Maybe. If possible, use
-- optioned instead.
optional :: Parser e a -> Parser e (Maybe a)
-- | Convert a parsing failure to a ().
optional_ :: Parser e a -> Parser e ()
-- | CPS'd version of optional. This is usually more efficient,
-- since it gets rid of the extra Maybe allocation.
optioned :: Parser e a -> (a -> Parser e b) -> Parser e b -> Parser e b
-- | Convert a parsing failure to an error.
cut :: Parser e a -> e -> Parser 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 e a -> e -> (e -> e -> e) -> Parser e a
-- | Succeed if the input is empty.
eof :: Parser 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 e ().
char :: Char -> Q Exp
-- | Read a Word8.
byte :: Word8 -> Parser 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 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 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 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 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 e Char
-- | Parse an ASCII Char for which a predicate holds.
satisfyASCII_ :: (Char -> Bool) -> Parser 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 e Char
-- | Parse any Word8.
anyWord8 :: Parser e Word8
-- | Parse any Word16.
anyWord16 :: Parser e Word16
-- | Parse any Word32.
anyWord32 :: Parser e Word32
-- | Parse any Word.
anyWord :: Parser e Word
-- | Parse any UTF-8-encoded Char.
anyChar :: Parser e Char
-- | Skip any UTF-8-encoded Char.
anyChar_ :: Parser 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 e Char
-- | Skip any Char in the ASCII range. More efficient than
-- anyChar_ if we're working only with ASCII.
anyCharASCII_ :: Parser 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 e a -> Parser e a -> Parser 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 e a -> Parser e b -> Parser e b -> Parser 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 e b -> Parser e a -> Parser 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 e a -> Parser e b -> Parser 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 e a -> Parser e [a]
-- | Skip a parser zero or more times.
many_ :: Parser e a -> Parser 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 e a -> Parser e [a]
-- | Skip a parser one or more times.
some_ :: Parser e a -> Parser e ()
-- | Succeed if the first parser succeeds and the second one fails.
notFollowedBy :: Parser e a -> Parser e b -> Parser 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 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 e ()
-- | The end of the input.
endPos :: Pos
-- | Return the consumed span of a parser.
spanOf :: Parser e a -> Parser e Span
-- | Bind the result together with the span of the result. CPS'd version of
-- spanOf for better unboxing.
spanned :: Parser e a -> (a -> Span -> Parser e b) -> Parser e b
-- | Return the ByteString consumed by a parser. Note: it's more
-- efficient to use spanOf and spanned instead.
byteStringOf :: Parser e a -> Parser 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 e a -> (a -> ByteString -> Parser e b) -> Parser 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 e a -> Parser 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
-- if the Span points outside the current buffer, or if the
-- Span start is greater than the end position.
unsafeSpanToByteString :: Span -> Parser e ByteString
-- | Slice into a ByteString using a Span. The result is
-- invalid if the Span is not a valid slice of the first argument.
unsafeSlice :: ByteString -> Span -> 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 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 e String
-- | Take the rest of the input as a String. Assumes UTF-8 encoding.
takeRest :: Parser 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 e String
-- | Convert a String to an UTF-8-coded ByteString.
packUTF8 :: String -> ByteString
-- | Convert an UTF-8-coded ByteString to a String.
unpackUTF8 :: ByteString -> String
-- | Check that the input has at least the given number of bytes.
ensureBytes# :: Int -> Parser e ()
-- | Unsafely read a concrete byte from the input. It's not checked that
-- the input has enough bytes.
scan8# :: Word -> Parser e ()
-- | Unsafely read two concrete bytes from the input. It's not checked that
-- the input has enough bytes.
scan16# :: Word -> Parser e ()
-- | Unsafely read four concrete bytes from the input. It's not checked
-- that the input has enough bytes.
scan32# :: Word -> Parser e ()
-- | Unsafely read eight concrete bytes from the input. It's not checked
-- that the input has enough bytes.
scan64# :: Word -> Parser e ()
-- | Unsafely read and return a byte from the input. It's not checked that
-- the input is non-empty.
scanAny8# :: Parser e Word8
-- | Template function, creates a Parser 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 e ()
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 e)
instance GHC.Base.Applicative (FlatParse.Basic.Parser e)
instance GHC.Base.Monad (FlatParse.Basic.Parser 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 error message.
Msg :: String -> Expected
-- | A literal expected thing.
Lit :: String -> Expected
-- | A parsing error.
data Error
-- | A precisely known error, like leaving out "in" from "let".
Precise :: Pos -> Expected -> Error
-- | An imprecise error, when we expect a number of different things, but
-- parse something else.
Imprecise :: Pos -> [Expected] -> Error
errorPos :: Error -> Pos
-- | Merge two errors. Inner errors (which were thrown at points with more
-- consumed inputs) are preferred. If errors are thrown at identical
-- input positions, we prefer precise errors to imprecise ones.
--
-- 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 items on inner errors.
cut :: Parser a -> [Expected] -> Parser a
-- | Precise cut: we propagate at most a single error.
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.
symbol' :: String -> Q Exp
-- | Parse a keyword string.
keyword :: String -> Q Exp
-- | Parse a keyword string, throw precise error on failure.
keyword' :: 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 Data.String.IsString FlatParse.Examples.BasicLambda.Lexer.Expected
-- | 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.
ident' :: Parser Name
digit :: Parser Int
int :: Parser Int
-- | Parse a literal, identifier or parenthesized expression.
atom :: Parser Tm
atom' :: Parser Tm
-- | 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 an Int reader
-- environment, custom error types, and an Int state.
module FlatParse.Stateful
-- | Parser e a has an error type e and a return type
-- a.
newtype Parser e a
Parser :: (ForeignPtrContents -> Int# -> Addr# -> Addr# -> Int# -> Res# e a) -> Parser e a
[runParser#] :: Parser e a -> ForeignPtrContents -> Int# -> 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. The first Int argument is the reader environment,
-- while the second one is the state.
runParser :: Parser e a -> Int -> 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 e a -> Int -> Int -> String -> Result e a
-- | Query the Int state.
get :: Parser e Int
-- | Write the Int state.
put :: Int -> Parser e ()
-- | Modify the Int state.
modify :: (Int -> Int) -> Parser e ()
-- | Query the Int environment.
ask :: Parser e Int
-- | Run a parser in a modified environment.
local :: (Int -> Int) -> Parser e a -> Parser e a
-- | The failing parser. By default, parser choice (<|>)
-- arbitrarily backtracks on parser failure.
empty :: Parser 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 e a
-- | Save the parsing state, then run a parser, then restore the state.
lookahead :: Parser e a -> Parser e a
-- | Convert a parsing failure to a success.
fails :: Parser e a -> Parser e ()
-- | Convert a parsing error into failure.
try :: Parser e a -> Parser e a
-- | Convert a parsing failure to a Maybe. If possible, use
-- optioned instead.
optional :: Parser e a -> Parser e (Maybe a)
-- | Convert a parsing failure to a ().
optional_ :: Parser e a -> Parser e ()
-- | CPS'd version of optional. This is usually more efficient,
-- since it gets rid of the extra Maybe allocation.
optioned :: Parser e a -> (a -> Parser e b) -> Parser e b -> Parser e b
-- | Convert a parsing failure to an error.
cut :: Parser e a -> e -> Parser 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 e a -> e -> (e -> e -> e) -> Parser e a
-- | Succeed if the input is empty.
eof :: Parser 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 e ().
char :: Char -> Q Exp
-- | Read a Word8.
byte :: Word8 -> Parser 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 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 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 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 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 e Char
-- | Parse an ASCII Char for which a predicate holds.
satisfyASCII_ :: (Char -> Bool) -> Parser 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 e Char
-- | Parse any Word8.
anyWord8 :: Parser e Word8
-- | Parse any Word16.
anyWord16 :: Parser e Word16
-- | Parse any Word32.
anyWord32 :: Parser e Word32
-- | Parse any Word.
anyWord :: Parser e Word
-- | Parse any UTF-8-encoded Char.
anyChar :: Parser e Char
-- | Skip any UTF-8-encoded Char.
anyChar_ :: Parser 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 e Char
-- | Skip any Char in the ASCII range. More efficient than
-- anyChar_ if we're working only with ASCII.
anyCharASCII_ :: Parser 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 e a -> Parser e a -> Parser 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 e a -> Parser e b -> Parser e b -> Parser 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 e b -> Parser e a -> Parser 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 e a -> Parser e b -> Parser 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 e a -> Parser e [a]
-- | Skip a parser zero or more times.
many_ :: Parser e a -> Parser 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 e a -> Parser e [a]
-- | Skip a parser one or more times.
some_ :: Parser e a -> Parser 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 e a -> Parser e b -> Parser 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 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 e ()
-- | The end of the input.
endPos :: Pos
-- | Return the consumed span of a parser. Use spanned if possible
-- for better efficiency.
spanOf :: Parser e a -> Parser e Span
-- | Bind the result together with the span of the result. CPS'd version of
-- spanOf for better unboxing.
spanned :: Parser e a -> (a -> Span -> Parser e b) -> Parser e b
-- | Return the ByteString consumed by a parser. Note: it's more
-- efficient to use spanOf and spanned instead.
byteStringOf :: Parser e a -> Parser 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 e a -> (a -> ByteString -> Parser e b) -> Parser 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 e a -> Parser 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 e ByteString
-- | Slice into a ByteString using a Span. The result is
-- invalid if the Span is not a valid slice of the first argument.
unsafeSlice :: ByteString -> Span -> 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 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 e String
-- | Take the rest of the input as a String. Assumes UTF-8 encoding.
takeRest :: Parser 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 e String
-- | Convert a String to an UTF-8-coded ByteString.
packUTF8 :: String -> ByteString
-- | Convert an UTF-8-coded ByteString to a String.
unpackUTF8 :: ByteString -> String
-- | Check that the input has at least the given number of bytes.
ensureBytes# :: Int -> Parser e ()
-- | Unsafely read a concrete byte from the input. It's not checked that
-- the input has enough bytes.
scan8# :: Word -> Parser e ()
-- | Unsafely read two concrete bytes from the input. It's not checked that
-- the input has enough bytes.
scan16# :: Word -> Parser e ()
-- | Unsafely read four concrete bytes from the input. It's not checked
-- that the input has enough bytes.
scan32# :: Word -> Parser e ()
-- | Unsafely read eight concrete bytes from the input. It's not checked
-- that the input has enough bytes.
scan64# :: Word -> Parser e ()
-- | Unsafely read and return a byte from the input. It's not checked that
-- the input is non-empty.
scanAny8# :: Parser e Word8
-- | Template function, creates a Parser 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 e ()
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 e)
instance GHC.Base.Applicative (FlatParse.Stateful.Parser e)
instance GHC.Base.Monad (FlatParse.Stateful.Parser e)