Van Laarhoven style homogeneous lenses. Mnemonic: "Lens outer inner", same type argument order as get :: o -> i.

Strictly set inner part i of structure o as designated by Lens' o i.

Strictly modify inner part i of structure o using a function i -> i.

Strictly write a part of the state.

Strictly modify a part of the state.

Modify a part of the state monadically.

Strictly modify a part of the state monadically.

Strictly modify a part of the state monadically, and return some result.

Modify a part of the state locally.

Access a map value at a given key.

Apply a different Traversal or Fold to each side of a Bitraversable container.

beside :: Traversal s t a b                -> Traversal s' t' a b                -> Traversal (r s s') (r t t') a b
beside :: IndexedTraversal i s t a b       -> IndexedTraversal i s' t' a b       -> IndexedTraversal i (r s s') (r t t') a b
beside :: IndexPreservingTraversal s t a b -> IndexPreservingTraversal s' t' a b -> IndexPreservingTraversal (r s s') (r t t') a b

beside :: Traversal s t a b                -> Traversal s' t' a b                -> Traversal (s,s') (t,t') a b
beside :: Lens s t a b                     -> Lens s' t' a b                     -> Traversal (s,s') (t,t') a b
beside :: Fold s a                         -> Fold s' a                          -> Fold (s,s') a
beside :: Getter s a                       -> Getter s' a                        -> Fold (s,s') a

beside :: IndexedTraversal i s t a b       -> IndexedTraversal i s' t' a b       -> IndexedTraversal i (s,s') (t,t') a b
beside :: IndexedLens i s t a b            -> IndexedLens i s' t' a b            -> IndexedTraversal i (s,s') (t,t') a b
beside :: IndexedFold i s a                -> IndexedFold i s' a                 -> IndexedFold i (s,s') a
beside :: IndexedGetter i s a              -> IndexedGetter i s' a               -> IndexedFold i (s,s') a

beside :: IndexPreservingTraversal s t a b -> IndexPreservingTraversal s' t' a b -> IndexPreservingTraversal (s,s') (t,t') a b
beside :: IndexPreservingLens s t a b      -> IndexPreservingLens s' t' a b      -> IndexPreservingTraversal (s,s') (t,t') a b
beside :: IndexPreservingFold s a          -> IndexPreservingFold s' a           -> IndexPreservingFold (s,s') a
beside :: IndexPreservingGetter s a        -> IndexPreservingGetter s' a         -> IndexPreservingFold (s,s') a

>>> ("hello",["world","!!!"])^..beside id traverse
["hello","world","!!!"]

Traverse both parts of a Bitraversable container with matching types.

Usually that type will be a pair. Use each to traverse the elements of arbitrary homogeneous tuples.

>>> (1,2) & both *~ 10
(10,20)

>>> over both length ("hello","world")
(5,5)

>>> ("hello","world")^.both
"helloworld"

both :: Traversal (a, a)       (b, b)       a b
both :: Traversal (Either a a) (Either b b) a b

Traverse both parts of a Bitraversable1 container with matching types.

Usually that type will be a pair.

both1 :: Traversal1 (a, a)       (b, b)       a b
both1 :: Traversal1 (Either a a) (Either b b) a b

Clone a Traversal yielding an IndexPreservingTraversal that passes through whatever index it is composed with.

Clone a Traversal1 yielding an IndexPreservingTraversal1 that passes through whatever index it is composed with.

Clone an IndexedTraversal yielding an IndexedTraversal with the same index.

Clone an IndexedTraversal1 yielding an IndexedTraversal1 with the same index.

A Traversal is completely characterized by its behavior on a Bazaar.

Cloning a Traversal is one way to make sure you aren't given something weaker, such as a Fold and can be used as a way to pass around traversals that have to be monomorphic in f.

Note: This only accepts a proper Traversal (or Lens). To clone a Lens as such, use cloneLens.

Note: It is usually better to use ReifiedTraversal and runTraversal than to cloneTraversal. The former can execute at full speed, while the latter needs to round trip through the Bazaar.

>>> let foo l a = (view (getting (cloneTraversal l)) a, set (cloneTraversal l) 10 a)
>>> foo both ("hello","world")
("helloworld",(10,10))

