Control.Lens.Setter

A Setter a b c d 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 => (c -> d) -> f c -> f d we monomorphize the type to obtain (c -> d) -> a -> b and then decorate it with Identity to obtain

type Setter a b c d = (c -> Identity d) -> a -> Identity b

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 a b c d = forall f. Settable f => (c -> f d) -> a -> f b

The only Lens-like law that can apply to a Setter l is that

 set l c (set l b a) = set l c a

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

However, two functor laws apply to a Setter:

1. adjust l id = id

2. adjust l f . adjust l g = adjust l (f . g)

These an be stated more directly:

1. l pure = pure

2. l f . run . l g = l (f . run . 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.

class Applicative f => Settable f where

Anything Settable must be isomorphic to the Identity Functor.

Methods

run :: f a -> a

Instances

Settable Identity

Settable Mutator

Settable f => Settable (Backwards f)

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

Consuming Setters

type Setting a b c d = (c -> Mutator d) -> a -> Mutator b

Running a Setter instantiates it to a concrete type.

When consuming a setter, use this type.

newtype Mutator a

Mutator is just a renamed Identity functor to give better error messages when someone attempts to use a getter as a setter.

Constructors

Mutator

Fields

runMutator :: a

Instances

Functor Mutator

Applicative Mutator

Settable Mutator

Building Setters

sets :: ((c -> d) -> a -> b) -> Setter a b c d

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 . adjust = id

adjust . 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        = adjust mapped

fmapDefault = adjust traverse

(<$)        = set mapped

Functional Combinators

adjust :: Setting a b c d -> (c -> d) -> a -> b

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

fmap        = adjust mapped

fmapDefault = adjust traverse

Free Theorems:

1. sets . adjust = id

2. adjust . sets = id

Another way to view adjust is to say that it transformers a Setter into a "semantic editor combinator".

adjust :: Setter a b c d -> (c -> d) -> a -> b

mapOf :: Setting a b c d -> (c -> d) -> a -> b

Modify the target of a Lens or all the targets of a Setter or Traversal with a function. This is an alias for adjust that is provided for consistency.

mapOf       = adjust

fmap        = mapOf mapped

fmapDefault = mapOf traverse

Free Theorems:

1. sets . mapOf = id

2. mapOf . sets = id

 mapOf :: Setter a b c d      -> (c -> d) -> a -> b
 mapOf :: Iso a b c d         -> (c -> d) -> a -> b
 mapOf :: Lens a b c d        -> (c -> d) -> a -> b
 mapOf :: Traversal a b c d   -> (c -> d) -> a -> b

set :: Setting a b c d -> d -> a -> b

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

(<$) = set mapped

 set :: Setter a b c d    -> d -> a -> b
 set :: Iso a b c d       -> d -> a -> b
 set :: Lens a b c d      -> d -> a -> b
 set :: Traversal a b c d -> d -> a -> b

(.~) :: Setting a b c d -> d -> a -> b

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

>>> import Control.Lens
>>> _1 .~ "hello" $ (42,"world")
("hello","world")

 (.~) :: Setter a b c d    -> d -> a -> b
 (.~) :: Iso a b c d       -> d -> a -> b
 (.~) :: Lens a b c d      -> d -> a -> b
 (.~) :: Traversal a b c d -> d -> a -> b

(%~) :: Setting a b c d -> (c -> d) -> a -> b

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 adjust

fmap f = mapped %~ f

fmapDefault f = traverse %~ f

>>> import Control.Lens
>>> _2 %~ length $ (1,"hello")
(1,5)

 (%~) :: Setter a b c d    -> (c -> d) -> a -> b
 (%~) :: Iso a b c d       -> (c -> d) -> a -> b
 (%~) :: Lens a b c d      -> (c -> d) -> a -> b
 (%~) :: Traversal a b c d -> (c -> d) -> a -> b

(+~) :: Num c => Setting a b c c -> c -> a -> b

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

>>> import Control.Lens
>>> _1 +~ 1 $ (1,2)
(2,2)

(-~) :: Num c => Setting a b c c -> c -> a -> b

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

>>> import Control.Lens
>>> _1 -~ 2 $ (1,2)
(-1,2)

(*~) :: Num c => Setting a b c c -> c -> a -> b

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

>>> import Control.Lens
>>> _2 *~ 4 $ (1,2)
(1,8)

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

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

(^~) :: (Num c, Integral e) => Setting a b c c -> e -> a -> b

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

>>> import Control.Lens
>>> _2 ^~ 2 $ (1,3)
(1,9)

(^^~) :: (Fractional c, Integral e) => Setting a b c c -> e -> a -> b

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

>>> import Control.Lens
>>> _2 ^^~ (-1) $ (1,2)
(1,0.5)

(**~) :: Floating c => Setting a b c c -> c -> a -> b

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

>>> import Control.Lens
>>> _2 **~ pi $ (1,3)
(1,31.54428070019754)

(||~) :: Setting a b Bool Bool -> Bool -> a -> b

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

(&&~) :: Setting a b Bool Bool -> Bool -> a -> b

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

(<>~) :: Monoid c => Setting a b c c -> c -> a -> b

Modify the target of a monoidally valued by mappending another value.

(<.~) :: Setting a b c d -> d -> a -> (d, b)

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 .~ d directly is a good idea.

State Combinators

(.=) :: MonadState a m => Setting a a c d -> d -> 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.

 (.=) :: MonadState a m => Iso a a c d             -> d -> m ()
 (.=) :: MonadState a m => Lens a a c d            -> d -> m ()
 (.=) :: MonadState a m => Traversal a a c d       -> d -> m ()
 (.=) :: MonadState a m => Setter a a c d          -> d -> m ()

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

(%=) :: MonadState a m => Setting a a c d -> (c -> d) -> m ()

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

 (%=) :: MonadState a m => Iso a a c d             -> (c -> d) -> m ()
 (%=) :: MonadState a m => Lens a a c d            -> (c -> d) -> m ()
 (%=) :: MonadState a m => Traversal a a c d       -> (c -> d) -> m ()
 (%=) :: MonadState a m => Setter a a c d          -> (c -> d) -> m ()

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

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

Example:

 fresh = do
   id += 1
   access id

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

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

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

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

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

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

(^=) :: (MonadState a m, Fractional b, Integral c) => SimpleSetting a b -> c -> m ()

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

(^^=) :: (MonadState a m, Fractional b, Integral c) => SimpleSetting a b -> c -> m ()

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

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

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

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

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

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

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

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

Modify the target(s) of a Simple Lens, Iso, Setter or Traversal by mappending a value.

(<.=) :: MonadState a m => Setting a a c d -> d -> m d

Set with pass-through

This is useful for chaining assignment

 do x <- _2 <.= (an expensive expression)

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

(<~) :: MonadState a m => Setting a a c d -> m d -> m ()

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

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

MonadWriter

whisper :: (MonadWriter b m, Monoid a) => Setting a b c d -> d -> m ()

Tell a part of a value to a MonadWriter, filling in the rest from mempty

 whisper l d = tell (set l d mempty)

Simplicity

type SimpleSetter a b = Setter a a b b

 'SimpleSetter' = 'Simple' 'Setter'

type SimpleSetting a b = Setting a a b b

 'SimpleSetting' m = 'Simple' 'Setting'