Portability | Rank2Types |
---|---|
Stability | provisional |
Maintainer | Edward Kmett <ekmett@gmail.com> |
Safe Haskell | None |
A
is a generalization of Setter
a b c dfmap
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 ::
we monomorphize the type to obtain Functor
f => (c -> d) -> f c -> f d(c -> d) -> a -> b
and then decorate it with Identity
to obtain
typeSetter
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 (<$
).
- type Setter a b c d = forall f. Settable f => (c -> f d) -> a -> f b
- sets :: ((c -> d) -> a -> b) -> Setter a b c d
- mapped :: Functor f => Setter (f a) (f b) a b
- over :: Setting a b c d -> (c -> d) -> a -> b
- mapOf :: Setting a b c d -> (c -> d) -> a -> b
- set :: Setting a b c d -> d -> a -> b
- (.~) :: Setting a b c d -> d -> a -> b
- (%~) :: Setting a b c d -> (c -> d) -> a -> b
- (+~) :: Num c => Setting a b c c -> c -> a -> b
- (-~) :: Num c => Setting a b c c -> c -> a -> b
- (*~) :: Num c => Setting a b c c -> c -> a -> b
- (//~) :: Fractional c => Setting a b c c -> c -> a -> b
- (^~) :: (Num c, Integral e) => Setting a b c c -> e -> a -> b
- (^^~) :: (Fractional c, Integral e) => Setting a b c c -> e -> a -> b
- (**~) :: Floating c => Setting a b c c -> c -> a -> b
- (||~) :: Setting a b Bool Bool -> Bool -> a -> b
- (&&~) :: Setting a b Bool Bool -> Bool -> a -> b
- (<.~) :: Setting a b c d -> d -> a -> (d, b)
- assign :: MonadState a m => Setting a a c d -> d -> m ()
- (.=) :: MonadState a m => Setting a a c d -> d -> m ()
- (%=) :: MonadState a m => Setting a a c d -> (c -> d) -> m ()
- (+=) :: (MonadState a m, Num b) => SimpleSetting a b -> b -> m ()
- (-=) :: (MonadState a m, Num b) => SimpleSetting a b -> b -> m ()
- (*=) :: (MonadState a m, Num b) => SimpleSetting a b -> b -> m ()
- (//=) :: (MonadState a m, Fractional b) => SimpleSetting a b -> b -> m ()
- (^=) :: (MonadState a m, Fractional b, Integral c) => SimpleSetting a b -> c -> m ()
- (^^=) :: (MonadState a m, Fractional b, Integral c) => SimpleSetting a b -> c -> m ()
- (**=) :: (MonadState a m, Floating b) => SimpleSetting a b -> b -> m ()
- (||=) :: MonadState a m => SimpleSetting a Bool -> Bool -> m ()
- (&&=) :: MonadState a m => SimpleSetting a Bool -> Bool -> m ()
- (<.=) :: MonadState a m => Setting a a c d -> d -> m d
- (<~) :: MonadState a m => Setting a a c d -> m d -> m ()
- newtype ReifiedSetter a b c d = ReifySetter {
- reflectSetter :: Setter a b c d
- type Setting a b c d = (c -> Mutator d) -> a -> Mutator b
- type SimpleSetting a b = Setting a a b b
- type SimpleSetter a b = Setter a a b b
- type SimpleReifiedSetter a b = ReifiedSetter a a b b
- class Applicative f => Settable f
- data Mutator a
Setters
type Setter a b c d = forall f. Settable f => (c -> f d) -> a -> f bSource
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
:
over
lid
≡id
over
l f.
over
l g ≡over
l (f.
g)
These an be stated more directly:
lpure
≡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.
Building Setters
Common Setters
mapped :: Functor f => Setter (f a) (f b) a bSource
This setter can be used to map over all of the values in a Functor
.
fmap
≡over
mapped
fmapDefault
≡over
traverse
(<$
) ≡set
mapped
>>>
over mapped (+1) [1,2,3]
[2,3,4]
>>>
set mapped () [1,2,3]
[(),(),()]
>>>
mapped.mapped %~ (+1) $ [[1,2],[3]]
[[2,3],[4]]
>>>
over (mapped._2) length [("hello","world"),("leaders","!!!")]
[("hello",5),("leaders",3)]
Functional Combinators
over :: Setting a b c d -> (c -> d) -> a -> bSource
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
>>>
over mapped (*10) [1,2,3]
[10,20,30]
>>>
over _1 show (10,20)
("10",20)
Another way to view over
is to say that it transformers a Setter
into a
"semantic editor combinator".
over
::Setter
a b c d -> (c -> d) -> a -> b
mapOf :: Setting a b c d -> (c -> d) -> a -> bSource
Modify the target of a Lens
or all the targets of a Setter
or Traversal
with a function. This is an alias for over
that is provided for consistency.
mapOf
≡over
fmap
≡mapOf
mapped
fmapDefault
≡mapOf
traverse
sets
.
mapOf
≡id
mapOf
.
sets
≡id
>>>
mapOf mapped (+1) [1,2,3,4]
[2,3,4,5]
>>>
mapOf _1 (+1) (1,2)
(2,2)
>>>
mapOf both (+1) (1,2)
(2,3)
mapOf
::Setter
a b c d -> (c -> d) -> a -> bmapOf
::Iso
a b c d -> (c -> d) -> a -> bmapOf
::Lens
a b c d -> (c -> d) -> a -> bmapOf
::Traversal
a b c d -> (c -> d) -> a -> b
set :: Setting a b c d -> d -> a -> bSource
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
a b c d -> d -> a -> bset
::Iso
a b c d -> d -> a -> bset
::Lens
a b c d -> d -> a -> bset
::Traversal
a b c d -> d -> a -> b
(.~) :: Setting a b c d -> d -> a -> bSource
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
>>>
_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 -> bSource
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
%~
ffmapDefault
f ≡traverse
%~
f
>>>
_2 %~ length $ (1,"hello")
(1,5)
>>>
traverse %~ (+1) $ [1,2,3]
[2,3,4]
>>>
_2 %~ (+1) $ (3,4)
(3,5)
>>>
traverse.traverse %~ length $ [["hello","world"],["!!!"]]
[[5,5],[3]]
(%~
) ::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 -> bSource
Increment the target(s) of a numerically valued Lens
, Setter
or Traversal
>>>
_1 +~ 1 $ (1,2)
(2,2)
>>>
both +~ 2 $ (5,6)
(7,8)
(+~
) :: Num b =>Simple
Setter
a b -> b -> a -> a (+~
) :: Num b =>Simple
Iso
a b -> b -> a -> a (+~
) :: Num b =>Simple
Lens
a b -> b -> a -> a (+~
) :: Num b =>Simple
Traversal
a b -> b -> a -> a
(-~) :: Num c => Setting a b c c -> c -> a -> bSource
Decrement the target(s) of a numerically valued Lens
, Iso
, Setter
or Traversal
>>>
_1 -~ 2 $ (1,2)
(-1,2)
>>>
mapped.mapped -~ 1 $ [[4,5],[6,7]]
[[3,4],[5,6]]
(-~
) ::Num
b =>Simple
Setter
a b -> b -> a -> a (-~
) ::Num
b =>Simple
Iso
a b -> b -> a -> a (-~
) ::Num
b =>Simple
Lens
a b -> b -> a -> a (-~
) ::Num
b =>Simple
Traversal
a b -> b -> a -> a
(*~) :: Num c => Setting a b c c -> c -> a -> bSource
Multiply the target(s) of a numerically valued Lens
, Iso
, Setter
or Traversal
>>>
_2 *~ 4 $ (1,2)
(1,8)
>>>
mapped *~ 2 $ Just 24
Just 48
(*~
) ::Num
b =>Simple
Setter
a b -> b -> a -> a (*~
) ::Num
b =>Simple
Iso
a b -> b -> a -> a (*~
) ::Num
b =>Simple
Lens
a b -> b -> a -> a (*~
) ::Num
b =>Simple
Traversal
a b -> b -> a -> a
(//~) :: Fractional c => Setting a b c c -> c -> a -> bSource
Divide the target(s) of a numerically valued Lens
, Iso
, Setter
or Traversal
>>>
_2 //~ 2 $ ("Hawaii",10)
("Hawaii",5.0)
(//~
) ::Fractional
b =>Simple
Setter
a b -> b -> a -> a (//~
) ::Fractional
b =>Simple
Iso
a b -> b -> a -> a (//~
) ::Fractional
b =>Simple
Lens
a b -> b -> a -> a (//~
) ::Fractional
b =>Simple
Traversal
a b -> b -> a -> a
(^~) :: (Num c, Integral e) => Setting a b c c -> e -> a -> bSource
Raise the target(s) of a numerically valued Lens
, Setter
or Traversal
to a non-negative integral power
>>>
_2 ^~ 2 $ (1,3)
(1,9)
(^~
) :: (Num
b,Integral
c) =>Simple
Setter
a b -> c -> a -> a (^~
) :: (Num
b,Integral
c) =>Simple
Iso
a b -> c -> a -> a (^~
) :: (Num
b,Integral
c) =>Simple
Lens
a b -> c -> a -> a (^~
) :: (Num
b,Integral
c) =>Simple
Traversal
a b -> c -> a -> a
(^^~) :: (Fractional c, Integral e) => Setting a b c c -> e -> a -> bSource
Raise the target(s) of a fractionally valued Lens
, Setter
or Traversal
to an integral power
>>>
_2 ^^~ (-1) $ (1,2)
(1,0.5)
(^^~
) :: (Fractional
b,Integral
c) =>Simple
Setter
a b -> c -> a -> a (^^~
) :: (Fractional
b,Integral
c) =>Simple
Iso
a b -> c -> a -> a (^^~
) :: (Fractional
b,Integral
c) =>Simple
Lens
a b -> c -> a -> a (^^~
) :: (Fractional
b,Integral
c) =>Simple
Traversal
a b -> c -> a -> a
(**~) :: Floating c => Setting a b c c -> c -> a -> bSource
Raise the target(s) of a floating-point valued Lens
, Setter
or Traversal
to an arbitrary power.
>>>
_2 **~ pi $ (1,3)
(1,31.54428070019754)
(**~
) ::Floating
b =>Simple
Setter
a b -> b -> a -> a (**~
) ::Floating
b =>Simple
Iso
a b -> b -> a -> a (**~
) ::Floating
b =>Simple
Lens
a b -> b -> a -> a (**~
) ::Floating
b =>Simple
Traversal
a b -> b -> a -> a
(||~) :: Setting a b Bool Bool -> Bool -> a -> bSource
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
aBool
->Bool
-> a -> a (||~
) ::Simple
Iso
aBool
->Bool
-> a -> a (||~
) ::Simple
Lens
aBool
->Bool
-> a -> a (||~
) ::Simple
Traversal
aBool
->Bool
-> a -> a
(&&~) :: Setting a b Bool Bool -> Bool -> a -> bSource
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
aBool
->Bool
-> a -> a (&&~
) ::Simple
Iso
aBool
->Bool
-> a -> a (&&~
) ::Simple
Lens
aBool
->Bool
-> a -> a (&&~
) ::Simple
Traversal
aBool
->Bool
-> a -> a
(<.~) :: Setting a b c d -> d -> a -> (d, b)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.
.~
d
>>>
_3 <.~ "world" $ ("good","morning","vietnam")
("world",("good","morning","world"))
>>>
import Data.Map as Map
>>>
_2.at "hello" <.~ Just "world" $ (42,Map.fromList [("goodnight","gracie")])
(Just "world",(42,fromList [("goodnight","gracie"),("hello","world")]))
(<.~
) ::Setter
a b c d -> d -> a -> (d, b) (<.~
) ::Iso
a b c d -> d -> a -> (d, b) (<.~
) ::Lens
a b c d -> d -> a -> (d, b) (<.~
) ::Traversal
a b c d -> d -> a -> (d, b)
State Combinators
assign :: MonadState a m => Setting a a c d -> d -> 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 (.=
).
assign
::MonadState
a m =>Simple
Iso
a b -> b -> m ()assign
::MonadState
a m =>Simple
Lens
a b -> b -> m ()assign
::MonadState
a m =>Simple
Traversal
a b -> b -> m ()assign
::MonadState
a m =>Simple
Setter
a b -> b -> m ()
(.=) :: MonadState a m => Setting a a c d -> d -> 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
.
(.=
) ::MonadState
a m =>Simple
Iso
a b -> b -> m () (.=
) ::MonadState
a m =>Simple
Lens
a b -> b -> m () (.=
) ::MonadState
a m =>Simple
Traversal
a b -> b -> m () (.=
) ::MonadState
a m =>Simple
Setter
a b -> b -> m ()
(%=) :: MonadState a m => Setting a a c d -> (c -> d) -> m ()Source
Map over the target of a Lens
or all of the targets of a Setter
or Traversal
in our monadic state.
(%=
) ::MonadState
a m =>Simple
Iso
a b -> (b -> b) -> m () (%=
) ::MonadState
a m =>Simple
Lens
a b -> (b -> b) -> m () (%=
) ::MonadState
a m =>Simple
Traversal
a b -> (b -> b) -> m () (%=
) ::MonadState
a m =>Simple
Setter
a b -> (b -> b) -> m ()
(+=) :: (MonadState a m, Num b) => SimpleSetting a b -> b -> m ()Source
Modify the target(s) of a Simple
Lens
, Iso
, Setter
or Traversal
by adding a value
Example:
fresh :: MonadState Int m => m Int fresh = doid
+=
1use
id
(+=
) :: (MonadState
a m,Num
b) =>Simple
Setter
a b -> b -> m () (+=
) :: (MonadState
a m,Num
b) =>Simple
Iso
a b -> b -> m () (+=
) :: (MonadState
a m,Num
b) =>Simple
Lens
a b -> b -> m () (+=
) :: (MonadState
a m,Num
b) =>Simple
Traversal
a b -> b -> m ()
(-=) :: (MonadState a m, Num b) => SimpleSetting a b -> b -> m ()Source
Modify the target(s) of a Simple
Lens
, Iso
, Setter
or Traversal
by subtracting a value
(-=
) :: (MonadState
a m,Num
b) =>Simple
Setter
a b -> b -> m () (-=
) :: (MonadState
a m,Num
b) =>Simple
Iso
a b -> b -> m () (-=
) :: (MonadState
a m,Num
b) =>Simple
Lens
a b -> b -> m () (-=
) :: (MonadState
a m,Num
b) =>Simple
Traversal
a b -> b -> m ()
(*=) :: (MonadState a m, Num b) => SimpleSetting a b -> b -> m ()Source
Modify the target(s) of a Simple
Lens
, Iso
, Setter
or Traversal
by multiplying by value.
(*=
) :: (MonadState
a m,Num
b) =>Simple
Setter
a b -> b -> m () (*=
) :: (MonadState
a m,Num
b) =>Simple
Iso
a b -> b -> m () (*=
) :: (MonadState
a m,Num
b) =>Simple
Lens
a b -> b -> m () (*=
) :: (MonadState
a m,Num
b) =>Simple
Traversal
a b -> b -> m ()
(//=) :: (MonadState a m, Fractional b) => SimpleSetting a b -> b -> m ()Source
Modify the target(s) of a Simple
Lens
, Iso
, Setter
or Traversal
by dividing by a value.
(//=
) :: (MonadState
a m,Fractional
b) =>Simple
Setter
a b -> b -> m () (//=
) :: (MonadState
a m,Fractional
b) =>Simple
Iso
a b -> b -> m () (//=
) :: (MonadState
a m,Fractional
b) =>Simple
Lens
a b -> b -> m () (//=
) :: (MonadState
a m,Fractional
b) =>Simple
Traversal
a b -> b -> m ()
(^=) :: (MonadState a m, Fractional b, Integral c) => SimpleSetting a b -> c -> m ()Source
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) =>Simple
Setter
a b -> c -> m () (^=
) :: (MonadState
a m,Fractional
b,Integral
c) =>Simple
Iso
a b -> c -> m () (^=
) :: (MonadState
a m,Fractional
b,Integral
c) =>Simple
Lens
a b -> c -> m () (^=
) :: (MonadState
a m,Fractional
b,Integral
c) =>Simple
Traversal
a b -> c -> m ()
(^^=) :: (MonadState a m, Fractional b, Integral c) => SimpleSetting a b -> c -> m ()Source
Raise the target(s) of a numerically valued Lens
, Setter
or Traversal
to an integral power.
(^^=
) :: (MonadState
a m,Fractional
b,Integral
c) =>Simple
Setter
a b -> c -> m () (^^=
) :: (MonadState
a m,Fractional
b,Integral
c) =>Simple
Iso
a b -> c -> m () (^^=
) :: (MonadState
a m,Fractional
b,Integral
c) =>Simple
Lens
a b -> c -> m () (^^=
) :: (MonadState
a m,Fractional
b,Integral
c) =>Simple
Traversal
a b -> c -> m ()
(**=) :: (MonadState a m, Floating b) => SimpleSetting a b -> b -> m ()Source
Raise the target(s) of a numerically valued Lens
, Setter
or Traversal
to an arbitrary power
(**=
) :: (MonadState
a m,Floating
b) =>Simple
Setter
a b -> b -> m () (**=
) :: (MonadState
a m,Floating
b) =>Simple
Iso
a b -> b -> m () (**=
) :: (MonadState
a m,Floating
b) =>Simple
Lens
a b -> b -> m () (**=
) :: (MonadState
a m,Floating
b) =>Simple
Traversal
a b -> b -> m ()
(||=) :: MonadState a m => SimpleSetting a Bool -> Bool -> m ()Source
Modify the target(s) of a Simple
Lens
, 'Iso, Setter
or Traversal
by taking their logical ||
with a value
(||=
) ::MonadState
a m =>Simple
Setter
aBool
->Bool
-> m () (||=
) ::MonadState
a m =>Simple
Iso
aBool
->Bool
-> m () (||=
) ::MonadState
a m =>Simple
Lens
aBool
->Bool
-> m () (||=
) ::MonadState
a m =>Simple
Traversal
aBool
->Bool
-> m ()
(&&=) :: MonadState a m => SimpleSetting a Bool -> Bool -> m ()Source
Modify the target(s) of a Simple
Lens
, Iso
, Setter
or Traversal
by taking their logical &&
with a value
(&&=
) ::MonadState
a m =>Simple
Setter
aBool
->Bool
-> m () (&&=
) ::MonadState
a m =>Simple
Iso
aBool
->Bool
-> m () (&&=
) ::MonadState
a m =>Simple
Lens
aBool
->Bool
-> m () (&&=
) ::MonadState
a m =>Simple
Traversal
aBool
->Bool
-> m ()
(<.=) :: MonadState a m => Setting a a c d -> d -> m dSource
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
a m =>Setter
a a c d -> d -> m d (<.=
) ::MonadState
a m =>Iso
a a c d -> d -> m d (<.=
) ::MonadState
a m =>Lens
a a c d -> d -> m d (<.=
) ::MonadState
a m =>Traversal
a a c d -> d -> m d
(<~) :: MonadState a m => Setting a a c d -> m d -> m ()Source
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
...
Storing Setters
newtype ReifiedSetter a b c d Source
Reify a setter so it can be stored safely in a container.
ReifySetter | |
|
Setter Internals
type SimpleSetting a b = Setting a a b bSource
This is a useful alias for use when consuming a SimpleSetter
.
Most user code will never have to use this type.
typeSimpleSetting
m =Simple
Setting
Simplicity
type SimpleSetter a b = Setter a a b bSource
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
typeSimpleSetter
=Simple
Setter
type SimpleReifiedSetter a b = ReifiedSetter a a b bSource
Exported for legible error messages
class Applicative f => Settable f Source