lens-4.19.1: Lenses, Folds and Traversals

Control.Lens.Lens

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

# Lenses

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

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 purepure
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 Source #

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 Source #

Every IndexedLens is a valid Lens and a valid IndexedTraversal.

type IndexedLens' i s a = IndexedLens i s s a a Source #

## Concrete Lenses

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

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 Source #

type AnIndexedLens i s t a b = Optical (Indexed i) (->) (Pretext (Indexed i) a b) s t a b Source #

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

# Combinators

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

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 Source #

Build an IndexedLens from a Getter and a Setter.

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

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

withLens :: forall s t a b rep (r :: TYPE rep). ALens s t a b -> ((s -> a) -> (s -> b -> t) -> r) -> r Source #

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

(%%~) :: LensLike f s t a b -> (a -> f b) -> s -> f t infixr 4 Source #

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

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

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

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

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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

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

Since: base-4.8.0.0

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

Flipped version of <$>. (<&>) = flip fmap #### 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 Since: base-4.11.0.0 (??) :: Functor f => f (a -> b) -> a -> f b infixl 1 Source # 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 Source # 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 Source # Merge two lenses, getters, setters, folds or traversals. chosenchoosing 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 Source # This is a Lens that updates either side of an Either, where both sides have the same type. chosenchoosing 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') Source # 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 :: Corepresentable p => ALens s t a b -> Lens (p e s) (p e t) (p e a) (p e b) Source # 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 Source # 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 Source # 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 Source # 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 Source # 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 Source # 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 Source # 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 Source # 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 Source # 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 Source # 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 Source # 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 Source # (<>) 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. (<<%~) :: LensLike ((,) a) s t a b -> (a -> b) -> s -> (a, t) infixr 4 Source # 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 Source # 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 Source # 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 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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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) # Setting State with Passthrough (<%=) :: MonadState s m => LensLike ((,) b) s s a b -> (a -> b) -> m b infix 4 Source # 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 Source # 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 Source # 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 Source # 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 Source # 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 Source # 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 Source # 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 Source # 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 Source # 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 Source # 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 Source # (<>) 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. (<<%=) :: (Strong p, MonadState s m) => Over p ((,) a) s s a b -> p a b -> m a infix 4 Source # 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 Source # 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 Source # 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 Source # 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 Source # 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 Source # 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 Source # Modify the target of a Lens into your Monads 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 Source # 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 Source # 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 Source # 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 Source # 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 Source # 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 Source # 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 => ALens s s a b -> m b -> m b infixr 2 Source # 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 Source # 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 Source # 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 Source # 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 Source # 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 Source # A version of set that works on ALens. >>> storing _2 "world" ("hello","there") ("hello","world") (^#) :: s -> ALens s t a b -> a infixl 8 Source # A version of (^.) that works on ALens. >>> ("hello","world")^#_2 "world" (#~) :: ALens s t a b -> b -> s -> t infixr 4 Source # A version of (.~) that works on ALens. >>> ("hello","there") & _2 #~ "world" ("hello","world") (#%~) :: ALens s t a b -> (a -> b) -> s -> t infixr 4 Source # 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 Source # 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 Source # 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 Source # 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 Source # A version of (.=) that works on ALens. (#%=) :: MonadState s m => ALens s s a b -> (a -> b) -> m () infix 4 Source # A version of (%=) that works on ALens. (#%%=) :: MonadState s m => ALens s s a b -> (a -> (r, b)) -> m r infix 4 Source # A version of (%%=) that works on ALens. (<#=) :: MonadState s m => ALens s s a b -> b -> m b infix 4 Source # A version of (<.=) that works on ALens. (<#%=) :: MonadState s m => ALens s s a b -> (a -> b) -> m b infix 4 Source # A version of (<%=) that works on ALens. # Common Lenses devoid :: Over p f Void Void a b Source # 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 () Source # We can always retrieve a () from any type. >>> "hello"^.united () >>> "hello" & united .~ () "hello" head1 :: Traversable1 t => Lens' (t a) a Source # A Lens focusing on the first element of a Traversable1 container. >>> 2 :| [3, 4] & head1 +~ 10 12 :| [3,4] >>> Identity True ^. head1 True last1 :: Traversable1 t => Lens' (t a) a Source # 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 Source # 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  Source # Instance detailsDefined in Control.Lens.Internal.Context Methodsipos :: Context a c t -> a Source #ipeek :: c -> Context a c t -> t Source #ipeeks :: (a -> c) -> Context a c t -> t Source #iseek :: b -> Context a c t -> Context b c t Source #iseeks :: (a -> b) -> Context a c t -> Context b c t Source #iexperiment :: Functor f => (b -> f c) -> Context b c t -> f t Source #context :: Context a b t -> Context a b t Source # Source # Instance detailsDefined in Control.Lens.Internal.Context Methodsiextract :: Context a a t -> t Source #iduplicate :: Context a c t -> Context a b (Context b c t) Source #iextend :: (Context b c t -> r) -> Context a c t -> Context a b r Source # Source # Instance detailsDefined in Control.Lens.Internal.Context Methodsifmap :: (s -> t) -> Context a b s -> Context a b t Source # a ~ b => ComonadStore a (Context a b) Source # Instance detailsDefined in Control.Lens.Internal.Context Methodspos :: 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 # Functor (Context a b) Source # Instance detailsDefined in Control.Lens.Internal.Context Methodsfmap :: (a0 -> b0) -> Context a b a0 -> Context a b b0 #(<$) :: a0 -> Context a b b0 -> Context a b a0 # a ~ b => Comonad (Context a b) Source # Instance detailsDefined in Control.Lens.Internal.Context Methodsextract :: 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 # Sellable ((->) :: Type -> Type -> Type) Context Source # Instance detailsDefined in Control.Lens.Internal.Context Methodssell :: a -> Context a b b Source #

type Context' a = Context a a Source #

type Context' a s = Context a a s

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

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 Source #

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