lens-5.3.3: Lenses, Folds and Traversals

Copyright | (C) 2012-16 Edward Kmett
License | BSD-style (see the file LICENSE)
Maintainer | Edward Kmett <ekmett@gmail.com>
Stability | provisional
Portability | Rank2Types
Safe Haskell | Trustworthy
Language | Haskell2010

Control.Lens.Lens

Contents

- Lenses
  - Concrete Lenses
- Combinators
  - General Purpose Combinators
- Lateral Composition
- Setting Functionally with Passthrough
- Setting State with Passthrough
- Cloning Lenses
- Arrow operators
- ALens Combinators
- Common Lenses
- Context
- Lens fusion

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 a `Getter` can't require an `Applicative` constraint.

`Functor`, however, is a constraint on 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 `Contravariant`.

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 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 :: Type -> Type). 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 :: Type -> Type) (p :: Type -> Type -> Type). (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 = Optical (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 :: (s -> a) -> (s -> b -> t) -> IndexPreservingLens s t a b
- withLens :: ALens s t a b -> ((s -> a) -> (s -> b -> t) -> r) -> r
- (%%~) :: forall {k} f s (t :: k) a (b :: k). LensLike f s t a b -> (a -> f b) -> s -> f t
- (%%=) :: forall {k} s m p r (a :: k) b. MonadState s m => Over p ((,) r) s s a b -> p a (r, b) -> m r
- (%%@~) :: forall {k1} i f s (t :: k1) a (b :: k1). Over (Indexed i) f s t a b -> (i -> a -> f b) -> s -> f t
- (%%@=) :: MonadState s m => Over (Indexed i) ((,) r) s s a b -> (i -> a -> (r, b)) -> m r
- (<%@~) :: Over (Indexed i) ((,) b) s t a b -> (i -> a -> b) -> s -> (b, t)
- (<%@=) :: MonadState s m => Over (Indexed i) ((,) b) s s a b -> (i -> a -> b) -> m b
- (<<%@~) :: Over (Indexed i) ((,) a) s t a b -> (i -> a -> b) -> s -> (a, t)
- (<<%@=) :: MonadState s m => Over (Indexed i) ((,) a) s s a b -> (i -> a -> b) -> m a
- (&) :: a -> (a -> b) -> b
- (<&>) :: Functor f => f a -> (a -> b) -> f b
- (??) :: Functor f => f (a -> b) -> a -> f b
- (&~) :: s -> State s a -> s
- 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 :: forall a b p f. (Conjoined p, Functor f) => p a (f b) -> p (Either a a) (f (Either b b))
- alongside :: LensLike (AlongsideLeft f b') s t a b -> LensLike (AlongsideRight f t) s' t' a' b' -> LensLike f (s, s') (t, t') (a, a') (b, b')
- inside :: forall (p :: Type -> Type -> Type) s t a b e. Corepresentable p => ALens s t a b -> Lens (p e s) (p e t) (p e a) (p e b)
- (<%~) :: LensLike ((,) b) s t a b -> (a -> b) -> s -> (b, t)
- (<+~) :: Num a => LensLike ((,) a) s t a a -> a -> s -> (a, t)
- (<-~) :: Num a => LensLike ((,) a) s t a a -> a -> s -> (a, t)
- (<*~) :: Num a => LensLike ((,) a) s t a a -> a -> s -> (a, t)
- (<//~) :: Fractional a => LensLike ((,) a) s t a a -> a -> s -> (a, t)
- (<^~) :: (Num a, Integral e) => LensLike ((,) a) s t a a -> e -> s -> (a, t)
- (<^^~) :: (Fractional a, Integral e) => LensLike ((,) a) s t a a -> e -> s -> (a, t)
- (<**~) :: Floating a => LensLike ((,) a) s t a a -> a -> s -> (a, t)
- (<||~) :: LensLike ((,) Bool) s t Bool Bool -> Bool -> s -> (Bool, t)
- (<&&~) :: LensLike ((,) Bool) s t Bool Bool -> Bool -> s -> (Bool, t)
- (<<>~) :: Semigroup m => LensLike ((,) m) s t m m -> m -> s -> (m, t)
- (<<>:~) :: Semigroup m => LensLike ((,) m) s t m m -> m -> s -> (m, t)
- (<<%~) :: LensLike ((,) a) s t a b -> (a -> b) -> s -> (a, t)
- (<<.~) :: LensLike ((,) a) s t a b -> b -> s -> (a, t)
- (<<?~) :: LensLike ((,) a) s t a (Maybe b) -> b -> s -> (a, t)
- (<<+~) :: Num a => LensLike' ((,) a) s a -> a -> s -> (a, s)
- (<<-~) :: Num a => LensLike' ((,) a) s a -> a -> s -> (a, s)
- (<<*~) :: Num a => LensLike' ((,) a) s a -> a -> s -> (a, s)
- (<<//~) :: Fractional a => LensLike' ((,) a) s a -> a -> s -> (a, s)
- (<<^~) :: (Num a, Integral e) => LensLike' ((,) a) s a -> e -> s -> (a, s)
- (<<^^~) :: (Fractional a, Integral e) => LensLike' ((,) a) s a -> e -> s -> (a, s)
- (<<**~) :: Floating a => LensLike' ((,) a) s a -> a -> s -> (a, s)
- (<<||~) :: LensLike' ((,) Bool) s Bool -> Bool -> s -> (Bool, s)
- (<<&&~) :: LensLike' ((,) Bool) s Bool -> Bool -> s -> (Bool, s)
- (<<<>~) :: Semigroup r => LensLike' ((,) r) s r -> r -> s -> (r, s)
- (<<<>:~) :: Semigroup m => LensLike' ((,) m) s m -> m -> s -> (m, s)
- (<%=) :: MonadState s m => LensLike ((,) b) s s a b -> (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, Semigroup r) => LensLike' ((,) r) s r -> r -> m r
- (<<>:=) :: (MonadState s m, Semigroup r) => LensLike' ((,) r) s r -> r -> m r
- (<<%=) :: (Strong p, MonadState s m) => Over 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 => LensLike ((,) a) s s a (Maybe b) -> b -> 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, 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, Semigroup r) => LensLike' ((,) r) s r -> r -> m r
- (<<<>:=) :: (MonadState s m, Semigroup r) => LensLike' ((,) r) s r -> r -> m r
- (<<~) :: 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
- overA :: Arrow ar => LensLike (Context a b) s t a b -> ar a b -> ar s t
- 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 :: forall {k} p f (a :: k) b. Over p f Void Void a b
- united :: forall a f. Functor f => (() -> f ()) -> a -> f a
- head1 :: forall (t :: Type -> Type) a. Traversable1 t => Lens' (t a) a
- last1 :: forall (t :: Type -> Type) a. Traversable1 t => Lens' (t a) a
- data Context a b t = Context (b -> t) a
- type Context' a = Context a a
- locus :: forall (p :: Type -> Type -> Type -> Type) a c s b. IndexedComonadStore p => Lens (p a c s) (p b c s) a b
- fusing :: Functor f => LensLike (Yoneda f) s t a b -> LensLike f s t a b

# Lenses

type Lens s t a b = forall (f :: Type -> Type). 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 v s)  ≡ v

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

    set l (view l s) s  ≡ s

3) Setting twice is the same as setting once:

    set l v' (set l v s) ≡ set l v' s

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/.

There are some emergent properties of these laws:

1) ``set` l s` must be injective for every `s` This is a consequence of law #1

2) ``set` l` must be surjective, because of law #2, which indicates that it is possible to obtain any `v` from some `s` such that ``set` s v = s`

