lens-3.8.7.3: Lenses, Folds and Traversals

Portability | Rank2Types
Stability | provisional
Maintainer | Edward Kmett <ekmett@gmail.com>
Safe Haskell | Trustworthy

Control.Lens.Lens

Contents

- Lenses
  - Concrete Lenses
- Combinators
- Lateral Composition
- Setting Functionally with Passthrough
- Setting State with Passthrough
- Cloning Lenses
- ALens Combinators
- Common Lenses
- Context

Description

A ``Lens` s t a b` is a purely functional reference.

While a `Traversal` could be used for `Getting` like a valid `Fold`, it wasn't a valid `Getter` as `Applicative` wasn't a superclass of `Gettable`.

`Functor`, however is the superclass of both.

     type Lens s t a b = forall f. Functor f => (a -> f b) -> s -> f t

Every `Lens` is a valid `Setter`.

Every `Lens` can be used for `Getting` like a `Fold` that doesn't use the `Applicative` or `Gettable`.

Every `Lens` is a valid `Traversal` that only uses the `Functor` part of the `Applicative` it is supplied.

Every `Lens` can be used for `Getting` like a valid `Getter`, since `Functor` is a superclass of `Gettable`.

Since every `Lens` can be used for `Getting` like a valid `Getter` it follows that it must view exactly one element in the structure.

The `Lens` laws follow from this property and the desire for it to act like a `Traversable` when used as a `Traversal`.

In the examples below, `getter` and `setter` are supplied as example getters and setters, and are not actual functions supplied by this package.

Synopsis

