Text.Parsec

This module includes everything you need to get started writing a parser.

By default this module is set up to parse character data. If you'd like to parse the result of your own tokenizer you should start with the following imports:

 import Text.Parsec.Prim
 import Text.Parsec.Combinator

Then you can implement your own version of satisfy on top of the tokenPrim primitive.

Parsers

type ParsecT = ParsecDSL

type Parsec s u = ParsecT s u Identity

token

Arguments

:: Stream s Identity t

=> (t -> String)

Token pretty-printing function.

-> (t -> SourcePos)

Computes the position of a token.

-> (t -> Maybe a)

Matching function for the token to parse.

-> Parsec s u a

tokens :: (Monad m, Stream s m t, Eq t) => ([t] -> String) -> (SourcePos -> [t] -> SourcePos) -> [t] -> ParsecT s u m [t]

runParserT :: Stream s m t => ParsecT s u m a -> u -> SourceName -> s -> m (Either ParseError a)

runParser :: Stream s Identity t => Parsec s u a -> u -> SourceName -> s -> Either ParseError a

parse :: Stream s Identity t => Parsec s () a -> SourceName -> s -> Either ParseError a

parseTest :: (Stream s Identity t, Show a) => Parsec s () a -> s -> IO ()

getPosition :: Monad m => ParsecT s u m SourcePos

Returns the current source position. See also SourcePos.

getInput :: Monad m => ParsecT s u m s

Returns the current input

getState :: Monad m => ParsecT s u m u

Returns the current user state.

putState :: Monad m => u -> ParsecT s u m ()

putState st set the user state to st.

modifyState :: Monad m => (u -> u) -> ParsecT s u m ()

modifyState f applies function f to the user state. Suppose that we want to count identifiers in a source, we could use the user state as:

 expr  = do{ x <- identifier
           ; modifyState (+1)
           ; return (Id x)
           }

Combinators

(<|>) :: ParsecT s u m a -> ParsecT s u m a -> ParsecT s u m a infixr 1

(<?>) :: ParsecT s u m a -> String -> ParsecT s u m a infix 0

label :: ParsecT s u m a -> String -> ParsecT s u m a

A synonym for <?>, but as a function instead of an operator.

labels :: ParsecT s u m a -> [String] -> ParsecT s u m a

try :: ParsecT s u m a -> ParsecT s u m a

unexpected :: Stream s m t => String -> ParsecT s u m a

choice :: Stream s m t => [ParsecT s u m a] -> ParsecT s u m a

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.

many :: ParsecT s u m a -> ParsecT s u m [a]

many1 :: Stream s m t => ParsecT s u m a -> ParsecT s u m [a]

many1 p applies the parser p one or more times. Returns a list of the returned values of p.

 word  = many1 letter

skipMany :: ParsecT s u m a -> ParsecT s u m ()

skipMany1 :: Stream s m t => ParsecT s u m a -> ParsecT s u m ()

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

count :: Stream s m t => Int -> ParsecT s u m a -> ParsecT s u m [a]

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.

between :: Stream s m t => ParsecT s u m open -> ParsecT s u m close -> ParsecT s u m a -> ParsecT s u m a

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

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

option :: Stream s m t => a -> ParsecT s u m a -> ParsecT s u m a

option x p tries to apply parser p. If p fails without consuming input, it returns the value x, otherwise the value returned by p.

 priority  = option 0 (do{ d <- digit
                         ; return (digitToInt d) 
                         })

optionMaybe :: Stream s m t => ParsecT s u m a -> ParsecT s u m (Maybe a)

optionMaybe p tries to apply parser p. If p fails without consuming input, it return Nothing, otherwise it returns Just the value returned by p.

optional :: Stream s m t => ParsecT s u m a -> ParsecT s u m ()

optional p tries to apply parser p. It will parse p or nothing. It only fails if p fails after consuming input. It discards the result of p.

sepBy :: Stream s m t => ParsecT s u m a -> ParsecT s u m sep -> ParsecT s u m [a]

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 :: Stream s m t => ParsecT s u m a -> ParsecT s u m sep -> ParsecT s u m [a]

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

endBy :: Stream s m t => ParsecT s u m a -> ParsecT s u m sep -> ParsecT s u m [a]

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

  cStatements  = cStatement `endBy` semi

endBy1 :: Stream s m t => ParsecT s u m a -> ParsecT s u m sep -> ParsecT s u m [a]

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

sepEndBy :: Stream s m t => ParsecT s u m a -> ParsecT s u m sep -> ParsecT s u m [a]

sepEndBy p sep parses zero or more occurrences of p, separated and optionally ended by sep, ie. haskell style statements. Returns a list of values returned by p.

 haskellStatements  = haskellStatement `sepEndBy` semi

