This type represents parsers as a first-class value.

Values of this type are constructed using the library's combinators, to build up a final Parsec value that can be passed to parse or one of the similar functions. This is implemented internally similar to other libraries like parsec and gigaparsec.

Since: 0.1.0.0

Similar to Either, this type represents whether a parser has failed or not.

This is chosen instead of Either to be more specific about the naming.

Since: 0.1.0.0

A fold for the Result type.

This functions like the either function does for Either.

Since: 0.2.0.0

Runs a parser against some input.

Given a parser, some input, and a way of producing parse errors of a desired type (via ErrorBuilder), this function runs a parser to produce either a successful result or an error. Note that the err type parameter is first, which allows for parse @String to make use of the defaultly formated String error messages. This may not be required if it is clear from context. To make this process nicer within GHCi, consider using parseRepl.

Since: 0.2.0.0

Runs a parser against some input obtained from a given file.

Given a parser, a filename, and a way of producing parse errors of a desired type (via ErrorBuilder), this function runs a parser to produce either a successful result or an error. First, input is collected by reading the file, and then the result is returned within IO; the filename is forwarded on to the ErrorBuilder, which may mean it forms part of the generated error messages.

Note that the err type parameter is first, which allows for parseFromFile @String to make use of the defaultly formated String error messages. This may not be required if it is clear from context.

Since: 0.2.1.0

Runs a parser against some input, pretty-printing the result to the terminal.

Compared, with parse, this function will always generate error messages as strings and will print them nicely to the terminal (on multiple lines). If the parser succeeds, the result will also be printed to the terminal. This is useful for playing around with parsers in GHCi, seeing the results more clearly.

Since: 0.2.0.0

This combinator parses its argument p, but rolls back any consumed input on failure.

If the parser p succeeds, then atomic p has no effect. However, if p failed, then any input that it consumed is rolled back. This has two uses: it ensures that the parser p is all-or-nothing when consuming input, and it allows for parsers that consume input to backtrack when they fail (with (<|>)). It should be used for the latter purpose sparingly, however, since excessive backtracking in a parser can result in much lower efficiency.

Examples

>>> parse (string "abc" <|> string "abd") "abd"
Failure .. -- first parser consumed a, so no backtrack
>>> parse (atomic (string "abc") <|> string "abd") "abd"
Success "abd" -- first parser does not consume input on failure now

Since: 0.1.0.0

This combinator parses its argument p, but does not consume input if it succeeds.

If the parser p succeeds, then lookAhead p will roll back any input consumed whilst parsing p. If p fails, however, then the whole combinator fails and any input consumed remains consumed. If this behaviour is not desirable, consider pairing lookAhead with atomic.

Examples