cloneTraversal :: LensLike (Bazaar (->) a b) s t a b -> Traversal s t a b

A Traversal1 is completely characterized by its behavior on a Bazaar1.

Fuse a Traversal by reassociating all of the (<*>) operations to the left and fusing all of the fmap calls into one. This is particularly useful when constructing a Traversal using operations from GHC.Generics.

Given a pair of Traversals foo and bar,

confusing (foo.bar) = foo.bar

However, foo and bar are each going to use the Applicative they are given.

confusing exploits the Yoneda lemma to merge their separate uses of fmap into a single fmap. and it further exploits an interesting property of the right Kan lift (or Curried) to left associate all of the uses of (<*>) to make it possible to fuse together more fmaps.

This is particularly effective when the choice of functor f is unknown at compile time or when the Traversal foo.bar in the above description is recursive or complex enough to prevent inlining.

fusing is a version of this combinator suitable for fusing lenses.

confusing :: Traversal s t a b -> Traversal s t a b

Try the second traversal. If it returns no entries, try again with all entries from the first traversal, recursively.

deepOf :: Fold s s          -> Fold s a                   -> Fold s a
deepOf :: Traversal' s s    -> Traversal' s a             -> Traversal' s a
deepOf :: Traversal s t s t -> Traversal s t a b          -> Traversal s t a b
deepOf :: Fold s s          -> IndexedFold i s a          -> IndexedFold i s a
deepOf :: Traversal s t s t -> IndexedTraversal i s t a b -> IndexedTraversal i s t a b

Visit all but the first n targets of a Traversal, Fold, Getter or Lens.

>>> ("hello","world") ^? dropping 1 both
Just "world"

Dropping works on infinite traversals as well:

>>> [1..] ^? dropping 1 folded
Just 2

dropping :: Int -> Traversal' s a                   -> Traversal' s a
dropping :: Int -> Lens' s a                        -> Traversal' s a
dropping :: Int -> Iso' s a                         -> Traversal' s a
dropping :: Int -> Prism' s a                       -> Traversal' s a
dropping :: Int -> Getter s a                       -> Fold s a
dropping :: Int -> Fold s a                         -> Fold s a
dropping :: Int -> IndexedTraversal' i s a          -> IndexedTraversal' i s a
dropping :: Int -> IndexedLens' i s a               -> IndexedTraversal' i s a
dropping :: Int -> IndexedGetter i s a              -> IndexedFold i s a
dropping :: Int -> IndexedFold i s a                -> IndexedFold i s a

Traverse the nth element of a Traversable container.

element ≡ elementOf traverse

Traverse the nth elementOf a Traversal, Lens or Iso if it exists.

>>> [[1],[3,4]] & elementOf (traverse.traverse) 1 .~ 5
[[1],[5,4]]

>>> [[1],[3,4]] ^? elementOf (folded.folded) 1
Just 3

>>> timingOut $ ['a'..] ^?! elementOf folded 5
'f'

>>> timingOut $ take 10 $ elementOf traverse 3 .~ 16 $ [0..]
[0,1,2,16,4,5,6,7,8,9]

elementOf :: Traversal' s a -> Int -> IndexedTraversal' Int s a
elementOf :: Fold s a       -> Int -> IndexedFold Int s a

Traverse (or fold) selected elements of a Traversal (or Fold) where their ordinal positions match a predicate.

elementsOf :: Traversal' s a -> (Int -> Bool) -> IndexedTraversal' Int s a
elementsOf :: Fold s a       -> (Int -> Bool) -> IndexedFold Int s a

Try the first Traversal (or Fold), falling back on the second Traversal (or Fold) if it returns no entries.

This is only a valid Traversal if the second Traversal is disjoint from the result of the first or returns exactly the same results. These conditions are trivially met when given a Lens, Iso, Getter, Prism or "affine" Traversal -- one that has 0 or 1 target.

Mutatis mutandis for Fold.

>>> [0,1,2,3] ^? failing (ix 1) (ix 2)
Just 1

>>> [0,1,2,3] ^? failing (ix 42) (ix 2)
Just 2

failing :: Traversal s t a b -> Traversal s t a b -> Traversal s t a b
failing :: Prism s t a b     -> Prism s t a b     -> Traversal s t a b
failing :: Fold s a          -> Fold s a          -> Fold s a

