Portability | Rank2Types |
---|---|

Stability | provisional |

Maintainer | Edward Kmett <ekmett@gmail.com> |

Safe Haskell | Trustworthy |

A

is a generalization of `Setter`

s t a b`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

we monomorphize the type to obtain `fmap`

:: `Functor`

f => (a -> b) -> f a -> f b`(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 (`<$`

).

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

`>>>`

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

`>>>`

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

`>>>`

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

`>>>`

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

`>>>`

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

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

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`

`>>>`

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

`>>>`

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

`>>>`

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

`>>>`

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

`>>>`

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

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

`>>>`

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

`>>>`

Just b`set lifted b (Just a)`

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`

`>>>`

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

`>>>`

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

`>>>`

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

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

.

`>>>`

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

`>>>`

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

`>>>`

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

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

`>>>`

h x (f y)`(mapped.argument %~ f) h x 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.*

`>>>`

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

Another way to view `over`

is to say that it transforms a `Setter`

into a
"semantic editor combinator".

`>>>`

Just (f a)`over mapped f (Just a)`

`>>>`

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

`>>>`

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

`>>>`

("10",20)`over _1 show (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`

`>>>`

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

`>>>`

[(),(),(),()]`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,e)`(a,b,c,d) & _4 .~ e`

`>>>`

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

`>>>`

(c,c)`(a,b) & both .~ 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,f c)`(a,b,c) & _3 %~ f`

`>>>`

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

`>>>`

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

`>>>`

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

`>>>`

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

`>>>`

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

(`%~`

) ::`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 + c,b)`(a,b) & _1 +~ c`

`>>>`

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

`>>>`

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

`>>>`

[(a + e,b + e),(c + e,d + e)]`[(a,b),(c,d)] & traverse.both +~ 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 - c,b)`(a,b) & _1 -~ c`

`>>>`

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

`>>>`

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

`>>>`

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

(`-~`

) ::`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 * c,b)`(a,b) & _1 *~ c`

`>>>`

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

`>>>`

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

`>>>`

Just 48`Just 24 & mapped *~ 2`

(`*~`

) ::`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 / c,b)`(a,b) & _1 //~ c`

`>>>`

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

`>>>`

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

(`//~`

) ::`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,9)`(1,3) & _2 ^~ 2`

(`^~`

) :: (`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,0.5)`(1,2) & _2 ^^~ (-1)`

(`^^~`

) :: (`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**c,b)`(a,b) & _1 **~ c`

`>>>`

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

`>>>`

(1,31.54428070019754)`_2 **~ pi $ (1,3)`

(`**~`

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

.

`>>>`

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

`>>>`

(False,True)`both ||~ False $ (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 {getSum = a + c},b)`(Sum a,b) & _1 <>~ Sum c`

`>>>`

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

`>>>`

("hello!!!","world!!!")`both <>~ "!!!" $ ("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`

.

`>>>`

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

`>>>`

(False,False)`both &&~ False $ (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

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

directly is a good idea.
`.~`

t

`>>>`

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

`>>>`

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

`>>>`

(Just "world",(42,fromList [("goodnight","gracie"),("hello","world")]))`(42,Map.fromList [("goodnight","gracie")]) & _2.at "hello" <.~ Just "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)

`>>>`

Just a`Nothing & id ?~ a`

`>>>`

fromList [(3,x)]`Map.empty & at 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 `

directly is a good idea.
`?~`

d

`>>>`

`import Data.Map as Map`

`>>>`

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

(`<?~`

) ::`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 (`.=`

).

`>>>`

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

`>>>`

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

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

.

`>>>`

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

`>>>`

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

(`.=`

) ::`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 ()

(%=) :: (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.

`>>>`

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

`>>>`

(f a,f b)`execState (do both %= f) (a,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`

`>>>`

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

`>>>`

(fromList [(1,10),(2,100)],"hello")`execState (do _1.at 1.non 0 += 10) (Map.fromList [(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.

`>>>`

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

(`-=`

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

`>>>`

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

(`*=`

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

`>>>`

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

(`//=`

) :: (`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

`>>>`

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

(`**=`

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

`>>>`

(True,True,True,False)`execState (do _1 ||= True; _2 ||= False; _3 ||= True; _4 ||= False) (True,True,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, Monoid a) => ASetter' s a -> a -> m ()Source

Modify the target(s) of a `Lens'`

, `Iso`

, `Setter`

or `Traversal`

by `mappend`

ing a value.

`>>>`

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

`>>>`

("hello!!!","world!!!")`execState (both <>= "!!!") ("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.

`>>>`

(True,False,False,False)`execState (do _1 &&= True; _2 &&= False; _3 &&= True; _4 &&= False) (True,True,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 `

will avoid unused binding warnings.
`.=`

d

(`<.=`

) ::`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.

`>>>`

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

`>>>`

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

(`?=`

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

will avoid unused binding warnings.
`?=`

d

(`<?=`

) ::`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
...

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

`>>>`

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

`>>>`

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

`>>>`

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

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

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