Copyright | (C) 2013-2016 Edward Kmett 2015-2016 Artyom Kazak 2018 Monadfix |
---|---|
License | BSD-style (see the file LICENSE) |
Safe Haskell | Trustworthy |
Language | Haskell2010 |
- Setter: modifies something in a structure
- Getter: extracts a value from a structure
- Fold: extracts multiple elements
- Lens: a combined getter-and-setter
- Iso: a lens that only changes the representation
- Traversal: a lens iterating over several elements
- Prism: a traversal iterating over at most 1 element
- Other types
This module provides the essential functionality. There are other packages in the microlens family – mix and match them at will. If you're writing an app, you want microlens-platform – it provides the most functionality.
- microlens-mtl – (
+=
) and friends,use
,zoom
/magnify
- microlens-th –
makeLenses
andmakeFields
- microlens-ghc – everything in microlens + instances to make
each
/at
/ix
usable with arrays,ByteString
, and containers - microlens-platform – microlens-ghc + microlens-mtl + microlens-th + instances for
Text
,Vector
, andHashMap
- microlens-contra –
Fold
andGetter
that are exact copies of types in lens
Unofficial:
- microlens-aeson – a port of lens-aeson
Synopsis
- (&) :: a -> (a -> b) -> b
- (<&>) :: Functor f => f a -> (a -> b) -> f b
- type ASetter s t a b = (a -> Identity b) -> s -> Identity t
- type ASetter' s a = ASetter s s a a
- sets :: ((a -> b) -> s -> t) -> ASetter s t a b
- (%~) :: ASetter s t a b -> (a -> b) -> s -> t
- over :: ASetter s t a b -> (a -> b) -> s -> t
- (+~) :: Num a => ASetter s t a a -> a -> s -> t
- (-~) :: Num a => ASetter s t a a -> a -> s -> t
- (<>~) :: Monoid a => ASetter s t a a -> a -> s -> t
- (.~) :: ASetter s t a b -> b -> s -> t
- set :: ASetter s t a b -> b -> s -> t
- (?~) :: ASetter s t a (Maybe b) -> b -> s -> t
- (<%~) :: LensLike ((,) b) s t a b -> (a -> b) -> s -> (b, t)
- (<<%~) :: LensLike ((,) a) s t a b -> (a -> b) -> s -> (a, t)
- (<<.~) :: LensLike ((,) a) s t a b -> b -> s -> (a, t)
- mapped :: Functor f => ASetter (f a) (f b) a b
- type SimpleGetter s a = forall r. Getting r s a
- type Getting r s a = (a -> Const r a) -> s -> Const r s
- (^.) :: s -> Getting a s a -> a
- to :: (s -> a) -> SimpleGetter s a
- type SimpleFold s a = forall r. Monoid r => Getting r s a
- (^..) :: s -> Getting (Endo [a]) s a -> [a]
- toListOf :: Getting (Endo [a]) s a -> s -> [a]
- (^?) :: s -> Getting (First a) s a -> Maybe a
- (^?!) :: HasCallStack => s -> Getting (Endo a) s a -> a
- traverseOf_ :: Functor f => Getting (Traversed r f) s a -> (a -> f r) -> s -> f ()
- forOf_ :: Functor f => Getting (Traversed r f) s a -> s -> (a -> f r) -> f ()
- has :: Getting Any s a -> s -> Bool
- folded :: Foldable f => SimpleFold (f a) a
- folding :: Foldable f => (s -> f a) -> SimpleFold s a
- type Lens s t a b = forall f. Functor f => (a -> f b) -> s -> f t
- type Lens' s a = Lens s s a a
- lens :: (s -> a) -> (s -> b -> t) -> Lens s t a b
- at :: At m => Index m -> Lens' m (Maybe (IxValue m))
- _1 :: Field1 s t a b => Lens s t a b
- _2 :: Field2 s t a b => Lens s t a b
- _3 :: Field3 s t a b => Lens s t a b
- _4 :: Field4 s t a b => Lens s t a b
- _5 :: Field5 s t a b => Lens s t a b
- strict :: Strict lazy strict => Lens' lazy strict
- lazy :: Strict lazy strict => Lens' strict lazy
- non :: Eq a => a -> Lens' (Maybe a) a
- type Traversal s t a b = forall f. Applicative f => (a -> f b) -> s -> f t
- type Traversal' s a = Traversal s s a a
- traverseOf :: LensLike f s t a b -> (a -> f b) -> s -> f t
- forOf :: LensLike f s t a b -> s -> (a -> f b) -> f t
- singular :: HasCallStack => Traversal s t a a -> Lens s t a a
- failing :: Traversal s t a b -> Traversal s t a b -> Traversal s t a b
- filtered :: (a -> Bool) -> Traversal' a a
- both :: Traversal (a, a) (b, b) a b
- traversed :: Traversable f => Traversal (f a) (f b) a b
- each :: Each s t a b => Traversal s t a b
- ix :: Ixed m => Index m -> Traversal' m (IxValue m)
- _head :: Cons s s a a => Traversal' s a
- _tail :: Cons s s a a => Traversal' s s
- _init :: Snoc s s a a => Traversal' s s
- _last :: Snoc s s a a => Traversal' s a
- mapAccumLOf :: LensLike (State acc) s t a b -> (acc -> a -> (acc, b)) -> acc -> s -> (acc, t)
- _Left :: Traversal (Either a b) (Either a' b) a a'
- _Right :: Traversal (Either a b) (Either a b') b b'
- _Just :: Traversal (Maybe a) (Maybe a') a a'
- _Nothing :: Traversal' (Maybe a) ()
- type LensLike f s t a b = (a -> f b) -> s -> f t
- type LensLike' f s a = LensLike f s s a a
Documentation
This operator is useful when you want to modify something several times. For instance, if you want to change 1st and 3rd elements of a tuple, you can write this:
(1,2,3)&
_1
.~
0&
_3
%~
negate
instead of e.g. this:
(_1
.~
0).
(_3
%~
negate
)$
(1,2,3)
or this:
set
_1
0.
over
_3
negate
$
(1,2,3)
x<&>
f = f<$>
x
It's often useful when writing lenses. For instance, let's say you're writing ix
for Map
; if the key is found in the map, you have to apply a function to it and then change the map based on the new value – which requires a lambda, like this:
ix
key f map = case Map.lookup key map of Just val -> (\val' -> Map.insert key val' map)<$>
f val Nothing ->pure
map
With (<&>
) you can get rid of parentheses and move the long lambda expression to the right of the value (like when you use >>=
):
ix
key f map = case Map.lookup key map of Just val -> f val<&>
\val' -> Map.insert key val' map Nothing ->pure
map
Setter: modifies something in a structure
A setter is, broadly speaking, something that lets you modify a part of some value. Most likely you already know some setters:
first
:: (a -> b) -> (a, x) -> (b, x)(modifies 1st element of a pair; corresponds to
_1
)left
:: (a -> b) ->Either
a x ->Either
b xmap
:: (a -> b) -> [a] -> [b](modifies every element in a list; corresponds to
mapped
)
As you see, a setter takes a function, a value, and applies the function to some part (or several parts) of the value. Moreover, setters can be pretty specific – for instance, a function that modifies the 3rd element of a list is a setter too:
-- Modify 3rd element in a list, if present. modify3rd :: (a -> a) -> [a] -> [a] modify3rd f (a:b:c:xs) = a : b : f c : xs modify3rd _ xs = xs
A nice thing about setters is that they compose easily – you can write
and it would be a function that takes a list of map
.
left
Either
s and modifies all of them that are Left
s.
This library provides its own type for setters – ASetter
; it's needed so that some functions in this library (like _1
) would be usable both as setters and as getters. You can turn an ordinary function like map
to a “lensy” setter with sets
.
To apply a setter to a value, use (%~
) or over
:
>>>
[1,2,3] & mapped %~ succ
[2,3,4]>>>
over _head toUpper "jane"
"Jane"
To modify a value deeper inside the structure, use (.
):
>>>
["abc","def","ghi"] & ix 1 . ix 2 %~ toUpper
["abc","deF","ghi"]
To set a value instead of modifying it, use set
or (.~
):
>>>
"abc" & mapped .~ 'x'
"xxx">>>
set _2 'X' ('a','b','c')
('a','X','c')
It's also possible to get both the old and the new value back – see (<%~
) and (<<%~
).
type ASetter s t a b = (a -> Identity b) -> s -> Identity t Source #
ASetter s t a b
is something that turns a function modifying a value into a function modifying a structure. If you ignore Identity
(as Identity a
is the same thing as a
), the type is:
type ASetter s t a b = (a -> b) -> s -> t
The reason Identity
is used here is for ASetter
to be composable with other types, such as Lens
.
Technically, if you're writing a library, you shouldn't use this type for setters you are exporting from your library; the right type to use is Setter
, but it is not provided by this package (because then it'd have to depend on distributive). It's completely alright, however, to export functions which take an ASetter
as an argument.
(%~) :: ASetter s t a b -> (a -> b) -> s -> t infixr 4 Source #
(%~
) applies a function to the target; an alternative explanation is that it is an inverse of sets
, which turns a setter into an ordinary function.
is the same thing as mapped
%~
reverse
.fmap
reverse
See over
if you want a non-operator synonym.
Negating the 1st element of a pair:
>>>
(1,2) & _1 %~ negate
(-1,2)
Turning all Left
s in a list to upper case:
>>>
(mapped._Left.mapped %~ toUpper) [Left "foo", Right "bar"]
[Left "FOO",Right "bar"]
over :: ASetter s t a b -> (a -> b) -> s -> t Source #
Getting fmap
in a roundabout way:
over
mapped
::Functor
f => (a -> b) -> f a -> f bover
mapped
=fmap
Applying a function to both components of a pair:
over
both
:: (a -> b) -> (a, a) -> (b, b)over
both
= \f t -> (f (fst t), f (snd t))
Using
as a replacement for over
_2
second
:
>>>
over _2 show (10,20)
(10,"20")
(+~) :: Num a => ASetter s t a a -> a -> s -> t Source #
Increment the target(s) of a numerically valued Lens
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 =>Lens'
s a -> a -> s -> s (+~
) ::Num
a =>Traversal'
s a -> a -> s -> s
(-~) :: Num a => ASetter s t a a -> a -> s -> t Source #
Decrement the target(s) of a numerically valued Lens
, 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 =>Lens'
s a -> a -> s -> s (-~
) ::Num
a =>Traversal'
s a -> a -> s -> s
(<>~) :: Monoid a => ASetter s t a a -> a -> s -> t infixr 4 Source #
(<>~
) appends a value monoidally to the target.
>>>
("hello", "goodbye") & both <>~ " world!"
("hello world!", "goodbye world!")
(<%~) :: LensLike ((,) b) s t a b -> (a -> b) -> s -> (b, t) infixr 4 Source #
This is a version of (%~
) which modifies the structure and returns it along with the new value:
>>>
(1, 2) & _1 <%~ negate
(-1, (-1, 2))
Simpler type signatures:
(<%~
) ::Lens
s t a b -> (a -> b) -> s -> (b, t) (<%~
) ::Monoid
b =>Traversal
s t a b -> (a -> b) -> s -> (b, t)
Since it does getting in addition to setting, you can't use it with ASetter
(but you can use it with lens and traversals).
mapped :: Functor f => ASetter (f a) (f b) a b Source #
mapped
is a setter for everything contained in a functor. You can use it to map over lists, Maybe
, or even IO
(which is something you can't do with traversed
or each
).
Here mapped
is used to turn a value to all non-Nothing
values in a list:
>>>
[Just 3,Nothing,Just 5] & mapped.mapped .~ 0
[Just 0,Nothing,Just 0]
Keep in mind that while mapped
is a more powerful setter than each
, it can't be used as a getter! This won't work (and will fail with a type error):
[(1,2),(3,4),(5,6)]^..
mapped
.both
Getter: extracts a value from a structure
A getter extracts something from a value; in fact, any function is a getter. However, same as with setters, this library uses a special type for getters so that functions like _1
would be usable both as a setter and a getter. An ordinary function can be turned into a getter with to
.
Using a getter is done with (^.
) or view
from Lens.Micro.Extras:
>>>
('x','y') ^. _1
'x'>>>
view (ix 2) [0..5]
2
Getters can be composed with (.
):
>>>
[(1,2),(3,4),(5,6)] ^. ix 1 . _2
4
A getter always returns exactly 1 element (getters that can return more than one element are called folds and are present in this library as well).
type SimpleGetter s a = forall r. Getting r s a Source #
A SimpleGetter s a
extracts a
from s
; so, it's the same thing as (s -> a)
, but you can use it in lens chains because its type looks like this:
type SimpleGetter s a = forall r. (a -> Const r a) -> s -> Const r s
Since Const r
is a functor, SimpleGetter
has the same shape as other lens types and can be composed with them. To get (s -> a)
out of a SimpleGetter
, choose r ~ a
and feed Const :: a -> Const a a
to the getter:
-- the actual signature is more permissive: --view
::Getting
a s a -> s -> aview
::SimpleGetter
s a -> s -> aview
getter =getConst
. getterConst
The actual Getter
from lens is more general:
type Getter s a = forall f. (Contravariant f, Functor f) => (a -> f a) -> s -> f s
I'm not currently aware of any functions that take lens's Getter
but won't accept SimpleGetter
, but you should try to avoid exporting SimpleGetter
s anyway to minimise confusion. Alternatively, look at microlens-contra, which provides a fully lens-compatible Getter
.
Lens users: you can convert a SimpleGetter
to Getter
by applying to . view
to it.
type Getting r s a = (a -> Const r a) -> s -> Const r s Source #
Functions that operate on getters and folds – such as (^.
), (^..
), (^?
) – use Getter r s a
(with different values of r
) to describe what kind of result they need. For instance, (^.
) needs the getter to be able to return a single value, and so it accepts a getter of type Getting a s a
. (^..
) wants the getter to gather values together, so it uses Getting (Endo [a]) s a
(it could've used Getting [a] s a
instead, but it's faster with Endo
). The choice of r
depends on what you want to do with elements you're extracting from s
.
(^.) :: s -> Getting a s a -> a infixl 8 Source #
(^.
) applies a getter to a value; in other words, it gets a value out of a structure using a getter (which can be a lens, traversal, fold, etc.).
Getting 1st field of a tuple:
(^.
_1
) :: (a, b) -> a (^.
_1
) =fst
When (^.
) is used with a traversal, it combines all results using the Monoid
instance for the resulting type. For instance, for lists it would be simple concatenation:
>>>
("str","ing") ^. each
"string"
The reason for this is that traversals use Applicative
, and the Applicative
instance for Const
uses monoid concatenation to combine “effects” of Const
.
A non-operator version of (^.
) is called view
, and it's a bit more general than (^.
) (it works in MonadReader
). If you need the general version, you can get it from microlens-mtl; otherwise there's view
available in Lens.Micro.Extras.
to :: (s -> a) -> SimpleGetter s a Source #
to
creates a getter from any function:
a^.
to
f = f a
It's most useful in chains, because it lets you mix lenses and ordinary functions. Suppose you have a record which comes from some third-party library and doesn't have any lens accessors. You want to do something like this:
value ^. _1 . field . at 2
However, field
isn't a getter, and you have to do this instead:
field (value ^. _1) ^. at 2
but now value
is in the middle and it's hard to read the resulting code. A variant with to
is prettier and more readable:
value ^. _1 . to field . at 2
Fold: extracts multiple elements
Folds are getters that can return more than one element (or no elements at all). Except for some rare cases, a fold is the same thing as (s -> [a])
; you can use folding
to turn any function of type (s -> f a)
(where f
is Foldable
) into a fold.
Folds can be applied to values by using operators like (^..
), (^?
), etc:
>>>
(1,2) ^.. both
[1,2]
A nice thing about folds is that you can combine them with (<>
) to concatenate their outputs:
>>>
(1,2,3) ^.. (_2 <> _1)
[2,1]
When you need to get all elements of the same type in a complicated structure, (<>
) can be more helpful than each
:
>>>
([1,2], 3, [Nothing, Just 4]) ^.. (_1.each <> _2 <> _3.each._Just)
[1,2,3,4]
(Just like setters and getters before, folds can be composed with (.
).)
The (<>
) trick works nicely with (^?
), too. For instance, if you want to get the 9th element of the list, but would be fine with 5th too if the list is too short, you could combine ix 9
and ix 5
:
>>>
[0..9] ^? (ix 9 <> ix 5)
Just 9>>>
[0..8] ^? (ix 9 <> ix 5)
Just 5>>>
[0..3] ^? (ix 9 <> ix 5)
Nothing
(Unfortunately, this trick won't help you with setting or modifying.)
type SimpleFold s a = forall r. Monoid r => Getting r s a Source #
A SimpleFold s a
extracts several a
s from s
; so, it's pretty much the same thing as (s -> [a])
, but you can use it with lens operators.
The actual Fold
from lens is more general:
type Fold s a = forall f. (Contravariant f, Applicative f) => (a -> f a) -> s -> f s
There are several functions in lens that accept lens's Fold
but won't accept SimpleFold
; I'm aware of
takingWhile
,
droppingWhile
,
backwards
,
foldByOf
,
foldMapByOf
.
For this reason, try not to export SimpleFold
s if at all possible. microlens-contra provides a fully lens-compatible Fold
.
Lens users: you can convert a SimpleFold
to Fold
by applying folded . toListOf
to it.
(^..) :: s -> Getting (Endo [a]) s a -> [a] infixl 8 Source #
s ^.. t
returns the list of all values that t
gets from s
.
A Maybe
contains either 0 or 1 values:
>>>
Just 3 ^.. _Just
[3]
Gathering all values in a list of tuples:
>>>
[(1,2),(3,4)] ^.. each.each
[1,2,3,4]
(^?) :: s -> Getting (First a) s a -> Maybe a infixl 8 Source #
s ^? t
returns the 1st element t
returns, or Nothing
if t
doesn't return anything. It's trivially implemented by passing the First
monoid to the getter.
Safe head
:
>>>
[] ^? each
Nothing
>>>
[1..3] ^? each
Just 1
>>>
Left 1 ^? _Right
Nothing
>>>
Right 1 ^? _Right
Just 1
A non-operator version of (^?
) is called preview
, and – like view
– it's a bit more general than (^?
) (it works in MonadReader
). If you need the general version, you can get it from microlens-mtl; otherwise there's preview
available in Lens.Micro.Extras.
traverseOf_ :: Functor f => Getting (Traversed r f) s a -> (a -> f r) -> s -> f () Source #
Apply an action to all targets and discard the result (like mapM_
or traverse_
):
>>>
traverseOf_ both putStrLn ("hello", "world")
hello world
Works with anything that allows getting, including lenses and getters (so, anything except for ASetter
). Should be faster than traverseOf
when you don't need the result.
forOf_ :: Functor f => Getting (Traversed r f) s a -> s -> (a -> f r) -> f () Source #
traverseOf_
with flipped arguments. Useful if the “loop body” is a lambda
or a do
block, or in some other cases – for instance, you can avoid
accidentally using for_
on a tuple or Either
by switching
to
. Or you can write custom loops like these:forOf_
each
forOf_
both
(a, b) $ \x -> ...forOf_
each
[1..10] $ \x -> ...forOf_
(each
._Right
) $ \x -> ...
has :: Getting Any s a -> s -> Bool Source #
has
checks whether a getter (any getter, including lenses, traversals, and folds) returns at least 1 value.
Checking whether a list is non-empty:
>>>
has each []
False
You can also use it with e.g. _Left
(and other 0-or-1 traversals) as a replacement for isNothing
, isJust
and other isConstructorName
functions:
>>>
has _Left (Left 1)
True
folded :: Foldable f => SimpleFold (f a) a Source #
folding :: Foldable f => (s -> f a) -> SimpleFold s a Source #
Lens: a combined getter-and-setter
Lenses are composable “pointers” at values inside some bigger structure (e.g. _1
points at the first element of a tuple). You can use (^.
) to get, (.~
) to set, and (%~
) to modify:
>>>
(1,2) ^. _1
1>>>
(1,2) & _1 .~ 3
(3,2)>>>
(1,2) & _1 %~ negate
(-1,2)
To apply a monadic action (or an Applicative
action, or even a Functor
action) to the pointed value, just apply the lens directly or use traverseOf
(or traverseOf_
if you don't need the result):
>>>
traverseOf_ _1 print (1,2)
1
>>>
_1 id (Just 1, 2)
Just (1, 2)>>>
_1 id (Nothing, 2)
Nothing
A Lens
can only point at a single value inside a structure (unlike a Traversal
).
(.
) composes lenses (i.e. if a B
is a part of A
, and a C
is a part of B
, then b.c
lets you operate on C
inside A
). You can create lenses with lens
, or you can write them by hand.
There are several ways to get lenses for some datatype:
- They can already be provided by the package, by
microlens
, or by some other package like microlens-platform. - They can be provided by some unofficial package (like microlens-aeson).
- You can get them by combining already existing lenses.
- You can derive them with Template Haskell (with microlens-th).
- You can write them with
lens
if you have a setter and a getter. It's a simple and good way. - You can write them manually (sometimes it looks a bit better than the variant with
lens
, sometimes worse). The generic template is as follows:
somelens :: Lens s t a b
-- “f” is the “a -> f b” function, “s” is the structure.
somelens f s =
let
a = ... -- Extract the value from “s”.
rebuildWith b = ... -- Write a function which would
-- combine “s” and modified value
-- to produce new structure.
in
rebuildWith <$>
f a -- Apply the structure-producing
-- function to the modified value.
Here's the _1
lens, for instance:
_1
::Lens
(a, x) (b, x) a b_1
f (a, x) = (\b -> (b, x))<$>
f a
Here's a more complicated lens, which extracts several values from a structure (in a tuple):
type Age = Int type City = String type Country = String data Person = Person Age City Country -- This lens lets you access all location-related information about a person. location ::Lens'
Person (City, Country) location f (Person age city country) = (\(city', country') -> Person age city' country')<$>
f (city, country)
You even can choose to use a lens to present all information contained in the structure (in a different way). Such lenses are called Iso
in lens's terminology. For instance (assuming you don't mind functions that can error out), here's a lens which lets you act on the string representation of a value:
string :: (Read a, Show a) =>Lens'
a String string f s = read<$>
f (show s)
Using it to reverse a number:
>>> 123&
string%~
reverse 321
type Lens s t a b = forall f. Functor f => (a -> f b) -> s -> f t Source #
Lens s t a b
is the lowest common denominator of a setter and a getter, something that has the power of both; it has a Functor
constraint, and since both Const
and Identity
are functors, it can be used whenever a getter or a setter is needed.
a
is the type of the value inside of structureb
is the type of the replaced values
is the type of the whole structuret
is the type of the structure after replacinga
in it withb
type Lens' s a = Lens s s a a Source #
This is a type alias for monomorphic lenses which don't change the type of the container (or of the value inside).
lens :: (s -> a) -> (s -> b -> t) -> Lens s t a b Source #
lens
creates a Lens
from a getter and a setter. The resulting lens isn't the most effective one (because of having to traverse the structure twice when modifying), but it shouldn't matter much.
A (partial) lens for list indexing:
ix :: Int ->Lens'
[a] a ix i =lens
(!!
i) -- getter (\s b -> take i s ++ b : drop (i+1) s) -- setter
Usage:
>>> [1..9]^.
ix 3 4 >>> [1..9] & ix 3%~
negate [1,2,3,-4,5,6,7,8,9]
When getting, the setter is completely unused; when setting, the getter is unused. Both are used only when the value is being modified. For instance, here we define a lens for the 1st element of a list, but instead of a legitimate getter we use undefined
. Then we use the resulting lens for setting and it works, which proves that the getter wasn't used:
>>>
[1,2,3] & lens undefined (\s b -> b : tail s) .~ 10
[10,2,3]
at :: At m => Index m -> Lens' m (Maybe (IxValue m)) Source #
This lens lets you read, write, or delete elements in Map
-like structures. It returns Nothing
when the value isn't found, just like lookup
:
Data.Map.lookup k m = m ^.
at k
However, it also lets you insert and delete values by setting the value to
or Just
valueNothing
:
Data.Map.insert k a m = m&
at k.~
Just a Data.Map.delete k m = m&
at k.~
Nothing
Or you could use (?~
) instead of (.~
):
Data.Map.insert k a m = m&
at k?~
a
Note that at
doesn't work for arrays or lists. You can't delete an arbitrary element from an array (what would be left in its place?), and you can't set an arbitrary element in a list because if the index is out of list's bounds, you'd have to somehow fill the stretch between the last element and the element you just inserted (i.e. [1,2,3] & at 10 .~ 5
is undefined). If you want to modify an already existing value in an array or list, you should use ix
instead.
at
is often used with non
. See the documentation of non
for examples.
Note that at
isn't strict for Map
, even if you're using Data.Map.Strict
:
>>>
Data.Map.Strict.size (Data.Map.Strict.empty & at 1 .~ Just undefined)
1
The reason for such behavior is that there's actually no “strict Map
” type; Data.Map.Strict
just provides some strict functions for ordinary Map
s.
This package doesn't actually provide any instances for at
, but there are instances for Map
and IntMap
in microlens-ghc and an instance for HashMap
in microlens-platform.
_1 :: Field1 s t a b => Lens s t a b Source #
Gives access to the 1st field of a tuple (up to 5-tuples).
Getting the 1st component:
>>>
(1,2,3,4,5) ^. _1
1
Setting the 1st component:
>>>
(1,2,3) & _1 .~ 10
(10,2,3)
Note that this lens is lazy, and can set fields even of undefined
:
>>>
set _1 10 undefined :: (Int, Int)
(10,*** Exception: Prelude.undefined
This is done to avoid violating a lens law stating that you can get back what you put:
>>>
view _1 . set _1 10 $ (undefined :: (Int, Int))
10
The implementation (for 2-tuples) is:
_1
f t = (,)<$>
f (fst
t)<*>
pure
(snd
t)
or, alternatively,
_1
f ~(a,b) = (\a' -> (a',b))<$>
f a
(where ~
means a lazy pattern).
Iso: a lens that only changes the representation
Isos (or isomorphisms) are lenses that convert a value instead of targeting a part of it; in other words, inside of every list lives a reversed list, inside of every strict Text
lives a lazy Text
, and inside of every (a, b)
lives a (b, a)
. Since an isomorphism doesn't lose any information, it's possible to reverse it and use it in the opposite direction by using from
from the lens library:
from :: Iso' s a -> Iso' a s
However, it's not possible for microlens to export isomorphisms, because their type depends on Profunctor
, which resides in the profunctors library, which is a somewhat huge dependency. So, all isomorphisms included here are lenses instead (and thus you can't use them in the opposite direction).
strict :: Strict lazy strict => Lens' lazy strict Source #
strict
lets you convert between strict and lazy versions of a datatype:
>>>
let someText = "hello" :: Lazy.Text
>>>
someText ^. strict
"hello" :: Strict.Text
It can also be useful if you have a function that works on a strict type but your type is lazy:
stripDiacritics :: Strict.Text -> Strict.Text stripDiacritics = ...
>>>
let someText = "Paul Erdős" :: Lazy.Text
>>>
someText & strict %~ stripDiacritics
"Paul Erdos" :: Lazy.Text
strict
works on ByteString
and StateT
/WriterT
/RWST
if you use microlens-ghc, and additionally on Text
if you use microlens-platform.
non :: Eq a => a -> Lens' (Maybe a) a Source #
non
lets you “relabel” a Maybe
by equating Nothing
to an arbitrary value (which you can choose):
>>>
Just 1 ^. non 0
1
>>>
Nothing ^. non 0
0
The most useful thing about non
is that relabeling also works in other direction. If you try to set
the “forbidden” value, it'll be turned to Nothing
:
>>>
Just 1 & non 0 .~ 0
Nothing
Setting anything else works just fine:
>>>
Just 1 & non 0 .~ 5
Just 5
Same happens if you try to modify a value:
>>>
Just 1 & non 0 %~ subtract 1
Nothing
>>>
Just 1 & non 0 %~ (+ 1)
Just 2
non
is often useful when combined with at
. For instance, if you have a map of songs and their playcounts, it makes sense not to store songs with 0 plays in the map; non
can act as a filter that wouldn't pass such entries.
Decrease playcount of a song to 0, and it'll be gone:
>>>
fromList [("Soon",1),("Yesterday",3)] & at "Soon" . non 0 %~ subtract 1
fromList [("Yesterday",3)]
Try to add a song with 0 plays, and it won't be added:
>>>
fromList [("Yesterday",3)] & at "Soon" . non 0 .~ 0
fromList [("Yesterday",3)]
But it will be added if you set any other number:
>>>
fromList [("Yesterday",3)] & at "Soon" . non 0 .~ 1
fromList [("Soon",1),("Yesterday",3)]
non
is also useful when working with nested maps. Here a nested map is created when it's missing:
>>>
Map.empty & at "Dez Mona" . non Map.empty . at "Soon" .~ Just 1
fromList [("Dez Mona",fromList [("Soon",1)])]
and here it is deleted when its last entry is deleted (notice that non
is used twice here):
>>>
fromList [("Dez Mona",fromList [("Soon",1)])] & at "Dez Mona" . non Map.empty . at "Soon" . non 0 %~ subtract 1
fromList []
To understand the last example better, observe the flow of values in it:
- the map goes into
at "Dez Mona"
- the nested map (wrapped into
Just
) goes intonon Map.empty
Just
is unwrapped and the nested map goes intoat "Soon"
Just 1
is unwrapped bynon 0
Then the final value – i.e. 1 – is modified by subtract 1
and the result (which is 0) starts flowing backwards:
non 0
sees the 0 and produces aNothing
at "Soon"
seesNothing
and deletes the corresponding value from the map- the resulting empty map is passed to
non Map.empty
, which sees that it's empty and thus producesNothing
at "Dez Mona"
seesNothing
and removes the key from the map
Traversal: a lens iterating over several elements
Traversals are like lenses but they can point at multiple values. Use (^..
) to get all values, (^?
) to get the 1st value, (.~
) to set values, (%~
) to modify them. (.
) composes traversals just as it composes lenses. (^.
) can be used with traversals as well, but don't confuse it with (^..
) – (^..
) gets all traversed values, (^.
) combines traversed values using the (<>
) operation (if the values are instances of Monoid
; if they aren't, it won't compile). traverseOf
and traverseOf_
apply an action to all pointed values of a traversal.
Traversals don't differ from lenses when it comes to setting – you can use usual (%~
) and (.~
) to modify and set values. Getting is a bit different, because you have to decide what to do in the case of multiple values. In particular, you can use these combinators (as well as everything else in the “Folds” section):
- (
^..
) gets a list of values - (
^?
) gets the 1st value (orNothing
if there are no values) - (
^?!
) gets the 1st value and throws an exception if there are no values
If you are sure that the traversal will traverse at least one value, you can convert it to a lens with singular
.
traversed
is a universal traversal for anything that belongs to the Traversable
typeclass. However, in many cases each
works as well and is shorter and nicer-looking.
type Traversal s t a b = forall f. Applicative f => (a -> f b) -> s -> f t Source #
Traversal s t a b
is a generalisation of Lens
which allows many targets (possibly 0). It's achieved by changing the constraint to Applicative
instead of Functor
– indeed, the point of Applicative
is that you can combine effects, which is just what we need to have many targets.
Ultimately, traversals should follow 2 laws:
t pure ≡ pure fmap (t f) . t g ≡ getCompose . t (Compose . fmap f . g)
The 1st law states that you can't change the shape of the structure or do anything funny with elements (traverse elements which aren't in the structure, create new elements out of thin air, etc.). The 2nd law states that you should be able to fuse 2 identical traversals into one. For a more detailed explanation of the laws, see this blog post (if you prefer rambling blog posts), or The Essence Of The Iterator Pattern (if you prefer papers).
Traversing any value twice is a violation of traversal laws. You can, however, traverse values in any order.
type Traversal' s a = Traversal s s a a Source #
This is a type alias for monomorphic traversals which don't change the type of the container (or of the values inside).
traverseOf :: LensLike f s t a b -> (a -> f b) -> s -> f t Source #
Apply an action to all targets (like mapM
or traverse
):
>>>
traverseOf both readFile ("file1", "file2")
(<contents of file1>, <contents of file2>)
>>>
traverseOf _1 id (Just 1, 2)
Just (1, 2)>>>
traverseOf _1 id (Nothing, 2)
Nothing
You can also just apply the lens/traversal directly (but traverseOf
might be more readable):
>>>
both readFile ("file1", "file2")
(<contents of file1>, <contents of file2>)
If you don't need the result, use traverseOf_
.
forOf :: LensLike f s t a b -> s -> (a -> f b) -> f t Source #
traverseOf
with flipped arguments. Useful if the “loop body” is a lambda or
a do
block.
singular :: HasCallStack => Traversal s t a a -> Lens s t a a Source #
singular
turns a traversal into a lens that behaves like a single-element traversal:
>>>
[1,2,3] ^. singular each
1
>>>
[1,2,3] & singular each %~ negate
[-1,2,3]
If there is nothing to return, it'll throw an error:
>>>
[] ^. singular each
*** Exception: Lens.Micro.singular: empty traversal
However, it won't fail if you are merely setting the value:
>>>
[] & singular each %~ negate
failing :: Traversal s t a b -> Traversal s t a b -> Traversal s t a b infixl 5 Source #
failing
lets you chain traversals together; if the 1st traversal fails, the 2nd traversal will be used.
>>>
([1,2],[3]) & failing (_1.each) (_2.each) .~ 0
([0,0],[3])
>>>
([],[3]) & failing (_1.each) (_2.each) .~ 0
([],[0])
Note that the resulting traversal won't be valid unless either both traversals don't touch each others' elements, or both traversals return exactly the same results. To see an example of how failing
can generate invalid traversals, see this Stackoverflow question.
filtered :: (a -> Bool) -> Traversal' a a Source #
filtered
is a traversal that filters elements “passing” through it:
>>>
(1,2,3,4) ^.. each
[1,2,3,4]
>>>
(1,2,3,4) ^.. each . filtered even
[2,4]
It also can be used to modify elements selectively:
>>>
(1,2,3,4) & each . filtered even %~ (*100)
(1,200,3,400)
The implementation of filtered
is very simple. Consider this traversal, which always “traverses” just the value it's given:
id :: Traversal'
a a
id f s = f s
And this traversal, which traverses nothing (in other words, doesn't traverse the value it's given):
ignored ::Traversal'
a a ignored f s =pure
s
And now combine them into a traversal that conditionally traverses the value it's given, and you get filtered
:
filtered :: (a -> Bool) ->Traversal'
a a filtered p f s = if p s then f s elsepure
s
By the way, note that filtered
can generate illegal traversals – sometimes this can bite you. In particular, an optimisation that should be safe becomes unsafe. (To the best of my knowledge, this optimisation never happens automatically. If you just use filtered
to modify/view something, you're safe. If you don't define any traversals that use filtered
, you're safe too.)
Let's use evens
as an example:
evens =filtered
even
If evens
was a legal traversal, you'd be able to fuse several applications of evens
like this:
over
evens f.
over
evens g =over
evens (f.
g)
Unfortunately, in case of evens
this isn't a correct optimisation:
- the left-side variant applies
g
to all even numbers, and then appliesf
to all even numbers that are left afterf
(becausef
might've turned some even numbers into odd ones) - the right-side variant applies
f
andg
to all even numbers
Of course, when you are careful and know what you're doing, you won't try to make such an optimisation. However, if you export an illegal traversal created with filtered
and someone tries to use it, they might mistakenly assume that it's legal, do the optimisation, and silently get an incorrect result.
If you are using filtered
with some another traversal that doesn't overlap with -whatever the predicate checks-, the resulting traversal will be legal. For instance, here the predicate looks at the 1st element of a tuple, but the resulting traversal only gives you access to the 2nd:
pairedWithEvens ::Traversal
[(Int, a)] [(Int, b)] a b pairedWithEvens =each
.
filtered
(even
.
fst
).
_2
Since you can't do anything with the 1st components through this traversal, the following holds for any f
and g
:
over
pairedWithEvens f.
over
pairedWithEvens g =over
pairedWithEvens (f.
g)
traversed :: Traversable f => Traversal (f a) (f b) a b Source #
traversed
traverses any Traversable
container (list, vector, Map
, Maybe
, you name it):
>>>
Just 1 ^.. traversed
[1]
traversed
is the same as traverse
, but can be faster thanks to magic rewrite rules.
each :: Each s t a b => Traversal s t a b Source #
each
tries to be a universal Traversal
– it behaves like traversed
in most situations, but also adds support for e.g. tuples with same-typed values:
>>>
(1,2) & each %~ succ
(2,3)
>>>
["x", "y", "z"] ^. each
"xyz"
However, note that each
doesn't work on every instance of Traversable
. If you have a Traversable
which isn't supported by each
, you can use traversed
instead. Personally, I like using each
instead of traversed
whenever possible – it's shorter and more descriptive.
You can use each
with these things:
each
::Traversal
[a] [b] a beach
::Traversal
(Maybe
a) (Maybe
b) a beach
::Traversal
(a,a) (b,b) a beach
::Traversal
(a,a,a) (b,b,b) a beach
::Traversal
(a,a,a,a) (b,b,b,b) a beach
::Traversal
(a,a,a,a,a) (b,b,b,b,b) a beach
:: (RealFloat
a,RealFloat
b) =>Traversal
(Complex
a) (Complex
b) a b
You can also use each
with types from array, bytestring, and containers by using microlens-ghc, or additionally with types from vector, text, and unordered-containers by using microlens-platform.
ix :: Ixed m => Index m -> Traversal' m (IxValue m) Source #
This traversal lets you access (and update) an arbitrary element in a list, array, Map
, etc. (If you want to insert or delete elements as well, look at at
.)
An example for lists:
>>>
[0..5] & ix 3 .~ 10
[0,1,2,10,4,5]
You can use it for getting, too:
>>>
[0..5] ^? ix 3
Just 3
Of course, the element may not be present (which means that you can use ix
as a safe variant of (!!
)):
>>>
[0..5] ^? ix 10
Nothing
Another useful instance is the one for functions – it lets you modify their outputs for specific inputs. For instance, here's maximum
that returns 0 when the list is empty (instead of throwing an exception):
maximum0 =maximum
&
ix
[].~
0
The following instances are provided in this package:
ix
::Int
->Traversal'
[a] aix
:: (Eq
e) => e ->Traversal'
(e -> a) a
You can also use ix
with types from array, bytestring, and containers by using microlens-ghc, or additionally with types from vector, text, and unordered-containers by using microlens-platform.
_head :: Cons s s a a => Traversal' s a Source #
_head
traverses the 1st element of something (usually a list, but can also be a Seq
, etc):
>>>
[1..5] ^? _head
Just 1
It can be used to modify too, as in this example where the 1st letter of a sentence is capitalised:
>>>
"mary had a little lamb." & _head %~ toTitle
"Mary had a little lamb."
The reason it's a traversal and not a lens is that there's nothing to traverse when the list is empty:
>>>
[] ^? _head
Nothing
This package only lets you use _head
on lists, but if you use microlens-ghc you get instances for ByteString
and Seq
, and if you use microlens-platform you additionally get instances for Text
and Vector
.
_tail :: Cons s s a a => Traversal' s s Source #
_tail
gives you access to the tail of a list (or Seq
, etc):
>>>
[1..5] ^? _tail
Just [2,3,4,5]
You can modify the tail as well:
>>>
[4,1,2,3] & _tail %~ reverse
[4,3,2,1]
Since lists are monoids, you can use _tail
with plain (^.
) (and then it'll return an empty list if you give it an empty list):
>>>
[1..5] ^. _tail
[2,3,4,5]
>>>
[] ^. _tail
[]
If you want to traverse each element of the tail, use _tail
with each
:
>>>
"I HATE CAPS." & _tail.each %~ toLower
"I hate caps."
This package only lets you use _tail
on lists, but if you use microlens-ghc you get instances for ByteString
and Seq
, and if you use microlens-platform you additionally get instances for Text
and Vector
.
_init :: Snoc s s a a => Traversal' s s Source #
_last :: Snoc s s a a => Traversal' s a Source #
mapAccumLOf :: LensLike (State acc) s t a b -> (acc -> a -> (acc, b)) -> acc -> s -> (acc, t) Source #
This generalizes mapAccumL
to an arbitrary Traversal
. (Note that it doesn't work on folds, only traversals.)
mapAccumL
≡mapAccumLOf
traverse
Prism: a traversal iterating over at most 1 element
Prisms are traversals that always target 0 or 1 values. Moreover, it's possible to reverse a prism, using it to construct a structure instead of peeking into it. Here's an example from the lens library:
>>> over _Left (+1) (Left 2) Left 3 >>> _Left # 5 Left 5
However, it's not possible for microlens to export prisms, because their type depends on Choice
from profunctors. So, all prisms included here are traversals instead (and you can't reverse them).
_Left :: Traversal (Either a b) (Either a' b) a a' Source #
_Left
targets the value contained in an Either
, provided it's a Left
.
Gathering all Left
s in a structure (like the lefts
function, but not necessarily just for lists):
>>>
[Left 1, Right 'c', Left 3] ^.. each._Left
[1,3]
Checking whether an Either
is a Left
(like isLeft
):
>>>
has _Left (Left 1)
True
>>>
has _Left (Right 1)
False
Extracting a value (if you're sure it's a Left
):
>>>
Left 1 ^?! _Left
1
Mapping over all Left
s:
>>>
(each._Left %~ map toUpper) [Left "foo", Right "bar"]
[Left "FOO",Right "bar"]
Implementation:
_Left
f (Left a) =Left
<$>
f a_Left
_ (Right b) =pure
(Right
b)
_Just :: Traversal (Maybe a) (Maybe a') a a' Source #
_Just
targets the value contained in a Maybe
, provided it's a Just
.
See documentation for _Left
(as these 2 are pretty similar). In particular, it can be used to write these:
- Unsafely extracting a value from a
Just
:
fromJust
= (^?!
_Just
)
- Checking whether a value is a
Just
:
isJust
=has
_Just
- Converting a
Maybe
to a list (empty or consisting of a single element):
maybeToList
= (^..
_Just
)
- Gathering all
Just
s in a list:
catMaybes
= (^..
each
.
_Just
)
_Nothing :: Traversal' (Maybe a) () Source #
_Nothing
targets a ()
if the Maybe
is a Nothing
, and doesn't target anything otherwise:
>>>
Just 1 ^.. _Nothing
[]
>>>
Nothing ^.. _Nothing
[()]
It's not particularly useful (unless you want to use
as a replacement for has
_Nothing
isNothing
), and provided mainly for consistency.
Implementation:
_Nothing
f Nothing =const
Nothing
<$>
f ()_Nothing
_ j =pure
j
Other types
type LensLike f s t a b = (a -> f b) -> s -> f t Source #
LensLike
is a type that is often used to make combinators as general as possible. For instance, take (<<%~
), which only requires the passed lens to be able to work with the (,) a
functor (lenses and traversals can do that). The fully expanded type is as follows:
(<<%~
) :: ((a -> (a, b)) -> s -> (a, t)) -> (a -> b) -> s -> (a, t)
With LensLike
, the intent to use the (,) a
functor can be made a bit clearer:
(<<%~
) :: LensLike ((,) a) s t a b -> (a -> b) -> s -> (a, t)