These cases are also supported, trivially, but are boring, because the left hand side always succeeds.

failing :: Lens s t a b      -> Traversal s t a b -> Traversal s t a b
failing :: Iso s t a b       -> Traversal s t a b -> Traversal s t a b
failing :: Equality s t a b  -> Traversal s t a b -> Traversal s t a b
failing :: Getter s a        -> Fold s a          -> Fold s a

If both of the inputs are indexed, the result is also indexed, so you can apply this to a pair of indexed traversals or indexed folds, obtaining an indexed traversal or indexed fold.

failing :: IndexedTraversal i s t a b -> IndexedTraversal i s t a b -> IndexedTraversal i s t a b
failing :: IndexedFold i s a          -> IndexedFold i s a          -> IndexedFold i s a

These cases are also supported, trivially, but are boring, because the left hand side always succeeds.

failing :: IndexedLens i s t a b      -> IndexedTraversal i s t a b -> IndexedTraversal i s t a b
failing :: IndexedGetter i s a        -> IndexedGetter i s a        -> IndexedFold i s a

Try to map a function over this Traversal, failing if the Traversal has no targets.

>>> failover (element 3) (*2) [1,2] :: Maybe [Int]
Nothing

>>> failover _Left (*2) (Right 4) :: Maybe (Either Int Int)
Nothing

>>> failover _Right (*2) (Right 4) :: Maybe (Either Int Int)
Just (Right 8)

failover :: Alternative m => Traversal s t a b -> (a -> b) -> s -> m t

forMOf is a flipped version of mapMOf, consistent with the definition of forM.

>>> forMOf both (1,3) $ \x -> [x, x + 1]
[(1,3),(1,4),(2,3),(2,4)]

forM ≡ forMOf traverse
forMOf l ≡ flip (mapMOf l)
iforMOf l s ≡ forM l s . Indexed

forMOf :: Monad m => Iso s t a b       -> s -> (a -> m b) -> m t
forMOf :: Monad m => Lens s t a b      -> s -> (a -> m b) -> m t
forMOf :: Monad m => Traversal s t a b -> s -> (a -> m b) -> m t

A version of traverseOf with the arguments flipped, such that:

>>> forOf each (1,2,3) print
1
2
3
((),(),())

This function is only provided for consistency, flip is strictly more general.

forOf ≡ flip
forOf ≡ flip . traverseOf

for ≡ forOf traverse
ifor l s ≡ for l s . Indexed

forOf :: Functor f => Iso s t a b -> s -> (a -> f b) -> f t
forOf :: Functor f => Lens s t a b -> s -> (a -> f b) -> f t
forOf :: Applicative f => Traversal s t a b -> s -> (a -> f b) -> f t

The non-empty version of holesOf. This extract a non-empty list of immediate children according to a given Traversal1 as editable contexts.

>>> let head1 f s = runPretext (NonEmpty.head $ holes1Of traversed1 s) f
>>> ('a' :| "bc") ^. head1
'a'

>>> ('a' :| "bc") & head1 %~ toUpper
'A' :| "bc"

holes1Of :: Iso' s a                 -> s -> NonEmpty (Pretext' (->) a s)
holes1Of :: Lens' s a                -> s -> NonEmpty (Pretext' (->) a s)
holes1Of :: Traversal1' s a          -> s -> NonEmpty (Pretext' (->) a s)
holes1Of :: IndexedLens' i s a       -> s -> NonEmpty (Pretext' (Indexed i) a s)
holes1Of :: IndexedTraversal1' i s a -> s -> NonEmpty (Pretext' (Indexed i) a s)

The one-level version of contextsOf. This extracts a list of the immediate children according to a given Traversal as editable contexts.

Given a context you can use pos to see the values, peek at what the structure would be like with an edited result, or simply extract the original structure.

propChildren l x = toListOf l x == map pos (holesOf l x)
propId l x = all (== x) [extract w | w <- holesOf l x]

holesOf :: Iso' s a                -> s -> [Pretext' (->) a s]
holesOf :: Lens' s a               -> s -> [Pretext' (->) a s]
holesOf :: Traversal' s a          -> s -> [Pretext' (->) a s]
holesOf :: IndexedLens' i s a      -> s -> [Pretext' (Indexed i) a s]
holesOf :: IndexedTraversal' i s a -> s -> [Pretext' (Indexed i) a s]

