Text.ParserCombinators.Poly.StateLazy

The only differences between a State and a StateLazy parser are the instance of Applicative, and the type (and implementation) of runParser. We therefore need to newtype the original Parser type, to allow it to have a different instance.

A return type like Either, that distinguishes not only between right and wrong answers, but also has commitment, so that a failure cannot be undone. This should only be used for writing very primitive parsers - really it is an internal detail of the library. The z type is the remaining unconsumed input.

Apply a parser to an input token sequence.

Parse a non-empty list of items.

Parse a bracketed item, discarding the brackets. If everything matches except the closing bracket, the whole parse fails soft, which can give less-than-satisfying error messages. If you want better error messages, try calling with e.g. bracket open (commit close) item

The Commitment class is an abstraction over all the current concrete representations of monadic/applicative parser combinators in this package. The common feature is two-level error-handling. Some primitives must be implemented specific to each parser type (e.g. depending on whether the parser has a running state, or whether it is lazy). But given those primitives, large numbers of combinators do not depend any further on the internal structure of the particular parser.

The PolyParse class is an abstraction gathering all of the common features that a two-level error-handling parser requires: the applicative parsing interface, the monadic interface, and commitment.

There are two additional basic combinators that we expect to be implemented afresh for every concrete type, but which (for technical reasons) cannot be class methods. They are next and satisfy.

Apply a parsed function to a parsed value. Rather like ordinary function application lifted into parsers.

x discard y parses both x and y, but discards the result of y. Rather like const lifted into parsers.

When a simple fail is not strong enough, use failBad for emphasis. An emphasised (severe) error cannot be overridden by choice operators.

adjustErrBad is just like adjustErr except it also raises the severity of the error.

Helper for formatting error messages: indents all lines by a fixed amount.

Parse the first alternative in the list that succeeds.

'exactly n p' parses precisely n items, using the parser p, in sequence.

'upto n p' parses n or fewer items, using the parser p, in sequence.

Parse a list of items separated by discarded junk.

Parse a non-empty list of items separated by discarded junk.

Parse a list of items, discarding the start, end, and separator items.

manyFinally' is like manyFinally, except when the terminator parser overlaps with the element parser. In manyFinally e t, the parser t is tried only when parser e fails, whereas in manyFinally' e t, the parser t is always tried first, then parser e only if the terminator is not found. For instance, manyFinally (accept "01") (accept "0") on input "0101010" returns ["01","01","01"], whereas manyFinally' with the same arguments and input returns [].

A monoid on applicative functors.

If defined, some and many should be the least solutions of the equations:

• some v = (:) Prelude.<$> v <*> many v

• many v = some v <|> pure []

Examples

>>> Nothing <|> Just 42Just 42

>>> [1, 2] <|> [3, 4][1,2,3,4]

>>> empty <|> print (2^15)32768

A functor with application, providing operations to

• embed pure expressions (pure), and

• sequence computations and combine their results (<*> and liftA2).

A minimal complete definition must include implementations of pure and of either <*> or liftA2. If it defines both, then they must behave the same as their default definitions:

(<*>) = liftA2 id

liftA2 f x y = f Prelude.<$> x <*> y

Further, any definition must satisfy the following:

Identity

pure id <*> v = v

Composition

pure (.) <*> u <*> v <*> w = u <*> (v <*> w)

Homomorphism

pure f <*> pure x = pure (f x)

Interchange

u <*> pure y = pure ($ y) <*> u

The other methods have the following default definitions, which may be overridden with equivalent specialized implementations:

• u *> v = (id <$ u) <*> v

• u <* v = liftA2 const u v

As a consequence of these laws, the Functor instance for f will satisfy

• fmap f x = pure f <*> x

It may be useful to note that supposing

forall x y. p (q x y) = f x . g y

it follows from the above that

liftA2 p (liftA2 q u v) = liftA2 f u . liftA2 g v