sepEndBy1 :: Stream s m t => ParsecT s u m a -> ParsecT s u m sep -> ParsecT s u m [a]

sepEndBy1 p sep parses one or more occurrences of p, separated and optionally ended by sep. Returns a list of values returned by p.

chainl :: Stream s m t => ParsecT s u m a -> ParsecT s u m (a -> a -> a) -> a -> ParsecT s u m a

chainl p op x 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 x is returned.

chainl1 :: Stream s m t => ParsecT s u m a -> ParsecT s u m (a -> a -> a) -> ParsecT s u m a

chainl1 p op x 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` addop
 term    = factor `chainl1` mulop
 factor  = parens expr <|> integer

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

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

chainr :: Stream s m t => ParsecT s u m a -> ParsecT s u m (a -> a -> a) -> a -> ParsecT s u m a

chainr p op x 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 x is returned.

chainr1 :: Stream s m t => ParsecT s u m a -> ParsecT s u m (a -> a -> a) -> ParsecT s u m a

chainr1 p op x 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.

eof :: (Stream s m t, Show t) => ParsecT s u m ()

This parser only succeeds at the end of the input. This is not a primitive parser but it is defined using notFollowedBy.

 eof  = notFollowedBy anyToken <?> "end of input"

notFollowedBy :: (Stream s m t, Show a) => ParsecT s u m a -> ParsecT s u m ()

notFollowedBy p only succeeds when parser p fails. This parser does not consume any input. This parser 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 behaviour as follows:

 keywordLet  = try (do{ string "let"
                      ; notFollowedBy alphaNum
                      })

manyTill :: Stream s m t => ParsecT s u m a -> ParsecT s u m end -> ParsecT s u m [a]

manyTill p end applies parser p zero or more times until parser end succeeds. Returns the list of values returned by p. This parser can be used to scan comments:

 simpleComment   = do{ string "<!--"
                     ; manyTill anyChar (try (string "-->"))
                     }

Note the overlapping parsers anyChar and string "-->", and therefore the use of the try combinator.

lookAhead :: Stream s m t => ParsecT s u m a -> ParsecT s u m a

anyToken :: (Stream s m t, Show t) => ParsecT s u m t

The parser anyToken accepts any kind of token. It is for example used to implement eof. Returns the accepted token.

Character Parsing

module Text.Parsec.Char

Error messages

data ParseError :: *

The abstract data type ParseError represents parse errors. It provides the source position (SourcePos) of the error and a list of error messages (Message). A ParseError can be returned by the function parse. ParseError is an instance of the Show and Eq classes.

Instances

Eq ParseError

Methods

(==) :: ParseError -> ParseError -> Bool

(/=) :: ParseError -> ParseError -> Bool

Show ParseError

Methods

showsPrec :: Int -> ParseError -> ShowS

show :: ParseError -> String

showList :: [ParseError] -> ShowS

errorPos :: ParseError -> SourcePos

Extracts the source position from the parse error

Position

data SourcePos :: *

The abstract data type SourcePos represents source positions. It contains the name of the source (i.e. file name), a line number and a column number. SourcePos is an instance of the Show, Eq and Ord class.

Instances

Eq SourcePos

Methods

(==) :: SourcePos -> SourcePos -> Bool

(/=) :: SourcePos -> SourcePos -> Bool

Data SourcePos

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> SourcePos -> c SourcePos

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c SourcePos

toConstr :: SourcePos -> Constr

dataTypeOf :: SourcePos -> DataType

dataCast1 :: Typeable (* -> *) t => (forall d. Data d => c (t d)) -> Maybe (c SourcePos)

dataCast2 :: Typeable (* -> * -> *) t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c SourcePos)

gmapT :: (forall b. Data b => b -> b) -> SourcePos -> SourcePos

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> SourcePos -> r

gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> SourcePos -> r

gmapQ :: (forall d. Data d => d -> u) -> SourcePos -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> SourcePos -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> SourcePos -> m SourcePos

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> SourcePos -> m SourcePos

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> SourcePos -> m SourcePos

Ord SourcePos

Methods

compare :: SourcePos -> SourcePos -> Ordering

(<) :: SourcePos -> SourcePos -> Bool

(<=) :: SourcePos -> SourcePos -> Bool

(>) :: SourcePos -> SourcePos -> Bool

(>=) :: SourcePos -> SourcePos -> Bool

max :: SourcePos -> SourcePos -> SourcePos

min :: SourcePos -> SourcePos -> SourcePos

Show SourcePos

Methods

showsPrec :: Int -> SourcePos -> ShowS

show :: SourcePos -> String

showList :: [SourcePos] -> ShowS

type SourceName = String

type Line = Int

type Column = Int

sourceName :: SourcePos -> SourceName

Extracts the name of the source from a source position.

sourceLine :: SourcePos -> Line

Extracts the line number from a source position.

sourceColumn :: SourcePos -> Column

Extracts the column number from a source position.

incSourceLine :: SourcePos -> Line -> SourcePos

Increments the line number of a source position.

incSourceColumn :: SourcePos -> Column -> SourcePos

Increments the column number of a source position.

setSourceLine :: SourcePos -> Line -> SourcePos

Set the line number of a source position.

setSourceColumn :: SourcePos -> Column -> SourcePos

Set the column number of a source position.

setSourceName :: SourcePos -> SourceName -> SourcePos

Set the name of the source.

Low-level operations

manyAccum :: (a -> [a] -> [a]) -> ParsecT s u m a -> ParsecT s u m [a]

tokenPrim

Arguments

:: Stream s m t

=> (t -> String)

Token pretty-printing function.

-> (SourcePos -> t -> s -> SourcePos)

Next position calculating function.

-> (t -> Maybe a)

Matching function for the token to parse.

-> ParsecT s u m a

tokenPrimEx :: Stream s m t => (t -> String) -> (SourcePos -> t -> s -> SourcePos) -> Maybe (SourcePos -> t -> s -> u -> u) -> (t -> Maybe a) -> ParsecT s u m a

runPT :: (Monad m, Stream s m t) => ParsecT s u m a -> u -> SourceName -> s -> m (Either ParseError a)

unknownError :: State s u -> ParseError

sysUnExpectError :: String -> SourcePos -> Reply s u a

mergeErrorReply :: ParseError -> Reply s u a -> Reply s u a

getParserState :: Monad m => ParsecT s u m (State s u)

Returns the full parser state as a State record.

setParserState :: Monad m => State s u -> ParsecT s u m (State s u)

setParserState st set the full parser state to st.

updateParserState :: Monad m => (State s u -> State s u) -> ParsecT s u m (State s u)

updateParserState f applies function f to the parser state.

class Monad m => Stream s m t | s -> t where

An instance of Stream has stream type s, underlying monad m and token type t determined by the stream

Some rough guidelines for a "correct" instance of Stream:

• unfoldM uncons gives the [t] corresponding to the stream
• A Stream instance is responsible for maintaining the "position within the stream" in the stream state s. This is trivial unless you are using the monad in a non-trivial way.

Minimal complete definition

uncons

Methods

uncons :: s -> m (Maybe (t, s))

Instances

Monad m => Stream ByteString m Char

Methods

uncons :: ByteString -> m (Maybe (Char, ByteString))

Monad m => Stream ByteString m Char

Methods

uncons :: ByteString -> m (Maybe (Char, ByteString))

Monad m => Stream Text m Char

Methods

uncons :: Text -> m (Maybe (Char, Text))

Monad m => Stream Text m Char

Methods

uncons :: Text -> m (Maybe (Char, Text))

Monad m => Stream [tok] m tok

Methods

uncons :: [tok] -> m (Maybe (tok, [tok]))

runParsecT :: ParsecT s u m a -> ParsecDSL s u m a

mkPT :: Monad m => (State s u -> m (Consumed (m (Reply s u a)))) -> ParsecT s u m a

Low-level creation of the ParsecT type. You really shouldn't have to do this.

runP :: Stream s Identity t => Parsec s u a -> u -> SourceName -> s -> Either ParseError a

data Consumed a :: * -> *

Constructors

Consumed a

Empty ~a

Instances

Functor Consumed

Methods

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

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

data Reply s u a :: * -> * -> * -> *

Constructors

Ok a ~(State s u) ParseError

Error ParseError

Instances

Functor (Reply s u)

Methods

fmap :: (a -> b) -> Reply s u a -> Reply s u b

(<$) :: a -> Reply s u b -> Reply s u a

data State s u :: * -> * -> *

Constructors

State

Fields

• stateInput :: s
• statePos :: ~SourcePos
• stateUser :: ~u

setPosition :: Monad m => SourcePos -> ParsecT s u m ()

setPosition pos sets the current source position to pos.

setInput :: Monad m => s -> ParsecT s u m ()

setInput input continues parsing with input. The getInput and setInput functions can for example be used to deal with #include files.

Other stuff

setState :: Monad m => u -> ParsecT s u m ()

An alias for putState for backwards compatibility.

updateState :: Monad m => (u -> u) -> ParsecT s u m ()

An alias for modifyState for backwards compatibility.

parsecMap :: (a -> b) -> ParsecT s u m a -> ParsecT s u m b

parserReturn :: a -> ParsecT s u m a

parserBind :: ParsecT s u m a -> (a -> ParsecT s u m b) -> ParsecT s u m b

parserFail :: String -> ParsecT s u m a

parserZero :: ParsecT s u m a

parserPlus :: ParsecT s u m a -> ParsecT s u m a -> ParsecT s u m a