Try to map a function which uses the index over this IndexedTraversal, failing if the IndexedTraversal has no targets.

ifailover :: Alternative m => IndexedTraversal i s t a b -> (i -> a -> b) -> s -> m t

Map each element of a structure targeted by a Lens to a monadic action, evaluate these actions from left to right, and collect the results, with access its position (and the arguments flipped).

forMOf l a ≡ iforMOf l a . const
iforMOf ≡ flip . imapMOf

iforMOf :: Monad m => IndexedLens i s t a b      -> s -> (i -> a -> m b) -> m t
iforMOf :: Monad m => IndexedTraversal i s t a b -> s -> (i -> a -> m b) -> m t

Traverse with an index (and the arguments flipped).

forOf l a ≡ iforOf l a . const
iforOf ≡ flip . itraverseOf

iforOf :: Functor f     => IndexedLens i s t a b       -> s -> (i -> a -> f b) -> f t
iforOf :: Applicative f => IndexedTraversal i s t a b  -> s -> (i -> a -> f b) -> f t
iforOf :: Apply f       => IndexedTraversal1 i s t a b -> s -> (i -> a -> f b) -> f t

This is the trivial empty Traversal.

ignored :: IndexedTraversal i s s a b

ignored ≡ const pure

>>> 6 & ignored %~ absurd
6

This IndexedTraversal allows you to traverse the individual stores in a Bazaar with access to their indices.

Generalizes mapAccumL to an arbitrary IndexedTraversal with access to the index.

imapAccumLOf accumulates state from left to right.

mapAccumLOf l ≡ imapAccumLOf l . const

imapAccumLOf :: IndexedLens i s t a b      -> (i -> acc -> a -> (acc, b)) -> acc -> s -> (acc, t)
imapAccumLOf :: IndexedTraversal i s t a b -> (i -> acc -> a -> (acc, b)) -> acc -> s -> (acc, t)

Generalizes mapAccumR to an arbitrary IndexedTraversal with access to the index.

imapAccumROf accumulates state from right to left.

mapAccumROf l ≡ imapAccumROf l . const

imapAccumROf :: IndexedLens i s t a b      -> (i -> acc -> a -> (acc, b)) -> acc -> s -> (acc, t)
imapAccumROf :: IndexedTraversal i s t a b -> (i -> acc -> a -> (acc, b)) -> acc -> s -> (acc, t)

Map each element of a structure targeted by a Lens to a monadic action, evaluate these actions from left to right, and collect the results, with access its position.

When you don't need access to the index mapMOf is more liberal in what it can accept.

mapMOf l ≡ imapMOf l . const

imapMOf :: Monad m => IndexedLens       i s t a b -> (i -> a -> m b) -> s -> m t
imapMOf :: Monad m => IndexedTraversal  i s t a b -> (i -> a -> m b) -> s -> m t
imapMOf :: Bind  m => IndexedTraversal1 i s t a b -> (i -> a -> m b) -> s -> m t

An indexed version of partsOf that receives the entire list of indices as its index.

A type-restricted version of ipartsOf that can only be used with an IndexedTraversal.

Traversal with an index.

NB: When you don't need access to the index then you can just apply your IndexedTraversal directly as a function!

itraverseOf ≡ withIndex
traverseOf l = itraverseOf l . const = id

itraverseOf :: Functor f     => IndexedLens i s t a b       -> (i -> a -> f b) -> s -> f t
itraverseOf :: Applicative f => IndexedTraversal i s t a b  -> (i -> a -> f b) -> s -> f t
itraverseOf :: Apply f       => IndexedTraversal1 i s t a b -> (i -> a -> f b) -> s -> f t

An indexed version of unsafePartsOf that receives the entire list of indices as its index.

This Traversal allows you to traverse the individual stores in a Bazaar.

This generalizes mapAccumL to an arbitrary Traversal.

mapAccumL ≡ mapAccumLOf traverse

mapAccumLOf accumulates State from left to right.

