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

Lift a value into the Structure.

Examples

>>> pure 1 :: Maybe Int
Just 1

>>> pure 'z' :: [Char]
"z"

>>> pure (pure ":D") :: Maybe [String]
Just [":D"]

The identity of <|>

empty <|> a     == a
a     <|> empty == a

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

An infix synonym for fmap.

The name of this operator is an allusion to $. Note the similarities between their types:

 ($)  ::              (a -> b) ->   a ->   b
(<$>) :: Functor f => (a -> b) -> f a -> f b

Whereas $ is function application, <$> is function application lifted over a Functor.

Examples

>>> show <$> Nothing
Nothing

>>> show <$> Just 3
Just "3"

>>> show <$> Left 17
Left 17

>>> show <$> Right 17
Right "17"

>>> (*2) <$> [1,2,3]
[2,4,6]

>>> even <$> (2,2)
(2,True)

Replace all locations in the input with the same value. The default definition is fmap . const, but this may be overridden with a more efficient version.

Examples

>>> 'a' <$ Just 2
Just 'a'
>>> 'a' <$ Nothing
Nothing

void value discards or ignores the result of evaluation, such as the return value of an IO action.

Examples

>>> void Nothing
Nothing

>>> void (Just 3)
Just ()

>>> void (Left 8675309)
Left 8675309

>>> void (Right 8675309)
Right ()

>>> void [1,2,3]
[(),(),()]

>>> void (1,2)
(1,())

>>> mapM print [1,2]
1
2
[(),()]

>>> void $ mapM print [1,2]
1
2

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

Sequential application.

A few functors support an implementation of <*> that is more efficient than the default one.

Example

>>> data MyState = MyState {arg1 :: Foo, arg2 :: Bar, arg3 :: Baz}

>>> produceFoo :: Applicative f => f Foo
>>> produceBar :: Applicative f => f Bar
>>> produceBaz :: Applicative f => f Baz

>>> mkState :: Applicative f => f MyState
>>> mkState = MyState <$> produceFoo <*> produceBar <*> produceBaz

Lift a binary function to actions.

Some functors support an implementation of liftA2 that is more efficient than the default one. In particular, if fmap is an expensive operation, it is likely better to use liftA2 than to fmap over the structure and then use <*>.

This became a typeclass method in 4.10.0.0. Prior to that, it was a function defined in terms of <*> and fmap.

Example

>>> liftA2 (,) (Just 3) (Just 5)
Just (3,5)

>>> liftA2 (+) [1, 2, 3] [4, 5, 6]
[5,6,7,6,7,8,7,8,9]

Sequence actions, discarding the value of the first argument.

Examples

>>> Just 2 *> Just 3
Just 3

>>> Nothing *> Just 3
Nothing

>>> import Data.Char
>>> import GHC.Internal.Text.ParserCombinators.ReadP
>>> let p = string "my name is " *> munch1 isAlpha <* eof
>>> readP_to_S p "my name is Simon"
[("Simon","")]

Sequence actions, discarding the value of the second argument.

A variant of <*> with the types of the arguments reversed. It differs from flip (<*>) in that the effects are resolved in the order the arguments are presented.

Examples

>>> (<**>) (print 1) (id <$ print 2)
1
2

>>> flip (<*>) (print 1) (id <$ print 2)
2
1

>>> ZipList [4, 5, 6] <**> ZipList [(+1), (*2), (/3)]
ZipList {getZipList = [5.0,10.0,2.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

An associative binary operation

The branch function is a natural generalisation of select: instead of skipping an unnecessary effect, it chooses which of the two given effectful functions to apply to a given argument; the other effect is unnecessary. It is possible to implement branch in terms of select, which is a good puzzle (give it a try!).

We can also implement select via branch:

selectB :: Selective f => f (Either a b) -> f (a -> b) -> f b
selectB x y = branch x y (pure id)

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

Zero or more.

Examples

>>> many (putStr "la")
lalalalalalalalala... * goes on forever *

>>> many Nothing
Just []

>>> take 5 <$> many (Just 1)
* hangs forever *

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

One or more.

Examples

>>> some (putStr "la")
lalalalalalalalala... * goes on forever *

>>> some Nothing
nothing

>>> take 5 <$> some (Just 1)
* hangs forever *

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