lens-action-0.2.0.2: Monadic Getters and Folds

Copyright | (C) 2012-14 Edward Kmett
License | BSD-style (see the file LICENSE)
Maintainer | Edward Kmett <ekmett@gmail.com>
Stability | experimental
Portability | non-portable
Safe Haskell | None
Language | Haskell98

Control.Lens.Action

Contents

- Composable Actions
- Indexed Actions
- Folds with Effects
- Implementation Details

Description

Synopsis

- type Action m s a = forall f r. Effective m r f => (a -> f a) -> s -> f s
- act :: Monad m => (s -> m a) -> IndexPreservingAction m s a
- acts :: IndexPreservingAction m (m a) a
- perform :: Monad m => Acting m a s a -> s -> m a
- performs :: (Profunctor p, Monad m) => Over p (Effect m e) s t a b -> p a e -> s -> m e
- liftAct :: (MonadTrans trans, Monad m) => Acting m a s a -> IndexPreservingAction (trans m) s a
- (^!) :: Monad m => s -> Acting m a s a -> m a
- (^!!) :: Monad m => s -> Acting m [a] s a -> m [a]
- (^!?) :: Monad m => s -> Acting m (Leftmost a) s a -> m (Maybe a)
- type IndexedAction i m s a = forall p f r. (Indexable i p, Effective m r f) => p a (f a) -> s -> f s
- iact :: Monad m => (s -> m (i, a)) -> IndexedAction i m s a
- iperform :: Monad m => IndexedActing i m (i, a) s a -> s -> m (i, a)
- iperforms :: Monad m => IndexedActing i m e s a -> (i -> a -> e) -> s -> m e
- (^@!) :: Monad m => s -> IndexedActing i m (i, a) s a -> m (i, a)
- (^@!!) :: Monad m => s -> IndexedActing i m [(i, a)] s a -> m [(i, a)]
- (^@!?) :: Monad m => s -> IndexedActing i m (Leftmost (i, a)) s a -> m (Maybe (i, a))
- type MonadicFold m s a = forall f r. (Effective m r f, Applicative f) => (a -> f a) -> s -> f s
- type IndexedMonadicFold i m s a = forall p f r. (Indexable i p, Effective m r f, Applicative f) => p a (f a) -> s -> f s
- type Acting m r s a = LensLike (Effect m r) s s a a
- type IndexedActing i m r s a = Over (Indexed i) (Effect m r) s s a a
- class (Monad m, Functor f, Contravariant f) => Effective m r f | f -> m r

# Composable Actions

type Action m s a = forall f r. Effective m r f => (a -> f a) -> s -> f s Source

An `Action` is a `Getter` enriched with access to a `Monad` for side-effects.

Every `Getter` can be used as an `Action`.

You can compose an `Action` with another `Action` using (`.`) from the `Prelude`.

act :: Monad m => (s -> m a) -> IndexPreservingAction m s a Source

Construct an `Action` from a monadic side-effect.

    >>> ["hello","world"]^!folded.act (\x -> [x,x ++ "!"])
    ["helloworld","helloworld!","hello!world","hello!world!"]

    act :: Monad m => (s -> m a) -> Action m s a
    act sma afb a = effective (sma a >>= ineffective . afb)

acts :: IndexPreservingAction m (m a) a Source

A self-running `Action`, analogous to `join`.

    acts ≡ act id

    >>> (1,"hello")^!_2.acts.to succ
    "ifmmp"

    > (1,getLine)^!!_2.acts.folded.to succ
    aa
    "bb"

perform :: Monad m => Acting m a s a -> s -> m a Source

Perform an `Action`.

    perform ≡ flip (^!)

performs :: (Profunctor p, Monad m) => Over p (Effect m e) s t a b -> p a e -> s -> m e Source

Perform an `Action` and modify the result.

    performs :: Monad m => Acting m e s a -> (a -> e) -> s -> m e

liftAct :: (MonadTrans trans, Monad m) => Acting m a s a -> IndexPreservingAction (trans m) s a Source

Apply a `Monad` transformer to an `Action`.

(^!) :: Monad m => s -> Acting m a s a -> m a infixr 8 Source

Perform an `Action`.

    >>> ["hello","world"]^!folded.act putStrLn
    hello
    world

