Control.Lens.Setter

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

Setters

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

The only Lens-like 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 an 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)]

Building Setters

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

Build a 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:

 sets . over ≡ id
 over . sets ≡ id

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

Common Setters

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

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

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

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

You sometimes have to use this, rather than mapped, because 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

Functional Combinators

over :: Setting s t a b -> (a -> b) -> s -> t

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

mapOf :: Setting s t a b -> (a -> b) -> s -> t

Deprecated: Use `over`

mapOf is a deprecated alias for over.

set :: Setting s t a b -> b -> s -> t

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

(.~) :: Setting s t a b -> b -> s -> t

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

(%~) :: Setting s t a b -> (a -> b) -> s -> t

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 => Setting s t a a -> a -> s -> t

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 => Simple Setter s a -> a -> s -> s
 (+~) :: Num a => Simple Iso s a -> a -> s -> s
 (+~) :: Num a => Simple Lens s a -> a -> s -> s
 (+~) :: Num a => Simple Traversal s a -> a -> s -> s

(-~) :: Num a => Setting s t a a -> a -> s -> t

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 => Simple Setter s a -> a -> s -> s
 (-~) :: Num a => Simple Iso s a -> a -> s -> s
 (-~) :: Num a => Simple Lens s a -> a -> s -> s
 (-~) :: Num a => Simple Traversal s a -> a -> s -> s

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

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 => Simple Setter s a -> a -> s -> s
 (*~) :: Num a => Simple Iso s a -> a -> s -> s
 (*~) :: Num a => Simple Lens s a -> a -> s -> s
 (*~) :: Num a => Simple Traversal s a -> a -> s -> s

(//~) :: Fractional s => Setting a b s s -> s -> a -> b

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 => Simple Setter s a -> a -> s -> s
 (//~) :: Fractional a => Simple Iso s a -> a -> s -> s
 (//~) :: Fractional a => Simple Lens s a -> a -> s -> s
 (//~) :: Fractional a => Simple Traversal s a -> a -> s -> s

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

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) => Simple Setter s a -> e -> s -> s
 (^~) :: (Num a, Integral e) => Simple Iso s a -> e -> s -> s
 (^~) :: (Num a, Integral e) => Simple Lens s a -> e -> s -> s
 (^~) :: (Num a, Integral e) => Simple Traversal s a -> e -> s -> s

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

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) => Simple Setter s a -> e -> s -> s
 (^^~) :: (Fractional a, Integral e) => Simple Iso s a -> e -> s -> s
 (^^~) :: (Fractional a, Integral e) => Simple Lens s a -> e -> s -> s
 (^^~) :: (Fractional a, Integral e) => Simple Traversal s a -> e -> s -> s

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

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 **~ pi $ (1,3)
(1,31.54428070019754)

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

(||~) :: Setting s t Bool Bool -> Bool -> s -> t

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

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

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

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

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

Modify the target of a monoidally valued by mappending 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

(&&~) :: Setting s t Bool Bool -> Bool -> s -> t

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

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

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

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

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

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)

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

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

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

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 b    -> (Maybe 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 => Setting s s a b -> b -> m ()

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 => Simple Iso s a       -> a -> m ()
 assign :: MonadState s m => Simple Lens s a      -> a -> m ()
 assign :: MonadState s m => Simple Traversal s a -> a -> m ()
 assign :: MonadState s m => Simple Setter s a    -> a -> m ()

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

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 => Simple Iso s a       -> a -> m ()
 (.=) :: MonadState s m => Simple Lens s a      -> a -> m ()
 (.=) :: MonadState s m => Simple Traversal s a -> a -> m ()
 (.=) :: MonadState s m => Simple Setter s a    -> a -> m ()

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

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

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 => Simple Iso s a       -> (a -> a) -> m ()
 (%=) :: MonadState s m => Simple Lens s a      -> (a -> a) -> m ()
 (%=) :: MonadState s m => Simple Traversal s a -> (a -> a) -> m ()
 (%=) :: MonadState s m => Simple Setter s a    -> (a -> a) -> m ()

(+=) :: (MonadState s m, Num a) => SimpleSetting s a -> a -> m ()

Modify the target(s) of a Simple 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) => Simple Setter s a -> a -> m ()
 (+=) :: (MonadState s m, Num a) => Simple Iso s a -> a -> m ()
 (+=) :: (MonadState s m, Num a) => Simple Lens s a -> a -> m ()
 (+=) :: (MonadState s m, Num a) => Simple Traversal s a -> a -> m ()

(-=) :: (MonadState s m, Num a) => SimpleSetting s a -> a -> m ()

Modify the target(s) of a Simple 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) => Simple Setter s a -> a -> m ()
 (-=) :: (MonadState s m, Num a) => Simple Iso s a -> a -> m ()
 (-=) :: (MonadState s m, Num a) => Simple Lens s a -> a -> m ()
 (-=) :: (MonadState s m, Num a) => Simple Traversal s a -> a -> m ()

(*=) :: (MonadState s m, Num a) => SimpleSetting s a -> a -> m ()