3) Given just the first two laws you can prove a weaker form of law #3 where the values `v` that you are setting match:

    set l v (set l v s) ≡ set l v s

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 :: Type -> Type) (p :: Type -> Type -> Type). (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 = Optical (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))

    lens :: (s -> a) -> (s -> a -> s) -> Lens' s a

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

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

iplens :: (s -> a) -> (s -> b -> t) -> IndexPreservingLens s t a b #

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

withLens :: ALens s t a b -> ((s -> a) -> (s -> b -> t) -> r) -> r #

Obtain a getter and a setter from a lens, reversing `lens`.

(%%~) :: forall {k} f s (t :: k) a (b :: k). LensLike f s t a b -> (a -> f b) -> s -> f t infixr 4 #

(`%%~`) 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.

    >>> [66,97,116,109,97,110] & each %%~ \a -> ("na", chr a)
    ("nananananana","Batman")

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)

(%%=) :: forall {k} s m p r (a :: k) b. MonadState s m => Over p ((,) r) s s a b -> p a (r, b) -> m r infix 4 #

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

(%%@~) :: forall {k1} i f s (t :: k1) a (b :: k1). Over (Indexed i) f s t a b -> (i -> a -> f b) -> s -> f t infixr 4 #

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
    (%%@~) :: Applicative 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 => Over (Indexed i) ((,) r) s s a b -> (i -> a -> (r, b)) -> m r infix 4 #

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

