pipes-parse-3.0.9: Parsing infrastructure for the pipes ecosystem

Safe Haskell | Safe-Inferred
Language | Haskell2010

Pipes.Parse

Contents

- Parsing
- Parsing Lenses
- Utilities
- Re-exports

Description

Element-agnostic parsing utilities for `pipes`

See Pipes.Parse.Tutorial for an extended tutorial

Synopsis

- type Parser a (m :: Type -> Type) r = forall x. StateT (Producer a m x) m r
- draw :: forall (m :: Type -> Type) a. Monad m => Parser a m (Maybe a)
- skip :: forall (m :: Type -> Type) a. Monad m => Parser a m Bool
- drawAll :: forall (m :: Type -> Type) a. Monad m => Parser a m [a]
- skipAll :: forall (m :: Type -> Type) a. Monad m => Parser a m ()
- unDraw :: forall (m :: Type -> Type) a. Monad m => a -> Parser a m ()
- peek :: forall (m :: Type -> Type) a. Monad m => Parser a m (Maybe a)
- isEndOfInput :: forall (m :: Type -> Type) a. Monad m => Parser a m Bool
- foldAll :: forall (m :: Type -> Type) x a b. Monad m => (x -> a -> x) -> x -> (x -> b) -> Parser a m b
- foldAllM :: Monad m => (x -> a -> m x) -> m x -> (x -> m b) -> Parser a m b
- span :: forall (m :: Type -> Type) a x. Monad m => (a -> Bool) -> Lens' (Producer a m x) (Producer a m (Producer a m x))
- splitAt :: forall (m :: Type -> Type) a x. Monad m => Int -> Lens' (Producer a m x) (Producer a m (Producer a m x))
- groupBy :: forall (m :: Type -> Type) a x. Monad m => (a -> a -> Bool) -> Lens' (Producer a m x) (Producer a m (Producer a m x))
- group :: forall (m :: Type -> Type) a x. (Monad m, Eq a) => Lens' (Producer a m x) (Producer a m (Producer a m x))
- toParser :: forall (m :: Type -> Type) a r. Monad m => Consumer (Maybe a) m r -> Parser a m r
- toParser_ :: forall (m :: Type -> Type) a. Monad m => Consumer a m X -> Parser a m ()
- parsed :: forall (m :: Type -> Type) a e b r. Monad m => Parser a m (Either e b) -> Producer a m r -> Producer b m (e, Producer a m r)
- parsed_ :: forall (m :: Type -> Type) a b r. Monad m => Parser a m (Maybe b) -> Producer a m r -> Producer b m (Producer a m r)
- parseForever :: forall (m :: Type -> Type) a r b. Monad m => (forall (n :: Type -> Type). Monad n => Parser a n (Either r b)) -> Pipe a b m r
- parseForever_ :: forall (m :: Type -> Type) a b. Monad m => (forall (n :: Type -> Type). Monad n => Parser a n (Maybe b)) -> Pipe a b m ()
- lift :: (MonadTrans t, Monad m) => m a -> t m a
- newtype StateT s (m :: Type -> Type) a = StateT {
  - runStateT :: s -> m (a, s)
  }
- evalStateT :: Monad m => StateT s m a -> s -> m a
- execStateT :: Monad m => StateT s m a -> s -> m s
- yield :: forall (m :: Type -> Type) a x' x. Functor m => a -> Proxy x' x () a m ()
- type Producer b = Proxy X () () b
- next :: Monad m => Producer a m r -> m (Either r (a, Producer a m r))

# Parsing

`pipes-parse` handles end-of-input and pushback by storing a `Producer` in a `StateT` layer.

Connect `Parser`s to `Producer`s using either `runStateT`, `evalStateT`, or `execStateT`:

    runStateT  :: Parser a m r -> Producer a m x -> m (r, Producer a m x)
    evalStateT :: Parser a m r -> Producer a m x -> m  r
    execStateT :: Parser a m r -> Producer a m x -> m    (Producer a m x)
                                                          ^^^^^^^^^^^^^^
                                                             Leftovers

type Parser a (m :: Type -> Type) r = forall x. StateT (Producer a m x) m r Source #

A `Parser` is an action that reads from and writes to a stored `Producer`

draw :: forall (m :: Type -> Type) a. Monad m => Parser a m (Maybe a) Source #

Draw one element from the underlying `Producer`, returning `Nothing` if the `Producer` is empty

skip :: forall (m :: Type -> Type) a. Monad m => Parser a m Bool Source #

Skip one element from the underlying `Producer`, returning `True` if successful or `False` if the `Producer` is empty

    skip = fmap isJust draw

drawAll :: forall (m :: Type -> Type) a. Monad m => Parser a m [a] Source #

Draw all elements from the underlying `Producer`

Note that `drawAll` is not an idiomatic use of `pipes-parse`, but I provide it for simple testing purposes. Idiomatic `pipes-parse` style consumes the elements immediately as they are generated instead of loading all elements into memory. For example, you can use `foldAll` or `foldAllM` for this purpose.

skipAll :: forall (m :: Type -> Type) a. Monad m => Parser a m () Source #