mapAccumLOf :: Iso s t a b       -> (acc -> a -> (acc, b)) -> acc -> s -> (acc, t)
mapAccumLOf :: Lens s t a b      -> (acc -> a -> (acc, b)) -> acc -> s -> (acc, t)
mapAccumLOf :: Traversal s t a b -> (acc -> a -> (acc, b)) -> acc -> s -> (acc, t)

mapAccumLOf :: LensLike (State acc) s t a b -> (acc -> a -> (acc, b)) -> acc -> s -> (acc, t)
mapAccumLOf l f acc0 s = swap (runState (l (a -> state (acc -> swap (f acc a))) s) acc0)

This generalizes mapAccumR to an arbitrary Traversal.

mapAccumR ≡ mapAccumROf traverse

mapAccumROf accumulates State from right to left.

mapAccumROf :: Iso s t a b       -> (acc -> a -> (acc, b)) -> acc -> s -> (acc, t)
mapAccumROf :: Lens s t a b      -> (acc -> a -> (acc, b)) -> acc -> s -> (acc, t)
mapAccumROf :: Traversal s t a b -> (acc -> a -> (acc, b)) -> acc -> s -> (acc, t)

mapAccumROf :: LensLike (Backwards (State acc)) s t a b -> (acc -> a -> (acc, b)) -> acc -> s -> (acc, t)

Map each element of a structure targeted by a Lens to a monadic action, evaluate these actions from left to right, and collect the results.

>>> mapMOf both (\x -> [x, x + 1]) (1,3)
[(1,3),(1,4),(2,3),(2,4)]

mapM ≡ mapMOf traverse
imapMOf l ≡ forM l . Indexed

mapMOf :: Monad m => Iso s t a b       -> (a -> m b) -> s -> m t
mapMOf :: Monad m => Lens s t a b      -> (a -> m b) -> s -> m t
mapMOf :: Monad m => Traversal s t a b -> (a -> m b) -> s -> m t

partsOf turns a Traversal into a Lens that resembles an early version of the uniplate (or biplate) type.

Note: You should really try to maintain the invariant of the number of children in the list.

>>> (a,b,c) & partsOf each .~ [x,y,z]
(x,y,z)

Any extras will be lost. If you do not supply enough, then the remainder will come from the original structure.

>>> (a,b,c) & partsOf each .~ [w,x,y,z]
(w,x,y)

>>> (a,b,c) & partsOf each .~ [x,y]
(x,y,c)

>>> ('b', 'a', 'd', 'c') & partsOf each %~ sort
('a','b','c','d')

So technically, this is only a Lens if you do not change the number of results it returns.

When applied to a Fold the result is merely a Getter.

partsOf :: Iso' s a       -> Lens' s [a]
partsOf :: Lens' s a      -> Lens' s [a]
partsOf :: Traversal' s a -> Lens' s [a]
partsOf :: Fold s a       -> Getter s [a]
partsOf :: Getter s a     -> Getter s [a]

A type-restricted version of partsOf that can only be used with a Traversal.

This permits the use of scanl1 over an arbitrary Traversal or Lens.

scanl1 ≡ scanl1Of traverse

scanl1Of :: Iso s t a a       -> (a -> a -> a) -> s -> t
scanl1Of :: Lens s t a a      -> (a -> a -> a) -> s -> t
scanl1Of :: Traversal s t a a -> (a -> a -> a) -> s -> t

This permits the use of scanr1 over an arbitrary Traversal or Lens.

scanr1 ≡ scanr1Of traverse

scanr1Of :: Iso s t a a       -> (a -> a -> a) -> s -> t
scanr1Of :: Lens s t a a      -> (a -> a -> a) -> s -> t
scanr1Of :: Traversal s t a a -> (a -> a -> a) -> s -> t

Evaluate each action in the structure from left to right, and collect the results.

>>> sequenceAOf both ([1,2],[3,4])
[(1,3),(1,4),(2,3),(2,4)]

sequenceA ≡ sequenceAOf traverse ≡ traverse id
sequenceAOf l ≡ traverseOf l id ≡ l id

sequenceAOf :: Functor f => Iso s t (f b) b       -> s -> f t
sequenceAOf :: Functor f => Lens s t (f b) b      -> s -> f t
sequenceAOf :: Applicative f => Traversal s t (f b) b -> s -> f t