(<%@~) :: Over (Indexed i) ((,) b) s t a b -> (i -> a -> b) -> s -> (b, t) infixr 4 #

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 => Over (Indexed i) ((,) b) s s a b -> (i -> a -> b) -> m b infix 4 #

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

(<<%@~) :: Over (Indexed i) ((,) a) s t a b -> (i -> a -> b) -> s -> (a, t) infixr 4 #

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

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

(<<%@=) :: MonadState s m => Over (Indexed i) ((,) a) s s a b -> (i -> a -> b) -> m a infix 4 #

Adjust the target of an `IndexedLens` returning the old value, or adjust all of the targets of an `IndexedTraversal` within the current state, and return a monoidal summary of the old values.

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

## General Purpose Combinators

(&) :: a -> (a -> b) -> b infixl 1 #

`&` is a reverse application operator. This provides notational convenience. Its precedence is one higher than that of the forward application operator `$`, which allows `&` to be nested in `$`.

This is a version of ``flip` `id``, where `id` is specialized from `a -> a` to `(a -> b) -> (a -> b)` which by the associativity of `(->)` is `(a -> b) -> a -> b`. flipping this yields `a -> (a -> b) -> b` which is the type signature of `&`

#### Examples

Expand

    >>> 5 & (+1) & show
    "6"

    >>> sqrt $ [1 / n^2 | n <- [1..1000]] & sum & (*6)
    3.1406380562059946

@since base-4.8.0.0

(<&>) :: Functor f => f a -> (a -> b) -> f b infixl 1 #

Flipped version of `<$>`.

    (<&>) = flip fmap

@since base-4.11.0.0

#### Examples

Expand

Apply `(+1)` to a list, a `Just` and a `Right`:

    >>> Just 2 <&> (+1)
    Just 3

    >>> [1,2,3] <&> (+1)
    [2,3,4]

    >>> Right 3 <&> (+1)
    Right 4

(??) :: Functor f => f (a -> b) -> a -> f b infixl 1 #

This is convenient to `flip` argument order of composite functions defined as:

    fab ?? a = fmap ($ a) fab

For the `Functor` instance `f = ((->) r)` you can reason about this function as if the definition was `(`??`) ≡ `flip``:

    >>> (h ?? x) a
    h a x

    >>> execState ?? [] $ modify (1:)
    [1]

    >>> over _2 ?? ("hello","world") $ length
    ("hello",5)

    >>> over ?? length ?? ("hello","world") $ _2
    ("hello",5)

(&~) :: s -> State s a -> s infixl 1 #

This can be used to chain lens operations using `op=` syntax rather than `op~` syntax for simple non-type-changing cases.

    >>> (10,20) & _1 .~ 30 & _2 .~ 40
    (30,40)

    >>> (10,20) &~ do _1 .= 30; _2 .= 40
    (30,40)

This does not support type-changing assignment, e.g.

    >>> (10,20) & _1 .~ "hello"
    ("hello",20)