Drain all elements from the underlying `Producer`

unDraw :: forall (m :: Type -> Type) a. Monad m => a -> Parser a m () Source #

Push back an element onto the underlying `Producer`

peek :: forall (m :: Type -> Type) a. Monad m => Parser a m (Maybe a) Source #

`peek` checks the first element of the stream, but uses `unDraw` to push the element back so that it is available for the next `draw` command.

    peek = do
        x <- draw
        case x of
            Nothing -> return ()
            Just a  -> unDraw a
        return x

isEndOfInput :: forall (m :: Type -> Type) a. Monad m => Parser a m Bool Source #

Check if the underlying `Producer` is empty

    isEndOfInput = fmap isNothing peek

foldAll Source #

Arguments

:: forall (m :: Type -> Type) x a b. Monad m |
=> (x -> a -> x) | Step function
-> x | Initial accumulator
-> (x -> b) | Extraction function
-> Parser a m b |

Fold all input values

    Control.Foldl.purely foldAll :: Monad m => Fold a b -> Parser a m b

foldAllM Source #

Arguments

:: Monad m |
=> (x -> a -> m x) | Step function
-> m x | Initial accumulator
-> (x -> m b) | Extraction function
-> Parser a m b |

Fold all input values monadically

    Control.Foldl.impurely foldAllM :: Monad m => FoldM a m b -> Parser a m b

# Parsing Lenses

Connect lenses to `Producer`s using (`^.`) or `view`:

    (^.) :: Producer a m x
         -> Lens' (Producer a m x) (Producer b m y)
         -> Producer b m y

Connect lenses to `Parser`s using `zoom`:

    zoom :: Lens' (Producer a m x) (Producer b m y)
         -> Parser b m r
         -> Parser a m r

Connect lenses to each other using (`.`) (i.e. function composition):

    (.) :: Lens' (Producer a m x) (Producer b m y)
        -> Lens' (Producer b m y) (Producer c m z)
        -> Lens' (Producer a m y) (Producer c m z)

span :: forall (m :: Type -> Type) a x. Monad m => (a -> Bool) -> Lens' (Producer a m x) (Producer a m (Producer a m x)) Source #

`span` is an improper lens that splits the `Producer` into two `Producer`s, where the outer `Producer` is the longest consecutive group of elements that satisfy the predicate

splitAt :: forall (m :: Type -> Type) a x. Monad m => Int -> Lens' (Producer a m x) (Producer a m (Producer a m x)) Source #

`splitAt` is an improper lens that splits a `Producer` into two `Producer`s after a fixed number of elements

groupBy :: forall (m :: Type -> Type) a x. Monad m => (a -> a -> Bool) -> Lens' (Producer a m x) (Producer a m (Producer a m x)) Source #

`groupBy` splits a `Producer` into two `Producer`s after the first group of elements that are equal according to the equality predicate

group :: forall (m :: Type -> Type) a x. (Monad m, Eq a) => Lens' (Producer a m x) (Producer a m (Producer a m x)) Source #

Like `groupBy`, where the equality predicate is (`==`)

# Utilities

toParser :: forall (m :: Type -> Type) a r. Monad m => Consumer (Maybe a) m r -> Parser a m r Source #

Convert a `Consumer` to a `Parser`

`Nothing` signifies end of input

toParser_ :: forall (m :: Type -> Type) a. Monad m => Consumer a m X -> Parser a m () Source #

Convert a never-ending `Consumer` to a `Parser`

parsed :: forall (m :: Type -> Type) a e b r. Monad m => Parser a m (Either e b) -> Producer a m r -> Producer b m (e, Producer a m r) Source #

