parsec-free-3.1.11.4: Parsec API encoded as a deeply-embedded DSL, for debugging and analysis

Copyright(c) Daan Leijen 1999-2001 (c) Paolo Martini 2007
LicenseBSD-style (see the LICENSE file)
Maintaineraslatter@gmail.com
Stabilityprovisional
Portabilityportable
Safe HaskellNone
LanguageHaskell2010

Text.Parsec

Contents

Description

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.

Synopsis

Parsers

type Parsec s u = ParsecT s u Identity Source #

token Source #

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] Source #

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

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

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

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 Source #

Returns the current user state.

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

putState st set the user state to st.

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

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 Source #

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

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

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

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

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

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

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

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] Source #

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

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 () Source #

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

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] Source #

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 Source #

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 Source #

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) Source #

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 () Source #

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] Source #

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] Source #

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] Source #

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] Source #

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] Source #

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] Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 () Source #

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 () Source #

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] Source #

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 Source #

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

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

Character Parsing

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.

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 
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 
Show SourcePos 

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] Source #

tokenPrim Source #

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 Source #

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

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

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

Returns the full parser state as a State record.

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

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) Source #

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 Source #

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 Source #

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

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 () Source #

An alias for putState for backwards compatibility.

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

An alias for modifyState for backwards compatibility.

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

parserReturn :: a -> ParsecT s u m a Source #

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

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