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

Stability | provisional |

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

Safe Haskell | Safe-Infered |

This package provides lens families, setters, getters, traversals and folds that
can all be composed automatically with each other (and other lenses from
other van Laarhoven lens libraries) using `(.)`

from Prelude, while
reducing the complexity of the API.

For a longer description and motivation of why you should care about lens families, see http://comonad.com/reader/2012/mirrored-lenses/.

Note: If you merely want your library to *provide* lenses you may not
have to actually import *any* lens library. For, say, a

, just export a function with the signature:
`Simple`

`Lens`

Bar Foo

foo :: Functor f => (Foo -> f Foo) -> Bar -> f Bar

and then you can compose it with other lenses with `(.)`

without needing
anything from this library at all.

Usage:

You can derive lenses automatically for many data types:

import Control.Lens.TH data Foo a = Foo { _fooArgs :: [String], _fooValue :: a } makeLenses ''Foo

This defines the following lenses:

fooArgs :: Simple Lens (Foo a) [String] fooValue :: Lens (Foo a) (Foo b) a b

The combinators here have unusually specific type signatures, so for particularly tricky ones, I've tried to list the simpler type signatures you might want to pretend the combinators have.

- type Lens a b c d = forall f. Functor f => (c -> f d) -> a -> f b
- type LensLike f a b c d = (c -> f d) -> a -> f b
- type Simple f a b = f a a b b
- lens :: (a -> c) -> (d -> a -> b) -> Lens a b c d
- iso :: (a -> c) -> (d -> b) -> Lens a b c d
- clone :: Functor f => LensLike (IndexedStore c d) a b c d -> (c -> f d) -> a -> f b
- type Getter a b c d = forall z. (c -> Const z d) -> a -> Const z b
- type Getting r a b c d = (c -> Const r d) -> a -> Const r b
- to :: (a -> c) -> Getter a b c d
- view :: Getting c a b c d -> a -> c
- views :: Getting m a b c d -> (c -> m) -> a -> m
- (^.) :: a -> Getting c a b c d -> c
- (^$) :: Getting c a b c d -> a -> c
- type Setter a b c d = (c -> Identity d) -> a -> Identity b
- sets :: ((c -> d) -> a -> b) -> Setter a b c d
- mapped :: Functor f => Setter (f a) (f b) a b
- adjust :: Setter a b c d -> (c -> d) -> a -> b
- set :: Setter a b c d -> d -> a -> b
- (=%=) :: Setter a b c d -> (c -> d) -> a -> b
- (=~=) :: Setter a b c d -> d -> a -> b
- (=+=) :: Num c => Setter a b c c -> c -> a -> b
- (=-=) :: Num c => Setter a b c c -> c -> a -> b
- (=*=) :: Num c => Setter a b c c -> c -> a -> b
- (=/=) :: Fractional c => Setter a b c c -> c -> a -> b
- (=||=) :: Setter a b Bool Bool -> Bool -> a -> b
- (=&&=) :: Setter a b Bool Bool -> Bool -> a -> b
- (=|=) :: Bits c => Setter a b c c -> c -> a -> b
- (=&=) :: Bits c => Setter a b c c -> c -> a -> b
- access :: MonadState a m => Getting c a b c d -> m c
- (%=) :: MonadState a m => Setter a a c d -> (c -> d) -> m ()
- (~=) :: MonadState a m => Setter a a c d -> d -> m ()
- (+=) :: (MonadState a m, Num b) => Simple Setter a b -> b -> m ()
- (-=) :: (MonadState a m, Num b) => Simple Setter a b -> b -> m ()
- (*=) :: (MonadState a m, Num b) => Simple Setter a b -> b -> m ()
- (//=) :: (MonadState a m, Fractional b) => Simple Setter a b -> b -> m ()
- (||=) :: MonadState a m => Simple Setter a Bool -> Bool -> m ()
- (&&=) :: MonadState a m => Simple Setter a Bool -> Bool -> m ()
- (|=) :: (MonadState a m, Bits b) => Simple Setter a b -> b -> m ()
- (&=) :: (MonadState a m, Bits b) => Simple Setter a b -> b -> m ()
- (%%=) :: MonadState a m => LensLike ((,) c) a a b b -> (b -> (c, b)) -> m c
- class Focus st where
- _1 :: Lens (a, c) (b, c) a b
- _2 :: Lens (c, a) (c, b) a b
- valueAt :: Ord k => k -> Simple Lens (Map k v) (Maybe v)
- valueAtInt :: Int -> Simple Lens (IntMap v) (Maybe v)
- bitAt :: Bits b => Int -> Simple Lens b Bool
- contains :: Ord k => k -> Simple Lens (Set k) Bool
- containsInt :: Int -> Simple Lens IntSet Bool
- identity :: Lens (Identity a) (Identity b) a b
- resultAt :: Eq e => e -> Simple Lens (e -> a) a
- real :: Simple Lens (Complex a) a
- imaginary :: Simple Lens (Complex a) a
- polarize :: RealFloat a => Simple Lens (Complex a) (a, a)
- type Fold a b c d = forall m. Monoid m => (c -> Const m d) -> a -> Const m b
- folded :: Foldable f => Fold (f c) b c d
- filtered :: Monoid m => (c -> Bool) -> Getting m a b c d -> Getting m a b c d
- reversed :: Getting (Dual m) a b c d -> Getting m a b c d
- foldMapOf :: Getting m a b c d -> (c -> m) -> a -> m
- foldOf :: Getting m a b m d -> a -> m
- foldrOf :: Getting (Endo e) a b c d -> (c -> e -> e) -> e -> a -> e
- foldlOf :: Getting (Dual (Endo e)) a b c d -> (e -> c -> e) -> e -> a -> e
- foldrOf' :: Getting (Dual (Endo (e -> e))) a b c d -> (c -> e -> e) -> e -> a -> e
- foldlOf' :: Getting (Endo (e -> e)) a b c d -> (e -> c -> e) -> e -> a -> e
- foldr1Of :: Getting (Endo (Maybe c)) a b c d -> (c -> c -> c) -> a -> c
- foldl1Of :: Getting (Dual (Endo (Maybe c))) a b c d -> (c -> c -> c) -> a -> c
- foldrMOf :: Monad m => Getting (Dual (Endo (e -> m e))) a b c d -> (c -> e -> m e) -> e -> a -> m e
- foldlMOf :: Monad m => Getting (Endo (e -> m e)) a b c d -> (e -> c -> m e) -> e -> a -> m e
- toListOf :: Getting [c] a b c d -> a -> [c]
- anyOf :: Getting Any a b c d -> (c -> Bool) -> a -> Bool
- allOf :: Getting All a b c d -> (c -> Bool) -> a -> Bool
- andOf :: Getting All a b Bool d -> a -> Bool
- orOf :: Getting Any a b Bool d -> a -> Bool
- productOf :: Getting (Product c) a b c d -> a -> c
- sumOf :: Getting (Sum c) a b c d -> a -> c
- traverseOf_ :: Functor f => Getting (Traversed f) a b c d -> (c -> f e) -> a -> f ()
- forOf_ :: Functor f => Getting (Traversed f) a b c d -> a -> (c -> f e) -> f ()
- sequenceAOf_ :: Functor f => Getting (Traversed f) a b (f ()) d -> a -> f ()
- mapMOf_ :: Monad m => Getting (Traversed (WrappedMonad m)) a b c d -> (c -> m e) -> a -> m ()
- forMOf_ :: Monad m => Getting (Traversed (WrappedMonad m)) a b c d -> a -> (c -> m e) -> m ()
- sequenceOf_ :: Monad m => Getting (Traversed (WrappedMonad m)) a b (m c) d -> a -> m ()
- asumOf :: Alternative f => Getting (Endo (f c)) a b (f c) d -> a -> f c
- msumOf :: MonadPlus m => Getting (Endo (m c)) a b (m c) d -> a -> m c
- concatMapOf :: Getting [e] a b c d -> (c -> [e]) -> a -> [e]
- concatOf :: Getting [e] a b [e] d -> a -> [e]
- elemOf :: Eq c => Getting Any a b c d -> c -> a -> Bool
- notElemOf :: Eq c => Getting All a b c d -> c -> a -> Bool
- lengthOf :: Getting (Sum Int) a b c d -> a -> Int
- nullOf :: Getting All a b c d -> a -> Bool
- maximumOf :: Getting (Max c) a b c d -> a -> Maybe c
- minimumOf :: Getting (Min c) a b c d -> a -> Maybe c
- maximumByOf :: Getting (Endo (Maybe c)) a b c d -> (c -> c -> Ordering) -> a -> Maybe c
- minimumByOf :: Getting (Endo (Maybe c)) a b c d -> (c -> c -> Ordering) -> a -> Maybe c
- findOf :: Getting (First c) a b c d -> (c -> Bool) -> a -> Maybe c
- type Traversal a b c d = forall f. Applicative f => (c -> f d) -> a -> f b
- traverseNothing :: Traversal a a c d
- traverseValueAt :: Ord k => k -> Simple Traversal (Map k v) v
- traverseValueAtInt :: Int -> Simple Traversal (IntMap v) v
- traverseHead :: Simple Traversal [a] a
- traverseTail :: Simple Traversal [a] [a]
- traverseLast :: Simple Traversal [a] a
- traverseInit :: Simple Traversal [a] [a]
- traverseLeft :: Traversal (Either a c) (Either b c) a b
- traverseRight :: Traversal (Either c a) (Either c b) a b
- traverseElement :: Traversable t => Int -> Simple Traversal (t a) a
- traverseElements :: Traversable t => (Int -> Bool) -> Simple Traversal (t a) a
- class TraverseByteString t where
- class TraverseText t where
- traverseText :: Simple Traversal t Char

- class TraverseValueAtMin t where
- traverseValueAtMin :: Simple Traversal (t v) v

- class TraverseValueAtMax t where
- traverseValueAtMax :: Simple Traversal (t v) v

- traverseBits :: Bits b => Simple Traversal b Bool
- traverseDynamic :: (Typeable a, Typeable b) => Traversal Dynamic Dynamic a b
- traverseException :: (Exception a, Exception b) => Traversal SomeException SomeException a b
- traverseOf :: LensLike f a b c d -> (c -> f d) -> a -> f b
- mapMOf :: LensLike (WrappedMonad m) a b c d -> (c -> m d) -> a -> m b
- sequenceAOf :: Applicative f => LensLike f a b (f c) (f c) -> a -> f b
- sequenceOf :: Monad m => LensLike (WrappedMonad m) a b (m c) (m c) -> a -> m b
- elementOf :: Applicative f => LensLike (AppliedState f) a b c c -> Int -> (c -> f c) -> a -> f b
- elementsOf :: Applicative f => LensLike (AppliedState f) a b c c -> (Int -> Bool) -> (c -> f c) -> a -> f b
- transposeOf :: LensLike ZipList a b [c] c -> a -> [b]

# Lenses

type Lens a b c d = forall f. Functor f => (c -> f d) -> a -> f bSource

A `Lens`

is actually a lens family as described in http://comonad.com/reader/2012/mirrored-lenses/.

With great power comes great responsibility and a `Lens`

is subject to the lens laws:

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

These laws are strong enough that the 4 type parameters of a `Lens`

cannot vary fully independently. For more on
how they interact, read the Why is it a Lens Family? section of http://comonad.com/reader/2012/mirrored-lenses/.

Every `Lens`

can be used directly as a `Getter`

, `Setter`

, `Fold`

or `Traversal`

.

identity :: Lens (Identity a) (Identity b) a b identity f (Identity a) = Identity <$> f a

type LensLike f a b c d = (c -> f d) -> a -> f bSource

Many combinators that accept a `Lens`

can also accept a `Traversal`

in limited situations.

They do so by specializing the type of `Functor`

that they require of the caller.

If a function accepts a

for some `LensLike`

f a b c d`Functor`

`f`

, then they may be passed a `Lens`

.

Further, if `f`

is an `Applicative`

, they may also be passed a `Traversal`

.

# Simple Lenses

## Constructing Lenses

lens :: (a -> c) -> (d -> a -> b) -> Lens a b c dSource

Build a `Lens`

from a getter and a setter.

lens :: Functor f => (a -> c) -> (d -> a -> b) -> (c -> f d) -> a -> f b

iso :: (a -> c) -> (d -> b) -> Lens a b c dSource

Built a `Lens`

from an isomorphism family

iso :: Functor f => (a -> c) -> (d -> b) -> (c -> f d) -> a -> f b

clone :: Functor f => LensLike (IndexedStore c d) a b c d -> (c -> f d) -> a -> f bSource

Cloning a `Lens`

is one way to make sure you arent given
something weaker, such as a `Traversal`

and can be used
as a way to pass around lenses that have to be monomorphic in `f`

.

Note: This only accepts a proper `Lens`

, because `IndexedStore`

lacks its
(admissable) Applicative instance.

# Getters

type Getter a b c d = forall z. (c -> Const z d) -> a -> Const z bSource

A `Getter`

describes how to retrieve a single value in a way that can be composed with
other lens-like constructions.

Unlike a `Lens`

a `Getter`

is read-only. Since a `Getter`

cannot be used to write back
there are no lens laws that can be applied to it.

Moreover, a `Getter`

can be used directly as a `Fold`

, since it just ignores the `Monoid`

.

In practice the `b`

and `d`

are left dangling and unused, and as such is no real point in
using a

.
`Simple`

`Getter`

type Getter a b c d = forall z. LensLike (Const z) a b c d

type Getting r a b c d = (c -> Const r d) -> a -> Const r bSource

Most `Getter`

combinators are able to be used with both a `Getter`

or a `Fold`

in
limited situations, to do so, they need to be monomorphic in what we are going to
extract with `Const`

.

If a function accepts a `Getting r a b c d`

, then when `r`

is a Monoid, you can
pass a `Fold`

(or `Traversal`

), otherwise you can only pass this a `Getter`

or `Lens`

.

type Getting r a b c d = LensLike (Const r) a b c d

## Getting Values

view :: Getting c a b c d -> a -> cSource

View the value pointed to by a `Getter`

or `Lens`

or the result of folding over
all the results of a `Fold`

or `Traversal`

that points at a monoidal values.

It may be useful to think of `view`

as having these more restrictive signatures:

view :: Lens a b c d -> a -> c view :: Getter a b c d -> a -> c view :: Monoid m => Fold a b m d -> a -> m view :: Monoid m => Traversal a b m d -> a -> m

view :: ((c -> Const c d) -> a -> Const c b) -> a -> c

views :: Getting m a b c d -> (c -> m) -> a -> mSource

View the value of a `Getter`

, `Lens`

or the result of folding over the
result of mapping the targets of a `Fold`

or `Traversal`

.

It may be useful to think of `views`

as having these more restrictive signatures:

views :: Getter a b c d -> (c -> d) -> a -> d views :: Lens a b c d -> (c -> d) -> a -> d views :: Monoid m => Fold a b c d -> (c -> m) -> a -> m views :: Monoid m => Traversal a b c d -> (c -> m) -> a -> m

views :: ((c -> Const m d) -> a -> Const m b) -> (c -> m) -> a -> m

(^.) :: a -> Getting c a b c d -> cSource

View the value pointed to by a `Getter`

or `Lens`

or the result of folding over
all the results of a `Fold`

or `Traversal`

that points at a monoidal values.

This is the same operation as `view`

with the arguments flipped.

The fixity and semantics are such that subsequent field accesses can be performed with (Prelude..)

ghci> ((0, 1 :+ 2), 3)^._1._2.to magnitude 2.23606797749979

(^.) :: a -> Lens a b c d -> c (^.) :: a -> Getter a b c d -> c (^.) :: Monoid m => a -> Fold a b m d -> m (^.) :: Monoid m => a -> Traversal a b m d -> m

(^.) :: a -> ((c -> Const c d) -> a -> Const c b) -> c

(^$) :: Getting c a b c d -> a -> cSource

View the value pointed to by a `Getter`

or `Lens`

or the result of folding over
all the results of a `Fold`

or `Traversal`

that points at a monoidal values.

This is the same operation as `view`

, only infix.

(^$) :: Lens a b c d -> a -> c (^$) :: Getter a b c d -> a -> c (^$) :: Monoid m => Fold a b m d -> a -> m (^$) :: Monoid m => Traversal a b m d -> a -> m

(^$) :: ((c -> Const c d) -> a -> Const c b) -> a -> c

# Setters

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

The only `Lens`

-like law that applies 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 do not apply.

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.

type Setter a b c d = LensLike Identity a b c d

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

Build a Setter

sets . adjust = id adjust . sets = id

mapped :: Functor f => Setter (f a) (f b) a bSource

This setter can be used to map over all of the values in a container.

## Setting Values

(=/=) :: Fractional c => Setter a b c c -> c -> a -> bSource

# Manipulating State

access :: MonadState a m => Getting c a b c d -> m cSource

Access the target of a `Lens`

or `Getter`

in the current state, or access a
summary of a `Fold`

or `Traversal`

that points to a monoidal value.

access :: MonadState a m => Getter a b c d -> m c access :: MonadState a m => Lens a b c d -> m c access :: (MonadState a m, Monoid c) => Fold a b c d -> m c access :: (MonadState a m, Monoid c) => Traversal a b c d -> m c

access :: MonadState a m => ((c -> Const c d) -> a -> Const c b) -> m c

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

(~=) :: MonadState a m => Setter a a c d -> d -> m ()Source

(//=) :: (MonadState a m, Fractional b) => Simple Setter a b -> b -> m ()Source

(%%=) :: MonadState a m => LensLike ((,) c) a a b b -> (b -> (c, b)) -> m cSource

Modify the target of a `Lens`

in the current state returning some extra information of `c`

or
modify all targets of a `Traversal`

in the current state, extracting extra information of type `c`

and return a monoidal summary of the changes.

It may be useful to think of '(%%=)', instead, as having either of the following more restricted type signatures:

(%%=) :: MonadState a m => Simple Lens a b -> (b -> (c, b) -> m c (%%=) :: (MonadState a m, Monoid c) => Simple Traversal a b -> (b -> (c, b) -> m c

(%%=) :: MonadState a m => ((b -> (c,b)) -> a -> (c,a)) -> (b -> (c, b)) -> m c

This class allows us to use `focus`

on a number of different monad transformers.

focus :: Monad m => LensLike (Focusing m c) a a b b -> st b m c -> st a m cSource

Run a monadic action in a larger context than it was defined in, using a `Simple`

`Lens`

or 'Simple Traversal'.

This is commonly used to lift actions in a simpler state monad into a state monad with a larger state type.

When applied to a 'Simple `Traversal`

over multiple values, the actions for each target are executed sequentially
and the results are aggregated monoidally
and a monoidal summary
of the result is given.

focus :: Monad m => Simple Lens a b -> st b m c -> st a m c focus :: (Monad m, Monoid c) => Simple Traversal a b -> st b m c -> st a m c

focus_ :: Monad m => LensLike (Focusing m ()) a a b b -> st b m c -> st a m ()Source

Like `focus`

, but discarding any accumulated results as you go.

focus_ :: Monad m => Simple Lens a b -> st b m c -> st a m () focus_ :: (Monad m, Monoid c) => Simple Traversal a b -> st b m c -> st a m ()

## Common Lenses

_1 :: Lens (a, c) (b, c) a bSource

This is a lens that can change the value (and type) of the first field of a pair.

ghci> (1,2)^._1 1

ghci> _1 =+= "hello" $ (1,2) ("hello",2)

_1 :: Functor f => (a -> f b) -> (a,c) -> f (a,c)

_2 :: Lens (c, a) (c, b) a bSource

As `_1`

, but for the second field of a pair.

anyOf _2 :: (c -> Bool) -> (a, c) -> Bool traverse._2 :: (Applicative f, Traversable t) => (a -> f b) -> t (c, a) -> f (t (c, b)) foldMapOf (traverse._2) :: (Traversable t, Monoid m) => (c -> m) -> t (b, c) -> m

_2 :: Functor f => (a -> f b) -> (c,a) -> f (c,b)

valueAtInt :: Int -> Simple Lens (IntMap v) (Maybe v)Source

This `Lens`

can be used to read, write or delete a member of an `IntMap`

.

ghci> IntMap.fromList [(1,"hello")] ^. valueAtInt 1 Just "hello"

ghci> valueAtInt 2 =+= "goodbye" $ IntMap.fromList [(1,"hello")] fromList [(1,"hello"),(2,"goodbye")]

valueAtInt :: Int -> (Maybe v -> f (Maybe v)) -> IntMap v -> f (IntMap v)

bitAt :: Bits b => Int -> Simple Lens b BoolSource

This lens can be used to access the value of the nth bit in a number.

`bitsAt n`

is only a legal `Lens`

into `b`

if `0 <= n < bitSize (undefined :: b)`

identity :: Lens (Identity a) (Identity b) a bSource

This lens can be used to access the contents of the Identity monad

resultAt :: Eq e => e -> Simple Lens (e -> a) aSource

This lens can be used to change the result of a function but only where the arguments match the key given.

real :: Simple Lens (Complex a) aSource

Access the real part of a complex number

real :: Functor f => (a -> f a) -> Complex a -> f (Complex a)

imaginary :: Simple Lens (Complex a) aSource

Access the imaginary part of a complex number

imaginary :: Functor f => (a -> f a) -> Complex a -> f (Complex a)

polarize :: RealFloat a => Simple Lens (Complex a) (a, a)Source

This isn't *quite* a legal lens. Notably the `view l (set l b a) = b`

law
is violated when you set a polar value with 0 magnitude and non-zero phase
as the phase information is lost.

So don't do that. Otherwise this is a perfectly convenient lens.

polarize :: Functor f => ((a,a) -> f (a,a)) -> Complex a -> f (Complex a)

# Folds

type Fold a b c d = forall m. Monoid m => (c -> Const m d) -> a -> Const m bSource

A `Fold`

describes how to retrieve multiple values in a way that can be composed
with other lens-like constructions.

A

provides a structure with operations very similar to those of the `Fold`

a b c d`Foldable`

typeclass, see `foldMapOf`

and the other `Fold`

combinators.

By convention, if there exists a `foo`

method that expects a

, then there should be a
`Foldable`

(f c)`fooOf`

method that takes a

and a value of type `Fold`

a b c d`a`

.

A `Getter`

is a legal `Fold`

that just ignores the supplied `Monoid`

Unlike a `Traversal`

a `Fold`

is read-only. Since a `Fold`

cannot be used to write back
there are no lens laws that can be applied to it.

In practice the `b`

and `d`

are left dangling and unused, and as such is no real point in a

.
`Simple`

`Fold`

type Fold a b c d = forall m. Monoid m => Getting m a b c d

## Common Folds

## Fold Combinators

foldMapOf :: Getting m a b c d -> (c -> m) -> a -> mSource

foldMap = foldMapOf folded

foldMapOf = views

foldMapOf :: Getter a b c d -> (c -> m) -> a -> m foldMapOf :: Lens a b c d -> (c -> m) -> a -> m foldMapOf :: Monoid m => Fold a b c d -> (c -> m) -> a -> m foldMapOf :: Monoid m => Traversal a b c d -> (c -> m) -> a -> m

foldOf :: Getting m a b m d -> a -> mSource

fold = foldOf folded

foldOf = view

foldOf :: Getter a b m d -> a -> m foldOf :: Lens a b m d -> a -> m foldOf :: Monoid m => Fold a b m d -> a -> m foldOf :: Monoid m => Traversal a b m d -> a -> m

foldrOf :: Getting (Endo e) a b c d -> (c -> e -> e) -> e -> a -> eSource

Right-associative fold of parts of a structure that are viewed through a `Lens`

, `Getter`

, `Fold`

or `Traversal`

.

foldr = foldrOf folded

foldrOf :: Getter a b c d -> (c -> e -> e) -> e -> a -> e foldrOf :: Lens a b c d -> (c -> e -> e) -> e -> a -> e foldrOf :: Fold a b c d -> (c -> e -> e) -> e -> a -> e foldrOf :: Traversal a b c d -> (c -> e -> e) -> e -> a -> e

foldlOf :: Getting (Dual (Endo e)) a b c d -> (e -> c -> e) -> e -> a -> eSource

Left-associative fold of the parts of a structure that are viewed through a `Lens`

, `Getter`

, `Fold`

or `Traversal`

.

foldl = foldlOf folded

foldlOf :: Getter a b c d -> (e -> c -> e) -> e -> a -> e foldlOf :: Lens a b c d -> (e -> c -> e) -> e -> a -> e foldlOf :: Fold a b c d -> (e -> c -> e) -> e -> a -> e foldlOf :: Traversal a b c d -> (e -> c -> e) -> e -> a -> e

foldrOf' :: Getting (Dual (Endo (e -> e))) a b c d -> (c -> e -> e) -> e -> a -> eSource

Strictly fold right over the elements of a structure.

foldr' = foldrOf' folded

foldrOf' :: Getter a b c d -> (c -> e -> e) -> e -> a -> e foldrOf' :: Lens a b c d -> (c -> e -> e) -> e -> a -> e foldrOf' :: Fold a b c d -> (c -> e -> e) -> e -> a -> e foldrOf' :: Traversal a b c d -> (c -> e -> e) -> e -> a -> e

foldlOf' :: Getting (Endo (e -> e)) a b c d -> (e -> c -> e) -> e -> a -> eSource

Fold over the elements of a structure, associating to the left, but strictly.

foldl' = foldlOf' folded

foldlOf' :: Getter a b c d -> (e -> c -> e) -> e -> a -> e foldlOf' :: Lens a b c d -> (e -> c -> e) -> e -> a -> e foldlOf' :: Fold a b c d -> (e -> c -> e) -> e -> a -> e foldlOf' :: Traversal a b c d -> (e -> c -> e) -> e -> a -> e

foldr1Of :: Getting (Endo (Maybe c)) a b c d -> (c -> c -> c) -> a -> cSource

A variant of `foldrOf`

that has no base case and thus may only be applied to lenses and structures
such that the lens views at least one element of the structure.

foldr1Of l f = Prelude.foldr1 f . toListOf l

foldr1 = foldr1Of folded

foldr1Of :: Getter a b c d -> (c -> c -> c) -> a -> c foldr1Of :: Lens a b c d -> (c -> c -> c) -> a -> c foldr1Of :: Fold a b c d -> (c -> c -> c) -> a -> c foldr1Of :: Traversal a b c d -> (c -> c -> c) -> a -> c

foldl1Of :: Getting (Dual (Endo (Maybe c))) a b c d -> (c -> c -> c) -> a -> cSource

A variant of `foldlOf`

that has no base case and thus may only be applied to lenses and strutures such
that the lens views at least one element of the structure.

foldl1Of l f = Prelude.foldl1Of l f . toList

foldl1 = foldl1Of folded

foldl1Of :: Getter a b c d -> (c -> c -> c) -> a -> c foldl1Of :: Lens a b c d -> (c -> c -> c) -> a -> c foldl1Of :: Fold a b c d -> (c -> c -> c) -> a -> c foldl1Of :: Traversal a b c d -> (c -> c -> c) -> a -> c

foldrMOf :: Monad m => Getting (Dual (Endo (e -> m e))) a b c d -> (c -> e -> m e) -> e -> a -> m eSource

Monadic fold over the elements of a structure, associating to the right, i.e. from right to left.

foldrM = foldrMOf folded

foldrMOf :: Monad m => Getter a b c d -> (c -> e -> m e) -> e -> a -> m e foldrMOf :: Monad m => Lens a b c d -> (c -> e -> m e) -> e -> a -> m e foldrMOf :: Monad m => Fold a b c d -> (c -> e -> m e) -> e -> a -> m e foldrMOf :: Monad m => Traversal a b c d -> (c -> e -> m e) -> e -> a -> m e

foldlMOf :: Monad m => Getting (Endo (e -> m e)) a b c d -> (e -> c -> m e) -> e -> a -> m eSource

Monadic fold over the elements of a structure, associating to the left, i.e. from left to right.

foldlM = foldlMOf folded

foldlMOf :: Monad m => Getter a b c d -> (e -> c -> m e) -> e -> a -> m e foldlMOf :: Monad m => Lens a b c d -> (e -> c -> m e) -> e -> a -> m e foldlMOf :: Monad m => Fold a b c d -> (e -> c -> m e) -> e -> a -> m e foldlMOf :: Monad m => Traversal a b c d -> (e -> c -> m e) -> e -> a -> m e

toListOf :: Getting [c] a b c d -> a -> [c]Source

toList = toListOf folded

toListOf :: Getter a b c d -> a -> [c] toListOf :: Lens a b c d -> a -> [c] toListOf :: Fold a b c d -> a -> [c] toListOf :: Traversal a b c d -> a -> [c]

anyOf :: Getting Any a b c d -> (c -> Bool) -> a -> BoolSource

any = anyOf folded

anyOf :: Getter a b c d -> (c -> Bool) -> a -> Bool anyOf :: Lens a b c d -> (c -> Bool) -> a -> Bool anyOf :: Fold a b c d -> (c -> Bool) -> a -> Bool anyOf :: Traversal a b c d -> (c -> Bool) -> a -> Bool

allOf :: Getting All a b c d -> (c -> Bool) -> a -> BoolSource

all = allOf folded

allOf :: Getter a b c d -> (c -> Bool) -> a -> Bool allOf :: Lens a b c d -> (c -> Bool) -> a -> Bool allOf :: Fold a b c d -> (c -> Bool) -> a -> Bool allOf :: Traversal a b c d -> (c -> Bool) -> a -> Bool

andOf :: Getting All a b Bool d -> a -> BoolSource

and = andOf folded

andOf :: Getter a b Bool d -> a -> Bool andOf :: Lens a b Bool d -> a -> Bool andOf :: Fold a b Bool d -> a -> Bool andOf :: Traversl a b Bool d -> a -> Bool

orOf :: Getting Any a b Bool d -> a -> BoolSource

or = orOf folded

orOf :: Getter a b Bool d -> a -> Bool orOf :: Lens a b Bool d -> a -> Bool orOf :: Fold a b Bool d -> a -> Bool orOf :: Traversal a b Bool d -> a -> Bool

productOf :: Getting (Product c) a b c d -> a -> cSource

product = productOf folded

productOf :: Getter a b c d -> a -> c productOf :: Lens a b c d -> a -> c productOf :: Num c => Fold a b c d -> a -> c productOf :: Num c => Traversal a b c d -> a -> c

sumOf :: Getting (Sum c) a b c d -> a -> cSource

sum = sumOf folded

sumOf _1 :: (a, b) -> a sumOf (folded._1) :: (Foldable f, Num a) => f (a, b) -> a

sumOf :: Getter a b c d -> a -> c sumOf :: Lens a b c d -> a -> c sumOf :: Num c => Fold a b c d -> a -> c sumOf :: Num c => Traversal a b c d -> a -> c

traverseOf_ :: Functor f => Getting (Traversed f) a b c d -> (c -> f e) -> a -> f ()Source

When passed a `Getter`

, `traverseOf_`

can work over a `Functor`

.

When passed a `Fold`

, `traverseOf_`

requires an `Applicative`

.

traverse_ = traverseOf_ folded

traverseOf_ _2 :: Functor f => (c -> f e) -> (c1, c) -> f () traverseOf_ traverseLeft :: Applicative f => (a -> f b) -> Either a c -> f ()

The rather specific signature of traverseOf_ allows it to be used as if the signature was either:

traverseOf_ :: Functor f => Getter a b c d -> (c -> f e) -> a -> f () traverseOf_ :: Functor f => Lens a b c d -> (c -> f e) -> a -> f () traverseOf_ :: Applicative f => Fold a b c d -> (c -> f e) -> a -> f () traverseOf_ :: Applicative f => Traversal a b c d -> (c -> f e) -> a -> f ()

forOf_ :: Functor f => Getting (Traversed f) a b c d -> a -> (c -> f e) -> f ()Source

for_ = forOf_ folded

forOf_ :: Functor f => Getter a b c d -> a -> (c -> f e) -> f () forOf_ :: Functor f => Lens a b c d -> a -> (c -> f e) -> f () forOf_ :: Applicative f => Fold a b c d -> a -> (c -> f e) -> f () forOf_ :: Applicative f => Traversal a b c d -> a -> (c -> f e) -> f ()

sequenceAOf_ :: Functor f => Getting (Traversed f) a b (f ()) d -> a -> f ()Source

sequenceA_ = sequenceAOf_ folded

sequenceAOf_ :: Functor f => Getter a b (f ()) d -> a -> f () sequenceAOf_ :: Functor f => Lens a b (f ()) d -> a -> f () sequenceAOf_ :: Applicative f => Fold a b (f ()) d -> a -> f () sequenceAOf_ :: Applicative f => Traversal a b (f ()) d -> a -> f ()

mapMOf_ :: Monad m => Getting (Traversed (WrappedMonad m)) a b c d -> (c -> m e) -> a -> m ()Source

mapM_ = mapMOf_ folded

mapMOf_ :: Monad m => Getter a b c d -> (c -> m e) -> a -> m () mapMOf_ :: Monad m => Lens a b c d -> (c -> m e) -> a -> m () mapMOf_ :: Monad m => Fold a b c d -> (c -> m e) -> a -> m () mapMOf_ :: Monad m => Traversal a b c d -> (c -> m e) -> a -> m ()

forMOf_ :: Monad m => Getting (Traversed (WrappedMonad m)) a b c d -> a -> (c -> m e) -> m ()Source

forM_ = forMOf_ folded

forMOf_ :: Monad m => Getter a b c d -> a -> (c -> m e) -> m () forMOf_ :: Monad m => Lens a b c d -> a -> (c -> m e) -> m () forMOf_ :: Monad m => Fold a b c d -> a -> (c -> m e) -> m () forMOf_ :: Monad m => Traversal a b c d -> a -> (c -> m e) -> m ()

sequenceOf_ :: Monad m => Getting (Traversed (WrappedMonad m)) a b (m c) d -> a -> m ()Source

sequence_ = sequenceOf_ folded

sequenceOf_ :: Monad m => Getter a b (m b) d -> a -> m () sequenceOf_ :: Monad m => Lens a b (m b) d -> a -> m () sequenceOf_ :: Monad m => Fold a b (m b) d -> a -> m () sequenceOf_ :: Monad m => Traversal a b (m b) d -> a -> m ()

asumOf :: Alternative f => Getting (Endo (f c)) a b (f c) d -> a -> f cSource

The sum of a collection of actions, generalizing `concatOf`

.

asum = asumOf folded

asumOf :: Alternative f => Getter a b c d -> a -> f c asumOf :: Alternative f => Lens a b c d -> a -> f c asumOf :: Alternative f => Fold a b c d -> a -> f c asumOf :: Alternative f => Traversal a b c d -> a -> f c

msumOf :: MonadPlus m => Getting (Endo (m c)) a b (m c) d -> a -> m cSource

The sum of a collection of actions, generalizing `concatOf`

.

msum = msumOf folded

msumOf :: MonadPlus m => Getter a b c d -> a -> m c msumOf :: MonadPlus m => Lens a b c d -> a -> m c msumOf :: MonadPlus m => Fold a b c d -> a -> m c msumOf :: MonadPlus m => Traversal a b c d -> a -> m c

concatMapOf :: Getting [e] a b c d -> (c -> [e]) -> a -> [e]Source

concatMap = concatMapOf folded

concatMapOf :: Getter a b c d -> (c -> [e]) -> a -> [e] concatMapOf :: Lens a b c d -> (c -> [e]) -> a -> [e] concatMapOf :: Fold a b c d -> (c -> [e]) -> a -> [e] concatMapOf :: Traversal a b c d -> (c -> [e]) -> a -> [e]

concatOf :: Getting [e] a b [e] d -> a -> [e]Source

concat = concatOf folded

concatOf :: Getter a b [e] d -> a -> [e] concatOf :: Lens a b [e] d -> a -> [e] concatOf :: Fold a b [e] d -> a -> [e] concatOf :: a b [e] d -> a -> [e]

elemOf :: Eq c => Getting Any a b c d -> c -> a -> BoolSource

elem = elemOf folded

elemOf :: Eq c => Getter a b c d -> c -> a -> Bool elemOf :: Eq c => Lens a b c d -> c -> a -> Bool elemOf :: Eq c => Fold a b c d -> c -> a -> Bool elemOf :: Eq c => Traversal a b c d -> c -> a -> Bool

notElemOf :: Eq c => Getting All a b c d -> c -> a -> BoolSource

notElem = notElemOf folded

notElemOf :: Eq c => Getter a b c d -> c -> a -> Bool notElemOf :: Eq c => Fold a b c d -> c -> a -> Bool notElemOf :: Eq c => Lens a b c d -> c -> a -> Bool notElemOf :: Eq c => Traversal a b c d -> c -> a -> Bool

lengthOf :: Getting (Sum Int) a b c d -> a -> IntSource

Note: this can be rather inefficient for large containers.

length = lengthOf folded

lengthOf _1 :: (a, b) -> Int lengthOf _1 = 1 lengthOf (folded.folded) :: Foldable f => f (g a) -> Int

lengthOf :: Getter a b c d -> a -> Int lengthOf :: Lens a b c d -> a -> Int lengthOf :: Fold a b c d -> a -> Int lengthOf :: Traversal a b c d -> a -> Int

nullOf :: Getting All a b c d -> a -> BoolSource

Returns `True`

if this `Fold`

or `Traversal`

has no targets in the given container.

Note: nullOf on a valid `Lens`

or `Getter`

will always return `False`

null = nullOf folded

This may be rather inefficient compared to the `null`

check of many containers.

nullOf _1 :: (a, b) -> Int nullOf _1 = False nullOf (folded._1.folded) :: Foldable f => f (g a, b) -> Bool

nullOf :: Getter a b c d -> a -> Bool nullOf :: Lens a b c d -> a -> Bool nullOf :: Fold a b c d -> a -> Bool nullOf :: Traversal a b c d -> a -> Bool

maximumOf :: Getting (Max c) a b c d -> a -> Maybe cSource

Obtain the maximum element (if any) targeted by a `Fold`

or `Traversal`

Note: maximumOf on a valid `Lens`

or `Getter`

will always return `Just`

a value.

maximum = fromMaybe (error "empty") . maximumOf folded

maximumOf :: Getter a b c d -> a -> Maybe c maximumOf :: Lens a b c d -> a -> Maybe c maximumOf :: Ord c => Fold a b c d -> a -> Maybe c maximumOf :: Ord c => Traversal a b c d -> a -> Maybe c

minimumOf :: Getting (Min c) a b c d -> a -> Maybe cSource

Obtain the minimum element (if any) targeted by a `Fold`

or `Traversal`

Note: minimumOf on a valid `Lens`

or `Getter`

will always return `Just`

a value.

minimum = fromMaybe (error "empty") . minimumOf folded

minimumOf :: Getter a b c d -> a -> Maybe c minimumOf :: Lens a b c d -> a -> Maybe c minimumOf :: Ord c => Fold a b c d -> a -> Maybe c minimumOf :: Ord c => Traversal a b c d -> a -> Maybe c

maximumByOf :: Getting (Endo (Maybe c)) a b c d -> (c -> c -> Ordering) -> a -> Maybe cSource

Obtain the maximum element (if any) targeted by a `Fold`

, `Traversal`

, `Lens`

or `Getter`

according to a user supplied ordering.

maximumBy cmp = fromMaybe (error "empty") . maximumByOf folded cmp

maximumByOf :: Getter a b c d -> (c -> c -> Ordering) -> a -> Maybe c maximumByOf :: Lens a b c d -> (c -> c -> Ordering) -> a -> Maybe c maximumByOf :: Fold a b c d -> (c -> c -> Ordering) -> a -> Maybe c maximumByOf :: Traversal a b c d -> (c -> c -> Ordering) -> a -> Maybe c

minimumByOf :: Getting (Endo (Maybe c)) a b c d -> (c -> c -> Ordering) -> a -> Maybe cSource

Obtain the minimum element (if any) targeted by a `Fold`

, `Traversal`

, `Lens`

or `Getter`

according to a user supplied ordering.

minimumBy cmp = fromMaybe (error "empty") . minimumByOf folded cmp

minimumByOf :: Getter a b c d -> (c -> c -> Ordering) -> a -> Maybe c minimumByOf :: Lens a b c d -> (c -> c -> Ordering) -> a -> Maybe c minimumByOf :: Fold a b c d -> (c -> c -> Ordering) -> a -> Maybe c minimumByOf :: Traversal a b c d -> (c -> c -> Ordering) -> a -> Maybe c

# Traversals

type Traversal a b c d = forall f. Applicative f => (c -> f d) -> a -> f bSource

A `Traversal`

can be used directly as a `Setter`

or a `Fold`

(but not as a `Lens`

) and provides
the ability to both read and update multiple fields, subject to some relatively weak `Traversal`

laws.

These are also known as `MultiLens`

families, but they have the signature and spirit of

traverse :: Traversable f => Traversal (f a) (f b) a b

and the more evocative name suggests their application.

## Common Traversals

traverseNothing :: Traversal a a c dSource

This is the traversal that never succeeds at returning any values

traverseNothing :: Applicative f => (c -> f d) -> a -> f a

traverseValueAt :: Ord k => k -> Simple Traversal (Map k v) vSource

Traverse the value at a given key in a Map

traverseValueAt :: (Applicative f, Ord k) => k -> (v -> f v) -> Map k v -> f (Map k v) traverseValueAt k = valueAt k . traverse

traverseValueAtInt :: Int -> Simple Traversal (IntMap v) vSource

Traverse the value at a given key in an IntMap

traverseValueAtInt :: Applicative f => Int -> (v -> f v) -> IntMap v -> f (IntMap v) traverseValueAtInt k = valueAtInt k . traverse

traverseHead :: Simple Traversal [a] aSource

traverseHead :: Applicative f => (a -> f a) -> [a] -> f [a]

traverseTail :: Simple Traversal [a] [a]Source

Traversal for editing the tail of a list.

traverseTail :: Applicative f => ([a] -> f [a]) -> [a] -> f [a]

traverseLast :: Simple Traversal [a] aSource

Traverse the last element in a list.

traverseLast = traverseValueAtMax

traverseLast :: Applicative f => (a -> f a) -> [a] -> f [a]

traverseInit :: Simple Traversal [a] [a]Source

Traverse all but the last element of a list

traverseInit :: Applicative f => ([a] -> f [a]) -> [a] -> f [a]

traverseLeft :: Traversal (Either a c) (Either b c) a bSource

A traversal for tweaking the left-hand value in an Either:

traverseLeft :: Applicative f => (a -> f b) -> Either a c -> f (Either b c)

traverseRight :: Traversal (Either c a) (Either c b) a bSource

traverse the right-hand value in an Either:

traverseRight :: Applicative f => (a -> f b) -> Either c a -> f (Either c a) traverseRight = traverse

Unfortunately the instance for 'Traversable (Either c)' is still missing from
base, so this can't just be `traverse`

traverseElement :: Traversable t => Int -> Simple Traversal (t a) aSource

Traverse a single element in a traversable container.

traverseElement :: (Applicative f, Traversable t) => Int -> (a -> f a) -> t a -> f (t a)

traverseElements :: Traversable t => (Int -> Bool) -> Simple Traversal (t a) aSource

Traverse elements where a predicate holds on their position in a traversable container

traverseElements :: Applicative f, Traversable t) => (Int -> Bool) -> (a -> f a) -> t a -> f (t a)

class TraverseByteString t whereSource

Provides ad hoc overloading for `traverseByteString`

traverseByteString :: Simple Traversal t Word8Source

Traverse the individual bytes in a `ByteString`

anyOf traverseByteString (==0x80) :: TraverseByteString b => b -> Bool

class TraverseText t whereSource

Provides ad hoc overloading for `traverseText`

class TraverseValueAtMin t whereSource

Types that support traversal of the value of the minimal key

This is separate from `TraverseValueAtMax`

because a min-heap
or max-heap may be able to support one, but not the other.

traverseValueAtMin :: Simple Traversal (t v) vSource

Traverse the value for the minimal key

class TraverseValueAtMax t whereSource

Types that support traversal of the value of the maximal key

This is separate from `TraverseValueAtMin`

because a min-heap
or max-heap may be able to support one, but not the other.

traverseValueAtMax :: Simple Traversal (t v) vSource

Traverse the value for the maximal key

traverseBits :: Bits b => Simple Traversal b BoolSource

Traverse over all bits in a numeric type.

ghci> toListOf traverseBits (5 :: Word8) [True,False,True,False,False,False,False,False]

If you supply this an Integer, it won't crash, but the result will be an infinite traversal that can be productively consumed.

ghci> toListOf traverseBits 5 [True,False,True,False,False,False,False,False,False,False,False,False...

traverseException :: (Exception a, Exception b) => Traversal SomeException SomeException a bSource

Traverse the strongly typed `Exception`

contained in `SomeException`

where the type of your function matches
the desired `Exception`

.

traverseException :: (Applicative f, Exception a, Exception b) => (a -> f b) -> SomeException -> f SomeException

## Traversal Combinators

traverseOf :: LensLike f a b c d -> (c -> f d) -> a -> f bSource

Provided for completeness, but this is just the identity function.

traverseOf = id traverse = traverseOf traverse

mapMOf :: LensLike (WrappedMonad m) a b c d -> (c -> m d) -> a -> m bSource

mapM = mapMOf traverse

mapMOf :: Monad m => Lens a b c d -> (c -> m d) -> a -> m b mapMOf :: Monad m => Traversal a b c d -> (c -> m d) -> a -> m b

sequenceAOf :: Applicative f => LensLike f a b (f c) (f c) -> a -> f bSource

sequenceA = sequenceAOf traverse

sequenceAOf :: Applicative f => Lens a b (f c) (f c) -> a -> f b sequenceAOf :: Applicative f => Traversal a b (f c) (f c) -> a -> f b

sequenceOf :: Monad m => LensLike (WrappedMonad m) a b (m c) (m c) -> a -> m bSource

sequence = sequenceOf traverse

sequenceOf :: Monad m => Lens a b (m c) (m c) -> a -> m b sequenceOf :: Monad m => Traversal a b (m c) (m c) -> a -> m b

elementOf :: Applicative f => LensLike (AppliedState f) a b c c -> Int -> (c -> f c) -> a -> f bSource

elementsOf :: Applicative f => LensLike (AppliedState f) a b c c -> (Int -> Bool) -> (c -> f c) -> a -> f bSource

transposeOf :: LensLike ZipList a b [c] c -> a -> [b]Source

transpose = transposeOf traverse -- modulo the ragged arrays support

transposeOf _2 :: (b, [a]) -> [(b, a)]