Modify the target(s) of a Simple 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) => Simple Setter s a -> a -> m ()
 (*=) :: (MonadState s m, Num a) => Simple Iso s a -> a -> m ()
 (*=) :: (MonadState s m, Num a) => Simple Lens s a -> a -> m ()
 (*=) :: (MonadState s m, Num a) => Simple Traversal s a -> a -> m ()

(//=) :: (MonadState s m, Fractional a) => SimpleSetting s a -> a -> m ()

Modify the target(s) of a Simple 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) => Simple Setter s a -> a -> m ()
 (//=) :: (MonadState s m, Fractional a) => Simple Iso s a -> a -> m ()
 (//=) :: (MonadState s m, Fractional a) => Simple Lens s a -> a -> m ()
 (//=) :: (MonadState s m, Fractional a) => Simple Traversal s a -> a -> m ()

(^=) :: (MonadState s m, Num a, Integral e) => SimpleSetting s a -> e -> m ()

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) => Simple Setter s a -> e -> m ()
 (^=) ::  (MonadState s m, Num a, Integral e) => Simple Iso s a -> e -> m ()
 (^=) ::  (MonadState s m, Num a, Integral e) => Simple Lens s a -> e -> m ()
 (^=) ::  (MonadState s m, Num a, Integral e) => Simple Traversal s a -> e -> m ()

(^^=) :: (MonadState s m, Fractional a, Integral e) => SimpleSetting s a -> e -> m ()

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

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

(**=) :: (MonadState s m, Floating a) => SimpleSetting s a -> a -> m ()

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) => Simple Setter s a -> a -> m ()
 (**=) ::  (MonadState s m, Floating a) => Simple Iso s a -> a -> m ()
 (**=) ::  (MonadState s m, Floating a) => Simple Lens s a -> a -> m ()
 (**=) ::  (MonadState s m, Floating a) => Simple Traversal s a -> a -> m ()

(||=) :: MonadState s m => SimpleSetting s Bool -> Bool -> m ()

Modify the target(s) of a Simple 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 => Simple Setter s Bool -> Bool -> m ()
 (||=) :: MonadState s m => Simple Iso s Bool -> Bool -> m ()
 (||=) :: MonadState s m => Simple Lens s Bool -> Bool -> m ()
 (||=) :: MonadState s m => Simple Traversal s Bool -> Bool -> m ()

(<>=) :: (MonadState s m, Monoid a) => SimpleSetting s a -> a -> m ()

Modify the target(s) of a Simple Lens, Iso, Setter or Traversal by mappending 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) => Simple Setter s a -> a -> m ()
 (<>=) :: (MonadState s m, Monoid a) => Simple Iso s a -> a -> m ()
 (<>=) :: (MonadState s m, Monoid a) => Simple Lens s a -> a -> m ()
 (<>=) :: (MonadState s m, Monoid a) => Simple Traversal s a -> a -> m ()

(&&=) :: MonadState s m => SimpleSetting s Bool -> Bool -> m ()

Modify the target(s) of a Simple 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 => Simple Setter s Bool -> Bool -> m ()
 (&&=) :: MonadState s m => Simple Iso s Bool -> Bool -> m ()
 (&&=) :: MonadState s m => Simple Lens s Bool -> Bool -> m ()
 (&&=) :: MonadState s m => Simple Traversal s Bool -> Bool -> m ()

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

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 => Setting s s a (Maybe b) -> b -> m ()

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 => Simple Iso s (Maybe a)       -> a -> m ()
 (?=) :: MonadState s m => Simple Lens s (Maybe a)      -> a -> m ()
 (?=) :: MonadState s m => Simple Traversal s (Maybe a) -> a -> m ()
 (?=) :: MonadState s m => Simple Setter s (Maybe a)    -> a -> m ()

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

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 => Setting s s a b -> m b -> m ()

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.

Simplified State Setting

set' :: Setting s s a a -> a -> s -> s

Replace the target of a Lens or all of the targets of a Simple Setter or Simple 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' :: Simple Setter s a    -> a -> s -> s
 set' :: Simple Iso s a       -> a -> s -> s
 set' :: Simple Lens s a      -> a -> s -> s
 set' :: Simple Traversal s a -> a -> s -> s

Storing Setters

newtype ReifiedSetter s t a b

Reify a setter so it can be stored safely in a container.

Constructors

ReifySetter

Fields

reflectSetter :: Setter s t a b

Setter Internals

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

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 SimpleSetting s a = Setting s s a a

This is a useful alias for use when consuming a SimpleSetter.

Most user code will never have to use this type.

type SimpleSetting m = Simple Setting

Simplicity

type SimpleSetter s a = Setter s s a a

A Simple 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 :: SimpleSetter Text Char

type SimpleSetter = Simple Setter

type SimpleReifiedSetter s a = ReifiedSetter s s a a

type SimpleReifiedSetter = Simple ReifiedSetter

Exported for legible error messages

class Applicative f => Settable f

Anything Settable must be isomorphic to the Identity Functor.

Instances

Settable Identity

so you can pass our a Setter into combinators from other lens libraries

Settable Mutator

(Applicative (Backwards f), Settable f) => Settable (Backwards f)

backwards

(Applicative (Compose f g), Settable f, Settable g) => Settable (Compose f g)

data Mutator a

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

Functor Mutator

Applicative Mutator

Settable Mutator