# 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 :: forall a b p f. (Conjoined p, Functor f) => p a (f b) -> p (Either a a) (f (Either b 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 :: LensLike (AlongsideLeft f b') s t a b -> LensLike (AlongsideRight f t) s' t' a' b' -> LensLike f (s, s') (t, t') (a, a') (b, b') #

`alongside` makes a `Lens` from two other lenses or a `Getter` from two other getters by executing them on their respective halves of a product.

    >>> (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')
    alongside :: Getter s   a   -> Getter s'    a'    -> Getter (s,s')        (a,a')

inside :: forall (p :: Type -> Type -> Type) s t a b e. Corepresentable p => ALens s t a b -> Lens (p e s) (p e t) (p e a) (p e b) #

Lift a `Lens` so it can run under a function (or other corepresentable profunctor).

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

    >>> (\x -> (x-1,x+1)) ^. inside _1 $ 5
    4

    >>> runState (modify (1:) >> modify (2:)) ^. (inside _2) $ []
    [2,1]

# Setting Functionally with Passthrough

(<%~) :: LensLike ((,) b) s t a b -> (a -> b) -> s -> (b, t) infixr 4 #

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

When you do not need the result of the operation, (`%~`) 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 => LensLike ((,) a) s t a a -> a -> s -> (a, t) infixr 4 #

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 => LensLike ((,) a) s t a a -> a -> s -> (a, t) infixr 4 #

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 => LensLike ((,) a) s t a a -> a -> s -> (a, t) infixr 4 #

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 a => Lens' s a -> a -> s -> (a, s)
    (<*~) :: Num a => Iso'  s a -> a -> s -> (a, s)

(<//~) :: Fractional a => LensLike ((,) a) s t a a -> a -> s -> (a, t) infixr 4 #

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 a => Lens' s a -> a -> s -> (a, s)
    (<//~) :: Fractional a => Iso'  s a -> a -> s -> (a, s)

(<^~) :: (Num a, Integral e) => LensLike ((,) a) s t a a -> e -> s -> (a, t) infixr 4 #

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 operation, (`^~`) is more flexible.

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

(<^^~) :: (Fractional a, Integral e) => LensLike ((,) a) s t a a -> e -> s -> (a, t) infixr 4 #

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 operation, (`^^~`) is more flexible.

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

(<**~) :: Floating a => LensLike ((,) a) s t a a -> a -> s -> (a, t) infixr 4 #

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 operation, (`**~`) is more flexible.

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

(<||~) :: LensLike ((,) Bool) s t Bool Bool -> Bool -> s -> (Bool, t) infixr 4 #

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)

(<&&~) :: LensLike ((,) Bool) s t Bool Bool -> Bool -> s -> (Bool, t) infixr 4 #

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)

(<<>~) :: Semigroup m => LensLike ((,) m) s t m m -> m -> s -> (m, t) infixr 4 #

(`<>`) a `Semigroup` 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.

(<<>:~) :: Semigroup m => LensLike ((,) m) s t m m -> m -> s -> (m, t) infixr 4 #

(`<>`) a `Semigroup` value onto the front of the target of a `Lens` and return the result. However, unlike (`<<>~`), it is prepended to the head side.

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

(<<%~) :: LensLike ((,) a) s t a b -> (a -> b) -> s -> (a, t) infixr 4 #

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      -> (a -> b) -> s -> (a, t)
    (<<%~) ::             Iso s t a b       -> (a -> b) -> s -> (a, t)
    (<<%~) :: Monoid a => Traversal s t a b -> (a -> b) -> s -> (a, t)

(<<.~) :: LensLike ((,) a) s t a b -> b -> s -> (a, t) infixr 4 #

Replace 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 a => Traversal s t a b -> b -> s -> (a, t)

(<<?~) :: LensLike ((,) a) s t a (Maybe b) -> b -> s -> (a, t) infixr 4 #

Replace the target of a `Lens` with a `Just` value, but return the old value.

If you do not need the old value (`?~`) is more flexible.

    >>> import qualified Data.Map as Map
    >>> _2.at "hello" <<?~ "world" $ (42,Map.fromList [("goodnight","gracie")])
    (Nothing,(42,fromList [("goodnight","gracie"),("hello","world")]))

    (<<?~) :: Iso s t a (Maybe b)       -> b -> s -> (a, t)
    (<<?~) :: Lens s t a (Maybe b)      -> b -> s -> (a, t)
    (<<?~) :: Traversal s t a (Maybe b) -> b -> s -> (a, t)

(<<+~) :: Num a => LensLike' ((,) a) s a -> a -> s -> (a, s) infixr 4 #

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

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

    >>> (a,b) & _1 <<+~ c
    (a,(a + c,b))

    >>> (a,b) & _2 <<+~ c
    (b,(a,b + c))

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

(<<-~) :: Num a => LensLike' ((,) a) s a -> a -> s -> (a, s) infixr 4 #

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

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

    >>> (a,b) & _1 <<-~ c
    (a,(a - c,b))

    >>> (a,b) & _2 <<-~ c
    (b,(a,b - c))

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

(<<*~) :: Num a => LensLike' ((,) a) s a -> a -> s -> (a, s) infixr 4 #

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

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

    >>> (a,b) & _1 <<*~ c
    (a,(a * c,b))

    >>> (a,b) & _2 <<*~ c
    (b,(a,b * c))

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

(<<//~) :: Fractional a => LensLike' ((,) a) s a -> a -> s -> (a, s) infixr 4 #

Divide the target of a numerically valued `Lens` and return the old value.

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

    >>> (a,b) & _1 <<//~ c
    (a,(a / c,b))

    >>> ("Hawaii",10) & _2 <<//~ 2
    (10.0,("Hawaii",5.0))

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

(<<^~) :: (Num a, Integral e) => LensLike' ((,) a) s a -> e -> s -> (a, s) infixr 4 #

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

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

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

(<<^^~) :: (Fractional a, Integral e) => LensLike' ((,) a) s a -> e -> s -> (a, s) infixr 4 #

Raise the target of a fractionally valued `Lens` to an integral power and return the old value.

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

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

(<<**~) :: Floating a => LensLike' ((,) a) s a -> a -> s -> (a, s) infixr 4 #

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

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

    >>> (a,b) & _1 <<**~ c
    (a,(a**c,b))

    >>> (a,b) & _2 <<**~ c
    (b,(a,b**c))

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

(<<||~) :: LensLike' ((,) Bool) s Bool -> Bool -> s -> (Bool, s) infixr 4 #

Logically `||` the target of a `Bool`-valued `Lens` and return the old value.

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

    >>> (False,6) & _1 <<||~ True
    (False,(True,6))

    >>> ("hello",True) & _2 <<||~ False
    (True,("hello",True))

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

(<<&&~) :: LensLike' ((,) Bool) s Bool -> Bool -> s -> (Bool, s) infixr 4 #

Logically `&&` the target of a `Bool`-valued `Lens` and return the old value.

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

    >>> (False,6) & _1 <<&&~ True
    (False,(False,6))

    >>> ("hello",True) & _2 <<&&~ False
    (True,("hello",False))

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

(<<<>~) :: Semigroup r => LensLike' ((,) r) s r -> r -> s -> (r, s) infixr 4 #

Modify the target of a monoidally valued `Lens` by using (`<>`) a new value and return the old value.

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

    >>> (Sum a,b) & _1 <<<>~ Sum c
    (Sum {getSum = a},(Sum {getSum = a + c},b))

    >>> _2 <<<>~ ", 007" $ ("James", "Bond")
    ("Bond",("James","Bond, 007"))

    (<<<>~) :: Semigroup r => Lens' s r -> r -> s -> (r, s)
    (<<<>~) :: Semigroup r => Iso' s r -> r -> s -> (r, s)

(<<<>:~) :: Semigroup m => LensLike' ((,) m) s m -> m -> s -> (m, s) infixr 4 #

(`<>`) a `Semigroup` value onto the front of the target of a `Lens` and return the old result. However, unlike (`<<>~`), it is prepended to the head side.

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

# Setting State with Passthrough

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

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 infix 4 #

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 infix 4 #

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 infix 4 #

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 infix 4 #

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 infix 4 #

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 infix 4 #

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 infix 4 #

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 infix 4 #

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 infix 4 #

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, Semigroup r) => LensLike' ((,) r) s r -> r -> m r infix 4 #

(`<>`) a `Semigroup` 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.

(<<>:=) :: (MonadState s m, Semigroup r) => LensLike' ((,) r) s r -> r -> m r infix 4 #

(`<>`) a `Semigroup` value onto the front of the target of a `Lens` into your `Monad'`s state and return the result. However, unlike (`<<>=`), it is prepended to the head side.

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

(<<%=) :: (Strong p, MonadState s m) => Over p ((,) a) s s a b -> p a b -> m a infix 4 #

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`, 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 a) => 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 infix 4 #

Replace the target of a `Lens` into your `Monad'`s state with a user supplied value and return the old value that was replaced.

When applied to a `Traversal`, 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 -> m a
    (<<.=) :: MonadState s m             => Iso' s a       -> a -> m a
    (<<.=) :: (MonadState s m, Monoid a) => Traversal' s a -> a -> m a

(<<?=) :: MonadState s m => LensLike ((,) a) s s a (Maybe b) -> b -> m a infix 4 #

Replace the target of a `Lens` into your `Monad'`s state with `Just` a user supplied value and return the old value that was replaced.

When applied to a `Traversal`, 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 t a (Maybe b)      -> b -> m a
    (<<?=) :: MonadState s m             => Iso s t a (Maybe b)       -> b -> m a
    (<<?=) :: (MonadState s m, Monoid a) => Traversal s t a (Maybe b) -> b -> m a

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

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

When you do not need the result of the operation, (`+=`) 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 infix 4 #

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

When you do not need the result of the operation, (`-=`) 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 infix 4 #

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

When you do not need the result of the operation, (`*=`) 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 infix 4 #

Modify the target of a `Lens` into your `Monad`s state by dividing by a value and return the old value that was replaced.

When you do not need the result of the operation, (`//=`) 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 infix 4 #

Modify the target of a `Lens` into your `Monad'`s state by raising it by a non-negative power and return the old value that was replaced.

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 -> a -> m a

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

Modify the target of a `Lens` into your `Monad'`s state by raising it by an integral power and return the old value that was replaced.

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

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

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

Modify the target of a `Lens` into your `Monad'`s state by raising it by an arbitrary power and return the old value that was replaced.

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 infix 4 #

Modify the target of a `Lens` into your `Monad'`s state by taking its logical `||` with a value and return the old value that was replaced.

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 infix 4 #

Modify the target of a `Lens` into your `Monad'`s state by taking its logical `&&` with a value and return the old value that was replaced.

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, Semigroup r) => LensLike' ((,) r) s r -> r -> m r infix 4 #