>>> parse (lookAhead (string "aaa") *> string "aaa") "aaa"
Success "aaa"
>>> parse (lookAhead (string "abc") <|> string "abd" "abd"
Failure .. -- lookAhead does not roll back input consumed on failure

Since: 0.1.0.0

This combinator parses its argument p, and succeeds when p fails and vice-versa, never consuming input.

If the parser p succeeds, then notFollowedBy p will fail, consuming no input. Otherwise, should p fail, then notFollowedBy p will succeed, consuming no input and returning ().

Examples

keyword :: String -> Parsec ()
keyword kw = atomic $ string kw *> notFollowedBy letterOrDigit

Since: 0.1.0.0

This parser only succeeds at the end of the input.

Equivalent to `notFollowedBy(item)`.

Examples

>>> parse eof "a"
Failure ..
>>> parse eof ""
Success ()

Since: 0.1.0.0

This parser produces () without having any other effect.

When this parser is ran, no input is required, nor consumed, and the given value will always be successfully returned. It has no other effect on the state of the parser.

Since: 0.1.0.0

This combinator produces a value without having any other effect.

When this combinator is run, no input is required, nor consumed, and the given value will always be successfully returned. It has no other effect on the state of the parser.

Note: This is a re-export of Control.Applicative.pure. If you use pure from this module, it actually has the more general type as found in Control.Applicative.pure (it works for any Applicative p, rather than just Parsec).

For Gigaparsec Developers: Do not import this, use Control.Applicative.pure, as this has the more general type.

Since: 0.1.0.0

This parser fails immediately, with an unknown parse error.

Although this parser has type Parsec a, no a will actually be returned, as this parser fails.

This is the 'zero' or 'identity' of <|>:

p <|> empty = empty <|> p = p

Note: This is a re-export of Control.Applicative.empty. If you use empty from this module, it actually has the more general type as found in Control.Applicative.empty (it works for any Applicative p, rather than just Parsec).

For Gigaparsec Developers: Do not import this, use Control.Applicative.empty, as this has the more general type.

Since: 0.1.0.0

This combinator, pronounced "as", replaces the result of the given parser, ignoring the old result.

Similar to ($), except the old result of the given parser is not required to compute the new result. This is useful when the result is a constant value (or function!). Functionally the same as p *> pure x or const x $ p.

In scala parsley, this combinator is known as #> or 'as'.

Examples

>>> parse (string "true" $> true) "true"
Success true

Since: 0.1.0.0

This combinator applies a function f to the result of a parser p.

When p succeeds with value x, return f x.

This can be used to build more complex results from parsers, instead of just characters or strings.

Note: This is a re-export of Data.Functor.<$>. If you use <$> from this module, it actually has the more general type as found in Data.Functor.<$> (it works for any Functor f, rather than just Parsec).

For Gigaparsec Developers: Do not import this, use Data.Functor.<$> (or the Prelude), as this has the more general type.

Since: 0.1.0.0

This combinator runs the given parser p, and ignores its results, instead returning the given value x.

Similar to <$>, except the result of p is not required to compute the result. This may be defined in terms of <$>:

x <$ p = const x <$> p

Note: This is a re-export of Data.Functor.<$. If you use <$ from this module, it actually has the more general type as found in Data.Functor.<$ (it works for any Functor f, rather than just Parsec).

For Gigaparsec Developers: Do not import this, use Data.Functor.<$ (or the Prelude), as this has the more general type.

Since: 0.1.0.0

Run the given parser p, then discard its result.

This combinator is useful when p should be run, but its result is not required.

Note: This is a re-export of Data.Functor.void. If you use void from this module, it actually has the more general type as found in Data.Functor.void (it works for any Applicative p, rather than just Parsec).

For Gigaparsec Developers: Do not import this, use Data.Functor.void, as this has the more general type.

Since: 0.1.0.0

This combinator, pronounced "zip", first parses p then parses q: if both succeed the result of p is paired with that of q.

First, runs p, yielding x on success, then runs q, yielding y on success. If both are successful then (x, y) is returned. If either fail then the entire combinator fails.

Examples

>>> p = char 'a' <~> char 'b'
>>> parse p "ab"
Success ('a', 'b')
>>> parse p "b"
Failure ..
>>> parse p "a"
Failure ..

Since: 0.1.0.0

This combinator, pronounced "cons", first parses p and then ps: if both succeed the result of this parser is prepended onto the result of ps.

First, runs p, yielding x on success, then runs ps, yielding xs on success. If both are successful then x : xs is returned. If either fail then the entire combinator fails.

Examples

some p = p <:> many(p)

Since: 0.1.0.0

This combinator, pronounced "ap", first parses p then parses q: if both succeed then the function p returns is applied to the value returned by q.

First, runs p, yielding a function f on success, then runs q, yielding a value x on success. If both p and q are successful, then returns f x. If either fail then the entire combinator fails.

Note: This is a re-export of Control.Applicative.<*>. If you use <*> from this module, it actually has the more general type as found in Control.Applicative.<*> (it works for any Applicative p, rather than just Parsec).

For Gigaparsec Developers: Do not import this, use Control.Applicative.<*>, as this has the more general type.

Since: 0.1.0.0

This combinator applies the given parsers in sequence and then applies the given function f of to all of the results.

First, parse p, then parse q. If both parsers succeed, this combinator succeeds, returning the application of f to the results of p and q. If either p or q fails, this combinator fails.

Note: This is a re-export of Control.Applicative.liftA2. If you use liftA2 from this module, it actually has the more general type as found in Control.Applicative.liftA2 (it works for any Applicative p, rather than just Parsec).

For Gigaparsec Developers: Do not import this, use Control.Applicative.liftA2, as this has the more general type.

Since: 0.1.0.0

This combinator, pronounced "then", first parses p then parses q: if both p and q succeed then the result of q is returned.

First, runs p, yielding x on success, then runs q, yielding y on success. If both p and q are successful then returns y and ignores x If either fail then the entire combinator fails.

Note: This is a re-export of Control.Applicative.*>. If you use *> from this module, it actually has the more general type as found in Control.Applicative.*> (it works for any Applicative p, rather than just Parsec).

For Gigaparsec Developers: Do not import this, use Control.Applicative.*>, as this has the more general type.

Since: 0.1.0.0

This combinator, pronounced "then discard", first parses p then parses q: if both succeed then the result of p is returned.

First, runs p, yielding x on success, then runs q, yielding y on success. If both p and q are successful then returns x and ignores y. If either fail then the entire combinator fails.

Note: This is a re-export of Control.Applicative.<*. If you use <* from this module, it actually has the more general type as found in Control.Applicative.<* (it works for any Applicative p, rather than just Parsec).

For Gigaparsec Developers: Do not import this, use Control.Applicative.<*, as this has the more general type.

Since: 0.1.0.0

Given parsers p and f, this combinator, pronounced "reverse ap", first parses p then parses f: if both succeed then returns the result of f to that of p.

First, runs p, yielding a value x on success, then f is ran, yielding a function g on success. If both are successful, then g(x) is returned. If either fail then the entire combinator fails.

Compared with <*>, this combinator is useful for left-factoring: when two branches of a parser share a common prefix, this can often be factored out; but the result of that factored prefix may be required to help generate the results of each branch. In this case, the branches can return functions that, when given the factored result, can produce the original results from before the factoring.

Note: This is a re-export of Control.Applicative.<**>. If you use <**> from this module, it actually has the more general type as found in Control.Applicative.<**> (it works for any Applicative p, rather than just Parsec).

For Gigaparsec Developers: Do not import this, use Control.Applicative.<**>, as this has the more general type.

Since: 0.1.0.0

This combinator, pronounced "sum", wraps the given parser's result in Left if it succeeds, and parses q if it failed without consuming input, wrapping the result in Right.

If the given parser p is successful, then its result is wrapped up using Left and no further action is taken. Otherwise, if p fails without consuming input, then q is parsed instead and its result is wrapped up using Right. If p fails having consumed input, this combinator fails. This is functionally equivalent to Left $ p | Right $ q.

The reason for this behaviour is that it prevents space leaks and improves error messages. If this behaviour is not desired, use atomic p to rollback any input consumed on failure.

Examples

>>> p = string "abc" <+> char "xyz"
>>> parse p "abc"
Success (Left "abc")
>>> parse p "xyz"
Success (Right "xyz")
>>> parse p "ab"
Failure .. -- first parser consumed an 'a'!

Since: 0.1.0.0

Given the parsers p and q, this combinator parses p; if p fails without consuming input, it then parses q.

If p is successful, then this combinator is successful and no further action is taken. Otherwise, if p fails without consuming input, then q is parsed instead. If p (or q) fails having consumed input, this combinator fails.

This behaviour prevents space leaks and improves error messages. If this is not desired, use atomic p to rollback any input consumed on failure in the first branch.

This combinator is associative, meaning that:

(p <|> q) <|> r = p <|> (q <|> r)

Note: This is a re-export of Control.Applicative.|. If you use <|> from this module, it actually has the more general type as found in Control.Applicative.| (it works for any Applicative p, rather than just Parsec).

For Gigaparsec Developers: Do not import this, use Control.Applicative.|, as this has the more general type.

Since: 0.1.0.0

This combinator parses its first argument p, then parses q only if p returns a Left.

First, parse p, which, if successful, will produce either a Left x or a Right y:

• If a Left x is produced, then the parser q is executed to produce a function f, and f x is returned.
• Otherwise, if a Right(y) is produced, y is returned unmodified and q is not parsed.

If either p or q fails, the entire combinator fails. This is a special case of branch where the right branch is pure id.

Note: This is a re-export of Control.Selective.select. If you use select from this module, it actually has the more general type as found in Control.Selective.select (it works for any Selective p, rather than just Parsec).

For Gigaparsec Developers: Do not import this, use Control.Selective.select, as this has the more general type.

Since: 0.1.0.0

This combinator parses its first argument either, and then parses either left or right depending on its result.

First, parses either, which, if successful, produces either a Left x or a Right y:

• If a Left x is produced, run left is to produce a function f, and return f x.
• If a Right y is produced, run right to produce a function g, and return g y.

If either of the two executed parsers fail, the entire combinator fails.

Note: This is a re-export of Control.Selective.branch. If you use branch from this module, it actually has the more general type as found in Control.Selective.branch (it works for any Selective p, rather than just Parsec).

For Gigaparsec Developers: Do not import this, use Control.Selective.branch, as this has the more general type.

Since: 0.1.0.0

This combinator filters the result of the given parser p using the given predicate, succeeding only if the predicate returns True.

First, parse p. If it succeeds then take its result x and apply it to the predicate pred. If pred x is true, then return x. Otherwise, the combinator fails.

Examples

>>> keywords = Set.fromList ["if", "then", "else"]
>>> identifier = filterS (\v -> not (Set.member v keywords)) (some letter)
>>> parse identifier "hello"
Success "hello"
>>> parse identifier "if"
Failure ..

Since: 0.2.2.0

This combinator applies a function f to the result of the given parser p: if it returns a Just y, y is returned, otherwise this combinator fails.

First, parse p. If it succeeds, apply the function f to the result x. If f x returns Just y, return y. If f x returns Nothing, or p failed then this combinator fails. Is a more efficient way of performing a filterS and fmap at the same time.

Examples

>>> int = ...
>>> safeDiv = mapMaybeS (\(x, y) -> if y /= 0 then Just (div x y) else Nothing) (int <~> (char ' ' *> int))
>>> parse safeDiv "7 0"
Failure .. -- y cannot be 0!
>>> parse safeDiv "10 2"
Success 5

Since: 0.2.2.0

Repeatedly parse the given parser zero or more times, collecting the results into a list.

Parses the given parser p repeatedly until it fails. If p failed having consumed input, this combinator fails. Otherwise, when p fails without consuming input, this combinator will return all of the results, x₁ through xₙ (with n >= 0), in a List: [x₁, .., xₙ]. If p was never successful, the empty List is returned.

Note: This is a re-export of Control.Applicative.many. If you use many from this module, it actually has the more general type as found in Control.Applicative.many (it works for any Applicative p, rather than just Parsec).

For Gigaparsec Developers: Do not import this, use Control.Applicative.some, as this has the more general type.

Since: 0.1.0.0

This combinator will parse the given parser zero or more times combining the results with the function f and base value k from the left.

The given parser p will continue to be parsed until it fails having not consumed input. All of the results generated by the successful parses are then combined in a left-to-right fashion using the function f: the left-most value provided to f is the value k.

If p does fail at any point having consumed input, this combinator will fail.

Since: 0.3.0.0

This combinator will parse the given parser p zero or more times, combining the results with the function f and base value k from the right.

p will continue to be parsed until it fails having not consumed input. All of the results generated by the successful parses are then combined in a right-to-left fashion using the function f: the right-most value provided to f is the value k. If this parser does fail at any point having consumed input, this combinator will fail.

Examples

many = manyr (:) []

Since: 0.3.0.0

This combinator acts like the foldMap function but with a parser.

The parser manyMap f p, will parse p zero or more times, then adapt each result with the function f to produce a bunch of values in some Monoid m. These values are then combined together to form a single value; if p could not be parsed, it will return the mempty for m.

Examples

>>> parse (manyMap Set.singleton item) "aaaab"
Success (Set.fromList ['a', 'b'])

Since: 0.2.2.0

Repeatedly parse the given parser one or more times, collecting the results into a list.

Parses the given parser p repeatedly until it fails. If p failed having consumed input, this combinator fails. Otherwise, when p fails without consuming input, this combinator will return all of the results, x₁ through xₙ (with n >= 1), in a List: [x₁, .., xₙ]. If p was not successful at least one time, this combinator fails.

See Also: some for a version of this combinator which returns a NonEmpty list of results.

Note: This is a re-export of Control.Applicative.some. If you use some from this module, it actually has the more general type as found in Control.Applicative.some (it works for any Applicative p, rather than just Parsec).

For Gigaparsec Developers: Do not import this, use Control.Applicative.some, as this has the more general type.

Since: 0.1.0.0

This combinator will parse the given parser one or more times combining the results with the function f and base value k from the left.

The given parser p will continue to be parsed until it fails having not consumed input. All of the results generated by the successful parses are then combined in a left-to-right fashion using the function f: the left-most value provided to f is the value k. If p fails at any point having consumed input, this combinator fails.

Examples

natural = somel (\x d -> x * 10 + digitToInt d) 0 digit

Since: 0.3.0.0

This combinator will parse the given parser p one or more times, combining the results with the function f and base value k from the right.

p will continue to be parsed until it fails having not consumed input. All of the results generated by the successful parses are then combined in a right-to-left fashion using the function f: the right-most value provided to f is the value k. If this parser does fail at any point having consumed input, this combinator will fail.

Examples

some = somer (:) []

Since: 0.3.0.0

This combinator acts like the foldMap function but with a parser.

The parser manyMap f p, will parse p one or more times, then adapt each result with the function f to produce a bunch of values in some Semigroup s. These values are then combined together to form a single value.

Examples

>>> parse (someMap Max item) "bdcjb"
Success (Max 'j')
>>> parse (someMap Min item) "bdcjb"
Success (Max 'b')

Since: 0.2.2.0