lens-3.8.4: Lenses, Folds and Traversals

PortabilityRank2Types
Stabilityprovisional
MaintainerEdward Kmett <ekmett@gmail.com>
Safe HaskellTrustworthy

Control.Lens.Setter

Contents

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

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 idid
 over l f . over l g ≡ over l (f . g)

These can be stated more directly:

 l purepure
 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 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 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 idid
 f g . f h ≡ f (g . h)

Equational reasoning:

 setting . overid
 over . settingid

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.

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.

 fmapover mapped
 fmapDefaultover 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.

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

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

 fmapover mapped
 fmapDefaultover traverse
 sets . overid
 over . setsid

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

(&&~) :: 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 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) => 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 idid
 f g . f h ≡ f (g . h)

Equational reasoning:

 isets . ioverid
 iover . isetsid

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 
(Applicative (Backwards f), Distributive (Backwards f), Traversable (Backwards f), Settable f) => Settable (Backwards f)

backwards

(Applicative (Compose f g), Distributive (Compose f g), Traversable (Compose f g), 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.

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.