Copyright | (c) Daan Leijen 1999-2001 |
---|---|
License | BSD-style (see the file LICENSE) |
Maintainer | Christian Maeder <chr.maeder@web.de> |
Stability | provisional |
Portability | portable |
Safe Haskell | Safe-Inferred |
Language | Haskell98 |
The primitive parser combinators.
Synopsis
- (*>) :: Applicative f => f a -> f b -> f b
- (<$) :: Functor f => a -> f b -> f a
- (<$>) :: Functor f => (a -> b) -> f a -> f b
- (<*) :: Applicative f => f a -> f b -> f a
- (<*>) :: Applicative f => f (a -> b) -> f a -> f b
- (<?>) :: GenParser tok st a -> String -> GenParser tok st a
- (<|>) :: Alternative f => f a -> f a -> f a
- data GenParser tok st a
- type Parser a = GenParser Char () a
- parse :: GenParser tok () a -> SourceName -> [tok] -> Either ParseError a
- parseFromFile :: Parser a -> SourceName -> IO (Either ParseError a)
- parseTest :: Show a => GenParser tok () a -> [tok] -> IO ()
- runParser :: GenParser tok st a -> st -> SourceName -> [tok] -> Either ParseError a
- label :: GenParser tok st a -> String -> GenParser tok st a
- labels :: GenParser tok st a -> [String] -> GenParser tok st a
- lookAhead :: GenParser tok st a -> GenParser tok st a
- pzero :: GenParser tok st a
- token :: (tok -> String) -> (tok -> SourcePos) -> (tok -> Maybe a) -> GenParser tok st a
- tokenPrim :: (tok -> String) -> (SourcePos -> tok -> [tok] -> SourcePos) -> (tok -> Maybe a) -> GenParser tok st a
- tokenPrimEx :: (tok -> String) -> (SourcePos -> tok -> [tok] -> SourcePos) -> Maybe (SourcePos -> tok -> [tok] -> st -> st) -> (tok -> Maybe a) -> GenParser tok st a
- tokens :: Eq tok => ([tok] -> String) -> (SourcePos -> [tok] -> SourcePos) -> [tok] -> GenParser tok st [tok]
- try :: GenParser tok st a -> GenParser tok st a
- unexpected :: String -> GenParser tok st a
- many :: Alternative f => f a -> f [a]
- skipMany :: GenParser tok st a -> GenParser tok st ()
- getState :: GenParser tok st st
- setState :: st -> GenParser tok st ()
- updateState :: (st -> st) -> GenParser tok st ()
- data State tok st = State {
- stateInput :: [tok]
- statePos :: !SourcePos
- stateUser :: !st
- getInput :: GenParser tok st [tok]
- getParserState :: GenParser tok st (State tok st)
- getPosition :: GenParser tok st SourcePos
- setInput :: [tok] -> GenParser tok st ()
- setParserState :: State tok st -> GenParser tok st (State tok st)
- setPosition :: SourcePos -> GenParser tok st ()
Documentation
(*>) :: Applicative f => f a -> f b -> f b infixl 4 #
Sequence actions, discarding the value of the first argument.
'as
' can be understood as the *>
bsdo
expression
do as bs
This is a tad complicated for our ApplicativeDo
extension
which will give it a Monad
constraint. For an Applicative
constraint we write it of the form
do _ <- as b <- bs pure b
(<$>) :: Functor f => (a -> b) -> f a -> f b infixl 4 #
An infix synonym for fmap
.
The name of this operator is an allusion to $
.
Note the similarities between their types:
($) :: (a -> b) -> a -> b (<$>) :: Functor f => (a -> b) -> f a -> f b
Whereas $
is function application, <$>
is function
application lifted over a Functor
.
Examples
Convert from a
to a Maybe
Int
using Maybe
String
show
:
>>>
show <$> Nothing
Nothing>>>
show <$> Just 3
Just "3"
Convert from an
to an
Either
Int
Int
Either
Int
String
using show
:
>>>
show <$> Left 17
Left 17>>>
show <$> Right 17
Right "17"
Double each element of a list:
>>>
(*2) <$> [1,2,3]
[2,4,6]
Apply even
to the second element of a pair:
>>>
even <$> (2,2)
(2,True)
(<*) :: Applicative f => f a -> f b -> f a infixl 4 #
Sequence actions, discarding the value of the second argument.
Using ApplicativeDo
: 'as
' can be understood as
the <*
bsdo
expression
do a <- as bs pure a
(<*>) :: Applicative f => f (a -> b) -> f a -> f b infixl 4 #
(<?>) :: GenParser tok st a -> String -> GenParser tok st a infix 0 Source #
The parser p ? msg
behaves as parser p
, but whenever the
parser p
fails without consuming any input, it replaces expect
error messages with the expect error message msg
.
This is normally used at the end of a set alternatives where we want
to return an error message in terms of a higher level construct
rather than returning all possible characters. For example, if the
expr
parser from the try
example would fail, the error
message is: '...: expecting expression'. Without the (<?>)
combinator, the message would be like '...: expecting "let" or
letter', which is less friendly.
(<|>) :: Alternative f => f a -> f a -> f a infixl 3 #
An associative binary operation
data GenParser tok st a Source #
Instances
Monad (GenParser tok st) Source # | |
Functor (GenParser tok st) Source # | |
MonadFail (GenParser tok st) Source # | |
Defined in Text.ParserCombinators.Parsec.Prim | |
Applicative (GenParser tok st) Source # | |
Defined in Text.ParserCombinators.Parsec.Prim pure :: a -> GenParser tok st a # (<*>) :: GenParser tok st (a -> b) -> GenParser tok st a -> GenParser tok st b # liftA2 :: (a -> b -> c) -> GenParser tok st a -> GenParser tok st b -> GenParser tok st c # (*>) :: GenParser tok st a -> GenParser tok st b -> GenParser tok st b # (<*) :: GenParser tok st a -> GenParser tok st b -> GenParser tok st a # | |
Alternative (GenParser tok st) Source # | |
MonadPlus (GenParser tok st) Source # | |
parse :: GenParser tok () a -> SourceName -> [tok] -> Either ParseError a Source #
parse p filePath input
runs a parser p
without user
state. The filePath
is only used in error messages and may be the
empty string. Returns either a ParseError
(Left
)
or a value of type a
(Right
).
main = case parse numbers "" "11, 2, 43" of Left err -> print err Right xs -> print (sum xs) numbers = commaSep integer
parseFromFile :: Parser a -> SourceName -> IO (Either ParseError a) Source #
parseTest :: Show a => GenParser tok () a -> [tok] -> IO () Source #
The expression parseTest p input
applies a parser p
against
input input
and prints the result to stdout. Used for testing
parsers.
runParser :: GenParser tok st a -> st -> SourceName -> [tok] -> Either ParseError a Source #
The most general way to run a parser. runParser p state filePath
input
runs parser p
on the input list of tokens input
,
obtained from source filePath
with the initial user state st
.
The filePath
is only used in error messages and may be the empty
string. Returns either a ParseError
(Left
) or a
value of type a
(Right
).
parseFromFile p fname = do input <- readFile fname return (runParser p () fname input)
lookAhead :: GenParser tok st a -> GenParser tok st a Source #
lookAhead p
parses p
without consuming any input.
token :: (tok -> String) -> (tok -> SourcePos) -> (tok -> Maybe a) -> GenParser tok st a Source #
The parser token showTok posFromTok testTok
accepts a token t
with result x
when the function testTok t
returns
. The
source position of the Just
xt
should be returned by posFromTok t
and
the token can be shown using showTok t
.
This combinator is expressed in terms of tokenPrim
.
It is used to accept user defined token streams. For example,
suppose that we have a stream of basic tokens tupled with source
positions. We can than define a parser that accepts single tokens as:
mytoken x = token showTok posFromTok testTok where showTok (pos,t) = show t posFromTok (pos,t) = pos testTok (pos,t) = if x == t then Just t else Nothing
tokenPrim :: (tok -> String) -> (SourcePos -> tok -> [tok] -> SourcePos) -> (tok -> Maybe a) -> GenParser tok st a Source #
The parser token showTok nextPos testTok
accepts a token t
with result x
when the function testTok t
returns
. The
token can be shown using Just
xshowTok t
. The position of the next
token should be returned when nextPos
is called with the current
source position pos
, the current token t
and the rest of the
tokens toks
, nextPos pos t toks
.
This is the most primitive combinator for accepting tokens. For
example, the char
parser could be implemented as:
char c = tokenPrim showChar nextPos testChar where showChar x = "'" ++ x ++ "'" testChar x = if x == c then Just x else Nothing nextPos pos x xs = updatePosChar pos x
tokenPrimEx :: (tok -> String) -> (SourcePos -> tok -> [tok] -> SourcePos) -> Maybe (SourcePos -> tok -> [tok] -> st -> st) -> (tok -> Maybe a) -> GenParser tok st a Source #
The most primitive token recogniser. The expression
tokenPrimEx show nextpos mbnextstate test
, recognises tokens when test
returns Just x
(and returns the value x
). Tokens are shown in error
messages using show
. The position is calculated using nextpos
, and finally,
mbnextstate
, can hold a function that updates the user state on every token
recognised (nice to count tokens :-).
The function is packed into a Maybe
type for performance reasons.
tokens :: Eq tok => ([tok] -> String) -> (SourcePos -> [tok] -> SourcePos) -> [tok] -> GenParser tok st [tok] Source #
try :: GenParser tok st a -> GenParser tok st a Source #
The parser try p
behaves like parser p
, except that it
pretends that it hasn't consumed any input when an error occurs.
This combinator is used whenever arbitrary look ahead is needed.
Since it pretends that it hasn't consumed any input when p
fails,
the (<|>
) combinator will try its second alternative even when the
first parser failed while consuming input.
The try
combinator can for example be used to distinguish
identifiers and reserved words. Both reserved words and identifiers
are a sequence of letters. Whenever we expect a certain reserved
word where we can also expect an identifier we have to use the try
combinator. Suppose we write:
expr = letExpr <|> identifier <?> "expression" letExpr = string "let" *> ... identifier = many1 letter
If the user writes "lexical", the parser fails with: unexpected
'x', expecting 't' in "let"
. Indeed, since the (<|>
) combinator
only tries alternatives when the first alternative hasn't consumed
input, the identifier
parser is never tried (because the prefix
"le" of the string "let"
parser is already consumed). The
right behaviour can be obtained by adding the try
combinator:
expr = letExpr <|> identifier <?> "expression" letExpr = try (string "let") *> identifier = many1 letter
unexpected :: String -> GenParser tok st a Source #
The parser unexpected msg
always fails with an unexpected error
message msg
without consuming any input.
The parsers fail
, (<?>
) and unexpected
are the three parsers
used to generate error messages. Of these, only (<?>
) is commonly
used. For an example of the use of unexpected
, see the definition
of notFollowedBy
.
many :: Alternative f => f a -> f [a] #
Zero or more.
skipMany :: GenParser tok st a -> GenParser tok st () Source #
skipMany p
applies the parser p
zero or more times, skipping
its result.
spaces = skipMany space
updateState :: (st -> st) -> GenParser tok st () Source #
updateState 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 updateState (+1) return (Id x)
getParserState :: GenParser tok st (State tok st) Source #
Returns the full parser state as a State
record.
getPosition :: GenParser tok st SourcePos Source #
Returns the current source position. See also SourcePos
.
setParserState :: State tok st -> GenParser tok st (State tok st) Source #
setParserState st
set the full parser state to st
.
setPosition :: SourcePos -> GenParser tok st () Source #
setPosition pos
sets the current source position to pos
.