If f is also a Monad, it should satisfy

• pure = return

• m1 <*> m2 = m1 >>= (\x1 -> m2 >>= (\x2 -> return (x1 x2)))

• (*>) = (>>)

(which implies that pure and <*> satisfy the applicative functor laws).

An infix synonym for fmap.

The name of this operator is an allusion to Prelude.$. Note the similarities between their types:

 ($)  ::              (a -> b) ->   a ->   b
(<$>) :: Functor f => (a -> b) -> f a -> f b

Whereas Prelude.$ is function application, <$> is function application lifted over a Functor.

Examples

Convert from a Maybe Int to a Maybe String using show:

>>> show <$> NothingNothing

>>> show <$> Just 3Just "3"

Convert from an Either Int Int to an Either Int String using show:

>>> show <$> Left 17Left 17

>>> show <$> Right 17Right "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)

Replace all locations in the input with the same value. The default definition is fmap . const, but this may be overridden with a more efficient version.

Examples

Perform a computation with Maybe and replace the result with a constant value if it is Just:

>>> 'a' <$ Just 2Just 'a'>>> 'a' <$ NothingNothing

One or none.

It is useful for modelling any computation that is allowed to fail.

Examples

Using the Alternative instance of Control.Monad.Except, the following functions:

>>> import Control.Monad.Except

>>> canFail = throwError "it failed" :: Except String Int>>> final = return 42                :: Except String Int

Can be combined by allowing the first function to fail:

>>> runExcept $ canFail *> finalLeft "it failed"

>>> runExcept $ optional canFail *> finalRight 42

A variant of <*> with the types of the arguments reversed. It differs from flip (<*>) in that the effects are resolved in the order the arguments are presented.

Examples

>>> (<**>) (print 1) (id <$ print 2)12

>>> flip (<*>) (print 1) (id <$ print 2)21

>>> ZipList [4, 5, 6] <**> ZipList [(+1), (*2), (/3)]ZipList {getZipList = [5.0,10.0,2.0]}

Lift a function to actions. Equivalent to Functor's fmap but implemented using only Applicative's methods: liftA f a = pure f <*> a

As such this function may be used to implement a Functor instance from an Applicative one.

Examples

Using the Applicative instance for Lists:

>>> liftA (+1) [1, 2][2,3]

Or the Applicative instance for Maybe

>>> liftA (+1) (Just 3)Just 4

Lift a ternary function to actions.

The sum of a collection of actions using (<|>), generalizing concat.

asum is just like msum, but generalised to Alternative.

Examples

Basic usage:

>>> asum [Just "Hello", Nothing, Just "World"]Just "Hello"

The Const functor.

Examples

>>> fmap (++ "World") (Const "Hello")Const "Hello"

Because we ignore the second type parameter to Const, the Applicative instance, which has (<*>) :: Monoid m => Const m (a -> b) -> Const m a -> Const m b essentially turns into Monoid m => m -> m -> m, which is (<>)

>>> Const [1, 2, 3] <*> Const [4, 5, 6]Const [1,2,3,4,5,6]

Lists, but with an Applicative functor based on zipping.

Examples

In contrast to the Applicative for GHC.List.List:

>>> (+) <$> [1, 2, 3] <*> [4, 5, 6][5,6,7,6,7,8,7,8,9]

The Applicative instance of ZipList applies the operation by pairing up the elements, analogous to zipWithN

>>> (+) <$> ZipList [1, 2, 3] <*> ZipList [4, 5, 6]ZipList {getZipList = [5,7,9]}

>>> (,,,) <$> ZipList [1, 2] <*> ZipList [3, 4] <*> ZipList [5, 6] <*> ZipList [7, 8]ZipList {getZipList = [(1,3,5,7),(2,4,6,8)]}

>>> ZipList [(+1), (^2), (/ 2)] <*> ZipList [5, 5, 5]ZipList {getZipList = [6.0,25.0,2.5]}