lens-3.10: Lenses, Folds and Traversals

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

Control.Lens.Setter

Contents

- Setters
- Building Setters
- Common Setters
- Functional Combinators
- State Combinators
- Writer Combinators
- Simplified State Setting
- Indexed Setters
- Exported for legible error messages
- Deprecated

Description

A ``Setter` s t a b` is a generalization of `fmap` from `Functor`. It allows you to map into a structure and change out the contents, but it isn't strong enough to allow you to enumerate those contents. Starting with ``fmap` :: `Functor` f => (a -> b) -> f a -> f b` we monomorphize the type to obtain `(a -> b) -> s -> t` and then decorate it with `Identity` to obtain:

     type Setter s t a b = (a -> Identity b) -> s -> Identity t

Every `Traversal` is a valid `Setter`, since `Identity` is `Applicative`.

Everything you can do with a `Functor`, you can do with a `Setter`. There are combinators that generalize `fmap` and (`<$`).

Synopsis

- type Setter s t a b = forall f. Settable f => (a -> f b) -> s -> f t
- type Setter' s a = Setter s s a a
- type IndexedSetter i s t a b = forall f p. (Indexable i p, Settable f) => p a (f b) -> s -> f t
- type IndexedSetter' i s a = IndexedSetter i s s a a
- type ASetter s t a b = (a -> Mutator b) -> s -> Mutator t
- type ASetter' s a = ASetter s s a a
- type AnIndexedSetter i s t a b = Indexed i a (Mutator b) -> s -> Mutator t
- type AnIndexedSetter' i s a = AnIndexedSetter i s s a a
- type Setting p s t a b = p a (Mutator b) -> s -> Mutator t
- type Setting' p s a = Setting p s s a a
- sets :: (Profunctor p, Profunctor q, Settable f) => (p a b -> q s t) -> Overloading p q f s t a b
- setting :: ((a -> b) -> s -> t) -> IndexPreservingSetter s t a b
- cloneSetter :: ASetter s t a b -> Setter s t a b
- cloneIndexPreservingSetter :: ASetter s t a b -> IndexPreservingSetter s t a b
- cloneIndexedSetter :: AnIndexedSetter i s t a b -> IndexedSetter i s t a b
- mapped :: Functor f => Setter (f a) (f b) a b
- lifted :: Monad m => Setter (m a) (m b) a b
- contramapped :: Contravariant f => Setter (f b) (f a) a b
- argument :: Profunctor p => Setter (p b r) (p a r) a b
- over :: Profunctor p => Setting p s t a b -> p a b -> s -> t
- set :: ASetter s t a b -> b -> s -> t
- (.~) :: ASetter s t a b -> b -> s -> t
- (%~) :: Profunctor p => Setting p s t a b -> p a b -> s -> t
- (+~) :: Num a => ASetter s t a a -> a -> s -> t
- (-~) :: Num a => ASetter s t a a -> a -> s -> t
- (*~) :: Num a => ASetter s t a a -> a -> s -> t
- (//~) :: Fractional a => ASetter s t a a -> a -> s -> t
- (^~) :: (Num a, Integral e) => ASetter s t a a -> e -> s -> t
- (^^~) :: (Fractional a, Integral e) => ASetter s t a a -> e -> s -> t
- (**~) :: Floating a => ASetter s t a a -> a -> s -> t
- (||~) :: ASetter s t Bool Bool -> Bool -> s -> t
- (<>~) :: Monoid a => ASetter s t a a -> a -> s -> t
- (&&~) :: ASetter s t Bool Bool -> Bool -> s -> t
- (<.~) :: ASetter s t a b -> b -> s -> (b, t)
- (?~) :: ASetter s t a (Maybe b) -> b -> s -> t
- (<?~) :: ASetter s t a (Maybe b) -> b -> s -> (b, t)
- assign :: MonadState s m => ASetter s s a b -> b -> m ()
- (.=) :: MonadState s m => ASetter s s a b -> b -> m ()
- (%=) :: (Profunctor p, MonadState s m) => Setting p s s a b -> p a b -> m ()
- (+=) :: (MonadState s m, Num a) => ASetter' s a -> a -> m ()
- (-=) :: (MonadState s m, Num a) => ASetter' s a -> a -> m ()
- (*=) :: (MonadState s m, Num a) => ASetter' s a -> a -> m ()
- (//=) :: (MonadState s m, Fractional a) => ASetter' s a -> a -> m ()
- (^=) :: (MonadState s m, Num a, Integral e) => ASetter' s a -> e -> m ()
- (^^=) :: (MonadState s m, Fractional a, Integral e) => ASetter' s a -> e -> m ()
- (**=) :: (MonadState s m, Floating a) => ASetter' s a -> a -> m ()
- (||=) :: MonadState s m => ASetter' s Bool -> Bool -> m ()
- (<>=) :: (MonadState s m, Monoid a) => ASetter' s a -> a -> m ()
- (&&=) :: MonadState s m => ASetter' s Bool -> Bool -> m ()
- (<.=) :: MonadState s m => ASetter s s a b -> b -> m b
- (?=) :: MonadState s m => ASetter s s a (Maybe b) -> b -> m ()
- (<?=) :: MonadState s m => ASetter s s a (Maybe b) -> b -> m b
- (<~) :: MonadState s m => ASetter s s a b -> m b -> m ()
- scribe :: (MonadWriter t m, Monoid s) => ASetter s t a b -> b -> m ()
- passing :: MonadWriter w m => Setter w w u v -> m (a, u -> v) -> m a
- ipassing :: MonadWriter w m => IndexedSetter i w w u v -> m (a, i -> u -> v) -> m a
- censoring :: MonadWriter w m => Setter w w u v -> (u -> v) -> m a -> m a
- icensoring :: MonadWriter w m => IndexedSetter i w w u v -> (i -> u -> v) -> m a -> m a
- set' :: ASetter' s a -> a -> s -> s
- imapOf :: AnIndexedSetter i s t a b -> (i -> a -> b) -> s -> t
- iover :: AnIndexedSetter i s t a b -> (i -> a -> b) -> s -> t
- isets :: ((i -> a -> b) -> s -> t) -> IndexedSetter i s t a b
- (%@~) :: AnIndexedSetter i s t a b -> (i -> a -> b) -> s -> t
- (%@=) :: MonadState s m => AnIndexedSetter i s s a b -> (i -> a -> b) -> m ()
- class (Applicative f, Distributive f, Traversable f) => Settable f
- data Mutator a
- mapOf :: Profunctor p => Setting p s t a b -> p a b -> s -> t

# Setters

type Setter s t a b = forall f. Settable f => (a -> f b) -> s -> f tSource

The only `LensLike` law that can apply to a `Setter` `l` is that

     set l y (set l x a) ≡ set l y a

You can't `view` a `Setter` in general, so the other two laws are irrelevant.

However, two `Functor` laws apply to a `Setter`:

     over l id ≡ id
     over l f . over l g ≡ over l (f . g)

These can be stated more directly:

     l pure ≡ pure
     l f . untainted . l g ≡ l (f . untainted . g)

You can compose a `Setter` with a `Lens` or a `Traversal` using (`.`) from the `Prelude` and the result is always only a `Setter` and nothing more.

    >>> over traverse f [a,b,c,d]
    [f a,f b,f c,f d]

    >>> over _1 f (a,b)
    (f a,b)

    >>> over (traverse._1) f [(a,b),(c,d)]
    [(f a,b),(f c,d)]

    >>> over both f (a,b)
    (f a,f b)

    >>> over (traverse.both) f [(a,b),(c,d)]
    [(f a,f b),(f c,f d)]

type Setter' s a = Setter s s a aSource

A `Setter'` is just a `Setter` that doesn't change the types.

These are particularly common when talking about monomorphic containers. e.g.

     sets Data.Text.map :: Setter' Text Char

     type Setter' = Setter'

type IndexedSetter i s t a b = forall f p. (Indexable i p, Settable f) => p a (f b) -> s -> f tSource

Every `IndexedSetter` is a valid `Setter`.

The `Setter` laws are still required to hold.

type IndexedSetter' i s a = IndexedSetter i s s a aSource

     type IndexedSetter' i = Simple (IndexedSetter i)

type ASetter s t a b = (a -> Mutator b) -> s -> Mutator tSource

Running a `Setter` instantiates it to a concrete type.

When consuming a setter directly to perform a mapping, you can use this type, but most user code will not need to use this type.

By choosing `Mutator` rather than `Identity`, we get nicer error messages.

type ASetter' s a = ASetter s s a aSource

This is a useful alias for use when consuming a `Setter'`.

Most user code will never have to use this type.

     type ASetter' = Simple ASetter

type AnIndexedSetter i s t a b = Indexed i a (Mutator b) -> s -> Mutator tSource

Running an `IndexedSetter` instantiates it to a concrete type.

When consuming a setter directly to perform a mapping, you can use this type, but most user code will not need to use this type.

By choosing `Mutator` rather than `Identity`, we get nicer error messages.

type AnIndexedSetter' i s a = AnIndexedSetter i s s a aSource

     type AnIndexedSetter' i = Simple (AnIndexedSetter i)

type Setting p s t a b = p a (Mutator b) -> s -> Mutator tSource

This is a convenient alias when defining highly polymorphic code that takes both `ASetter` and `AnIndexedSetter` as appropriate. If a function takes this it is expecting one of those two things based on context.

type Setting' p s a = Setting p s s a aSource

This is a convenient alias when defining highly polymorphic code that takes both `ASetter'` and `AnIndexedSetter'` as appropriate. If a function takes this it is expecting one of those two things based on context.

# Building Setters

sets :: (Profunctor p, Profunctor q, Settable f) => (p a b -> q s t) -> Overloading p q f s t a bSource

Build a `Setter`, `IndexedSetter` or `IndexPreservingSetter` depending on your choice of `Profunctor`.

     sets :: ((a -> b) -> s -> t) -> Setter s t a b

setting :: ((a -> b) -> s -> t) -> IndexPreservingSetter s t a bSource

Build an index-preserving `Setter` from a map-like function.

Your supplied function `f` is required to satisfy:

     f id ≡ id
     f g . f h ≡ f (g . h)

Equational reasoning:

     setting . over ≡ id
     over . setting ≡ id

Another way to view `sets` is that it takes a "semantic editor combinator" and transforms it into a `Setter`.

     setting :: ((a -> b) -> s -> t) -> Setter s t a b

cloneSetter :: ASetter s t a b -> Setter s t a bSource

Restore `ASetter` to a full `Setter`.

cloneIndexPreservingSetter :: ASetter s t a b -> IndexPreservingSetter s t a bSource

Build an `IndexPreservingSetter` from any `Setter`.

cloneIndexedSetter :: AnIndexedSetter i s t a b -> IndexedSetter i s t a bSource

Clone an `IndexedSetter`.

# Common Setters

mapped :: Functor f => Setter (f a) (f b) a bSource

This `Setter` can be used to map over all of the values in a `Functor`.

     fmap ≡ over mapped
     fmapDefault ≡ over traverse
     (<$) ≡ set mapped

    >>> over mapped f [a,b,c]
    [f a,f b,f c]

    >>> over mapped (+1) [1,2,3]
    [2,3,4]

    >>> set mapped x [a,b,c]
    [x,x,x]

    >>> [[a,b],[c]] & mapped.mapped +~ x
    [[a + x,b + x],[c + x]]

    >>> over (mapped._2) length [("hello","world"),("leaders","!!!")]
    [("hello",5),("leaders",3)]

     mapped :: Functor f => Setter (f a) (f b) a b

If you want an `IndexPreservingSetter` use ``setting` `fmap``.

lifted :: Monad m => Setter (m a) (m b) a bSource

This `setter` can be used to modify all of the values in a `Monad`.

You sometimes have to use this rather than `mapped` -- due to temporary insanity `Functor` is not a superclass of `Monad`.

     liftM ≡ over lifted

    >>> over lifted f [a,b,c]
    [f a,f b,f c]

    >>> set lifted b (Just a)
    Just b

If you want an `IndexPreservingSetter` use ``setting` `liftM``.

contramapped :: Contravariant f => Setter (f b) (f a) a bSource

This `Setter` can be used to map over all of the inputs to a `Contravariant`.

     contramap ≡ over contramapped

    >>> getPredicate (over contramapped (*2) (Predicate even)) 5
    True

    >>> getOp (over contramapped (*5) (Op show)) 100
    "500"

    >>> Prelude.map ($ 1) $ over (mapped . wrapping Op . contramapped) (*12) [(*2),(+1),(^3)]
    [24,13,1728]

argument :: Profunctor p => Setter (p b r) (p a r) a bSource

This `Setter` can be used to map over the input of a `Profunctor`.

The most common `Profunctor` to use this with is `(->)`.

    >>> (argument %~ f) g x
    g (f x)

    >>> (argument %~ show) length [1,2,3]
    7

    >>> (argument %~ f) h x y
    h (f x) y

Map over the argument of the result of a function -- i.e., its second argument:

    >>> (mapped.argument %~ f) h x y
    h x (f y)

     argument :: Setter (b -> r) (a -> r) a b

# Functional Combinators

over :: Profunctor p => Setting p s t a b -> p a b -> s -> tSource

Modify the target of a `Lens` or all the targets of a `Setter` or `Traversal` with a function.

     fmap ≡ over mapped
     fmapDefault ≡ over traverse
     sets . over ≡ id
     over . sets ≡ id

Given any valid `Setter` `l`, you can also rely on the law:

     over l f . over l g = over l (f . g)

e.g.

    >>> over mapped f (over mapped g [a,b,c]) == over mapped (f . g) [a,b,c]
    True

Another way to view `over` is to say that it transforms a `Setter` into a "semantic editor combinator".

    >>> over mapped f (Just a)
    Just (f a)

    >>> over mapped (*10) [1,2,3]
    [10,20,30]

    >>> over _1 f (a,b)
    (f a,b)

    >>> over _1 show (10,20)
    ("10",20)

     over :: Setter s t a b -> (a -> b) -> s -> t
     over :: ASetter s t a b -> (a -> b) -> s -> t

set :: ASetter s t a b -> b -> s -> tSource

Replace the target of a `Lens` or all of the targets of a `Setter` or `Traversal` with a constant value.

     (<$) ≡ set mapped

    >>> set _2 "hello" (1,())
    (1,"hello")

    >>> set mapped () [1,2,3,4]
    [(),(),(),()]

Note: Attempting to `set` a `Fold` or `Getter` will fail at compile time with an relatively nice error message.

     set :: Setter s t a b    -> b -> s -> t
     set :: Iso s t a b       -> b -> s -> t
     set :: Lens s t a b      -> b -> s -> t
     set :: Traversal s t a b -> b -> s -> t

(.~) :: ASetter s t a b -> b -> s -> tSource

Replace the target of a `Lens` or all of the targets of a `Setter` or `Traversal` with a constant value.

This is an infix version of `set`, provided for consistency with (`.=`).

     f <$ a ≡ mapped .~ f $ a

    >>> (a,b,c,d) & _4 .~ e
    (a,b,c,e)

    >>> (42,"world") & _1 .~ "hello"
    ("hello","world")

    >>> (a,b) & both .~ c
    (c,c)

     (.~) :: Setter s t a b    -> b -> s -> t
     (.~) :: Iso s t a b       -> b -> s -> t
     (.~) :: Lens s t a b      -> b -> s -> t
     (.~) :: Traversal s t a b -> b -> s -> t

(%~) :: Profunctor p => Setting p s t a b -> p a b -> s -> tSource

Modifies the target of a `Lens` or all of the targets of a `Setter` or `Traversal` with a user supplied function.

This is an infix version of `over`.

     fmap f ≡ mapped %~ f
     fmapDefault f ≡ traverse %~ f

    >>> (a,b,c) & _3 %~ f
    (a,b,f c)

    >>> (a,b) & both %~ f
    (f a,f b)

    >>> _2 %~ length $ (1,"hello")
    (1,5)

    >>> traverse %~ f $ [a,b,c]
    [f a,f b,f c]

    >>> traverse %~ even $ [1,2,3]
    [False,True,False]

    >>> traverse.traverse %~ length $ [["hello","world"],["!!!"]]
    [[5,5],[3]]

     (%~) :: Setter s t a b    -> (a -> b) -> s -> t
     (%~) :: Iso s t a b       -> (a -> b) -> s -> t
     (%~) :: Lens s t a b      -> (a -> b) -> s -> t
     (%~) :: Traversal s t a b -> (a -> b) -> s -> t

(+~) :: Num a => ASetter s t a a -> a -> s -> tSource

Increment the target(s) of a numerically valued `Lens`, `Setter` or `Traversal`.

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

    >>> (a,b) & both +~ c
    (a + c,b + c)

    >>> (1,2) & _2 +~ 1
    (1,3)

    >>> [(a,b),(c,d)] & traverse.both +~ e
    [(a + e,b + e),(c + e,d + e)]

     (+~) :: Num a => Setter' s a    -> a -> s -> s
     (+~) :: Num a => Iso' s a       -> a -> s -> s
     (+~) :: Num a => Lens' s a      -> a -> s -> s
     (+~) :: Num a => Traversal' s a -> a -> s -> s

(-~) :: Num a => ASetter s t a a -> a -> s -> tSource

Decrement the target(s) of a numerically valued `Lens`, `Iso`, `Setter` or `Traversal`.

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

    >>> (a,b) & both -~ c
    (a - c,b - c)

    >>> _1 -~ 2 $ (1,2)
    (-1,2)

    >>> mapped.mapped -~ 1 $ [[4,5],[6,7]]
    [[3,4],[5,6]]

     (-~) :: Num a => Setter' s a    -> a -> s -> s
     (-~) :: Num a => Iso' s a       -> a -> s -> s
     (-~) :: Num a => Lens' s a      -> a -> s -> s
     (-~) :: Num a => Traversal' s a -> a -> s -> s

(*~) :: Num a => ASetter s t a a -> a -> s -> tSource

Multiply the target(s) of a numerically valued `Lens`, `Iso`, `Setter` or `Traversal`.

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

    >>> (a,b) & both *~ c
    (a * c,b * c)

    >>> (1,2) & _2 *~ 4
    (1,8)

    >>> Just 24 & mapped *~ 2
    Just 48

     (*~) :: Num a => Setter' s a    -> a -> s -> s
     (*~) :: Num a => Iso' s a       -> a -> s -> s
     (*~) :: Num a => Lens' s a      -> a -> s -> s
     (*~) :: Num a => Traversal' s a -> a -> s -> s

(//~) :: Fractional a => ASetter s t a a -> a -> s -> tSource

Divide the target(s) of a numerically valued `Lens`, `Iso`, `Setter` or `Traversal`.

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

    >>> (a,b) & both //~ c
    (a / c,b / c)

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

     (//~) :: Fractional a => Setter' s a    -> a -> s -> s
     (//~) :: Fractional a => Iso' s a       -> a -> s -> s
     (//~) :: Fractional a => Lens' s a      -> a -> s -> s
     (//~) :: Fractional a => Traversal' s a -> a -> s -> s

(^~) :: (Num a, Integral e) => ASetter s t a a -> e -> s -> tSource

Raise the target(s) of a numerically valued `Lens`, `Setter` or `Traversal` to a non-negative integral power.

    >>> (1,3) & _2 ^~ 2
    (1,9)

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

(^^~) :: (Fractional a, Integral e) => ASetter s t a a -> e -> s -> tSource

Raise the target(s) of a fractionally valued `Lens`, `Setter` or `Traversal` to an integral power.

    >>> (1,2) & _2 ^^~ (-1)
    (1,0.5)

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

(**~) :: Floating a => ASetter s t a a -> a -> s -> tSource

Raise the target(s) of a floating-point valued `Lens`, `Setter` or `Traversal` to an arbitrary power.

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

    >>> (a,b) & both **~ c
    (a**c,b**c)

    >>> _2 **~ 10 $ (3,2)
    (3,1024.0)

     (**~) :: Floating a => Setter' s a    -> a -> s -> s
     (**~) :: Floating a => Iso' s a       -> a -> s -> s
     (**~) :: Floating a => Lens' s a      -> a -> s -> s
     (**~) :: Floating a => Traversal' s a -> a -> s -> s

(||~) :: ASetter s t Bool Bool -> Bool -> s -> tSource

Logically `||` the target(s) of a `Bool`-valued `Lens` or `Setter`.

    >>> both ||~ True $ (False,True)
    (True,True)

    >>> both ||~ False $ (False,True)
    (False,True)

     (||~) :: Setter' s Bool    -> Bool -> s -> s
     (||~) :: Iso' s Bool       -> Bool -> s -> s
     (||~) :: Lens' s Bool      -> Bool -> s -> s
     (||~) :: Traversal' s Bool -> Bool -> s -> s

(<>~) :: Monoid a => ASetter s t a a -> a -> s -> tSource

Modify the target of a monoidally valued by `mappend`ing another value.

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

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

    >>> both <>~ "!!!" $ ("hello","world")
    ("hello!!!","world!!!")

     (<>~) :: Monoid a => Setter s t a a    -> a -> s -> t
     (<>~) :: Monoid a => Iso s t a a       -> a -> s -> t
     (<>~) :: Monoid a => Lens s t a a      -> a -> s -> t
     (<>~) :: Monoid a => Traversal s t a a -> a -> s -> t

(&&~) :: ASetter s t Bool Bool -> Bool -> s -> tSource

Logically `&&` the target(s) of a `Bool`-valued `Lens` or `Setter`.

    >>> both &&~ True $ (False, True)
    (False,True)

    >>> both &&~ False $ (False, True)
    (False,False)

     (&&~) :: Setter' s Bool    -> Bool -> s -> s
     (&&~) :: Iso' s Bool       -> Bool -> s -> s
     (&&~) :: Lens' s Bool      -> Bool -> s -> s
     (&&~) :: Traversal' s Bool -> Bool -> s -> s

(<.~) :: ASetter s t a b -> b -> s -> (b, t)Source

Set with pass-through.

This is mostly present for consistency, but may be useful for for chaining assignments.

If you do not need a copy of the intermediate result, then using `l `.~` t` directly is a good idea.

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

    >>> ("good","morning","vietnam") & _3 <.~ "world"
    ("world",("good","morning","world"))

    >>> (42,Map.fromList [("goodnight","gracie")]) & _2.at "hello" <.~ Just "world"
    (Just "world",(42,fromList [("goodnight","gracie"),("hello","world")]))

     (<.~) :: Setter s t a b    -> b -> s -> (b, t)
     (<.~) :: Iso s t a b       -> b -> s -> (b, t)
     (<.~) :: Lens s t a b      -> b -> s -> (b, t)
     (<.~) :: Traversal s t a b -> b -> s -> (b, t)

(?~) :: ASetter s t a (Maybe b) -> b -> s -> tSource

Set the target of a `Lens`, `Traversal` or `Setter` to `Just` a value.

     l ?~ t ≡ set l (Just t)

    >>> Nothing & id ?~ a
    Just a

    >>> Map.empty & at 3 ?~ x
    fromList [(3,x)]

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

(<?~) :: ASetter s t a (Maybe b) -> b -> s -> (b, t)Source

Set to `Just` a value with pass-through.

This is mostly present for consistency, but may be useful for for chaining assignments.

If you do not need a copy of the intermediate result, then using `l `?~` d` directly is a good idea.

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

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

# State Combinators

assign :: MonadState s m => ASetter s s a b -> b -> m ()Source

Replace the target of a `Lens` or all of the targets of a `Setter` or `Traversal` in our monadic state with a new value, irrespective of the old.

This is an alias for (`.=`).

    >>> execState (do assign _1 c; assign _2 d) (a,b)
    (c,d)

    >>> execState (both .= c) (a,b)
    (c,c)

     assign :: MonadState s m => Iso' s a       -> a -> m ()
     assign :: MonadState s m => Lens' s a      -> a -> m ()
     assign :: MonadState s m => Traversal' s a -> a -> m ()
     assign :: MonadState s m => Setter' s a    -> a -> m ()

(.=) :: MonadState s m => ASetter s s a b -> b -> m ()Source

Replace the target of a `Lens` or all of the targets of a `Setter` or `Traversal` in our monadic state with a new value, irrespective of the old.

This is an infix version of `assign`.

    >>> execState (do _1 .= c; _2 .= d) (a,b)
    (c,d)

    >>> execState (both .= c) (a,b)
    (c,c)

     (.=) :: MonadState s m => Iso' s a       -> a -> m ()
     (.=) :: MonadState s m => Lens' s a      -> a -> m ()
     (.=) :: MonadState s m => Traversal' s a -> a -> m ()
     (.=) :: MonadState s m => Setter' s a    -> a -> m ()

It puts the state in the monad or it gets the hose again.

(%=) :: (Profunctor p, MonadState s m) => Setting p s s a b -> p a b -> m ()Source

Map over the target of a `Lens` or all of the targets of a `Setter` or `Traversal` in our monadic state.

    >>> execState (do _1 %= f;_2 %= g) (a,b)
    (f a,g b)

    >>> execState (do both %= f) (a,b)
    (f a,f b)

     (%=) :: MonadState s m => Iso' s a       -> (a -> a) -> m ()
     (%=) :: MonadState s m => Lens' s a      -> (a -> a) -> m ()
     (%=) :: MonadState s m => Traversal' s a -> (a -> a) -> m ()
     (%=) :: MonadState s m => Setter' s a    -> (a -> a) -> m ()

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

(+=) :: (MonadState s m, Num a) => ASetter' s a -> a -> m ()Source

Modify the target(s) of a `Lens'`, `Iso`, `Setter` or `Traversal` by adding a value.

Example:

     fresh :: MonadState Int m => m Int
     fresh = do
       id += 1
       use id

    >>> execState (do _1 += c; _2 += d) (a,b)
    (a + c,b + d)

    >>> execState (do _1.at 1.non 0 += 10) (Map.fromList [(2,100)],"hello")
    (fromList [(1,10),(2,100)],"hello")

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

(-=) :: (MonadState s m, Num a) => ASetter' s a -> a -> m ()Source

Modify the target(s) of a `Lens'`, `Iso`, `Setter` or `Traversal` by subtracting a value.

    >>> execState (do _1 -= c; _2 -= d) (a,b)
    (a - c,b - d)

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

(*=) :: (MonadState s m, Num a) => ASetter' s a -> a -> m ()Source

Modify the target(s) of a `Lens'`, `Iso`, `Setter` or `Traversal` by multiplying by value.

    >>> execState (do _1 *= c; _2 *= d) (a,b)
    (a * c,b * d)

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

(//=) :: (MonadState s m, Fractional a) => ASetter' s a -> a -> m ()Source

Modify the target(s) of a `Lens'`, `Iso`, `Setter` or `Traversal` by dividing by a value.

    >>> execState (do _1 //= c; _2 //= d) (a,b)
    (a / c,b / d)

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

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

Raise the target(s) of a numerically valued `Lens`, `Setter` or `Traversal` to a non-negative integral power.

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

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

Raise the target(s) of a numerically valued `Lens`, `Setter` or `Traversal` to an integral power.

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

(**=) :: (MonadState s m, Floating a) => ASetter' s a -> a -> m ()Source

Raise the target(s) of a numerically valued `Lens`, `Setter` or `Traversal` to an arbitrary power

    >>> execState (do _1 **= c; _2 **= d) (a,b)
    (a**c,b**d)

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

(||=) :: MonadState s m => ASetter' s Bool -> Bool -> m ()Source

Modify the target(s) of a `Lens'`, 'Iso, `Setter` or `Traversal` by taking their logical `||` with a value.

    >>> execState (do _1 ||= True; _2 ||= False; _3 ||= True; _4 ||= False) (True,True,False,False)
    (True,True,True,False)

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

(<>=) :: (MonadState s m, Monoid a) => ASetter' s a -> a -> m ()Source

Modify the target(s) of a `Lens'`, `Iso`, `Setter` or `Traversal` by `mappend`ing a value.

    >>> execState (do _1 <>= Sum c; _2 <>= Product d) (Sum a,Product b)
    (Sum {getSum = a + c},Product {getProduct = b * d})

    >>> execState (both <>= "!!!") ("hello","world")
    ("hello!!!","world!!!")

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

(&&=) :: MonadState s m => ASetter' s Bool -> Bool -> m ()Source

Modify the target(s) of a `Lens'`, `Iso`, `Setter` or `Traversal` by taking their logical `&&` with a value.

    >>> execState (do _1 &&= True; _2 &&= False; _3 &&= True; _4 &&= False) (True,True,False,False)
    (True,False,False,False)

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

(<.=) :: MonadState s m => ASetter s s a b -> b -> m bSource

Set with pass-through

This is useful for chaining assignment without round-tripping through your `Monad` stack.

     do x <- _2 <.= ninety_nine_bottles_of_beer_on_the_wall

If you do not need a copy of the intermediate result, then using `l `.=` d` will avoid unused binding warnings.

     (<.=) :: MonadState s m => Setter s s a b    -> b -> m b
     (<.=) :: MonadState s m => Iso s s a b       -> b -> m b
     (<.=) :: MonadState s m => Lens s s a b      -> b -> m b
     (<.=) :: MonadState s m => Traversal s s a b -> b -> m b

(?=) :: MonadState s m => ASetter s s a (Maybe b) -> b -> m ()Source

Replace the target of a `Lens` or all of the targets of a `Setter` or `Traversal` in our monadic state with `Just` a new value, irrespective of the old.

    >>> execState (do at 1 ?= a; at 2 ?= b) Map.empty
    fromList [(1,a),(2,b)]

    >>> execState (do _1 ?= b; _2 ?= c) (Just a, Nothing)
    (Just b,Just c)

     (?=) :: MonadState s m => Iso' s (Maybe a)       -> a -> m ()
     (?=) :: MonadState s m => Lens' s (Maybe a)      -> a -> m ()
     (?=) :: MonadState s m => Traversal' s (Maybe a) -> a -> m ()
     (?=) :: MonadState s m => Setter' s (Maybe a)    -> a -> m ()

(<?=) :: MonadState s m => ASetter s s a (Maybe b) -> b -> m bSource

Set `Just` a value with pass-through

This is useful for chaining assignment without round-tripping through your `Monad` stack.

     do x <- at foo <?= ninety_nine_bottles_of_beer_on_the_wall

If you do not need a copy of the intermediate result, then using `l `?=` d` will avoid unused binding warnings.

     (<?=) :: MonadState s m => Setter s s a (Maybe b)    -> b -> m b
     (<?=) :: MonadState s m => Iso s s a (Maybe b)       -> b -> m b
     (<?=) :: MonadState s m => Lens s s a (Maybe b)      -> b -> m b
     (<?=) :: MonadState s m => Traversal s s a (Maybe b) -> b -> m b

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

Run a monadic action, and set all of the targets of a `Lens`, `Setter` or `Traversal` to its result.

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

As a reasonable mnemonic, this lets you store the result of a monadic action in a `Lens` rather than in a local variable.

     do foo <- bar
        ...

will store the result in a variable, while

     do foo <~ bar
        ...

will store the result in a `Lens`, `Setter`, or `Traversal`.

# Writer Combinators

scribe :: (MonadWriter t m, Monoid s) => ASetter s t a b -> b -> m ()Source

Write to a fragment of a larger `Writer` format.

passing :: MonadWriter w m => Setter w w u v -> m (a, u -> v) -> m aSource

This is a generalization of `pass` that alows you to modify just a portion of the resulting `MonadWriter`.

ipassing :: MonadWriter w m => IndexedSetter i w w u v -> m (a, i -> u -> v) -> m aSource

This is a generalization of `pass` that alows you to modify just a portion of the resulting `MonadWriter` with access to the index of an `IndexedSetter`.

censoring :: MonadWriter w m => Setter w w u v -> (u -> v) -> m a -> m aSource

This is a generalization of `censor` that alows you to `censor` just a portion of the resulting `MonadWriter`.

icensoring :: MonadWriter w m => IndexedSetter i w w u v -> (i -> u -> v) -> m a -> m aSource

This is a generalization of `censor` that alows you to `censor` just a portion of the resulting `MonadWriter`, with access to the index of an `IndexedSetter`.

# Simplified State Setting

set' :: ASetter' s a -> a -> s -> sSource

Replace the target of a `Lens` or all of the targets of a `Setter'` or `Traversal` with a constant value, without changing its type.

This is a type restricted version of `set`, which retains the type of the original.

    >>> set' mapped x [a,b,c,d]
    [x,x,x,x]

    >>> set' _2 "hello" (1,"world")
    (1,"hello")

    >>> set' mapped 0 [1,2,3,4]
    [0,0,0,0]

Note: Attempting to adjust `set'` a `Fold` or `Getter` will fail at compile time with an relatively nice error message.

     set' :: Setter' s a    -> a -> s -> s
     set' :: Iso' s a       -> a -> s -> s
     set' :: Lens' s a      -> a -> s -> s
     set' :: Traversal' s a -> a -> s -> s

# Indexed Setters

imapOf :: AnIndexedSetter i s t a b -> (i -> a -> b) -> s -> tSource

Deprecated: Use `iover`

Map with index. (Deprecated alias for `iover`).

When you do not need access to the index, then `mapOf` is more liberal in what it can accept.

     mapOf l ≡ imapOf l . const

     imapOf :: IndexedSetter i s t a b    -> (i -> a -> b) -> s -> t
     imapOf :: IndexedLens i s t a b      -> (i -> a -> b) -> s -> t
     imapOf :: IndexedTraversal i s t a b -> (i -> a -> b) -> s -> t

iover :: AnIndexedSetter i s t a b -> (i -> a -> b) -> s -> tSource

Map with index. This is an alias for `imapOf`.

When you do not need access to the index, then `over` is more liberal in what it can accept.

     over l ≡ iover l . const
     iover l ≡ over l . Indexed

     iover :: IndexedSetter i s t a b    -> (i -> a -> b) -> s -> t
     iover :: IndexedLens i s t a b      -> (i -> a -> b) -> s -> t
     iover :: IndexedTraversal i s t a b -> (i -> a -> b) -> s -> t

isets :: ((i -> a -> b) -> s -> t) -> IndexedSetter i s t a bSource

Build an `IndexedSetter` from an `imap`-like function.

Your supplied function `f` is required to satisfy:

     f id ≡ id
     f g . f h ≡ f (g . h)

Equational reasoning:

     isets . iover ≡ id
     iover . isets ≡ id

Another way to view `sets` is that it takes a "semantic editor combinator" and transforms it into a `Setter`.

(%@~) :: AnIndexedSetter i s t a b -> (i -> a -> b) -> s -> tSource

Adjust every target of an `IndexedSetter`, `IndexedLens` or `IndexedTraversal` with access to the index.

     (%@~) ≡ imapOf

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

     l %~ f ≡ l %@~ const f

     (%@~) :: IndexedSetter i s t a b    -> (i -> a -> b) -> s -> t
     (%@~) :: IndexedLens i s t a b      -> (i -> a -> b) -> s -> t
     (%@~) :: IndexedTraversal i s t a b -> (i -> a -> b) -> s -> t

(%@=) :: MonadState s m => AnIndexedSetter i s s a b -> (i -> a -> b) -> m ()Source

Adjust every target in the current state of an `IndexedSetter`, `IndexedLens` or `IndexedTraversal` with access to the index.

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

     l %= f ≡ l %@= const f

     (%@=) :: MonadState s m => IndexedSetter i s s a b    -> (i -> a -> b) -> m ()
     (%@=) :: MonadState s m => IndexedLens i s s a b      -> (i -> a -> b) -> m ()
     (%@=) :: MonadState s m => IndexedTraversal i s t a b -> (i -> a -> b) -> m ()

# Exported for legible error messages

class (Applicative f, Distributive f, Traversable f) => Settable f Source

Anything `Settable` must be isomorphic to the `Identity` `Functor`.

Instances

Settable Identity | So you can pass our `Setter` into combinators from other lens libraries.
Settable Mutator |
Settable f => Settable (Backwards f) | `backwards`
(Settable f, Settable g) => Settable (Compose f g) |

data Mutator a Source

`Mutator` is just a renamed `Identity` `Functor` to give better error messages when someone attempts to use a `Getter` as a `Setter`.

Most user code will never need to see this type.

Instances

Monad Mutator |
Functor Mutator |
Applicative Mutator |
Foldable Mutator |
Traversable Mutator |
Comonad Mutator |
ComonadApply Mutator |
Distributive Mutator |
Apply Mutator |
Bind Mutator |
Extend Mutator |
Settable Mutator |

# Deprecated

mapOf :: Profunctor p => Setting p s t a b -> p a b -> s -> tSource

Deprecated: Use `over`

`mapOf` is a deprecated alias for `over`.