- type Lens s t a b = forall f. Functor f => (a -> f b) -> s -> f t
- type Lens' s a = Lens s s a a
- type IndexedLens i s t a b = forall f p. (Indexable i p, Functor f) => p a (f b) -> s -> f t
- type IndexedLens' i s a = IndexedLens i s s a a
- type ALens s t a b = LensLike (Pretext (->) a b) s t a b
- type ALens' s a = ALens s s a a
- type AnIndexedLens i s t a b = Overloading (Indexed i) (->) (Pretext (Indexed i) a b) s t a b
- type AnIndexedLens' i s a = AnIndexedLens i s s a a
- lens :: (s -> a) -> (s -> b -> t) -> Lens s t a b
- ilens :: (s -> (i, a)) -> (s -> b -> t) -> IndexedLens i s t a b
- iplens :: (Conjoined p, Functor f) => (s -> a) -> (s -> b -> t) -> Overloaded p f s t a b
- (%%~) :: Overloading p q f s t a b -> p a (f b) -> q s (f t)
- (%%=) :: MonadState s m => Overloading p (->) ((,) r) s s a b -> p a (r, b) -> m r
- (%%@~) :: IndexedLensLike i f s t a b -> (i -> a -> f b) -> s -> f t
- (%%@=) :: MonadState s m => IndexedLensLike i ((,) r) s s a b -> (i -> a -> (r, b)) -> m r
- (<%@~) :: Overloading (Indexed i) q ((,) b) s t a b -> (i -> a -> b) -> q s (b, t)
- (<%@=) :: MonadState s m => IndexedLensLike i ((,) b) s s a b -> (i -> a -> b) -> m b
- choosing :: Functor f => LensLike f s t a b -> LensLike f s' t' a b -> LensLike f (Either s s') (Either t t') a b
- chosen :: IndexPreservingLens (Either a a) (Either b b) a b
- alongside :: ALens s t a b -> ALens s' t' a' b' -> Lens (s, s') (t, t') (a, a') (b, b')
- inside :: ALens s t a b -> Lens (e -> s) (e -> t) (e -> a) (e -> b)
- (<%~) :: Profunctor p => Overloading p q ((,) b) s t a b -> p a b -> q s (b, t)
- (<+~) :: Num a => Overloading (->) q ((,) a) s t a a -> a -> q s (a, t)
- (<-~) :: Num a => Overloading (->) q ((,) a) s t a a -> a -> q s (a, t)
- (<*~) :: Num a => Overloading (->) q ((,) a) s t a a -> a -> q s (a, t)
- (<//~) :: Fractional a => Overloading (->) q ((,) a) s t a a -> a -> q s (a, t)
- (<^~) :: (Num a, Integral e) => Overloading (->) q ((,) a) s t a a -> e -> q s (a, t)
- (<^^~) :: (Fractional a, Integral e) => Overloading (->) q ((,) a) s t a a -> e -> q s (a, t)
- (<**~) :: Floating a => Overloading (->) q ((,) a) s t a a -> a -> q s (a, t)
- (<||~) :: Overloading (->) q ((,) Bool) s t Bool Bool -> Bool -> q s (Bool, t)
- (<&&~) :: Overloading (->) q ((,) Bool) s t Bool Bool -> Bool -> q s (Bool, t)
- (<<>~) :: Monoid m => Overloading (->) q ((,) m) s t m m -> m -> q s (m, t)
- (<<%~) :: Strong p => Overloading p q ((,) a) s t a b -> p a b -> q s (a, t)
- (<<.~) :: Overloading (->) q ((,) a) s t a b -> b -> q s (a, t)
- (<%=) :: (Profunctor p, MonadState s m) => Overloading p (->) ((,) b) s s a b -> p a b -> m b
- (<+=) :: (MonadState s m, Num a) => LensLike' ((,) a) s a -> a -> m a
- (<-=) :: (MonadState s m, Num a) => LensLike' ((,) a) s a -> a -> m a
- (<*=) :: (MonadState s m, Num a) => LensLike' ((,) a) s a -> a -> m a
- (<//=) :: (MonadState s m, Fractional a) => LensLike' ((,) a) s a -> a -> m a
- (<^=) :: (MonadState s m, Num a, Integral e) => LensLike' ((,) a) s a -> e -> m a
- (<^^=) :: (MonadState s m, Fractional a, Integral e) => LensLike' ((,) a) s a -> e -> m a
- (<**=) :: (MonadState s m, Floating a) => LensLike' ((,) a) s a -> a -> m a
- (<||=) :: MonadState s m => LensLike' ((,) Bool) s Bool -> Bool -> m Bool
- (<&&=) :: MonadState s m => LensLike' ((,) Bool) s Bool -> Bool -> m Bool
- (<<>=) :: (MonadState s m, Monoid r) => LensLike' ((,) r) s r -> r -> m r
- (<<%=) :: (Strong p, MonadState s m) => Overloading p (->) ((,) a) s s a b -> p a b -> m a
- (<<.=) :: MonadState s m => LensLike ((,) a) s s a b -> b -> m a
- (<<~) :: MonadState s m => ALens s s a b -> m b -> m b
- cloneLens :: ALens s t a b -> Lens s t a b
- cloneIndexPreservingLens :: ALens s t a b -> IndexPreservingLens s t a b
- cloneIndexedLens :: AnIndexedLens i s t a b -> IndexedLens i s t a b
- storing :: ALens s t a b -> b -> s -> t
- (^#) :: s -> ALens s t a b -> a
- (#~) :: ALens s t a b -> b -> s -> t
- (#%~) :: ALens s t a b -> (a -> b) -> s -> t
- (#%%~) :: Functor f => ALens s t a b -> (a -> f b) -> s -> f t
- (<#~) :: ALens s t a b -> b -> s -> (b, t)
- (<#%~) :: ALens s t a b -> (a -> b) -> s -> (b, t)
- (#=) :: MonadState s m => ALens s s a b -> b -> m ()
- (#%=) :: MonadState s m => ALens s s a b -> (a -> b) -> m ()
- (#%%=) :: MonadState s m => ALens s s a b -> (a -> (r, b)) -> m r
- (<#=) :: MonadState s m => ALens s s a b -> b -> m b
- (<#%=) :: MonadState s m => ALens s s a b -> (a -> b) -> m b
- devoid :: Over p f Void Void a b
- united :: Lens' a ()
- data Context a b t = Context (b -> t) a
- type Context' a = Context a a
- locus :: IndexedComonadStore p => Lens (p a c s) (p b c s) a b

# Lenses

type Lens s t a b = forall f. Functor f => (a -> f b) -> s -> f t

A `Lens` is actually a lens family as described in http://comonad.com/reader/2012/mirrored-lenses/.

With great power comes great responsibility and a `Lens` is subject to the three common sense `Lens` laws:

1) You get back what you put in:

     view l (set l b a)  ≡ b

2) Putting back what you got doesn't change anything:

     set l (view l a) a  ≡ a

3) Setting twice is the same as setting once:

     set l c (set l b a) ≡ set l c a

These laws are strong enough that the 4 type parameters of a `Lens` cannot vary fully independently. For more on how they interact, read the "Why is it a Lens Family?" section of http://comonad.com/reader/2012/mirrored-lenses/.

Every `Lens` can be used directly as a `Setter` or `Traversal`.

You can also use a `Lens` for `Getting` as if it were a `Fold` or `Getter`.

Since every `Lens` is a valid `Traversal`, the `Traversal` laws are required of any `Lens` you create:

     l pure ≡ pure
     fmap (l f) . l g ≡ getCompose . l (Compose . fmap f . g)

     type Lens s t a b = forall f. Functor f => LensLike f s t a b

type Lens' s a = Lens s s a a

     type Lens' = Simple Lens

type IndexedLens i s t a b = forall f p. (Indexable i p, Functor f) => p a (f b) -> s -> f t

Every `IndexedLens` is a valid `Lens` and a valid `IndexedTraversal`.

type IndexedLens' i s a = IndexedLens i s s a a

     type IndexedLens' i = Simple (IndexedLens i)

## Concrete Lenses

type ALens s t a b = LensLike (Pretext (->) a b) s t a b

When you see this as an argument to a function, it expects a `Lens`.

This type can also be used when you need to store a `Lens` in a container, since it is rank-1. You can turn them back into a `Lens` with `cloneLens`, or use it directly with combinators like `storing` and (`^#`).

type ALens' s a = ALens s s a a

     type ALens' = Simple ALens

type AnIndexedLens i s t a b = Overloading (Indexed i) (->) (Pretext (Indexed i) a b) s t a b

When you see this as an argument to a function, it expects an `IndexedLens`

type AnIndexedLens' i s a = AnIndexedLens i s s a a

     type AnIndexedLens' = Simple (AnIndexedLens i)

# Combinators

lens :: (s -> a) -> (s -> b -> t) -> Lens s t a b

Build a `Lens` from a getter and a setter.

     lens :: Functor f => (s -> a) -> (s -> b -> t) -> (a -> f b) -> s -> f t

    >>> s ^. lens getter setter
    getter s

    >>> s & lens getter setter .~ b
    setter s b

    >>> s & lens getter setter %~ f
    setter s (f (getter s))

ilens :: (s -> (i, a)) -> (s -> b -> t) -> IndexedLens i s t a b

Build an `IndexedLens` from a `Getter` and a `Setter`.

iplens :: (Conjoined p, Functor f) => (s -> a) -> (s -> b -> t) -> Overloaded p f s t a b

Build an index-preserving `Lens` from a `Getter` and a `Setter`.

     lens :: (s -> a) -> (s -> b -> t) -> Lens s t a b
     lens sa sbt afb s = sbt s <$> afb (sa s)

(%%~) :: Overloading p q f s t a b -> p a (f b) -> q s (f t)

(`%%~`) can be used in one of two scenarios:

When applied to a `Lens`, it can edit the target of the `Lens` in a structure, extracting a functorial result.

When applied to a `Traversal`, it can edit the targets of the traversals, extracting an applicative summary of its actions.

For all that the definition of this combinator is just:

     (%%~) ≡ id

It may be beneficial to think about it as if it had these even more restricted types, however:

     (%%~) :: Functor f =>     Iso s t a b       -> (a -> f b) -> s -> f t
     (%%~) :: Functor f =>     Lens s t a b      -> (a -> f b) -> s -> f t
     (%%~) :: Applicative f => Traversal s t a b -> (a -> f b) -> s -> f t

When applied to a `Traversal`, it can edit the targets of the traversals, extracting a supplemental monoidal summary of its actions, by choosing `f = ((,) m)`

     (%%~) ::             Iso s t a b       -> (a -> (r, b)) -> s -> (r, t)
     (%%~) ::             Lens s t a b      -> (a -> (r, b)) -> s -> (r, t)
     (%%~) :: Monoid m => Traversal s t a b -> (a -> (m, b)) -> s -> (m, t)

(%%=) :: MonadState s m => Overloading p (->) ((,) r) s s a b -> p a (r, b) -> m r

Modify the target of a `Lens` in the current state returning some extra information of type `r` or modify all targets of a `Traversal` in the current state, extracting extra information of type `r` and return a monoidal summary of the changes.

    >>> runState (_1 %%= \x -> (f x, g x)) (a,b)
    (f a,(g a,b))

     (%%=) ≡ (state .)

It may be useful to think of (`%%=`), instead, as having either of the following more restricted type signatures:

     (%%=) :: MonadState s m             => Iso s s a b       -> (a -> (r, b)) -> m r
     (%%=) :: MonadState s m             => Lens s s a b      -> (a -> (r, b)) -> m r
     (%%=) :: (MonadState s m, Monoid r) => Traversal s s a b -> (a -> (r, b)) -> m r

(%%@~) :: IndexedLensLike i f s t a b -> (i -> a -> f b) -> s -> f t

Adjust the target of an `IndexedLens` returning a supplementary result, or adjust all of the targets of an `IndexedTraversal` and return a monoidal summary of the supplementary results and the answer.

    (%%@~) ≡ withIndex

     (%%@~) :: Functor f => IndexedLens i s t a b      -> (i -> a -> f b) -> s -> f t
     (%%@~) :: Functor f => IndexedTraversal i s t a b -> (i -> a -> f b) -> s -> f t

In particular, it is often useful to think of this function as having one of these even more restricted type signatures:

     (%%@~) ::             IndexedLens i s t a b      -> (i -> a -> (r, b)) -> s -> (r, t)
     (%%@~) :: Monoid r => IndexedTraversal i s t a b -> (i -> a -> (r, b)) -> s -> (r, t)

(%%@=) :: MonadState s m => IndexedLensLike i ((,) r) s s a b -> (i -> a -> (r, b)) -> m r

Adjust the target of an `IndexedLens` returning a supplementary result, or adjust all of the targets of an `IndexedTraversal` within the current state, and return a monoidal summary of the supplementary results.

    l %%@= f ≡ state (l %%@~ f)

     (%%@=) :: MonadState s m                IndexedLens i s s a b      -> (i -> a -> (r, b)) -> s -> m r
     (%%@=) :: (MonadState s m, Monoid r) => IndexedTraversal i s s a b -> (i -> a -> (r, b)) -> s -> m r

(<%@~) :: Overloading (Indexed i) q ((,) b) s t a b -> (i -> a -> b) -> q s (b, t)

Adjust the target of an `IndexedLens` returning the intermediate result, or adjust all of the targets of an `IndexedTraversal` and return a monoidal summary along with the answer.

    l <%~ f ≡ l <%@~ const f

When you do not need access to the index then (`<%~`) is more liberal in what it can accept.

If you do not need the intermediate result, you can use (`%@~`) or even (`%~`).

     (<%@~) ::             IndexedLens i s t a b      -> (i -> a -> b) -> s -> (b, t)
     (<%@~) :: Monoid b => IndexedTraversal i s t a b -> (i -> a -> b) -> s -> (b, t)

(<%@=) :: MonadState s m => IndexedLensLike i ((,) b) s s a b -> (i -> a -> b) -> m b

Adjust the target of an `IndexedLens` returning the intermediate result, or adjust all of the targets of an `IndexedTraversal` within the current state, and return a monoidal summary of the intermediate results.

     (<%@=) :: MonadState s m                IndexedLens i s s a b      -> (i -> a -> b) -> m b
     (<%@=) :: (MonadState s m, Monoid b) => IndexedTraversal i s s a b -> (i -> a -> b) -> m b

# Lateral Composition

choosing :: Functor f => LensLike f s t a b -> LensLike f s' t' a b -> LensLike f (Either s s') (Either t t') a b

Merge two lenses, getters, setters, folds or traversals.

     chosen ≡ choosing id id

     choosing :: Getter s a     -> Getter s' a     -> Getter (Either s s') a
     choosing :: Fold s a       -> Fold s' a       -> Fold (Either s s') a
     choosing :: Lens' s a      -> Lens' s' a      -> Lens' (Either s s') a
     choosing :: Traversal' s a -> Traversal' s' a -> Traversal' (Either s s') a
     choosing :: Setter' s a    -> Setter' s' a    -> Setter' (Either s s') a

chosen :: IndexPreservingLens (Either a a) (Either b b) a b

This is a `Lens` that updates either side of an `Either`, where both sides have the same type.

     chosen ≡ choosing id id

    >>> Left a^.chosen
    a

    >>> Right a^.chosen
    a

    >>> Right "hello"^.chosen
    "hello"

    >>> Right a & chosen *~ b
    Right (a * b)

     chosen :: Lens (Either a a) (Either b b) a b
     chosen f (Left a)  = Left <$> f a
     chosen f (Right a) = Right <$> f a

alongside :: ALens s t a b -> ALens s' t' a' b' -> Lens (s, s') (t, t') (a, a') (b, b')

`alongside` makes a `Lens` from two other lenses.

    >>> (Left a, Right b)^.alongside chosen chosen
    (a,b)

    >>> (Left a, Right b) & alongside chosen chosen .~ (c,d)
    (Left c,Right d)

     alongside :: Lens s t a b -> Lens s' t' a' b' -> Lens (s,s') (t,t') (a,a') (b,b')

inside :: ALens s t a b -> Lens (e -> s) (e -> t) (e -> a) (e -> b)

Lift a `Lens` so it can run under a function.

# Setting Functionally with Passthrough

(<%~) :: Profunctor p => Overloading p q ((,) b) s t a b -> p a b -> q s (b, t)

Modify the target of a `Lens` and return the result.

When you do not need the result of the addition, (`%~`) is more flexible.

     (<%~) ::             Lens s t a b      -> (a -> b) -> s -> (b, t)
     (<%~) ::             Iso s t a b       -> (a -> b) -> s -> (b, t)
     (<%~) :: Monoid b => Traversal s t a b -> (a -> b) -> s -> (b, t)

(<+~) :: Num a => Overloading (->) q ((,) a) s t a a -> a -> q s (a, t)

Increment the target of a numerically valued `Lens` and return the result.

When you do not need the result of the addition, (`+~`) is more flexible.

     (<+~) :: Num a => Lens' s a -> a -> s -> (a, s)
     (<+~) :: Num a => Iso' s a  -> a -> s -> (a, s)

(<-~) :: Num a => Overloading (->) q ((,) a) s t a a -> a -> q s (a, t)

Decrement the target of a numerically valued `Lens` and return the result.

When you do not need the result of the subtraction, (`-~`) is more flexible.

     (<-~) :: Num a => Lens' s a -> a -> s -> (a, s)
     (<-~) :: Num a => Iso' s a  -> a -> s -> (a, s)

(<*~) :: Num a => Overloading (->) q ((,) a) s t a a -> a -> q s (a, t)

Multiply the target of a numerically valued `Lens` and return the result.

When you do not need the result of the multiplication, (`*~`) is more flexible.

     (<*~) :: Num b => Lens' s a -> a -> a -> (s, a)
     (<*~) :: Num b => Iso'  s a -> a -> a -> (s, a)

(<//~) :: Fractional a => Overloading (->) q ((,) a) s t a a -> a -> q s (a, t)

Divide the target of a fractionally valued `Lens` and return the result.

When you do not need the result of the division, (`//~`) is more flexible.

     (<//~) :: Fractional b => Lens' s a -> a -> a -> (s, a)
     (<//~) :: Fractional b => Iso'  s a -> a -> a -> (s, a)

(<^~) :: (Num a, Integral e) => Overloading (->) q ((,) a) s t a a -> e -> q s (a, t)

Raise the target of a numerically valued `Lens` to a non-negative `Integral` power and return the result.

When you do not need the result of the division, (`^~`) is more flexible.

     (<^~) :: (Num b, Integral e) => Lens' s a -> e -> a -> (a, s)
     (<^~) :: (Num b, Integral e) => Iso' s a -> e -> a -> (a, s)

(<^^~) :: (Fractional a, Integral e) => Overloading (->) q ((,) a) s t a a -> e -> q s (a, t)

Raise the target of a fractionally valued `Lens` to an `Integral` power and return the result.

When you do not need the result of the division, (`^^~`) is more flexible.

     (<^^~) :: (Fractional b, Integral e) => Lens' s a -> e -> a -> (a, s)
     (<^^~) :: (Fractional b, Integral e) => Iso' s a -> e -> a -> (a, s)

(<**~) :: Floating a => Overloading (->) q ((,) a) s t a a -> a -> q s (a, t)

Raise the target of a floating-point valued `Lens` to an arbitrary power and return the result.

When you do not need the result of the division, (`**~`) is more flexible.

     (<**~) :: Floating a => Lens' s a -> a -> s -> (a, s)
     (<**~) :: Floating a => Iso' s a  -> a -> s -> (a, s)

(<||~) :: Overloading (->) q ((,) Bool) s t Bool Bool -> Bool -> q s (Bool, t)

Logically `||` a Boolean valued `Lens` and return the result.

When you do not need the result of the operation, (`||~`) is more flexible.

     (<||~) :: Lens' s Bool -> Bool -> s -> (Bool, s)
     (<||~) :: Iso' s Bool  -> Bool -> s -> (Bool, s)

(<&&~) :: Overloading (->) q ((,) Bool) s t Bool Bool -> Bool -> q s (Bool, t)

Logically `&&` a Boolean valued `Lens` and return the result.

When you do not need the result of the operation, (`&&~`) is more flexible.

     (<&&~) :: Lens' s Bool -> Bool -> s -> (Bool, s)
     (<&&~) :: Iso' s Bool  -> Bool -> s -> (Bool, s)

(<<>~) :: Monoid m => Overloading (->) q ((,) m) s t m m -> m -> q s (m, t)

`mappend` a monoidal value onto the end of the target of a `Lens` and return the result.

When you do not need the result of the operation, (`<>~`) is more flexible.

(<<%~) :: Strong p => Overloading p q ((,) a) s t a b -> p a b -> q s (a, t)

Modify the target of a `Lens`, but return the old value.

When you do not need the result of the addition, (`%~`) is more flexible.

     (<<%~) ::             Lens s t a b      -> (a -> b) -> s -> (b, t)
     (<<%~) ::             Iso s t a b       -> (a -> b) -> s -> (b, t)
     (<<%~) :: Monoid b => Traversal s t a b -> (a -> b) -> s -> (b, t)

(<<.~) :: Overloading (->) q ((,) a) s t a b -> b -> q s (a, t)

Modify the target of a `Lens`, but return the old value.

When you do not need the old value, (`%~`) is more flexible.

     (<<%~) ::             Lens s t a b      -> b -> s -> (a, t)
     (<<%~) ::             Iso s t a b       -> b -> s -> (a, t)
     (<<%~) :: Monoid b => Traversal s t a b -> b -> s -> (a, t)

# Setting State with Passthrough

(<%=) :: (Profunctor p, MonadState s m) => Overloading p (->) ((,) b) s s a b -> p a b -> m b

Modify the target of a `Lens` into your 'Monad'\'s state by a user supplied function and return the result.

When applied to a `Traversal`, it this will return a monoidal summary of all of the intermediate results.

When you do not need the result of the operation, (`%=`) is more flexible.

     (<%=) :: MonadState s m             => Lens' s a      -> (a -> a) -> m a
     (<%=) :: MonadState s m             => Iso' s a       -> (a -> a) -> m a
     (<%=) :: (MonadState s m, Monoid a) => Traversal' s a -> (a -> a) -> m a

(<+=) :: (MonadState s m, Num a) => LensLike' ((,) a) s a -> a -> m a

Add to the target of a numerically valued `Lens` into your 'Monad'\'s state and return the result.

When you do not need the result of the addition, (`+=`) is more flexible.

     (<+=) :: (MonadState s m, Num a) => Lens' s a -> a -> m a
     (<+=) :: (MonadState s m, Num a) => Iso' s a -> a -> m a

(<-=) :: (MonadState s m, Num a) => LensLike' ((,) a) s a -> a -> m a

Subtract from the target of a numerically valued `Lens` into your 'Monad'\'s state and return the result.

When you do not need the result of the subtraction, (`-=`) is more flexible.

     (<-=) :: (MonadState s m, Num a) => Lens' s a -> a -> m a
     (<-=) :: (MonadState s m, Num a) => Iso' s a -> a -> m a

(<*=) :: (MonadState s m, Num a) => LensLike' ((,) a) s a -> a -> m a

Multiply the target of a numerically valued `Lens` into your 'Monad'\'s state and return the result.

When you do not need the result of the multiplication, (`*=`) is more flexible.

     (<*=) :: (MonadState s m, Num a) => Lens' s a -> a -> m a
     (<*=) :: (MonadState s m, Num a) => Iso' s a -> a -> m a

(<//=) :: (MonadState s m, Fractional a) => LensLike' ((,) a) s a -> a -> m a

Divide the target of a fractionally valued `Lens` into your 'Monad'\'s state and return the result.

When you do not need the result of the division, (`//=`) is more flexible.

     (<//=) :: (MonadState s m, Fractional a) => Lens' s a -> a -> m a
     (<//=) :: (MonadState s m, Fractional a) => Iso' s a -> a -> m a

(<^=) :: (MonadState s m, Num a, Integral e) => LensLike' ((,) a) s a -> e -> m a

Raise the target of a numerically valued `Lens` into your 'Monad'\'s state to a non-negative `Integral` power and return the result.

When you do not need the result of the operation, (`**=`) is more flexible.

     (<^=) :: (MonadState s m, Num a, Integral e) => Lens' s a -> e -> m a
     (<^=) :: (MonadState s m, Num a, Integral e) => Iso' s a -> e -> m a

(<^^=) :: (MonadState s m, Fractional a, Integral e) => LensLike' ((,) a) s a -> e -> m a

Raise the target of a fractionally valued `Lens` into your 'Monad'\'s state to an `Integral` power and return the result.

When you do not need the result of the operation, (`^^=`) is more flexible.

     (<^^=) :: (MonadState s m, Fractional b, Integral e) => Lens' s a -> e -> m a
     (<^^=) :: (MonadState s m, Fractional b, Integral e) => Iso' s a  -> e -> m a

(<**=) :: (MonadState s m, Floating a) => LensLike' ((,) a) s a -> a -> m a

Raise the target of a floating-point valued `Lens` into your 'Monad'\'s state to an arbitrary power and return the result.

When you do not need the result of the operation, (`**=`) is more flexible.

     (<**=) :: (MonadState s m, Floating a) => Lens' s a -> a -> m a
     (<**=) :: (MonadState s m, Floating a) => Iso' s a -> a -> m a

(<||=) :: MonadState s m => LensLike' ((,) Bool) s Bool -> Bool -> m Bool

Logically `||` a Boolean valued `Lens` into your 'Monad'\'s state and return the result.

When you do not need the result of the operation, (`||=`) is more flexible.

     (<||=) :: MonadState s m => Lens' s Bool -> Bool -> m Bool
     (<||=) :: MonadState s m => Iso' s Bool  -> Bool -> m Bool

(<&&=) :: MonadState s m => LensLike' ((,) Bool) s Bool -> Bool -> m Bool

Logically `&&` a Boolean valued `Lens` into your 'Monad'\'s state and return the result.

When you do not need the result of the operation, (`&&=`) is more flexible.

     (<&&=) :: MonadState s m => Lens' s Bool -> Bool -> m Bool
     (<&&=) :: MonadState s m => Iso' s Bool  -> Bool -> m Bool

(<<>=) :: (MonadState s m, Monoid r) => LensLike' ((,) r) s r -> r -> m r

`mappend` a monoidal value onto the end of the target of a `Lens` into your 'Monad'\'s state and return the result.

When you do not need the result of the operation, (`<>=`) is more flexible.

(<<%=) :: (Strong p, MonadState s m) => Overloading p (->) ((,) a) s s a b -> p a b -> m a

Modify the target of a `Lens` into your 'Monad'\'s state by a user supplied function and return the old value that was replaced.

When applied to a `Traversal`, it this will return a monoidal summary of all of the old values present.

When you do not need the result of the operation, (`%=`) is more flexible.

     (<<%=) :: MonadState s m             => Lens' s a      -> (a -> a) -> m a
     (<<%=) :: MonadState s m             => Iso' s a       -> (a -> a) -> m a
     (<<%=) :: (MonadState s m, Monoid b) => Traversal' s a -> (a -> a) -> m a

    (<<%=) :: MonadState s m => LensLike ((,)a) s s a b -> (a -> b) -> m a

(<<.=) :: MonadState s m => LensLike ((,) a) s s a b -> b -> m a

Modify the target of a `Lens` into your 'Monad'\'s state by a user supplied function and return the old value that was replaced.

When applied to a `Traversal`, it this will return a monoidal summary of all of the old values present.

When you do not need the result of the operation, (`%=`) is more flexible.

     (<<%=) :: MonadState s m             => Lens' s a      -> (a -> a) -> m a
     (<<%=) :: MonadState s m             => Iso' s a       -> (a -> a) -> m a
     (<<%=) :: (MonadState s m, Monoid t) => Traversal' s a -> (a -> a) -> m a

(<<~) :: MonadState s m => ALens s s a b -> m b -> m b

Run a monadic action, and set the target of `Lens` to its result.

     (<<~) :: MonadState s m => Iso s s a b   -> m b -> m b
     (<<~) :: MonadState s m => Lens s s a b  -> m b -> m b

NB: This is limited to taking an actual `Lens` than admitting a `Traversal` because there are potential loss of state issues otherwise.

# Cloning Lenses

cloneLens :: ALens s t a b -> Lens s t a b

Cloning a `Lens` is one way to make sure you aren't given something weaker, such as a `Traversal` and can be used as a way to pass around lenses that have to be monomorphic in `f`.

Note: This only accepts a proper `Lens`.

    >>> let example l x = set (cloneLens l) (x^.cloneLens l + 1) x in example _2 ("hello",1,"you")
    ("hello",2,"you")

cloneIndexPreservingLens :: ALens s t a b -> IndexPreservingLens s t a b

Clone a `Lens` as an `IndexedPreservingLens` that just passes through whatever index is on any `IndexedLens`, `IndexedFold`, `IndexedGetter` or `IndexedTraversal` it is composed with.

cloneIndexedLens :: AnIndexedLens i s t a b -> IndexedLens i s t a b

Clone an `IndexedLens` as an `IndexedLens` with the same index.

# ALens Combinators

storing :: ALens s t a b -> b -> s -> t

A version of `set` that works on `ALens`.

    >>> storing _2 "world" ("hello","there")
    ("hello","world")

(^#) :: s -> ALens s t a b -> a

A version of (`^.`) that works on `ALens`.

    >>> ("hello","world")^#_2
    "world"

(#~) :: ALens s t a b -> b -> s -> t

A version of (`.~`) that works on `ALens`.

    >>> ("hello","there") & _2 #~ "world"
    ("hello","world")

(#%~) :: ALens s t a b -> (a -> b) -> s -> t

A version of (`%~`) that works on `ALens`.

    >>> ("hello","world") & _2 #%~ length
    ("hello",5)

(#%%~) :: Functor f => ALens s t a b -> (a -> f b) -> s -> f t

A version of (`%%~`) that works on `ALens`.

    >>> ("hello","world") & _2 #%%~ \x -> (length x, x ++ "!")
    (5,("hello","world!"))

(<#~) :: ALens s t a b -> b -> s -> (b, t)

A version of (`<.~`) that works on `ALens`.

    >>> ("hello","there") & _2 <#~ "world"
    ("world",("hello","world"))

(<#%~) :: ALens s t a b -> (a -> b) -> s -> (b, t)

A version of (`<%~`) that works on `ALens`.

    >>> ("hello","world") & _2 <#%~ length
    (5,("hello",5))

(#=) :: MonadState s m => ALens s s a b -> b -> m ()

A version of (`.=`) that works on `ALens`.

(#%=) :: MonadState s m => ALens s s a b -> (a -> b) -> m ()

A version of (`%=`) that works on `ALens`.

(#%%=) :: MonadState s m => ALens s s a b -> (a -> (r, b)) -> m r

A version of (`%%=`) that works on `ALens`.

(<#=) :: MonadState s m => ALens s s a b -> b -> m b

A version of (`<#=`) that works on `ALens`.

(<#%=) :: MonadState s m => ALens s s a b -> (a -> b) -> m b

A version of (`<%=`) that works on `ALens`.

# Common Lenses

devoid :: Over p f Void Void a b

There is a field for every type in the `Void`. Very zen.

    >>> [] & mapped.devoid +~ 1
    []

Nothing & mapped.devoid %~ abs Nothing

     devoid :: Lens' Void a

united :: Lens' a ()

We can always retrieve a `()` from any type.

    >>> "hello"^.united
    ()

    >>> "hello" & united .~ ()
    "hello"

# Context

data Context a b t

The indexed store can be used to characterize a `Lens` and is used by `clone`.

``Context` a b t` is isomorphic to `newtype `Context` a b t = `Context` { runContext :: forall f. `Functor` f => (a -> f b) -> f t }`, and to `exists s. (s, `Lens` s t a b)`.

A `Context` is like a `Lens` that has already been applied to a some structure.

Constructors

Context (b -> t) a |

Instances

IndexedComonadStore Context |
IndexedComonad Context |
IndexedFunctor Context |
Sellable (->) Context |
~ * a b => ComonadStore a (Context a b) |
Functor (Context a b) |
~ * a b => Comonad (Context a b) |

type Context' a = Context a a

    type Context' a s = Context a a s

locus :: IndexedComonadStore p => Lens (p a c s) (p b c s) a b

This `Lens` lets you `view` the current `pos` of any indexed store comonad and `seek` to a new position. This reduces the API for working these instances to a single `Lens`.

     ipos w ≡ w ^. locus
     iseek s w ≡ w & locus .~ s
     iseeks f w ≡ w & locus %~ f

     locus :: Lens' (Context' a s) a
     locus :: Lens' (Pretext' p a s) a
     locus :: Lens' (PretextT' p g a s) a