Run a `Parser` repeatedly on a `Producer`, `yield`ing each `Right result

Returns the remainder of the `Producer` when the `Parser` returns `Left`

parsed_ :: forall (m :: Type -> Type) a b r. Monad m => Parser a m (Maybe b) -> Producer a m r -> Producer b m (Producer a m r) Source #

Run a `Parser` repeatedly on a `Producer`, `yield`ing each `Just` result

Returns the remainder of the `Producer` when the `Parser` returns `Nothing`

parseForever :: forall (m :: Type -> Type) a r b. Monad m => (forall (n :: Type -> Type). Monad n => Parser a n (Either r b)) -> Pipe a b m r Source #

Deprecated: Use `parsed` instead

Convert a `Parser` to a `Pipe` by running it repeatedly on the input

parseForever_ :: forall (m :: Type -> Type) a b. Monad m => (forall (n :: Type -> Type). Monad n => Parser a n (Maybe b)) -> Pipe a b m () Source #

Deprecated: Use `parsed_` instead

Variant of `parseForever` for parsers which return a Maybe instead of an Either

# Re-exports

Control.Monad.Trans.Class re-exports `lift`.

Control.Monad.Trans.State.Strict re-exports `StateT`, `runStateT`, `evalStateT`, and `execStateT`.

Pipes re-exports `Producer`, `yield`, and `next`.

lift :: (MonadTrans t, Monad m) => m a -> t m a Source #

Lift a computation from the argument monad to the constructed monad.

newtype StateT s (m :: Type -> Type) a Source #

A state transformer monad parameterized by:

- `s` - The state.
- `m` - The inner monad.

The `return` function leaves the state unchanged, while `>>=` uses the final state of the first computation as the initial state of the second.

Constructors

StateT |

Fields

- runStateT :: s -> m (a, s)

#### Instances

Instances details

MonadTrans (StateT s) |
Instance details Defined in Control.Monad.Trans.State.Strict Methods lift :: Monad m => m a -> StateT s m a Source #
MonadIO m => MonadIO (StateT s m) |
Instance details Defined in Control.Monad.Trans.State.Strict Methods liftIO :: IO a -> StateT s m a Source #
Contravariant m => Contravariant (StateT s m) |
Instance details Defined in Control.Monad.Trans.State.Strict Methods contramap :: (a' -> a) -> StateT s m a -> StateT s m a' Source # (>$) :: b -> StateT s m b -> StateT s m a Source #
(Functor m, MonadPlus m) => Alternative (StateT s m) |
Instance details Defined in Control.Monad.Trans.State.Strict Methods empty :: StateT s m a Source # (<|>) :: StateT s m a -> StateT s m a -> StateT s m a Source # some :: StateT s m a -> StateT s m [a] Source # many :: StateT s m a -> StateT s m [a] Source #
(Functor m, Monad m) => Applicative (StateT s m) |
Instance details Defined in Control.Monad.Trans.State.Strict Methods pure :: a -> StateT s m a Source # (<*>) :: StateT s m (a -> b) -> StateT s m a -> StateT s m b Source # liftA2 :: (a -> b -> c) -> StateT s m a -> StateT s m b -> StateT s m c Source # (*>) :: StateT s m a -> StateT s m b -> StateT s m b Source # (<*) :: StateT s m a -> StateT s m b -> StateT s m a Source #
Functor m => Functor (StateT s m) |
Instance details Defined in Control.Monad.Trans.State.Strict Methods fmap :: (a -> b) -> StateT s m a -> StateT s m b Source # (<$) :: a -> StateT s m b -> StateT s m a Source #
Monad m => Monad (StateT s m) |
Instance details Defined in Control.Monad.Trans.State.Strict Methods (>>=) :: StateT s m a -> (a -> StateT s m b) -> StateT s m b Source # (>>) :: StateT s m a -> StateT s m b -> StateT s m b Source # return :: a -> StateT s m a Source #
MonadPlus m => MonadPlus (StateT s m) |
Instance details Defined in Control.Monad.Trans.State.Strict Methods mzero :: StateT s m a Source # mplus :: StateT s m a -> StateT s m a -> StateT s m a Source #
MonadFail m => MonadFail (StateT s m) |
Instance details Defined in Control.Monad.Trans.State.Strict Methods fail :: String -> StateT s m a Source #
MonadFix m => MonadFix (StateT s m) |
Instance details Defined in Control.Monad.Trans.State.Strict Methods mfix :: (a -> StateT s m a) -> StateT s m a Source #
Generic (StateT s m a) |

Instance details

Defined in Control.Monad.Trans.State.Strict

Associated Types

type Rep (StateT s m a) |
Instance details Defined in Control.Monad.Trans.State.Strict type Rep (StateT s m a) = D1 ('MetaData "StateT" "Control.Monad.Trans.State.Strict" "transformers-0.6.1.1-inplace" 'True) (C1 ('MetaCons "StateT" 'PrefixI 'True) (S1 ('MetaSel ('Just "runStateT") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (s -> m (a, s)))))

Methods

from :: StateT s m a -> Rep (StateT s m a) x Source #

to :: Rep (StateT s m a) x -> StateT s m a Source #

type Rep (StateT s m a) |
Instance details Defined in Control.Monad.Trans.State.Strict type Rep (StateT s m a) = D1 ('MetaData "StateT" "Control.Monad.Trans.State.Strict" "transformers-0.6.1.1-inplace" 'True) (C1 ('MetaCons "StateT" 'PrefixI 'True) (S1 ('MetaSel ('Just "runStateT") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (s -> m (a, s)))))

evalStateT :: Monad m => StateT s m a -> s -> m a Source #

Evaluate a state computation with the given initial state and return the final value, discarding the final state.

-     evalStateT m s = liftM fst (runStateT m s)

execStateT :: Monad m => StateT s m a -> s -> m s Source #

Evaluate a state computation with the given initial state and return the final state, discarding the final value.

-     execStateT m s = liftM snd (runStateT m s)

yield :: forall (m :: Type -> Type) a x' x. Functor m => a -> Proxy x' x () a m () Source #

Produce a value

    yield :: Monad m => a -> Producer a m ()
    yield :: Monad m => a -> Pipe   x a m ()

type Producer b = Proxy X () () b Source #

`Producer`s can only `yield`

next :: Monad m => Producer a m r -> m (Either r (a, Producer a m r)) Source #

Consume the first value from a `Producer`

`next` either fails with a `Left` if the `Producer` terminates or succeeds with a `Right` providing the next value and the remainder of the `Producer`.