| Copyright | (c) comp 2020 |
|---|---|
| License | MIT |
| Maintainer | onecomputer00@gmail.com |
| Stability | stable |
| Portability | portable |
| Safe Haskell | Safe-Inferred |
| Language | Haskell2010 |
Hectoparsec
Description
Top-level module for Hectoparsec. These parsers are smart in keeping track of labels for parsers, which can be used to generate informational error messages. They also keep track of source positions, which can be attached to results.
To get started, define a parser type for your specific usecase. A parser works over a certain input stream and can
use a custom error type or label type. Custom input streams can be used by implementing the Stream typeclass.
import Control.Applicative import Data.Text (Text) import Data.Void (Void) import Hectoparsec -- Parser over a text stream, with no custom errors, and with string parser labels. type P =ParserText Void String data Color = Red | Green | Blue red, green, blue :: P Color red = Red <$string"red"<?>"red" green = Green <$string"green"<?>"green" blue = Blue <$string"blue"<?>"blue" color :: P Color color = red <|> green <|> blue parseColor :: FilePath -> Text -> Either (ParseErrorText Void String) Color parseColor fp s =evalParser(color <*endOfInput) fp s
Synopsis
- module Hectoparsec.Error
- module Hectoparsec.Pos
- module Hectoparsec.Stream
- module Hectoparsec.State
- data ParserT s e l m a
- evalParserT :: Monad m => ParserT s e l m a -> FilePath -> s -> m (Either (ParseError s e l) a)
- runParserT :: Monad m => ParserT s e l m a -> State s -> m (State s, Either (ParseError s e l) a)
- type Parser s e l = ParserT s e l Identity
- evalParser :: Parser s e l a -> FilePath -> s -> Either (ParseError s e l) a
- runParser :: Parser s e l a -> State s -> (State s, Either (ParseError s e l) a)
- class (Stream s, MonadPlus m) => MonadParser s e l m | m -> s e l where
- matchToken :: (Maybe (Token s) -> Either (ErrorItem s e l) a) -> m a
- matchTokens :: Int -> (Chunk s -> Either (ErrorItem s e l) a) -> m a
- matchTokenWhile :: (Token s -> Bool) -> (Chunk s -> Either (ErrorItem s e l) a) -> m a
- endOfInput :: m ()
- withLabel :: Maybe l -> m a -> m a
- try :: m a -> m a
- lookAhead :: m a -> m a
- notFollowedBy :: m a -> m ()
- recover :: (ParseError s e l -> m a) -> m a -> m a
- observing :: m a -> m (Either (ParseError s e l) a)
- parseError :: ParseError s e l -> m a
- getState :: m (State s)
- putState :: State s -> m ()
- anyToken :: MonadParser s e l m => m (Token s)
- char :: (MonadParser s e l m, Eq (Token s)) => Token s -> m (Token s)
- string :: forall s e l m. (MonadParser s e l m, Eq (Chunk s)) => Chunk s -> m (Chunk s)
- satisfy :: MonadParser s e l m => (Token s -> Bool) -> m (Token s)
- peek :: MonadParser s e l m => m (Maybe (Token s))
- peekNext :: MonadParser s e l m => m (Token s)
- countTokens :: forall s e l m. MonadParser s e l m => Int -> m (Chunk s)
- tokenWhile :: MonadParser s e l m => (Token s -> Bool) -> m (Chunk s)
- tokenWhile1 :: forall s e l m. MonadParser s e l m => (Token s -> Bool) -> m (Chunk s)
- matchRest :: MonadParser s e l m => m (Chunk s)
- atEnd :: MonadParser s e l m => m Bool
- label :: MonadParser s e l m => l -> m a -> m a
- (<?>) :: MonadParser s e l m => m a -> l -> m a
- hidden :: MonadParser s e l m => m a -> m a
- restore :: MonadParser s e l m => (ParseError s e l -> Bool) -> m a -> m a
- unexpected :: MonadParser s e l m => Unexpected s -> [l] -> m a
- failure :: MonadParser s e l m => String -> m a
- customError :: MonadParser s e l m => e -> m a
- getsState :: MonadParser s e l m => (State s -> a) -> m a
- modifyState :: MonadParser s e l m => (State s -> State s) -> m ()
- getInput :: MonadParser s e l m => m s
- getsInput :: MonadParser s e l m => (s -> a) -> m a
- putInput :: MonadParser s e l m => s -> m ()
- modifyInput :: MonadParser s e l m => (s -> s) -> m ()
- getPos :: MonadParser s e l m => m Pos
- getOffset :: MonadParser s e l m => m Int
Re-exports
module Hectoparsec.Error
module Hectoparsec.Pos
module Hectoparsec.Stream
module Hectoparsec.State
ParserT monad transformer
data ParserT s e l m a Source #
The type of a parser for a stream s, using custom errors e and custom labels l.
If custom errors or custom labels are not needed, you can simply set it to Void to ignore it. Generally,
if your parser cannot error, you would do so. Otherwise, you should set the error and label types to something that
would allow you to create useful error messages. In particular, labels are tracked in order to create a list of
expected items whenever parsers fail.
ParserT implements MonadParser for the primitive parser combinators, Alternative for branching parsers, and the
usual stack of Functor, Applicative, and Monad, along with the classes from mtl.
Instances
| Stream s => MonadParser s e l (ParserT s e l m) Source # | |
Defined in Hectoparsec.Primitive Methods matchToken :: (Maybe (Token s) -> Either (ErrorItem s e l) a) -> ParserT s e l m a Source # matchTokens :: Int -> (Chunk s -> Either (ErrorItem s e l) a) -> ParserT s e l m a Source # matchTokenWhile :: (Token s -> Bool) -> (Chunk s -> Either (ErrorItem s e l) a) -> ParserT s e l m a Source # endOfInput :: ParserT s e l m () Source # withLabel :: Maybe l -> ParserT s e l m a -> ParserT s e l m a Source # try :: ParserT s e l m a -> ParserT s e l m a Source # lookAhead :: ParserT s e l m a -> ParserT s e l m a Source # notFollowedBy :: ParserT s e l m a -> ParserT s e l m () Source # recover :: (ParseError s e l -> ParserT s e l m a) -> ParserT s e l m a -> ParserT s e l m a Source # observing :: ParserT s e l m a -> ParserT s e l m (Either (ParseError s e l) a) Source # parseError :: ParseError s e l -> ParserT s e l m a Source # | |
| MonadRWS r w st m => MonadRWS r w st (ParserT s e l m) Source # | |
Defined in Hectoparsec.Primitive | |
| MonadError err m => MonadError err (ParserT s e l m) Source # | |
Defined in Hectoparsec.Primitive Methods throwError :: err -> ParserT s e l m a Source # catchError :: ParserT s e l m a -> (err -> ParserT s e l m a) -> ParserT s e l m a Source # | |
| MonadReader r m => MonadReader r (ParserT s e l m) Source # | |
| MonadState st m => MonadState st (ParserT s e l m) Source # | |
| MonadWriter w m => MonadWriter w (ParserT s e l m) Source # | |
| MonadTrans (ParserT s e l) Source # | |
| MonadFail (ParserT s e l m) Source # | |
| MonadIO m => MonadIO (ParserT s e l m) Source # | |
| Alternative (ParserT s e l m) Source # | Allows for branching parsers. The Note that In general, if any branch comsumes input, regardless of success, that branch will be commited to, and error messages will be based entirely on that branch. |
| Applicative (ParserT s e l m) Source # | |
Defined in Hectoparsec.Primitive Methods pure :: a -> ParserT s e l m a Source # (<*>) :: ParserT s e l m (a -> b) -> ParserT s e l m a -> ParserT s e l m b Source # liftA2 :: (a -> b -> c) -> ParserT s e l m a -> ParserT s e l m b -> ParserT s e l m c Source # (*>) :: ParserT s e l m a -> ParserT s e l m b -> ParserT s e l m b Source # (<*) :: ParserT s e l m a -> ParserT s e l m b -> ParserT s e l m a Source # | |
| Functor (ParserT s e l m) Source # | |
| Monad (ParserT s e l m) Source # | |
| MonadPlus (ParserT s e l m) Source # | Equivalent to the |
| MonadCont m => MonadCont (ParserT s e l m) Source # | |
| (Stream s, IsString a, Eq a, a ~ Chunk s) => IsString (ParserT s e l m a) Source # | Allows for overloaded string literals to become parsers. This is equivalent to calling |
Defined in Hectoparsec.Primitive Methods fromString :: String -> ParserT s e l m a Source # | |
| Monoid a => Monoid (ParserT s e l m a) Source # | Lifts the underlying |
| Semigroup a => Semigroup (ParserT s e l m a) Source # | Lifts the underlying |
evalParserT :: Monad m => ParserT s e l m a -> FilePath -> s -> m (Either (ParseError s e l) a) Source #
Runs a parser given an input stream and the file name. Returns either the parse error or the result.
runParserT :: Monad m => ParserT s e l m a -> State s -> m (State s, Either (ParseError s e l) a) Source #
A variant of evalParserT that takes in an initial state and also gives the final state.
Parser monad
evalParser :: Parser s e l a -> FilePath -> s -> Either (ParseError s e l) a Source #
Runs a parser given an input stream and the file name. Returns either the parse error or the result.
runParser :: Parser s e l a -> State s -> (State s, Either (ParseError s e l) a) Source #
A variant of evalParser that takes in an initial state and also gives the final state.
MonadParser typeclass
class (Stream s, MonadPlus m) => MonadParser s e l m | m -> s e l where Source #
Monad m that implements the primitive parsers for a stream s, using custom errors e and custom labels l. These
parsers should have a notion of whether the input was consumed or not. They should also track the parser state, errors,
and labels.
The MonadPlus instance should be equal to the Alternative instance, and it should implement the
operations for branching parsers. In particular, p must commit to the first branch
that consumes input.<|> q
The ParserT instance is the canonical instance for this class.
Methods
Arguments
| :: (Maybe (Token s) -> Either (ErrorItem s e l) a) | A function to match on tokens. It can return either an error item or the resulting value. |
| -> m a |
Match on a token, returning either the value or an error. If this succeeds, input is consumed.
For matching by equality, use the derived char combinator.
Arguments
| :: Int | Length n of the chunk to take. If n <= 0, no tokens are taken. |
| -> (Chunk s -> Either (ErrorItem s e l) a) | A function to match on the chunk. If the chunk is empty, then n <= 0 or we are at the end. |
| -> m a |
Match on a chunk of at most n length, returning either the value or an error. If it fails, the parser will backtrack the stream. If this succeeds and chunk is non-empty, input is consumed.
For matching by equality, use the derived string combinator.
Arguments
| :: (Token s -> Bool) | The predicate to check a token. |
| -> (Chunk s -> Either (ErrorItem s e l) a) | A function to match on the chunk. |
| -> m a |
Take tokens that satisfy a predicate, and match on them, returning either the value or an error. If it fails, the parser will backtrack the stream. If this succeeds and the chunk is non-empty, input is consumed.
For matching just by a predicate, use the derived tokenWhile and tokenWhile1 combinators.
endOfInput :: m () Source #
A parser that only succeeds at the end of the stream.
withLabel :: Maybe l -> m a -> m a Source #
Adds or removes a label for a parser. See label and hidden for more information.
By default, no parsers defined in this library are labelled. It is entirely up to you to label parsers.
Backtracks a parser if it failed. That is, if a parser p fails, then try p will be considered to not have
consumed input. This can be used for arbitrary look ahead.
In the example below, alt1 will not act as expected, since red will consume the 'r', meaning rad will not
be tried. Adding try in alt2 will allow it to work as expected.
red =char'r' >>char'e' >>char'd' rad =char'r' >>char'a' >>char'd' alt1 = red <|> rad alt2 = try red <|> rad
lookAhead :: m a -> m a Source #
Backtracks a parser if it succeeds. That is, if a parser p succeeds, then lookAhead p will be considered to not
have consumed input.
This does not affect the parser if it fails, i.e. failed parsers can still consume input. Use try along with this
function if you need to backtrack on failure too.
notFollowedBy :: m a -> m () Source #
Creates a parser that only succeeds if the original fails.
This parser never consumes input nor modifies parser state.
recover :: (ParseError s e l -> m a) -> m a -> m a Source #
Creates a parser that can recover from parse failures.
If the recovery parser fails, it will act as if only the original parser failed.
observing :: m a -> m (Either (ParseError s e l) a) Source #
Observes the result of a parser, allowing parsing to continue on failure.
Note that this does not backtrack the parser whether it succeeds or fails.
parseError :: ParseError s e l -> m a Source #
Fails parsing with a parse error.
getState :: m (State s) Source #
Gets the parser state.
putState :: State s -> m () Source #
Replaces the parser state.
Instances
Derived combinators
Input consumption
anyToken :: MonadParser s e l m => m (Token s) Source #
Parses any token.
char :: (MonadParser s e l m, Eq (Token s)) => Token s -> m (Token s) Source #
Parses a specific token. Note that this parser is not labelled by default.
semicolon = char ';'
string :: forall s e l m. (MonadParser s e l m, Eq (Chunk s)) => Chunk s -> m (Chunk s) Source #
Parses a specific sequence of tokens. This fully backtracks, since it uses matchTokens. Note that this parser is not
labelled by default.
color = string "red" <|> string "green" <|> string "blue"
satisfy :: MonadParser s e l m => (Token s -> Bool) -> m (Token s) Source #
Parses a token that satisfies a predicate.
digit = satisfy isDigit
peek :: MonadParser s e l m => m (Maybe (Token s)) Source #
Peeks at the next token, without advancing the stream in any way.
peekNext :: MonadParser s e l m => m (Token s) Source #
Peeks at the next token, without advancing the stream in any way. If the stream is empty (i.e. there is no next token), an unexpected end of input error is reported.
countTokens :: forall s e l m. MonadParser s e l m => Int -> m (Chunk s) Source #
Parses a chunk of length exactly n, not more, not less. This fully backtracks, since it uses matchTokens.
tokenWhile :: MonadParser s e l m => (Token s -> Bool) -> m (Chunk s) Source #
Takes zero or more tokens that match a predicate. The resulting parser cannot fail. This fully backtracks,
since it uses matchTokenWhile. This should be more performant than using many and satisfy.
digits = tokenWhile isDigit
tokenWhile1 :: forall s e l m. MonadParser s e l m => (Token s -> Bool) -> m (Chunk s) Source #
Takes one or more tokens that match a predicate. This fully backtracks, since it uses matchTokenWhile. This should
be more performant than using some and satisfy.
digits1 = tokenWhile1 isDigit
matchRest :: MonadParser s e l m => m (Chunk s) Source #
Consumes the rest of the input. This parser cannot fail, though the chunk may be empty.
atEnd :: MonadParser s e l m => m Bool Source #
A parser that checks whether we are at the end of the stream.
Label combinators
label :: MonadParser s e l m => l -> m a -> m a Source #
Adds a label to a parser. This is used for labelling parsers that do not have one for better error messages, or for labelling a complex combination of parsers where you want to give it a more general label instead of merging the labels of each constituent parser.
label lbl p = withLabel (Just lbl) p(<?>) :: MonadParser s e l m => m a -> l -> m a infix 0 Source #
Adds a label to a parser. Simply a synonym for flip .label
:: MonadParser s e l m => m a -> m a Source #
Removes the label from a parser. This can be used to hide labels from errors.
hidden p = withLabel Nothing pError combinators
restore :: MonadParser s e l m => (ParseError s e l -> Bool) -> m a -> m a Source #
Restores the state to before using the parser if the error passes a predicate.
The result parser still fails if the given parser fails.
unexpected :: MonadParser s e l m => Unexpected s -> [l] -> m a Source #
Fails parsing with an unexpected item and a list of expected items.
failure :: MonadParser s e l m => String -> m a Source #
Fails parsing with a failure message. These errors are generally for broken invariants.
customError :: MonadParser s e l m => e -> m a Source #
Fails parsing with a custom error.
State combinators
getsState :: MonadParser s e l m => (State s -> a) -> m a Source #
Gets the parser state applied to a function.
getsState f = f <$> getStatemodifyState :: MonadParser s e l m => (State s -> State s) -> m () Source #
getInput :: MonadParser s e l m => m s Source #
Gets the input.
getsInput :: MonadParser s e l m => (s -> a) -> m a Source #
Gets the input applied to a function.
getsInput f = f <$> getInputputInput :: MonadParser s e l m => s -> m () Source #
Replaces the input.
modifyInput :: MonadParser s e l m => (s -> s) -> m () Source #
getPos :: MonadParser s e l m => m Pos Source #
Gets the position in the source text.
getOffset :: MonadParser s e l m => m Int Source #
Gets the offset in the input stream.