Modify the target of a `Lens` into your `Monad'`s state by using (`<>`) and return the old value that was replaced.

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

    (<<<>=) :: (MonadState s m, Semigroup r) => Lens' s r -> r -> m r
    (<<<>=) :: (MonadState s m, Semigroup r) => Iso' s r -> r -> m r

(<<<>:=) :: (MonadState s m, Semigroup r) => LensLike' ((,) r) s r -> r -> m r infix 4 #

(`<>`) a `Semigroup` value onto the front of the target of a `Lens` into your `Monad'`s state and return the old result. However, unlike (`<<<>=`), it is prepended to the head side.

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

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

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.

# Arrow operators

overA :: Arrow ar => LensLike (Context a b) s t a b -> ar a b -> ar s t #

`over` for Arrows.

Unlike `over`, `overA` can't accept a simple `Setter`, but requires a full lens, or close enough.

    >>> overA _1 ((+1) *** (+2)) ((1,2),6)
    ((2,4),6)

    overA :: Arrow ar => Lens s t a b -> ar a b -> ar s t

# 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 infixl 8 #

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

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

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

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

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

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

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 infixr 4 #

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) infixr 4 #

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

# Common Lenses

devoid :: forall {k} p f (a :: k) b. 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 :: forall a f. Functor f => (() -> f ()) -> a -> f a #

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

    >>> "hello"^.united
    ()

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

