Parser for ByteString inputs.

Result represents either success or some kind of failure.

You can find the problematic offset by subtracting length of the remainder from length of the original input.

Discards the remaining input and returns just the parse result. You might want to combine it with endOfInput for the best effect.

Example:

parseOnly (pContacts <* endOfInput) bstr

Accepts a single, matching byte.

Accepts a single, differing byte.

Accepts a single byte.

Accepts a single byte matching the predicate.

Peeks ahead, but does not consume.

Be careful, peeking behind end of the input fails. You might want to check using atEnd beforehand.

Accepts a matching string.

Accepts given number of bytes. Fails when not enough bytes are available.

Scans ahead statefully and then accepts whatever bytes the scanner liked. Scanner returns Nothing to mark end of the acceptable extent.

Like scan, but also returns the final scanner state.

Efficiently consume as long as the input bytes match the predicate. An inverse of takeTill.

Like takeWhile, but requires at least a single byte.

Efficiently consume until a byte matching the predicate is found. An inverse of takeWhile.

Same as takeTill, but requires at least a single byte.

Fails if the value returned by the parser does not conform to the predicate. Generalized form of string.

Example:

pInput = takeWhile isLetter `provided` (odd . length)

Tries various parsers, one by one.

Example:

pExpression = choice [ pConstant
                     , pVariable
                     , pBinaryOperation
                     , pFunctionApplication
                     ]

Given list of matchers and parsers, runs the first parser whose matcher succeeds on the input. This pattern makes for a simpler alternative to try used in other parser combinator libraries.

Example:

pProperty = branch [ ( string "public" <* skipSpace
                     , _ -> Property Public $ pToken
                     )
                   , ( string "private" <* skipSpace
                     , _ -> Property Private $ pToken
                     )
                   ]

Replicates the parser given number of times, collecting the results in a list. Fails if any instance of the parser fails.

Example:

pFourWords = (:) <$> word <*> count 3 (blank *> word)
  where word  = takeWhile1 isLetter
        blank = takeWhile1 isSpace

One or none.

Captures first parser as Left or the second as Right.

Shortcut for optional with a default value.

Example:

data Contact =
 Contact
   { contactName  :: Text
   , contactEmail :: Maybe Text
   }

pContact = Contact <$> pFullName <*> option pEmail

Zero or more.

Like many1, but requires at least one match.

Like many, but stops once the second parser matches the input ahead.

Example:

pBodyLines = pLine `manyTill` pEnd
  where pLine = takeTill (== 'n')
        pEnd  = string "n.n"

Similar to many, but interleaves the first parser with the second.

Example:

pLines = pLine sepBy char 'n'

Like sepBy, but requires at least one match.

Wraps the parser from both sides.

Example:

pToken = takeWhile1 (inClass "A-Za-z0-9_") `wrap` takeWhile isSpace

Makes the parser not only return the result, but also the original matched extent.

Names an extent of the parser.

When the extent returns a Failure, details are discarded and replaced with the extent as a whole.

When the extent returns an Error, it is adjusted to cover the whole extent, but the reason is left intact.

You should strive to make labeled extents as small as possible, approximately of a typical token size. For example:

pString = label "string" $ pStringContents `wrap` char '"'

Un-names an extent of the parser.

Same as label, but removes any expected values upon Failure. Very useful to mark comments and optional whitespace with.

Validate parser result and turn it into an Error upon failure.

Accept whatever input remains.

Peek at whatever input remains.

Accepts end of input and fails if we are not there yet.

Returns whether we are at the end of the input yet.

Calculate offset from the original input and the remainder.

The identity of <|>

Lift a value.

Conditional failure of Alternative computations. Defined by

guard True  = pure ()
guard False = empty

Examples

>>> safeDiv 4 0
Nothing
>>> safeDiv 4 2
Just 2

safeDiv :: Int -> Int -> Maybe Int
safeDiv x y | y /= 0    = Just (x `div` y)
            | otherwise = Nothing

safeDiv :: Int -> Int -> Maybe Int
safeDiv x y = do
  guard (y /= 0)
  return (x `div` y)

Conditional execution of Applicative expressions. For example,

when debug (putStrLn "Debugging")

will output the string Debugging if the Boolean value debug is True, and otherwise do nothing.

The reverse of when.

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

Using ApplicativeDo: 'void as' can be understood as the do expression

do as
   pure ()

with an inferred Functor constraint.

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