Sequence a container using a specified Applicative.

This is like traverseBy where the Traversable instance can be specified by any Traversal

sequenceByOf traverse ≡ sequenceBy

Sequence the (monadic) effects targeted by a Lens in a container from left to right.

>>> sequenceOf each ([1,2],[3,4],[5,6])
[(1,3,5),(1,3,6),(1,4,5),(1,4,6),(2,3,5),(2,3,6),(2,4,5),(2,4,6)]

sequence ≡ sequenceOf traverse
sequenceOf l ≡ mapMOf l id
sequenceOf l ≡ unwrapMonad . l WrapMonad

sequenceOf :: Monad m => Iso s t (m b) b       -> s -> m t
sequenceOf :: Monad m => Lens s t (m b) b      -> s -> m t
sequenceOf :: Monad m => Traversal s t (m b) b -> s -> m t

This converts a Traversal that you "know" will target one or more elements to a Lens. It can also be used to transform a non-empty Fold into a Getter.

The resulting Lens or Getter will be partial if the supplied Traversal returns no results.

>>> [1,2,3] ^. singular _head
1

>>> Left (ErrorCall "singular: empty traversal") <- try (evaluate ([] ^. singular _head)) :: IO (Either ErrorCall ())

>>> Left 4 ^. singular _Left
4

>>> [1..10] ^. singular (ix 7)
8

>>> [] & singular traverse .~ 0
[]

singular :: Traversal s t a a          -> Lens s t a a
singular :: Fold s a                   -> Getter s a
singular :: IndexedTraversal i s t a a -> IndexedLens i s t a a
singular :: IndexedFold i s a          -> IndexedGetter i s a

Visit the first n targets of a Traversal, Fold, Getter or Lens.

>>> [("hello","world"),("!!!","!!!")]^.. taking 2 (traverse.both)
["hello","world"]

>>> timingOut $ [1..] ^.. taking 3 traverse
[1,2,3]

>>> over (taking 5 traverse) succ "hello world"
"ifmmp world"

taking :: Int -> Traversal' s a                   -> Traversal' s a
taking :: Int -> Lens' s a                        -> Traversal' s a
taking :: Int -> Iso' s a                         -> Traversal' s a
taking :: Int -> Prism' s a                       -> Traversal' s a
taking :: Int -> Getter s a                       -> Fold s a
taking :: Int -> Fold s a                         -> Fold s a
taking :: Int -> IndexedTraversal' i s a          -> IndexedTraversal' i s a
taking :: Int -> IndexedLens' i s a               -> IndexedTraversal' i s a
taking :: Int -> IndexedGetter i s a              -> IndexedFold i s a
taking :: Int -> IndexedFold i s a                -> IndexedFold i s a

This generalizes transpose to an arbitrary Traversal.

Note: transpose handles ragged inputs more intelligently, but for non-ragged inputs:

>>> transposeOf traverse [[1,2,3],[4,5,6]]
[[1,4],[2,5],[3,6]]

transpose ≡ transposeOf traverse

Since every Lens is a Traversal, we can use this as a form of monadic strength as well:

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

Build a Traversal by providing a function which specifies the elements you wish to focus.

The caller provides a function of type:

Applicative f => (a -> f b) -> s -> f t

Which is a higher order function which accepts a "focusing function" and applies it to all desired focuses within s, then constructs a t using the Applicative instance of f.

Only elements which are "focused" using the focusing function will be targeted by the resulting traversal.

For example, we can explicitly write a traversal which targets the first and third elements of a tuple like this:

firstAndThird :: Traversal (a, x, a) (b, x, b) a b
firstAndThird = traversal go
  where
    go :: Applicative f => (a -> f b) -> (a, x, a) -> f (b, x, b)
    go focus (a, x, a') = liftA3 (,,) (focus a) (pure x) (focus a')

>>> (1,"two",3) & firstAndThird *~ 10
(10,"two",30)

>>> over firstAndThird length ("one",2,"three")
(3,2,5)

We can re-use existing Traversals when writing new ones by passing our focusing function along to them. This example re-uses traverse to focus all elements in a list which is embedded in a tuple. This traversal could also be written simply as _2 . traverse.