head1 :: forall (t :: Type -> Type) a. Traversable1 t => Lens' (t a) a #

A `Lens` focusing on the first element of a `Traversable1` container.

    >>> 2 :| [3, 4] & head1 +~ 10
    12 :| [3,4]

    >>> Identity True ^. head1
    True

last1 :: forall (t :: Type -> Type) a. Traversable1 t => Lens' (t a) a #

A `Lens` focusing on the last element of a `Traversable1` container.

    >>> 2 :| [3, 4] & last1 +~ 10
    2 :| [3,14]

    >>> Node 'a' [Node 'b' [], Node 'c' []] ^. last1
    'c'

# Context

data Context a b t #

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

``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

Instances details

IndexedComonad Context # |
Instance details Defined in Control.Lens.Internal.Context Methods iextract :: Context a a t -> t # iduplicate :: Context a c t -> Context a b (Context b c t) # iextend :: (Context b c t -> r) -> Context a c t -> Context a b r #
IndexedComonadStore Context # |
Instance details Defined in Control.Lens.Internal.Context Methods ipos :: Context a c t -> a # ipeek :: c -> Context a c t -> t # ipeeks :: (a -> c) -> Context a c t -> t # iseek :: b -> Context a c t -> Context b c t # iseeks :: (a -> b) -> Context a c t -> Context b c t # iexperiment :: Functor f => (b -> f c) -> Context b c t -> f t # context :: Context a b t -> Context a b t #
IndexedFunctor Context # |
Instance details Defined in Control.Lens.Internal.Context Methods ifmap :: (s -> t) -> Context a b s -> Context a b t #
a ~ b => ComonadStore a (Context a b) # |
Instance details Defined in Control.Lens.Internal.Context Methods pos :: Context a b a0 -> a # peek :: a -> Context a b a0 -> a0 # peeks :: (a -> a) -> Context a b a0 -> a0 # seek :: a -> Context a b a0 -> Context a b a0 # seeks :: (a -> a) -> Context a b a0 -> Context a b a0 # experiment :: Functor f => (a -> f a) -> Context a b a0 -> f a0 #
a ~ b => Comonad (Context a b) # |
Instance details Defined in Control.Lens.Internal.Context Methods extract :: Context a b a0 -> a0 # duplicate :: Context a b a0 -> Context a b (Context a b a0) # extend :: (Context a b a0 -> b0) -> Context a b a0 -> Context a b b0 #
Functor (Context a b) # |
Instance details Defined in Control.Lens.Internal.Context Methods fmap :: (a0 -> b0) -> Context a b a0 -> Context a b b0 # (<$) :: a0 -> Context a b b0 -> Context a b a0 #
Sellable (->) Context # |
Instance details Defined in Control.Lens.Internal.Context Methods sell :: a -> Context a b b #

type Context' a = Context a a #

    type Context' a s = Context a a s

locus :: forall (p :: Type -> Type -> Type -> Type) a c s b. 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 :: Conjoined p => Lens' (Pretext' p a s) a
    locus :: Conjoined p => Lens' (PretextT' p g a s) a

# Lens fusion

fusing :: Functor f => LensLike (Yoneda f) s t a b -> LensLike f s t a b #

Fuse a composition of lenses using `Yoneda` to provide `fmap` fusion.

In general, given a pair of lenses `foo` and `bar`

    fusing (foo.bar) = foo.bar

however, `foo` and `bar` are either going to `fmap` internally or they are trivial.

`fusing` exploits the `Yoneda` lemma to merge these separate uses into a single `fmap`.

This is particularly effective when the choice of functor `f` is unknown at compile time or when the `Lens` `foo.bar` in the above description is recursive or complex enough to prevent inlining.

    fusing :: Lens s t a b -> Lens s t a b