lens-3.9.0.2: Lenses, Folds and Traversals

Portability | non-portable
Stability | experimental
Maintainer | Edward Kmett <ekmett@gmail.com>
Safe Haskell | None

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 :: Action m (m a) a
- perform :: Monad m => Acting m a s t a b -> 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 t a b -> Action (trans m) s a
- (^!) :: Monad m => s -> Acting m a s t a b -> m a
- (^!!) :: Monad m => s -> Acting m [a] s t a b -> m [a]
- (^!?) :: Monad m => s -> Acting m (Leftmost a) s t a b -> 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 t a b -> s -> m (i, a)
- iperforms :: Monad m => IndexedActing i m e s t a b -> (i -> a -> e) -> s -> m e
- (^@!) :: Monad m => s -> IndexedActing i m (i, a) s t a b -> m (i, a)
- (^@!!) :: Monad m => s -> IndexedActing i m [(i, a)] s t a b -> m [(i, a)]
- (^@!?) :: Monad m => s -> IndexedActing i m (Leftmost (i, a)) s t a b -> 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 t a b = LensLike (Effect m r) s t a b
- type IndexedActing i m r s t a b = Over (Indexed i) (Effect m r) s t a b
- 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

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

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 :: Action m (m a) a

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

     acts ≡ act id

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

perform :: Monad m => Acting m a s t a b -> s -> m a

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

Perform an `Action` and modify the result.

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

liftAct :: (MonadTrans trans, Monad m) => Acting m a s t a b -> Action (trans m) s a

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

(^!) :: Monad m => s -> Acting m a s t a b -> m a

Perform an `Action`.

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

(^!!) :: Monad m => s -> Acting m [a] s t a b -> m [a]

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"]

(^!?) :: Monad m => s -> Acting m (Leftmost a) s t a b -> m (Maybe a)

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

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

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

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

Perform an `IndexedAction`.

     iperform ≡ flip (^@!)

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

Perform an `IndexedAction` and modify the result.

(^@!) :: Monad m => s -> IndexedActing i m (i, a) s t a b -> m (i, a)

Perform an `IndexedAction`.

(^@!!) :: Monad m => s -> IndexedActing i m [(i, a)] s t a b -> m [(i, a)]

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

(^@!?) :: Monad m => s -> IndexedActing i m (Leftmost (i, a)) s t a b -> m (Maybe (i, a))

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

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

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

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 t a b = LensLike (Effect m r) s t a b

Used to evaluate an `Action`.

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

Used to evaluate an `IndexedAction`.

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

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.

Instances

Effective Identity r (Accessor r) |
Monad m => Effective m r (Effect m r) |
Effective m r f => Effective m (Dual r) (Backwards f) |