selectNested :: Traversal (x, [a]) (x, [b]) a b
selectNested = traversal go
  where
    go :: Applicative f => (a -> f b) -> (x, [a]) -> f (x, [b])
    go focus (x, as) = liftA2 (,) (pure x) (traverse focus as)

>>> selectNested .~ "hello" $ (1,[2,3,4,5])
(1,["hello","hello","hello","hello"])

>>> (1,[2,3,4,5]) & selectNested *~ 3
(1,[6,9,12,15])

Note that the traversal function actually just returns the same function you pass to it. The function it accepts is in fact a valid traversal all on its own! The use of traversal does nothing except verify that the function it is passed matches the signature of a valid traversal. One could remove the traversal combinator from either of the last two examples and use the definition of go directly with no change in behaviour.

This function exists for consistency with the lens, prism and iso constructors as well as to serve as a touchpoint for beginners who wish to construct their own traversals but are uncertain how to do so.

Traverse a container using a specified Applicative.

This is like traverseBy where the Traversable instance can be specified by any Traversal

traverseByOf traverse ≡ traverseBy

Map each element of a structure targeted by a Lens or Traversal, evaluate these actions from left to right, and collect the results.

This function is only provided for consistency, id is strictly more general.

>>> traverseOf each print (1,2,3)
1
2
3
((),(),())

traverseOf ≡ id
itraverseOf l ≡ traverseOf l . Indexed
itraverseOf itraversed ≡ itraverse

This yields the obvious law:

traverse ≡ traverseOf traverse

traverseOf :: Functor f     => Iso s t a b        -> (a -> f b) -> s -> f t
traverseOf :: Functor f     => Lens s t a b       -> (a -> f b) -> s -> f t
traverseOf :: Apply f       => Traversal1 s t a b -> (a -> f b) -> s -> f t
traverseOf :: Applicative f => Traversal s t a b  -> (a -> f b) -> s -> f t

Traverse any Traversable container. This is an IndexedTraversal that is indexed by ordinal position.

Traverse any Traversable1 container. This is an IndexedTraversal1 that is indexed by ordinal position.

Traverse any Traversable container. This is an IndexedTraversal that is indexed by ordinal position.

unsafePartsOf turns a Traversal into a uniplate (or biplate) family.

If you do not need the types of s and t to be different, it is recommended that you use partsOf.

It is generally safer to traverse with the Bazaar rather than use this combinator. However, it is sometimes convenient.

This is unsafe because if you don't supply at least as many b's as you were given a's, then the reconstruction of t will result in an error!

When applied to a Fold the result is merely a Getter (and becomes safe).

unsafePartsOf :: Iso s t a b       -> Lens s t [a] [b]
unsafePartsOf :: Lens s t a b      -> Lens s t [a] [b]
unsafePartsOf :: Traversal s t a b -> Lens s t [a] [b]
unsafePartsOf :: Fold s a          -> Getter s [a]
unsafePartsOf :: Getter s a        -> Getter s [a]

This converts a Traversal that you "know" will target only one element to a Lens. It can also be used to transform a Fold into a Getter.

The resulting Lens or Getter will be partial if the Traversal targets nothing or more than one element.

>>> Left (ErrorCall "unsafeSingular: empty traversal") <- try (evaluate ([] & unsafeSingular traverse .~ 0)) :: IO (Either ErrorCall [Integer])

unsafeSingular :: Traversal s t a b          -> Lens s t a b
unsafeSingular :: Fold s a                   -> Getter s a
unsafeSingular :: IndexedTraversal i s t a b -> IndexedLens i s t a b
unsafeSingular :: IndexedFold i s a          -> IndexedGetter i s a

Sequence a container using its Traversable instance using explicitly provided Applicative operations. This is like sequence where the Applicative instance can be manually specified.

Traverse a container using its Traversable instance using explicitly provided Applicative operations. This is like traverse where the Applicative instance can be manually specified.

Functors representing data structures that can be transformed to structures of the same shape by performing an Applicative (or, therefore, Monad) action on each element from left to right.

A more detailed description of what same shape means, the various methods, how traversals are constructed, and example advanced use-cases can be found in the Overview section of Data.Traversable.

For the class laws see the Laws section of Data.Traversable.