megaparsec-9.7.0: Monadic parser combinators

Copyright | © 2015–present Megaparsec contributors © 2007 Paolo Martini © 1999–2001 Daan Leijen
License | FreeBSD
Maintainer | Mark Karpov <markkarpov92@gmail.com>
Stability | experimental
Portability | portable
Safe Haskell | Safe
Language | Haskell2010

Text.Megaparsec

Contents

- Re-exports
- Data types
- Running parser
- Primitive combinators
- Signaling parse errors
- Derivatives of primitive combinators
- Parser state combinators

Description

This module includes everything you need to get started writing a parser. If you are new to Megaparsec and don't know where to begin, take a look at the tutorial https://markkarpov.com/tutorial/megaparsec.html.

In addition to the Text.Megaparsec module, which exports and re-exports almost everything that you may need, we advise to import Text.Megaparsec.Char if you plan to work with a stream of `Char` tokens or Text.Megaparsec.Byte if you intend to parse binary data.

It is common to start working with the library by defining a type synonym like this:

    type Parser = Parsec Void Text
                         ^    ^
                         |    |
    Custom error component    Input stream type

Then you can write type signatures like `Parser `Int``—for a parser that returns an `Int` for example.

Similarly (since it's known to cause confusion), you should use `ParseErrorBundle` type parametrized like this:

    ParseErrorBundle Text Void
                     ^    ^
                     |    |
     Input stream type    Custom error component (the same you used in Parser)

Megaparsec uses some type-level machinery to provide flexibility without compromising on type safety. Thus type signatures are sometimes necessary to avoid ambiguous types. If you're seeing an error message that reads like “Type variable `e0` is ambiguous …”, you need to give an explicit signature to your parser to resolve the ambiguity. It's a good idea to provide type signatures for all top-level definitions.

Synopsis

- module Text.Megaparsec.Pos
- module Text.Megaparsec.Error
- module Text.Megaparsec.Stream
- module Control.Monad.Combinators
- data State s e = State {
  - stateInput :: s
  - stateOffset :: !Int
  - statePosState :: PosState s
  - stateParseErrors :: [ParseError s e]
  }
- data PosState s = PosState {
  - pstateInput :: s
  - pstateOffset :: !Int
  - pstateSourcePos :: !SourcePos
  - pstateTabWidth :: Pos
  - pstateLinePrefix :: String
  }
- type Parsec e s = ParsecT e s Identity
- data ParsecT e s (m :: Type -> Type) a
- parse :: Parsec e s a -> String -> s -> Either (ParseErrorBundle s e) a
- parseMaybe :: (Ord e, Stream s) => Parsec e s a -> s -> Maybe a
- parseTest :: (ShowErrorComponent e, Show a, VisualStream s, TraversableStream s) => Parsec e s a -> s -> IO ()
- runParser :: Parsec e s a -> String -> s -> Either (ParseErrorBundle s e) a
- runParser' :: Parsec e s a -> State s e -> (State s e, Either (ParseErrorBundle s e) a)
- runParserT :: Monad m => ParsecT e s m a -> String -> s -> m (Either (ParseErrorBundle s e) a)
- runParserT' :: Monad m => ParsecT e s m a -> State s e -> m (State s e, Either (ParseErrorBundle s e) a)
- class (Stream s, MonadPlus m) => MonadParsec e s (m :: Type -> Type) | m -> e s where
  - parseError :: ParseError s e -> m a
  - label :: String -> m a -> m a
  - hidden :: m a -> m a
  - try :: m a -> m a
  - lookAhead :: m a -> m a
  - notFollowedBy :: m a -> m ()
  - withRecovery :: (ParseError s e -> m a) -> m a -> m a
  - observing :: m a -> m (Either (ParseError s e) a)
  - eof :: m ()
  - token :: (Token s -> Maybe a) -> Set (ErrorItem (Token s)) -> m a
  - tokens :: (Tokens s -> Tokens s -> Bool) -> Tokens s -> m (Tokens s)
  - takeWhileP :: Maybe String -> (Token s -> Bool) -> m (Tokens s)
  - takeWhile1P :: Maybe String -> (Token s -> Bool) -> m (Tokens s)
  - takeP :: Maybe String -> Int -> m (Tokens s)
  - getParserState :: m (State s e)
  - updateParserState :: (State s e -> State s e) -> m ()
  - mkParsec :: (State s e -> Reply e s a) -> m a
- failure :: MonadParsec e s m => Maybe (ErrorItem (Token s)) -> Set (ErrorItem (Token s)) -> m a
- fancyFailure :: MonadParsec e s m => Set (ErrorFancy e) -> m a
- unexpected :: MonadParsec e s m => ErrorItem (Token s) -> m a
- customFailure :: MonadParsec e s m => e -> m a
- region :: MonadParsec e s m => (ParseError s e -> ParseError s e) -> m a -> m a
- registerParseError :: MonadParsec e s m => ParseError s e -> m ()
- registerFailure :: MonadParsec e s m => Maybe (ErrorItem (Token s)) -> Set (ErrorItem (Token s)) -> m ()
- registerFancyFailure :: MonadParsec e s m => Set (ErrorFancy e) -> m ()
- single :: MonadParsec e s m => Token s -> m (Token s)
- satisfy :: MonadParsec e s m => (Token s -> Bool) -> m (Token s)
- anySingle :: MonadParsec e s m => m (Token s)
- anySingleBut :: MonadParsec e s m => Token s -> m (Token s)
- oneOf :: (Foldable f, MonadParsec e s m) => f (Token s) -> m (Token s)
- noneOf :: (Foldable f, MonadParsec e s m) => f (Token s) -> m (Token s)
- chunk :: MonadParsec e s m => Tokens s -> m (Tokens s)
- (<?>) :: MonadParsec e s m => m a -> String -> m a
- match :: MonadParsec e s m => m a -> m (Tokens s, a)
- takeRest :: MonadParsec e s m => m (Tokens s)
- atEnd :: MonadParsec e s m => m Bool
- getInput :: MonadParsec e s m => m s
- setInput :: MonadParsec e s m => s -> m ()
- getSourcePos :: (TraversableStream s, MonadParsec e s m) => m SourcePos
- getOffset :: MonadParsec e s m => m Int
- setOffset :: MonadParsec e s m => Int -> m ()
- setParserState :: MonadParsec e s m => State s e -> m ()

# Re-exports

Note that we re-export monadic combinators from Control.Monad.Combinators because these are more efficient than `Applicative`-based ones (†). Thus `many` and `some` may clash with the functions from Control.Applicative. You need to hide the functions like this:

    import Control.Applicative hiding (many, some)

† As of Megaparsec 9.7.0 `many` and `some` are as efficient as their monadic counterparts.

Also note that you can import Control.Monad.Combinators.NonEmpty if you wish that combinators like `some` return `NonEmpty` lists. The module lives in the `parser-combinators` package (you need at least version 0.4.0).

This module is intended to be imported qualified:

    import qualified Control.Monad.Combinators.NonEmpty as NE

Other modules of interest are:

- Control.Monad.Combinators.Expr for parsing of expressions.
- Control.Applicative.Permutations for parsing of permutations phrases.

module Text.Megaparsec.Pos

module Text.Megaparsec.Error

module Text.Megaparsec.Stream

module Control.Monad.Combinators

# Data types

data State s e #

This is the Megaparsec's state parametrized over stream type `s` and custom error component type `e`.

Constructors

State |
Fields stateInput :: s The rest of input to process stateOffset :: !Int Number of processed tokens so far Since: 7.0.0 statePosState :: PosState s State that is used for line/column calculation Since: 7.0.0 stateParseErrors :: [ParseError s e] Collection of “delayed” `ParseError`s in reverse order. This means that the last registered error is the first element of the list. Since: 8.0.0

#### Instances

Instances details

(NFData s, NFData (ParseError s e)) => NFData (State s e) # |
Instance details Defined in Text.Megaparsec.State Methods rnf :: State s e -> () #
(Data e, Data (ParseError s e), Data s) => Data (State s e) # |
Instance details Defined in Text.Megaparsec.State Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> State s e -> c (State s e) # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (State s e) # toConstr :: State s e -> Constr # dataTypeOf :: State s e -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (State s e)) # dataCast2 :: Typeable t => (forall d e0. (Data d, Data e0) => c (t d e0)) -> Maybe (c (State s e)) # gmapT :: (forall b. Data b => b -> b) -> State s e -> State s e # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> State s e -> r # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> State s e -> r # gmapQ :: (forall d. Data d => d -> u) -> State s e -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> State s e -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> State s e -> m (State s e) # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> State s e -> m (State s e) # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> State s e -> m (State s e) #
Generic (State s e) # |
Instance details Defined in Text.Megaparsec.State Associated Types
type Rep (State s e) |
Instance details Defined in Text.Megaparsec.State type Rep (State s e) = D1 ('MetaData "State" "Text.Megaparsec.State" "megaparsec-9.7.0-CbJmYAiMrhRJAq8uh4lqvD" 'False) (C1 ('MetaCons "State" 'PrefixI 'True) ((S1 ('MetaSel ('Just "stateInput") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 s) :*: S1 ('MetaSel ('Just "stateOffset") 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 Int)) :*: (S1 ('MetaSel ('Just "statePosState") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (PosState s)) :*: S1 ('MetaSel ('Just "stateParseErrors") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [ParseError s e]))))
Methods from :: State s e -> Rep (State s e) x # to :: Rep (State s e) x -> State s e #
(Show (ParseError s e), Show s) => Show (State s e) # |
Instance details Defined in Text.Megaparsec.State Methods showsPrec :: Int -> State s e -> ShowS # show :: State s e -> String # showList :: [State s e] -> ShowS #
(Eq (ParseError s e), Eq s) => Eq (State s e) # |
Instance details Defined in Text.Megaparsec.State Methods (==) :: State s e -> State s e -> Bool # (/=) :: State s e -> State s e -> Bool #
type Rep (State s e) # |
Instance details Defined in Text.Megaparsec.State type Rep (State s e) = D1 ('MetaData "State" "Text.Megaparsec.State" "megaparsec-9.7.0-CbJmYAiMrhRJAq8uh4lqvD" 'False) (C1 ('MetaCons "State" 'PrefixI 'True) ((S1 ('MetaSel ('Just "stateInput") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 s) :*: S1 ('MetaSel ('Just "stateOffset") 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 Int)) :*: (S1 ('MetaSel ('Just "statePosState") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (PosState s)) :*: S1 ('MetaSel ('Just "stateParseErrors") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [ParseError s e]))))

data PosState s #

A special kind of state that is used to calculate line/column positions on demand.

Since: 7.0.0

Constructors

PosState |
Fields pstateInput :: s The rest of input to process pstateOffset :: !Int Offset corresponding to beginning of `pstateInput` pstateSourcePos :: !SourcePos Source position corresponding to beginning of `pstateInput` pstateTabWidth :: Pos Tab width to use for column calculation pstateLinePrefix :: String Prefix to prepend to offending line

#### Instances

Instances details

NFData s => NFData (PosState s) # |
Instance details Defined in Text.Megaparsec.State Methods rnf :: PosState s -> () #
Data s => Data (PosState s) # |
Instance details Defined in Text.Megaparsec.State Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> PosState s -> c (PosState s) # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (PosState s) # toConstr :: PosState s -> Constr # dataTypeOf :: PosState s -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (PosState s)) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (PosState s)) # gmapT :: (forall b. Data b => b -> b) -> PosState s -> PosState s # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> PosState s -> r # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> PosState s -> r # gmapQ :: (forall d. Data d => d -> u) -> PosState s -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> PosState s -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> PosState s -> m (PosState s) # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> PosState s -> m (PosState s) # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> PosState s -> m (PosState s) #
Generic (PosState s) # |
Instance details Defined in Text.Megaparsec.State Associated Types
type Rep (PosState s) |
Instance details Defined in Text.Megaparsec.State type Rep (PosState s) = D1 ('MetaData "PosState" "Text.Megaparsec.State" "megaparsec-9.7.0-CbJmYAiMrhRJAq8uh4lqvD" 'False) (C1 ('MetaCons "PosState" 'PrefixI 'True) ((S1 ('MetaSel ('Just "pstateInput") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 s) :*: S1 ('MetaSel ('Just "pstateOffset") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Int)) :*: (S1 ('MetaSel ('Just "pstateSourcePos") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 SourcePos) :*: (S1 ('MetaSel ('Just "pstateTabWidth") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Pos) :*: S1 ('MetaSel ('Just "pstateLinePrefix") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String)))))
Methods from :: PosState s -> Rep (PosState s) x # to :: Rep (PosState s) x -> PosState s #
Show s => Show (PosState s) # |
Instance details Defined in Text.Megaparsec.State Methods showsPrec :: Int -> PosState s -> ShowS # show :: PosState s -> String # showList :: [PosState s] -> ShowS #
Eq s => Eq (PosState s) # |
Instance details Defined in Text.Megaparsec.State Methods (==) :: PosState s -> PosState s -> Bool # (/=) :: PosState s -> PosState s -> Bool #
type Rep (PosState s) # |
Instance details Defined in Text.Megaparsec.State type Rep (PosState s) = D1 ('MetaData "PosState" "Text.Megaparsec.State" "megaparsec-9.7.0-CbJmYAiMrhRJAq8uh4lqvD" 'False) (C1 ('MetaCons "PosState" 'PrefixI 'True) ((S1 ('MetaSel ('Just "pstateInput") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 s) :*: S1 ('MetaSel ('Just "pstateOffset") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Int)) :*: (S1 ('MetaSel ('Just "pstateSourcePos") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 SourcePos) :*: (S1 ('MetaSel ('Just "pstateTabWidth") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Pos) :*: S1 ('MetaSel ('Just "pstateLinePrefix") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String)))))

type Parsec e s = ParsecT e s Identity #

`Parsec` is a non-transformer variant of the more general `ParsecT` monad transformer.

data ParsecT e s (m :: Type -> Type) a #

``ParsecT` e s m a` is a parser with custom data component of error `e`, stream type `s`, underlying monad `m` and return type `a`.

#### Instances

Instances details

(Ord e, Stream s) => MonadParsec e s (ParsecT e s m) # |
Instance details Defined in Text.Megaparsec.Internal Methods parseError :: ParseError s e -> ParsecT e s m a # label :: String -> ParsecT e s m a -> ParsecT e s m a # hidden :: ParsecT e s m a -> ParsecT e s m a # try :: ParsecT e s m a -> ParsecT e s m a # lookAhead :: ParsecT e s m a -> ParsecT e s m a # notFollowedBy :: ParsecT e s m a -> ParsecT e s m () # withRecovery :: (ParseError s e -> ParsecT e s m a) -> ParsecT e s m a -> ParsecT e s m a # observing :: ParsecT e s m a -> ParsecT e s m (Either (ParseError s e) a) # eof :: ParsecT e s m () # token :: (Token s -> Maybe a) -> Set (ErrorItem (Token s)) -> ParsecT e s m a # tokens :: (Tokens s -> Tokens s -> Bool) -> Tokens s -> ParsecT e s m (Tokens s) # takeWhileP :: Maybe String -> (Token s -> Bool) -> ParsecT e s m (Tokens s) # takeWhile1P :: Maybe String -> (Token s -> Bool) -> ParsecT e s m (Tokens s) # takeP :: Maybe String -> Int -> ParsecT e s m (Tokens s) # getParserState :: ParsecT e s m (State s e) # updateParserState :: (State s e -> State s e) -> ParsecT e s m () # mkParsec :: (State s e -> Reply e s a) -> ParsecT e s m a #
(VisualStream s, ShowErrorComponent e) => MonadParsecDbg e s (ParsecT e s m) # |
Instance details Defined in Text.Megaparsec.Debug Methods dbg :: Show a => String -> ParsecT e s m a -> ParsecT e s m a #
(Stream s, MonadError e' m) => MonadError e' (ParsecT e s m) # |
Instance details Defined in Text.Megaparsec.Internal Methods throwError :: e' -> ParsecT e s m a # catchError :: ParsecT e s m a -> (e' -> ParsecT e s m a) -> ParsecT e s m a #
(Stream s, MonadReader r m) => MonadReader r (ParsecT e s m) # |
Instance details Defined in Text.Megaparsec.Internal Methods ask :: ParsecT e s m r # local :: (r -> r) -> ParsecT e s m a -> ParsecT e s m a # reader :: (r -> a) -> ParsecT e s m a #
(Stream s, MonadState st m) => MonadState st (ParsecT e s m) # |
Instance details Defined in Text.Megaparsec.Internal Methods get :: ParsecT e s m st # put :: st -> ParsecT e s m () # state :: (st -> (a, st)) -> ParsecT e s m a #
(Stream s, MonadWriter w m) => MonadWriter w (ParsecT e s m) # | Since: 9.5.0
Instance details Defined in Text.Megaparsec.Internal Methods writer :: (a, w) -> ParsecT e s m a # tell :: w -> ParsecT e s m () # listen :: ParsecT e s m a -> ParsecT e s m (a, w) # pass :: ParsecT e s m (a, w -> w) -> ParsecT e s m a #
Stream s => MonadTrans (ParsecT e s) # |
Instance details Defined in Text.Megaparsec.Internal Methods lift :: Monad m => m a -> ParsecT e s m a #
(Stream s, MonadIO m) => MonadIO (ParsecT e s m) # |
Instance details Defined in Text.Megaparsec.Internal Methods liftIO :: IO a -> ParsecT e s m a #
(Ord e, Stream s) => Alternative (ParsecT e s m) # | `empty` is a parser that fails without consuming input.
Instance details Defined in Text.Megaparsec.Internal Methods empty :: ParsecT e s m a # (<|>) :: ParsecT e s m a -> ParsecT e s m a -> ParsecT e s m a # some :: ParsecT e s m a -> ParsecT e s m [a] # many :: ParsecT e s m a -> ParsecT e s m [a] #
Stream s => Applicative (ParsecT e s m) # | `pure` returns a parser that succeeds without consuming input.
Instance details Defined in Text.Megaparsec.Internal Methods pure :: a -> ParsecT e s m a # (<*>) :: ParsecT e s m (a -> b) -> ParsecT e s m a -> ParsecT e s m b # liftA2 :: (a -> b -> c) -> ParsecT e s m a -> ParsecT e s m b -> ParsecT e s m c # (*>) :: ParsecT e s m a -> ParsecT e s m b -> ParsecT e s m b # (<*) :: ParsecT e s m a -> ParsecT e s m b -> ParsecT e s m a #
Functor (ParsecT e s m) # |
Instance details Defined in Text.Megaparsec.Internal Methods fmap :: (a -> b) -> ParsecT e s m a -> ParsecT e s m b # (<$) :: a -> ParsecT e s m b -> ParsecT e s m a #
Stream s => Monad (ParsecT e s m) # | `return` returns a parser that succeeds without consuming input.
Instance details Defined in Text.Megaparsec.Internal Methods (>>=) :: ParsecT e s m a -> (a -> ParsecT e s m b) -> ParsecT e s m b # (>>) :: ParsecT e s m a -> ParsecT e s m b -> ParsecT e s m b # return :: a -> ParsecT e s m a #
(Ord e, Stream s) => MonadPlus (ParsecT e s m) # | `mzero` is a parser that fails without consuming input. Note: strictly speaking, this instance is unlawful. The right identity law does not hold, e.g. in general this is not true:
    v >> mzero = mzero
However the following holds:
    try v >> mzero = mzero
Instance details Defined in Text.Megaparsec.Internal Methods mzero :: ParsecT e s m a # mplus :: ParsecT e s m a -> ParsecT e s m a -> ParsecT e s m a #
Stream s => MonadFail (ParsecT e s m) # |
Instance details Defined in Text.Megaparsec.Internal Methods fail :: String -> ParsecT e s m a #
(Stream s, MonadFix m) => MonadFix (ParsecT e s m) # | Since: 6.0.0
Instance details Defined in Text.Megaparsec.Internal Methods mfix :: (a -> ParsecT e s m a) -> ParsecT e s m a #
(Stream s, MonadCont m) => MonadCont (ParsecT e s m) # |
Instance details Defined in Text.Megaparsec.Internal Methods callCC :: ((a -> ParsecT e s m b) -> ParsecT e s m a) -> ParsecT e s m a #
(Stream s, Monoid a) => Monoid (ParsecT e s m a) # | Since: 5.3.0
Instance details Defined in Text.Megaparsec.Internal Methods mempty :: ParsecT e s m a # mappend :: ParsecT e s m a -> ParsecT e s m a -> ParsecT e s m a # mconcat :: [ParsecT e s m a] -> ParsecT e s m a #
(Stream s, Semigroup a) => Semigroup (ParsecT e s m a) # | Since: 5.3.0
Instance details Defined in Text.Megaparsec.Internal Methods (<>) :: ParsecT e s m a -> ParsecT e s m a -> ParsecT e s m a # sconcat :: NonEmpty (ParsecT e s m a) -> ParsecT e s m a # stimes :: Integral b => b -> ParsecT e s m a -> ParsecT e s m a #
(a ~ Tokens s, IsString a, Eq a, Stream s, Ord e) => IsString (ParsecT e s m a) # | Since: 6.3.0
Instance details Defined in Text.Megaparsec.Internal Methods fromString :: String -> ParsecT e s m a #

# Running parser

parse #

Arguments

:: Parsec e s a | Parser to run
-> String | Name of source file
-> s | Input for parser
-> Either (ParseErrorBundle s e) a |

``parse` p file input` runs parser `p` over `Identity` (see `runParserT` if you're using the `ParsecT` monad transformer; `parse` itself is just a synonym for `runParser`). It returns either a `ParseErrorBundle` (`Left`) or a value of type `a` (`Right`). `errorBundlePretty` can be used to turn `ParseErrorBundle` into the string representation of the error message. See Text.Megaparsec.Error if you need to do more advanced error analysis.

    main = case parse numbers "" "11,2,43" of
             Left bundle -> putStr (errorBundlePretty bundle)
             Right xs -> print (sum xs)

    numbers = decimal `sepBy` char ','

`parse` is the same as `runParser`.

parseMaybe :: (Ord e, Stream s) => Parsec e s a -> s -> Maybe a #

``parseMaybe` p input` runs the parser `p` on `input` and returns the result inside `Just` on success and `Nothing` on failure. This function also parses `eof`, so if the parser doesn't consume all of its input, it will fail.

The function is supposed to be useful for lightweight parsing, where error messages (and thus file names) are not important and entire input should be consumed. For example, it can be used for parsing of a single number according to a specification of its format.

parseTest #

Arguments

:: (ShowErrorComponent e, Show a, VisualStream s, TraversableStream s) |
=> Parsec e s a | Parser to run
-> s | Input for parser
-> IO () |

The expression ``parseTest` p input` applies the parser `p` on the input `input` and prints the result to stdout. Useful for testing.

runParser #

Arguments

:: Parsec e s a | Parser to run
-> String | Name of source file
-> s | Input for parser
-> Either (ParseErrorBundle s e) a |

``runParser` p file input` runs parser `p` on the input stream of tokens `input`, obtained from source `file`. The `file` is only used in error messages and may be the empty string. Returns either a `ParseErrorBundle` (`Left`) or a value of type `a` (`Right`).

    parseFromFile p file = runParser p file <$> readFile file

`runParser` is the same as `parse`.

runParser' #

Arguments

:: Parsec e s a | Parser to run
-> State s e | Initial state
-> (State s e, Either (ParseErrorBundle s e) a) |

The function is similar to `runParser` with the difference that it accepts and returns the parser state. This allows us e.g. to specify arbitrary textual position at the beginning of parsing. This is the most general way to run a parser over the `Identity` monad.

Since: 4.2.0

runParserT #

Arguments

:: Monad m |
=> ParsecT e s m a | Parser to run
-> String | Name of source file
-> s | Input for parser
-> m (Either (ParseErrorBundle s e) a) |

``runParserT` p file input` runs parser `p` on the input list of tokens `input`, obtained from source `file`. The `file` is only used in error messages and may be the empty string. Returns a computation in the underlying monad `m` that returns either a `ParseErrorBundle` (`Left`) or a value of type `a` (`Right`).

runParserT' #

Arguments

:: Monad m |
=> ParsecT e s m a | Parser to run
-> State s e | Initial state
-> m (State s e, Either (ParseErrorBundle s e) a) |

This function is similar to `runParserT`, but like `runParser'` it accepts and returns parser state. This is thus the most general way to run a parser.

Since: 4.2.0

# Primitive combinators

class (Stream s, MonadPlus m) => MonadParsec e s (m :: Type -> Type) | m -> e s where #

Type class describing monads that implement the full set of primitive parsers.

Note that the following primitives are “fast” and should be taken advantage of as much as possible if your aim is a fast parser: `tokens`, `takeWhileP`, `takeWhile1P`, and `takeP`.

Minimal complete definition

parseError, label, try, lookAhead, notFollowedBy, withRecovery, observing, eof, token, tokens, takeWhileP, takeWhile1P, takeP, getParserState, updateParserState, mkParsec

Methods

parseError :: ParseError s e -> m a #

Stop parsing and report the `ParseError`. This is the only way to control position of the error without manipulating the parser state manually.

Since: 8.0.0

label :: String -> m a -> m a #

The parser ``label` name p` behaves as parser `p`, but whenever the parser `p` fails without consuming any input, it replaces names of “expected” tokens with the name `name`.

hidden :: m a -> m a #

``hidden` p` behaves just like parser `p`, but it doesn't show any “expected” tokens in error message when `p` fails.

Please use `hidden` instead of the old ``label` ""` idiom.

try :: m a -> m a #

The parser ``try` p` behaves like the parser `p`, except that it backtracks the parser state when `p` fails (either consuming input or not).

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 if the first parser failed while consuming input.

For example, here is a parser that is supposed to parse the word “let” or the word “lexical”:

    >>> parseTest (string "let" <|> string "lexical") "lexical"
    1:1:
    unexpected "lex"
    expecting "let"

What happens here? The first parser consumes “le” and fails (because it doesn't see a “t”). The second parser, however, isn't tried, since the first parser has already consumed some input! `try` fixes this behavior and allows backtracking to work:

    >>> parseTest (try (string "let") <|> string "lexical") "lexical"
    "lexical"

`try` also improves error messages in case of overlapping alternatives, because Megaparsec's hint system can be used:

    >>> parseTest (try (string "let") <|> string "lexical") "le"
    1:1:
    unexpected "le"
    expecting "let" or "lexical"

Note that as of Megaparsec 4.4.0, `string` backtracks automatically (see `tokens`), so it does not need `try`. However, the examples above demonstrate the idea behind `try` so well that it was decided to keep them. You still need to use `try` when your alternatives are complex, composite parsers.

lookAhead :: m a -> m a #

If `p` in ``lookAhead` p` succeeds (either consuming input or not) the whole parser behaves like `p` succeeded without consuming anything (parser state is not updated as well). If `p` fails, `lookAhead` has no effect, i.e. it will fail consuming input if `p` fails consuming input. Combine with `try` if this is undesirable.

notFollowedBy :: m a -> m () #

``notFollowedBy` p` only succeeds when the parser `p` fails. This parser never consumes any input and never modifies parser state. It can be used to implement the “longest match” rule.

withRecovery #

Arguments

:: (ParseError s e -> m a) | How to recover from failure
-> m a | Original parser
-> m a | Parser that can recover from failures

``withRecovery` r p` allows us to continue parsing even if the parser `p` fails. In this case `r` is called with the actual `ParseError` as its argument. Typical usage is to return a value signifying failure to parse this particular object and to consume some part of the input up to the point where the next object starts.

Note that if `r` fails, the original error message is reported as if without `withRecovery`. In no way recovering parser `r` can influence error messages.

Since: 4.4.0

observing #

Arguments

:: m a | The parser to run
-> m (Either (ParseError s e) a) |

``observing` p` allows us to “observe” failure of the `p` parser, should it happen, without actually ending parsing but instead getting the `ParseError` in `Left`. On success parsed value is returned in `Right` as usual. Note that this primitive just allows you to observe parse errors as they happen, it does not backtrack or change how the `p` parser works in any way.

Since: 5.1.0

eof :: m () #

This parser only succeeds at the end of input.

token #

Arguments

:: (Token s -> Maybe a) | Matching function for the token to parse
-> Set (ErrorItem (Token s)) | Used in the error message to mention the items that were expected
-> m a |

The parser ``token` test expected` accepts tokens for which the matching function `test` returns `Just` results. If `Nothing` is returned the `expected` set is used to report the items that were expected.

For example, the `satisfy` parser is implemented as:

    satisfy f = token testToken Set.empty
      where
        testToken x = if f x then Just x else Nothing

Note: type signature of this primitive was changed in the version 7.0.0.

tokens #

Arguments

:: (Tokens s -> Tokens s -> Bool) | Predicate to check equality of chunks
-> Tokens s | Chunk of input to match against
-> m (Tokens s) |

The parser ``tokens` test chk` parses a chunk of input `chk` and returns it. The supplied predicate `test` is used to check equality of given and parsed chunks after a candidate chunk of correct length is fetched from the stream.

This can be used for example to write `chunk`:

    chunk = tokens (==)

Note that beginning from Megaparsec 4.4.0, this is an auto-backtracking primitive, which means that if it fails, it never consumes any input. This is done to make its consumption model match how error messages for this primitive are reported (which becomes an important thing as user gets more control with primitives like `withRecovery`):

    >>> parseTest (string "abc") "abd"
    1:1:
    unexpected "abd"
    expecting "abc"

This means, in particular, that it's no longer necessary to use `try` with `tokens`-based parsers, such as `string` and `string'`. This feature does not affect performance in any way.

takeWhileP #

Arguments

:: Maybe String | Name for a single token in the row
-> (Token s -> Bool) | Predicate to use to test tokens
-> m (Tokens s) | A chunk of matching tokens

Parse zero or more tokens for which the supplied predicate holds. Try to use this as much as possible because for many streams this combinator is much faster than parsers built with `many` and `satisfy`.

    takeWhileP (Just "foo") f = many (satisfy f <?> "foo")
    takeWhileP Nothing      f = many (satisfy f)

The combinator never fails, although it may parse the empty chunk.

Since: 6.0.0

takeWhile1P #

Arguments

:: Maybe String | Name for a single token in the row
-> (Token s -> Bool) | Predicate to use to test tokens
-> m (Tokens s) | A chunk of matching tokens

Similar to `takeWhileP`, but fails if it can't parse at least one token. Try to use this as much as possible because for many streams this combinator is much faster than parsers built with `some` and `satisfy`.

    takeWhile1P (Just "foo") f = some (satisfy f <?> "foo")
    takeWhile1P Nothing      f = some (satisfy f)

Note that the combinator either succeeds or fails without consuming any input, so `try` is not necessary with it.

Since: 6.0.0

takeP #

Arguments

:: Maybe String | Name for a single token in the row
-> Int | How many tokens to extract
-> m (Tokens s) | A chunk of matching tokens

Extract the specified number of tokens from the input stream and return them packed as a chunk of stream. If there is not enough tokens in the stream, a parse error will be signaled. It's guaranteed that if the parser succeeds, the requested number of tokens will be returned.

The parser is roughly equivalent to:

    takeP (Just "foo") n = count n (anySingle <?> "foo")
    takeP Nothing      n = count n anySingle

Note that if the combinator fails due to insufficient number of tokens in the input stream, it backtracks automatically. No `try` is necessary with `takeP`.

Since: 6.0.0

getParserState :: m (State s e) #

Return the full parser state as a `State` record.

updateParserState :: (State s e -> State s e) -> m () #

``updateParserState` f` applies the function `f` to the parser state.

mkParsec :: (State s e -> Reply e s a) -> m a #

An escape hatch for defining custom `MonadParsec` primitives. You will need to import Text.Megaparsec.Internal in order to construct `Reply`.

Since: 9.4.0

#### Instances

Instances details

MonadParsec e s m => MonadParsec e s (IdentityT m) # |
Instance details Defined in Text.Megaparsec.Class Methods parseError :: ParseError s e -> IdentityT m a # label :: String -> IdentityT m a -> IdentityT m a # hidden :: IdentityT m a -> IdentityT m a # try :: IdentityT m a -> IdentityT m a # lookAhead :: IdentityT m a -> IdentityT m a # notFollowedBy :: IdentityT m a -> IdentityT m () # withRecovery :: (ParseError s e -> IdentityT m a) -> IdentityT m a -> IdentityT m a # observing :: IdentityT m a -> IdentityT m (Either (ParseError s e) a) # eof :: IdentityT m () # token :: (Token s -> Maybe a) -> Set (ErrorItem (Token s)) -> IdentityT m a # tokens :: (Tokens s -> Tokens s -> Bool) -> Tokens s -> IdentityT m (Tokens s) # takeWhileP :: Maybe String -> (Token s -> Bool) -> IdentityT m (Tokens s) # takeWhile1P :: Maybe String -> (Token s -> Bool) -> IdentityT m (Tokens s) # takeP :: Maybe String -> Int -> IdentityT m (Tokens s) # getParserState :: IdentityT m (State s e) # updateParserState :: (State s e -> State s e) -> IdentityT m () # mkParsec :: (State s e -> Reply e s a) -> IdentityT m a #
MonadParsec e s m => MonadParsec e s (ReaderT r m) # |
Instance details Defined in Text.Megaparsec.Class Methods parseError :: ParseError s e -> ReaderT r m a # label :: String -> ReaderT r m a -> ReaderT r m a # hidden :: ReaderT r m a -> ReaderT r m a # try :: ReaderT r m a -> ReaderT r m a # lookAhead :: ReaderT r m a -> ReaderT r m a # notFollowedBy :: ReaderT r m a -> ReaderT r m () # withRecovery :: (ParseError s e -> ReaderT r m a) -> ReaderT r m a -> ReaderT r m a # observing :: ReaderT r m a -> ReaderT r m (Either (ParseError s e) a) # eof :: ReaderT r m () # token :: (Token s -> Maybe a) -> Set (ErrorItem (Token s)) -> ReaderT r m a # tokens :: (Tokens s -> Tokens s -> Bool) -> Tokens s -> ReaderT r m (Tokens s) # takeWhileP :: Maybe String -> (Token s -> Bool) -> ReaderT r m (Tokens s) # takeWhile1P :: Maybe String -> (Token s -> Bool) -> ReaderT r m (Tokens s) # takeP :: Maybe String -> Int -> ReaderT r m (Tokens s) # getParserState :: ReaderT r m (State s e) # updateParserState :: (State s e -> State s e) -> ReaderT r m () # mkParsec :: (State s e -> Reply e s a) -> ReaderT r m a #
MonadParsec e s m => MonadParsec e s (StateT st m) # |
Instance details Defined in Text.Megaparsec.Class Methods parseError :: ParseError s e -> StateT st m a # label :: String -> StateT st m a -> StateT st m a # hidden :: StateT st m a -> StateT st m a # try :: StateT st m a -> StateT st m a # lookAhead :: StateT st m a -> StateT st m a # notFollowedBy :: StateT st m a -> StateT st m () # withRecovery :: (ParseError s e -> StateT st m a) -> StateT st m a -> StateT st m a # observing :: StateT st m a -> StateT st m (Either (ParseError s e) a) # eof :: StateT st m () # token :: (Token s -> Maybe a) -> Set (ErrorItem (Token s)) -> StateT st m a # tokens :: (Tokens s -> Tokens s -> Bool) -> Tokens s -> StateT st m (Tokens s) # takeWhileP :: Maybe String -> (Token s -> Bool) -> StateT st m (Tokens s) # takeWhile1P :: Maybe String -> (Token s -> Bool) -> StateT st m (Tokens s) # takeP :: Maybe String -> Int -> StateT st m (Tokens s) # getParserState :: StateT st m (State s e) # updateParserState :: (State s e -> State s e) -> StateT st m () # mkParsec :: (State s e -> Reply e s a) -> StateT st m a #
MonadParsec e s m => MonadParsec e s (StateT st m) # |
Instance details Defined in Text.Megaparsec.Class Methods parseError :: ParseError s e -> StateT st m a # label :: String -> StateT st m a -> StateT st m a # hidden :: StateT st m a -> StateT st m a # try :: StateT st m a -> StateT st m a # lookAhead :: StateT st m a -> StateT st m a # notFollowedBy :: StateT st m a -> StateT st m () # withRecovery :: (ParseError s e -> StateT st m a) -> StateT st m a -> StateT st m a # observing :: StateT st m a -> StateT st m (Either (ParseError s e) a) # eof :: StateT st m () # token :: (Token s -> Maybe a) -> Set (ErrorItem (Token s)) -> StateT st m a # tokens :: (Tokens s -> Tokens s -> Bool) -> Tokens s -> StateT st m (Tokens s) # takeWhileP :: Maybe String -> (Token s -> Bool) -> StateT st m (Tokens s) # takeWhile1P :: Maybe String -> (Token s -> Bool) -> StateT st m (Tokens s) # takeP :: Maybe String -> Int -> StateT st m (Tokens s) # getParserState :: StateT st m (State s e) # updateParserState :: (State s e -> State s e) -> StateT st m () # mkParsec :: (State s e -> Reply e s a) -> StateT st m a #
(Monoid w, MonadParsec e s m) => MonadParsec e s (WriterT w m) # |
Instance details Defined in Text.Megaparsec.Class Methods parseError :: ParseError s e -> WriterT w m a # label :: String -> WriterT w m a -> WriterT w m a # hidden :: WriterT w m a -> WriterT w m a # try :: WriterT w m a -> WriterT w m a # lookAhead :: WriterT w m a -> WriterT w m a # notFollowedBy :: WriterT w m a -> WriterT w m () # withRecovery :: (ParseError s e -> WriterT w m a) -> WriterT w m a -> WriterT w m a # observing :: WriterT w m a -> WriterT w m (Either (ParseError s e) a) # eof :: WriterT w m () # token :: (Token s -> Maybe a) -> Set (ErrorItem (Token s)) -> WriterT w m a # tokens :: (Tokens s -> Tokens s -> Bool) -> Tokens s -> WriterT w m (Tokens s) # takeWhileP :: Maybe String -> (Token s -> Bool) -> WriterT w m (Tokens s) # takeWhile1P :: Maybe String -> (Token s -> Bool) -> WriterT w m (Tokens s) # takeP :: Maybe String -> Int -> WriterT w m (Tokens s) # getParserState :: WriterT w m (State s e) # updateParserState :: (State s e -> State s e) -> WriterT w m () # mkParsec :: (State s e -> Reply e s a) -> WriterT w m a #
(Monoid w, MonadParsec e s m) => MonadParsec e s (WriterT w m) # |
Instance details Defined in Text.Megaparsec.Class Methods parseError :: ParseError s e -> WriterT w m a # label :: String -> WriterT w m a -> WriterT w m a # hidden :: WriterT w m a -> WriterT w m a # try :: WriterT w m a -> WriterT w m a # lookAhead :: WriterT w m a -> WriterT w m a # notFollowedBy :: WriterT w m a -> WriterT w m () # withRecovery :: (ParseError s e -> WriterT w m a) -> WriterT w m a -> WriterT w m a # observing :: WriterT w m a -> WriterT w m (Either (ParseError s e) a) # eof :: WriterT w m () # token :: (Token s -> Maybe a) -> Set (ErrorItem (Token s)) -> WriterT w m a # tokens :: (Tokens s -> Tokens s -> Bool) -> Tokens s -> WriterT w m (Tokens s) # takeWhileP :: Maybe String -> (Token s -> Bool) -> WriterT w m (Tokens s) # takeWhile1P :: Maybe String -> (Token s -> Bool) -> WriterT w m (Tokens s) # takeP :: Maybe String -> Int -> WriterT w m (Tokens s) # getParserState :: WriterT w m (State s e) # updateParserState :: (State s e -> State s e) -> WriterT w m () # mkParsec :: (State s e -> Reply e s a) -> WriterT w m a #
(Ord e, Stream s) => MonadParsec e s (ParsecT e s m) # |
Instance details Defined in Text.Megaparsec.Internal Methods parseError :: ParseError s e -> ParsecT e s m a # label :: String -> ParsecT e s m a -> ParsecT e s m a # hidden :: ParsecT e s m a -> ParsecT e s m a # try :: ParsecT e s m a -> ParsecT e s m a # lookAhead :: ParsecT e s m a -> ParsecT e s m a # notFollowedBy :: ParsecT e s m a -> ParsecT e s m () # withRecovery :: (ParseError s e -> ParsecT e s m a) -> ParsecT e s m a -> ParsecT e s m a # observing :: ParsecT e s m a -> ParsecT e s m (Either (ParseError s e) a) # eof :: ParsecT e s m () # token :: (Token s -> Maybe a) -> Set (ErrorItem (Token s)) -> ParsecT e s m a # tokens :: (Tokens s -> Tokens s -> Bool) -> Tokens s -> ParsecT e s m (Tokens s) # takeWhileP :: Maybe String -> (Token s -> Bool) -> ParsecT e s m (Tokens s) # takeWhile1P :: Maybe String -> (Token s -> Bool) -> ParsecT e s m (Tokens s) # takeP :: Maybe String -> Int -> ParsecT e s m (Tokens s) # getParserState :: ParsecT e s m (State s e) # updateParserState :: (State s e -> State s e) -> ParsecT e s m () # mkParsec :: (State s e -> Reply e s a) -> ParsecT e s m a #
(Monoid w, MonadParsec e s m) => MonadParsec e s (RWST r w st m) # | Since: 5.2.0
Instance details Defined in Text.Megaparsec.Class Methods parseError :: ParseError s e -> RWST r w st m a # label :: String -> RWST r w st m a -> RWST r w st m a # hidden :: RWST r w st m a -> RWST r w st m a # try :: RWST r w st m a -> RWST r w st m a # lookAhead :: RWST r w st m a -> RWST r w st m a # notFollowedBy :: RWST r w st m a -> RWST r w st m () # withRecovery :: (ParseError s e -> RWST r w st m a) -> RWST r w st m a -> RWST r w st m a # observing :: RWST r w st m a -> RWST r w st m (Either (ParseError s e) a) # eof :: RWST r w st m () # token :: (Token s -> Maybe a) -> Set (ErrorItem (Token s)) -> RWST r w st m a # tokens :: (Tokens s -> Tokens s -> Bool) -> Tokens s -> RWST r w st m (Tokens s) # takeWhileP :: Maybe String -> (Token s -> Bool) -> RWST r w st m (Tokens s) # takeWhile1P :: Maybe String -> (Token s -> Bool) -> RWST r w st m (Tokens s) # takeP :: Maybe String -> Int -> RWST r w st m (Tokens s) # getParserState :: RWST r w st m (State s e) # updateParserState :: (State s e -> State s e) -> RWST r w st m () # mkParsec :: (State s e -> Reply e s a) -> RWST r w st m a #
(Monoid w, MonadParsec e s m) => MonadParsec e s (RWST r w st m) # | Since: 5.2.0
Instance details Defined in Text.Megaparsec.Class Methods parseError :: ParseError s e -> RWST r w st m a # label :: String -> RWST r w st m a -> RWST r w st m a # hidden :: RWST r w st m a -> RWST r w st m a # try :: RWST r w st m a -> RWST r w st m a # lookAhead :: RWST r w st m a -> RWST r w st m a # notFollowedBy :: RWST r w st m a -> RWST r w st m () # withRecovery :: (ParseError s e -> RWST r w st m a) -> RWST r w st m a -> RWST r w st m a # observing :: RWST r w st m a -> RWST r w st m (Either (ParseError s e) a) # eof :: RWST r w st m () # token :: (Token s -> Maybe a) -> Set (ErrorItem (Token s)) -> RWST r w st m a # tokens :: (Tokens s -> Tokens s -> Bool) -> Tokens s -> RWST r w st m (Tokens s) # takeWhileP :: Maybe String -> (Token s -> Bool) -> RWST r w st m (Tokens s) # takeWhile1P :: Maybe String -> (Token s -> Bool) -> RWST r w st m (Tokens s) # takeP :: Maybe String -> Int -> RWST r w st m (Tokens s) # getParserState :: RWST r w st m (State s e) # updateParserState :: (State s e -> State s e) -> RWST r w st m () # mkParsec :: (State s e -> Reply e s a) -> RWST r w st m a #

# Signaling parse errors

The most general function to fail and end parsing is `parseError`. These are built on top of it. The section also includes functions starting with the `register` prefix which allow users to register “delayed” `ParseError`s.

failure #

Arguments

:: MonadParsec e s m |
=> Maybe (ErrorItem (Token s)) | Unexpected item (if any)
-> Set (ErrorItem (Token s)) | Expected items
-> m a |

Stop parsing and report a trivial `ParseError`.

Since: 6.0.0

fancyFailure #

Arguments

:: MonadParsec e s m |
=> Set (ErrorFancy e) | Fancy error components
-> m a |

Stop parsing and report a fancy `ParseError`. To report a single custom parse error, see `customFailure`.

Since: 6.0.0

unexpected :: MonadParsec e s m => ErrorItem (Token s) -> m a #

The parser ``unexpected` item` fails with an error message telling about unexpected item `item` without consuming any input.

    unexpected item = failure (Just item) Set.empty

customFailure :: MonadParsec e s m => e -> m a #

Report a custom parse error. For a more general version, see `fancyFailure`.

    customFailure = fancyFailure . Set.singleton . ErrorCustom

Since: 6.3.0

region #

Arguments

:: MonadParsec e s m |
=> (ParseError s e -> ParseError s e) | How to process `ParseError`s
-> m a | The “region” that the processing applies to
-> m a |

Specify how to process `ParseError`s that happen inside of this wrapper. This applies to both normal and delayed `ParseError`s.

As a side-effect of the implementation the inner computation will start with an empty collection of delayed errors and they will be updated and “restored” on the way out of `region`.

Since: 5.3.0

registerParseError :: MonadParsec e s m => ParseError s e -> m () #

Register a `ParseError` for later reporting. This action does not end parsing and has no effect except for adding the given `ParseError` to the collection of “delayed” `ParseError`s which will be taken into consideration at the end of parsing. Only if this collection is empty the parser will succeed. This is the main way to report several parse errors at once.

Since: 8.0.0

registerFailure #

Arguments

:: MonadParsec e s m |
=> Maybe (ErrorItem (Token s)) | Unexpected item (if any)
-> Set (ErrorItem (Token s)) | Expected items
-> m () |

Like `failure`, but for delayed `ParseError`s.

Since: 8.0.0

registerFancyFailure #

Arguments

:: MonadParsec e s m |
=> Set (ErrorFancy e) | Fancy error components
-> m () |

Like `fancyFailure`, but for delayed `ParseError`s.

Since: 8.0.0

# Derivatives of primitive combinators

single #

Arguments

:: MonadParsec e s m |
=> Token s | Token to match
-> m (Token s) |

``single` t` only matches the single token `t`.

    semicolon = single ';'

See also: `token`, `anySingle`, `char`, `char`.

Since: 7.0.0

satisfy #

Arguments

:: MonadParsec e s m |
=> (Token s -> Bool) | Predicate to apply
-> m (Token s) |

The parser ``satisfy` f` succeeds for any token for which the supplied function `f` returns `True`.

    digitChar = satisfy isDigit <?> "digit"
    oneOf cs  = satisfy (`elem` cs)

Performance note: when you need to parse a single token, it is often a good idea to use `satisfy` with the right predicate function instead of creating a complex parser using the combinators.

See also: `anySingle`, `anySingleBut`, `oneOf`, `noneOf`.

Since: 7.0.0

anySingle :: MonadParsec e s m => m (Token s) #

Parse and return a single token. It's a good idea to attach a `label` to this parser.

    anySingle = satisfy (const True)

See also: `satisfy`, `anySingleBut`.

Since: 7.0.0

anySingleBut #

Arguments

:: MonadParsec e s m |
=> Token s | Token we should not match
-> m (Token s) |

Match any token but the given one. It's a good idea to attach a `label` to this parser.

    anySingleBut t = satisfy (/= t)

See also: `single`, `anySingle`, `satisfy`.

Since: 7.0.0

oneOf #

Arguments

:: (Foldable f, MonadParsec e s m) |
=> f (Token s) | Collection of matching tokens
-> m (Token s) |

``oneOf` ts` succeeds if the current token is in the supplied collection of tokens `ts`. Returns the parsed token. Note that this parser cannot automatically generate the “expected” component of error message, so usually you should label it manually with `label` or (`<?>`).

    oneOf cs = satisfy (`elem` cs)

See also: `satisfy`.

    digit = oneOf ['0'..'9'] <?> "digit"

Performance note: prefer `satisfy` when you can because it's faster when you have only a couple of tokens to compare to:

    quoteFast = satisfy (\x -> x == '\'' || x == '\"')
    quoteSlow = oneOf "'\""

Since: 7.0.0

noneOf #

Arguments

:: (Foldable f, MonadParsec e s m) |
=> f (Token s) | Collection of taken we should not match
-> m (Token s) |

As the dual of `oneOf`, ``noneOf` ts` succeeds if the current token not in the supplied list of tokens `ts`. Returns the parsed character. Note that this parser cannot automatically generate the “expected” component of error message, so usually you should label it manually with `label` or (`<?>`).

    noneOf cs = satisfy (`notElem` cs)

See also: `satisfy`.

Performance note: prefer `satisfy` and `anySingleBut` when you can because it's faster.

Since: 7.0.0

chunk #

Arguments

:: MonadParsec e s m |
=> Tokens s | Chunk to match
-> m (Tokens s) |

``chunk` chk` only matches the chunk `chk`.

    divOrMod = chunk "div" <|> chunk "mod"

See also: `tokens`, `string`, `string`.

Since: 7.0.0

(<?>) :: MonadParsec e s m => m a -> String -> m a infix 0 #

A synonym for `label` in the form of an operator.

match :: MonadParsec e s m => m a -> m (Tokens s, a) #

Return both the result of a parse and a chunk of input that was consumed during parsing. This relies on the change of the `stateOffset` value to evaluate how many tokens were consumed. If you mess with it manually in the argument parser, prepare for troubles.

Since: 5.3.0

takeRest :: MonadParsec e s m => m (Tokens s) #

Consume the rest of the input and return it as a chunk. This parser never fails, but may return the empty chunk.

    takeRest = takeWhileP Nothing (const True)

Since: 6.0.0

atEnd :: MonadParsec e s m => m Bool #

Return `True` when end of input has been reached.

    atEnd = option False (True <$ hidden eof)

Since: 6.0.0

# Parser state combinators

getInput :: MonadParsec e s m => m s #

Return the current input.

setInput :: MonadParsec e s m => s -> m () #

``setInput` input` continues parsing with `input`.

getSourcePos :: (TraversableStream s, MonadParsec e s m) => m SourcePos #

Return the current source position. This function is not cheap, do not call it e.g. on matching of every token, that's a bad idea. Still you can use it to get `SourcePos` to attach to things that you parse.

The function works under the assumption that we move in the input stream only forwards and never backwards, which is always true unless the user abuses the library.

Since: 7.0.0

getOffset :: MonadParsec e s m => m Int #

Get the number of tokens processed so far.

See also: `setOffset`.

Since: 7.0.0

setOffset :: MonadParsec e s m => Int -> m () #

Set the number of tokens processed so far.

See also: `getOffset`.

Since: 7.0.0

setParserState :: MonadParsec e s m => State s e -> m () #

``setParserState` st` sets the parser state to `st`.

See also: `getParserState`, `updateParserState`.