(^!!) :: Monad m => s -> Acting m [a] s a -> m [a] infixr 8 Source

Perform a `MonadicFold` and collect all of the results in a list.

    >>> ["ab","cd","ef"]^!!folded.acts
    ["ace","acf","ade","adf","bce","bcf","bde","bdf"]

    > [1,2]^!!folded.act (i -> putStr (show i ++ ": ") >> getLine).each.to succ
    1: aa
    2: bb
    "bbcc"

(^!?) :: Monad m => s -> Acting m (Leftmost a) s a -> m (Maybe a) infixr 8 Source

Perform a `MonadicFold` and collect the leftmost result.

Note: this still causes all effects for all elements.

    >>> [Just 1, Just 2, Just 3]^!?folded.acts
    Just (Just 1)
    >>> [Just 1, Nothing]^!?folded.acts
    Nothing

# Indexed Actions

type IndexedAction i m s a = forall p f r. (Indexable i p, Effective m r f) => p a (f a) -> s -> f s Source

An `IndexedAction` is an `IndexedGetter` enriched with access to a `Monad` for side-effects.

Every `Getter` can be used as an `Action`.

You can compose an `Action` with another `Action` using (`.`) from the `Prelude`.

iact :: Monad m => (s -> m (i, a)) -> IndexedAction i m s a Source

Construct an `IndexedAction` from a monadic side-effect.

iperform :: Monad m => IndexedActing i m (i, a) s a -> s -> m (i, a) Source

Perform an `IndexedAction`.

    iperform ≡ flip (^@!)

iperforms :: Monad m => IndexedActing i m e s a -> (i -> a -> e) -> s -> m e Source

Perform an `IndexedAction` and modify the result.

(^@!) :: Monad m => s -> IndexedActing i m (i, a) s a -> m (i, a) infixr 8 Source

Perform an `IndexedAction`.

(^@!!) :: Monad m => s -> IndexedActing i m [(i, a)] s a -> m [(i, a)] infixr 8 Source

Obtain a list of all of the results of an `IndexedMonadicFold`.

(^@!?) :: Monad m => s -> IndexedActing i m (Leftmost (i, a)) s a -> m (Maybe (i, a)) infixr 8 Source

Perform an `IndexedMonadicFold` and collect the `Leftmost` result.

Note: this still causes all effects for all elements.

# Folds with Effects

type MonadicFold m s a = forall f r. (Effective m r f, Applicative f) => (a -> f a) -> s -> f s Source

A `MonadicFold` is a `Fold` enriched with access to a `Monad` for side-effects.

A `MonadicFold` can use side-effects to produce parts of the structure being folded (e.g. reading them from file).

Every `Fold` can be used as a `MonadicFold`, that simply ignores the access to the `Monad`.

You can compose a `MonadicFold` with another `MonadicFold` using (`.`) from the `Prelude`.

type IndexedMonadicFold i m s a = forall p f r. (Indexable i p, Effective m r f, Applicative f) => p a (f a) -> s -> f s Source

An `IndexedMonadicFold` is an `IndexedFold` enriched with access to a `Monad` for side-effects.

Every `IndexedFold` can be used as an `IndexedMonadicFold`, that simply ignores the access to the `Monad`.

You can compose an `IndexedMonadicFold` with another `IndexedMonadicFold` using (`.`) from the `Prelude`.

# Implementation Details

type Acting m r s a = LensLike (Effect m r) s s a a Source

Used to evaluate an `Action`.

type IndexedActing i m r s a = Over (Indexed i) (Effect m r) s s a a Source

Used to evaluate an `IndexedAction`.

class (Monad m, Functor f, Contravariant f) => Effective m r f | f -> m r Source

An `Effective` `Functor` ignores its argument and is isomorphic to a `Monad` wrapped around a value.

That said, the `Monad` is possibly rather unrelated to any `Applicative` structure.

Minimal complete definition

effective, ineffective

Instances

Effective Identity r (Const r) Source |
Monad m => Effective m r (Effect m r) Source |
Effective m r f => Effective m r (AlongsideRight f b) Source |
Effective m r f => Effective m r (AlongsideLeft f b) Source |
Effective m r f => Effective m (Dual r) (Backwards f) Source |