Data.Text.Parser

This module provides a parser for Unicode Text.

Documentation

newtype Parser a

Constructors

Parser

Fields

• runParser :: Text -> Maybe (a, Text)

Instances

MonadFail Parser

Defined in Data.Text.Parser

Methods

fail :: String -> Parser a

Alternative Parser

Defined in Data.Text.Parser

Methods

empty :: Parser a

(<|>) :: Parser a -> Parser a -> Parser a

some :: Parser a -> Parser [a]

many :: Parser a -> Parser [a]

Applicative Parser

Defined in Data.Text.Parser

Methods

pure :: a -> Parser a

(<*>) :: Parser (a -> b) -> Parser a -> Parser b

liftA2 :: (a -> b -> c) -> Parser a -> Parser b -> Parser c

(*>) :: Parser a -> Parser b -> Parser b

(<*) :: Parser a -> Parser b -> Parser a

Functor Parser

Defined in Data.Text.Parser

Methods

fmap :: (a -> b) -> Parser a -> Parser b

(<$) :: a -> Parser b -> Parser a

Monad Parser

Defined in Data.Text.Parser

Methods

(>>=) :: Parser a -> (a -> Parser b) -> Parser b

(>>) :: Parser a -> Parser b -> Parser b

return :: a -> Parser a

MonadPlus Parser

Defined in Data.Text.Parser

Methods

mzero :: Parser a

mplus :: Parser a -> Parser a -> Parser a

parseOnly :: Parser a -> Text -> Maybe a

Characters

char :: Char -> Parser Char

notChar :: Char -> Parser Char

anyChar :: Parser Char

satisfy :: (Char -> Bool) -> Parser Char

space :: Parser Char

isSpace :: Char -> Bool

Returns True for any Unicode space character, and the control characters \t, \n, \r, \f, \v.

skipSpace :: Parser ()

peekChar :: Parser Char

Strings

string :: Text -> Parser Text

stringCI :: Text -> Parser Text

take :: Int -> Parser Text

scan :: s -> (s -> Char -> Maybe s) -> Parser Text

runScanner :: s -> (s -> Char -> Maybe s) -> Parser (Text, s)

Like scan, but also returns the final scanner state.

inRange :: Char -> Char -> Char -> Bool

Tests whether the character lies within given range.

Definition:

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

notInRange :: Char -> Char -> Char -> Bool

Negation of inRange.

Definition:

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

takeWhile :: (Char -> Bool) -> Parser Text

takeWhile1 :: (Char -> Bool) -> Parser Text

takeTill :: (Char -> Bool) -> Parser Text

takeTill1 :: (Char -> Bool) -> Parser Text

Numbers

signed :: Num a => Parser a -> Parser a

decimal :: Integral a => Parser a

hexadecimal :: Integral a => Parser a

octal :: Integral a => Parser a

fractional :: Fractional a => Parser a

Combinators

provided :: (Alternative m, Monad m) => (a -> Bool) -> m a -> m a

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)

choice :: Alternative f => [f a] -> f a

Tries various parsers, one by one. Alias for asum.

Example:

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

count :: Monad m => Int -> m a -> m [a]

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

optional :: Alternative f => f a -> f (Maybe a)

One or none.

It is useful for modelling any computation that is allowed to fail.

Examples

Using the Alternative instance of Control.Monad.Except, the following functions:

>>> import Control.Monad.Except

>>> canFail = throwError "it failed" :: Except String Int
>>> final = return 42                :: Except String Int

Can be combined by allowing the first function to fail:

>>> runExcept $ canFail *> final
Left "it failed"
>>> runExcept $ optional canFail *> final
Right 42

eitherP :: Alternative f => f a -> f b -> f (Either a b)

Captures first parser as Left or the second as Right.

option :: Alternative f => a -> f a -> f a

Shortcut for optional with a default value.

Example:

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

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

many :: Alternative f => f a -> f [a]

Zero or more.

many1 :: Alternative f => f a -> f [a]

Like many1, but requires at least one match.

manyTill :: Alternative f => f a -> f a -> f [a]

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"

sepBy :: Alternative f => f a -> f b -> f [a]

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

Example:

pLines = pLine sepBy char 'n'

sepBy1 :: Alternative f => f a -> f b -> f [a]

Like sepBy, but requires at least one match.

wrap :: Applicative f => f a -> f b -> f a

Wraps the parser from both sides.

Example:

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

match :: Parser a -> Parser (Text, a)

End Of Input

takeText :: Parser Text

endOfInput :: Parser ()

atEnd :: Parser Bool

Miscelaneous

These are all generic methods, but since I sometimes forget about them, it is nice to have them listed here for reference what writing parsers.

empty :: Alternative f => f a

The identity of <|>

pure :: Applicative f => a -> f a

Lift a value.

guard :: Alternative f => Bool -> f ()

Conditional failure of Alternative computations. Defined by

guard True  = pure ()
guard False = empty

Examples

Common uses of guard include conditionally signaling an error in an error monad and conditionally rejecting the current choice in an Alternative-based parser.

As an example of signaling an error in the error monad Maybe, consider a safe division function safeDiv x y that returns Nothing when the denominator y is zero and Just (x `div` y) otherwise. For example:

>>> safeDiv 4 0
Nothing

>>> safeDiv 4 2
Just 2

A definition of safeDiv using guards, but not guard:

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

A definition of safeDiv using guard and Monad do-notation:

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

when :: Applicative f => Bool -> f () -> f ()

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.

unless :: Applicative f => Bool -> f () -> f ()

The reverse of when.

void :: Functor f => f a -> f ()

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

Examples

Replace the contents of a Maybe Int with unit:

>>> void Nothing
Nothing
>>> void (Just 3)
Just ()

Replace the contents of an Either Int Int with unit, resulting in an Either Int ():

>>> void (Left 8675309)
Left 8675309
>>> void (Right 8675309)
Right ()

Replace every element of a list with unit:

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

Replace the second element of a pair with unit:

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

Discard the result of an IO action:

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