An infix synonym for fmap.

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)

Flipped <$>.

Great for parsing infixes, e.g. addExpr = expr <$$> (+) <*> expr.

Sequential application.

Sequence actions, discarding the value of the first argument.

Sequence actions, discarding the value of the second argument.

A variant of <*> with the arguments reversed.

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.

Lift a value.

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

p <||> q tries to parse p, but if it fails, parses q.

Unlike the Alternative instance for ParsecT, backtracking will occur if p fails. That is, a parser such as string "flange" <||> string "fly" will succeed on the input "fly", whereas its Parsec counterpart will unintuitively fail.

choice ps tries to apply the parsers in the list ps in order, until one of them succeeds. Returns the value of the succeeding parser. Unlike the Parsec version, this one ensures that parsers do not consume input if they fail.

Given a map of parsers to parsers, attempt each key parser until one succeeds, then perform the value parser. Return the result of the value parser.

Attempt all of the passed parsers under the current conditions and return the value of the parser which makes it furthest into the input stream (and updates the parser's internals as if that were the only parser parsed).

longestOf [string "do", string "don't"]

option x p tries to apply parser p. If p fails, no input is consumed and x is returned.

optional p tries to parse p, but does not fail or consume input of p fails.

This is like optionMaybe, but is easier to type. See optional_.

optional_ p tries to parse p, but does not fail or consume input if p fails.

This is like Parsec's Text.Parsec.Combinator.optional', but the use of underscore is more idiomatic for actions whose results are ignored.

many p applies the parser p zero or more times and accumulates the result.

many p applies the parser p one or more times and accumulates the result.

many1_ p applies the parser p zero or more times, skipping its result.

many1_ p applies the parser p one or more times, skipping its result.

count n p parses n occurrences of p. If n is smaller or equal to zero, the parser equals to return []. Returns a list of n values returned by p.

atLeast n p applies the parser p n or more times.

atMost n p applies the parser p up to n times.

manyNM n m p applies the parser p n or more times up to m times.

Parse zero or more of any mix of the passed parsers.

As manyOf, but ignoring the results.

manyTill p end applies parser p zero or more times until parser end succeeds. Returns the list of values returned by p. The end parser does not consume input, c.f. manyThru. This parser can be used to scan comments:

 simpleComment = do { string "//"
                    ; anyChar `manyTill` char '\n'
                    }

Note that despite the overlapping parsers anyChar and char '\n', there is never a need to add a try: the end parser does not consume input on failure.

manyThru p end applies parser p zero or more times until parser end succeeds. Returns the list of values returned by p. The end parser does consume input, c.f. manyTill, but is not included in the result. This parser can be used to scan comments:

 simpleComment = do { string "<!--"
                    ; anyChar `manyThru` string "-->"
                    }

Note that despite the overlapping parsers anyChar and string "-->", there is no need to add a try: the end parser does not consume input on failure.

chomp p x will parse p, then, provided x succeeds, discard a subsequent parse of x. This combinator will only fail when p fails, not when x does.

between open close p parses open, followed by p and close. Returns the value returned by p.

 braces  = between (symbol "{") (symbol "}")

between2 p q is equivalent to between p p q

double_quoted = between2 (char '"')

sepBy p sep parses zero or more occurrences of p, separated by sep. Returns a list of values returned by p.

 commaSep p  = p `sepBy` (symbol ",")

sepBy1 p sep parses one or more occurrences of p, separated by sep. Returns a list of values returned by p.

sepEndBy p sep parses zero or more occurrences of p, separated and optionally ended by sep.

 haskellStatements  = haskellStatement `sepEndBy` semi

sepEndBy1 p sep parses one or more occurrences of p, separated and optionally ended by sep.

endBy p sep parses zero or more occurrences of p, seperated and ended by sep.

  cStatements  = cStatement `endBy` semi

endBy1 p sep parses one or more occurrences of p, seperated and ended by sep.

sepAroundBy p sep parses zero or more occurrences of p, separated and optionally starting with and ended by sep.

sepAroundBy1 p sep parses one or more occurrences of p, separated and optionally starting with and ended by sep.

chainl p op z parses zero or more occurrences of p, separated by op. Returns a value obtained by a left associative application of all functions returned by op to the values returned by p. If there are zero occurrences of p, the value z is returned. C.f. chainr.

chainl1 p op parses one or more occurrences of p, separated by op Returns a value obtained by a left associative application of all functions returned by op to the values returned by p. This parser can for example be used to eliminate left recursion which typically occurs in expression grammars.

 expr    = term   `chainl1` mulop
 term    = factor `chainl1` addop
 factor  = parens expr <|> integer

 mulop   =   do{ symbol "*"; return (*)   }
         <|> do{ symbol "/"; return (div) }

 addop   =   do{ symbol "+"; return (+) }
         <|> do{ symbol "-"; return (-) }

C.f. chainr1.

chainr p op z parses zero or more occurrences of p, separated by op Returns a value obtained by a right associative application of all functions returned by op to the values returned by p. If there are no occurrences of p, the value z is returned. C.f. chainl.

chainr1 p op parses one or more occurrences of p, separated by op Returns a value obtained by a right associative application of all functions returned by op to the values returned by p. C.f. chainl1.

lookAhead p parses p without consuming any input, even if p fails.

As lookAhead, but throw away result.

notFollowedBy p q parses p, but only when q will fail immediately after parsing p. Parsing q never consumes input, and if this combinator fails, no input is consumed.

This combinator can be used to implement the 'longest match' rule. For example, when recognizing keywords (for example let), we want to make sure that a keyword is not followed by a legal identifier character, in which case the keyword is actually an identifier (for example lets). We can program this behavior as follows:

 keywordLet = string "let" `notFollowedBy` alphaNum

Returns True if there is no input left, False if there is.

Succeed only when at the end of the input stream.

Uses the passed parser, but succeeds only if it consumes all of the input.

Parse using the passed parser, but also return the input that was not consumed.

The parser p <?> msg behaves as parser p, but whenever the parser p fails without consuming any input, it replaces expect error messages with the expect error message msg.

This is normally used at the end of a set alternatives where we want to return an error message in terms of a higher level construct rather than returning all possible characters. For example, if the expr parser from the try example would fail, the error message is: '...: expecting expression'. Without the (<?>) combinator, the message would be like '...: expecting "let" or letter', which is less friendly.

Flipped <?>.

Annotate the return value of the passed parser with the position just before parsing.

Annotate the return value of the passed parser with the position just after parsing.

Annotate the return value of the passed parser with the position just before and after parsing respectively.

The parser try p behaves like parser p, except that it pretends that it hasn't consumed any input when an error occurs.

This combinator is used whenever arbitrary look ahead is needed. Since it pretends that it hasn't consumed any input when p fails, the (<|>) combinator will try its second alternative even when the first parser failed while consuming input.

The try combinator can for example be used to distinguish identifiers and reserved words. Both reserved words and identifiers are a sequence of letters. Whenever we expect a certain reserved word where we can also expect an identifier we have to use the try combinator. Suppose we write:

 expr        = letExpr <|> identifier <?> "expression"

 letExpr     = do{ string "let"; ... }
 identifier  = many1 letter

If the user writes "lexical", the parser fails with: unexpected 'x', expecting 't' in "let". Indeed, since the (<|>) combinator only tries alternatives when the first alternative hasn't consumed input, the identifier parser is never tried (because the prefix "le" of the string "let" parser is already consumed). The right behaviour can be obtained by adding the try combinator:

 expr        = letExpr <|> identifier <?> "expression"

 letExpr     = do{ try (string "let"); ... }
 identifier  = many1 letter

This combinator implements choice. The parser p <|> q first applies p. If it succeeds, the value of p is returned. If p fails without consuming any input, parser q is tried. This combinator is defined equal to the mplus member of the MonadPlus class and the (<|>) member of Alternative.

The parser is called predictive since q is only tried when parser p didn't consume any input (i.e.. the look ahead is 1). This non-backtracking behaviour allows for both an efficient implementation of the parser combinators and the generation of good error messages.

The parser unexpected msg always fails with an unexpected error message msg without consuming any input.

The parsers fail, (<?>) and unexpected are the three parsers used to generate error messages. Of these, only (<?>) is commonly used. For an example of the use of unexpected, see the definition of notFollowedBy.