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 ASCII character.

Accepts a single, differing ASCII character.

Accepts a single character.

Accepts a single character matching the predicate.

Accepts a single ASCII white space character. See isSpace for details.

True for any of the [' ', '\t', '\n', '\v', '\f', '\r'] characters.

Please note that Data.Text.Parser re-exports isString, that considers more unicode codepoints, making it significantly slower.

Accepts multiple ASCII white space characters. See isSpace for details.

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 a matching string. Matching is performed in a case-insensitive manner under ASCII.

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.

Tests whether the character lies within given range.

Definition:

inRange lo hi = c -> (lo <= c && c <= hi)

Negation of inRange.

Definition:

notInRange lo hi = c -> (c <= lo || hi <= c)

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

Like takeWhile, but requires at least a single character.

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

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

Accepts optional '+' or '-' character and then applies it to the following parser result.

Accepts an integral number in the decimal format.

Accepts an integral number in the hexadecimal format in either case. Does not look for 0x or similar prefixes.

Accepts an integral number in the octal format.

Accepts a fractional number as a decimal optinally followed by a colon and the fractional part. Does not support exponentiation.

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.

Determine (line, column) from the original input and the remainder.

Counts line feed characters leading to the offset, so only use it on your slow path. For example when describing parsing errors.

Process the result for showing it to the user.

More precise Result description produced by explain.

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