Control.Lens.Combinators

An Iso between the lazy variant of a structure and its strict counterpart.

strict = from lazy

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 three common sense Lens laws:

1) You get back what you put in:

view l (set l v s)  ≡ v

2) Putting back what you got doesn't change anything:

set l (view l s) s  ≡ s

3) Setting twice is the same as setting once:

set l v' (set l v s) ≡ set l v' s

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/.

There are some emergent properties of these laws:

1) set l s must be injective for every s This is a consequence of law #1

2) set l must be surjective, because of law #2, which indicates that it is possible to obtain any v from some s such that set s v = s

3) Given just the first two laws you can prove a weaker form of law #3 where the values v that you are setting match:

set l v (set l v s) ≡ set l v s

Every Lens can be used directly as a Control.Lens.Setter.Setter or Traversal.

You can also use a Lens for Getting as if it were a Fold or Getter.

Since every Lens is a valid Traversal, the Traversal laws are required of any Lens you create:

l pure ≡ pure
fmap (l f) . l g ≡ getCompose . l (Compose . fmap f . g)

type Lens s t a b = forall f. Functor f => LensLike f s t a b

Reify a Lens so it can be stored safely in a container.

At provides a Lens that can be used to read, write or delete the value associated with a key in a Map-like container on an ad hoc basis.

An instance of At should satisfy:

ix k ≡ at k . traverse

This class provides a way to attach or detach elements on the left side of a structure in a flexible manner.

Extract each element of a (potentially monomorphic) container.

Notably, when applied to a tuple, this generalizes both to arbitrary homogeneous tuples.

>>> (1,2,3) & each *~ 10(10,20,30)

It can also be used on monomorphic containers like Text or ByteString.

>>> over each Char.toUpper ("hello"^.Text.packed)"HELLO"

>>> ("hello","world") & each.each %~ Char.toUpper("HELLO","WORLD")

A witness that (a ~ s, b ~ t).

Note: Composition with an Equality is index-preserving.

A Fold describes how to retrieve multiple values in a way that can be composed with other LensLike constructions.

A Fold s a provides a structure with operations very similar to those of the Foldable typeclass, see foldMapOf and the other Fold combinators.

By convention, if there exists a foo method that expects a Foldable (f a), then there should be a fooOf method that takes a Fold s a and a value of type s.

A Getter is a legal Fold that just ignores the supplied Monoid.

Unlike a Control.Lens.Traversal.Traversal a Fold is read-only. Since a Fold cannot be used to write back there are no Lens laws that apply.

Reify a Fold so it can be stored safely in a container.

This can also be useful for creatively combining folds as ReifiedFold s is isomorphic to ReaderT s [] and provides similar instances.

>>> ("hello","world")^..runFold ((,) <$> Fold _2 <*> Fold both)[("world","hello"),("world","world")]

A Getter describes how to retrieve a single value in a way that can be composed with other LensLike 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. In fact, it is isomorphic to an arbitrary function from (s -> a).

Moreover, a Getter can be used directly as a Control.Lens.Fold.Fold, since it just ignores the Applicative.

Reify a Getter so it can be stored safely in a container.

This can also be useful when combining getters in novel ways, as ReifiedGetter is isomorphic to (->) and provides similar instances.

>>> ("hello","world","!!!")^.runGetter ((,) <$> Getter _2 <*> Getter (_1.to length))("world",5)

A function with access to a index. This constructor may be useful when you need to store an Indexable in a container to avoid ImpredicativeTypes.

index :: Indexed i a b -> i -> a -> b

Isomorphism families can be composed with another Lens using (.) and id.

Since every Iso is both a valid Lens and a valid Prism, the laws for those types imply the following laws for an Iso f:

f . from f ≡ id
from f . f ≡ id

Note: Composition with an Iso is index- and measure- preserving.

Reify an Iso so it can be stored safely in a container.

This data type represents a path-compressed copy of one level of a source data structure. We can safely use path-compression because we know the depth of the tree.

Path compression is performed by viewing a Level as a PATRICIA trie of the paths into the structure to leaves at a given depth, similar in many ways to a Data.IntMap.IntMap, but unlike a regular PATRICIA trie we do not need to store the mask bits merely the depth of the fork.

One invariant of this structure is that underneath a Two node you will not find any Zero nodes, so Zero can only occur at the root.

A Plated type is one where we know how to extract its immediate self-similar children.

Example 1:

import Control.Applicative
import Control.Lens
import Control.Lens.Plated
import Data.Data
import Data.Data.Lens (uniplate)

data Expr
  = Val Int
  | Neg Expr
  | Add Expr Expr
  deriving (Eq,Ord,Show,Read,Data)

instance Plated Expr where
  plate f (Neg e) = Neg <$> f e
  plate f (Add a b) = Add <$> f a <*> f b
  plate _ a = pure a

or

instance Plated Expr where
  plate = uniplate

Example 2:

import Control.Applicative
import Control.Lens
import Control.Lens.Plated
import Data.Data
import Data.Data.Lens (uniplate)

data Tree a
  = Bin (Tree a) (Tree a)
  | Tip a
  deriving (Eq,Ord,Show,Read,Data)

instance Plated (Tree a) where
  plate f (Bin l r) = Bin <$> f l <*> f r
  plate _ t = pure t

or

instance Data a => Plated (Tree a) where
  plate = uniplate

Note the big distinction between these two implementations.

The former will only treat children directly in this tree as descendents, the latter will treat trees contained in the values under the tips also as descendants!

When in doubt, pick a Traversal and just use the various ...Of combinators rather than pollute Plated with orphan instances!

If you want to find something unplated and non-recursive with biplate use the ...OnOf variant with ignored, though those usecases are much better served in most cases by using the existing Lens combinators! e.g.

toListOf biplate ≡ universeOnOf biplate ignored

This same ability to explicitly pass the Traversal in question is why there is no analogue to uniplate's Biplate.

Moreover, since we can allow custom traversals, we implement reasonable defaults for polymorphic data types, that only Control.Traversable.traverse into themselves, and not their polymorphic arguments.

A Prism l is a Traversal that can also be turned around with re to obtain a Getter in the opposite direction.

There are three laws that a Prism should satisfy:

First, if I re or review a value with a Prism and then preview or use (^?), I will get it back:

preview l (review l b) ≡ Just b

Second, if you can extract a value a using a Prism l from a value s, then the value s is completely described by l and a:

preview l s ≡ Just a ⟹ review l a ≡ s

Third, if you get non-match t, you can convert it result back to s:

Control.Lens.Combinators.matching l s ≡ Left t ⟹ Control.Lens.Combinators.matching l t ≡ Left s

The first two laws imply that the Traversal laws hold for every Prism and that we traverse at most 1 element:

lengthOf l x <= 1

It may help to think of this as an Iso that can be partial in one direction.

Every Prism is a valid Traversal.

Every Iso is a valid Prism.

For example, you might have a Prism' Integer Numeric.Natural.Natural allows you to always go from a Numeric.Natural.Natural to an Integer, and provide you with tools to check if an Integer is a Numeric.Natural.Natural and/or to edit one if it is.

nat :: Prism' Integer Numeric.Natural.Natural
nat = prism toInteger $ \ i ->
   if i < 0
   then Left i
   else Right (fromInteger i)

Now we can ask if an Integer is a Numeric.Natural.Natural.

>>> 5^?natJust 5

>>> (-5)^?natNothing

We can update the ones that are:

>>> (-3,4) & both.nat *~ 2(-3,8)

And we can then convert from a Numeric.Natural.Natural to an Integer.

>>> 5 ^. re nat -- :: Natural5

Similarly we can use a Prism to traverse the Left half of an Either:

>>> Left "hello" & _Left %~ lengthLeft 5

or to construct an Either:

>>> 5^.re _LeftLeft 5

such that if you query it with the Prism, you will get your original input back.

>>> 5^.re _Left ^? _LeftJust 5

Another interesting way to think of a Prism is as the categorical dual of a Lens -- a co-Lens, so to speak. This is what permits the construction of outside.

Note: Composition with a Prism is index-preserving.

Reify a Prism so it can be stored safely in a container.

This is a limited form of a Prism that can only be used for re operations.

Like with a Getter, there are no laws to state for a Review.

You can generate a Review by using unto. You can also use any Prism or Iso directly as a Review.

The only LensLike law that can apply to a Setter l is that

set l y (set l x a) ≡ set l y a

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

However, two Functor laws apply to a Setter:

over l id ≡ id
over l f . over l g ≡ over l (f . g)

These can be stated more directly:

l pure ≡ pure
l f . untainted . l g ≡ l (f . untainted . g)

You can compose a Setter with a Lens or a Traversal using (.) from the Prelude and the result is always only a Setter and nothing more.

>>> over traverse f [a,b,c,d][f a,f b,f c,f d]

>>> over _1 f (a,b)(f a,b)

>>> over (traverse._1) f [(a,b),(c,d)][(f a,b),(f c,d)]

>>> over both f (a,b)(f a,f b)

>>> over (traverse.both) f [(a,b),(c,d)][(f a,f b),(f c,f d)]

Reify a Setter so it can be stored safely in a container.

A Traversal can be used directly as a Control.Lens.Setter.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 have also been known as multilenses, 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.

Most of the time the Traversal you will want to use is just traverse, but you can also pass any Lens or Iso as a Traversal, and composition of a Traversal (or Lens or Iso) with a Traversal (or Lens or Iso) using (.) forms a valid Traversal.

The laws for a Traversal t follow from the laws for Traversable as stated in "The Essence of the Iterator Pattern".

t pure ≡ pure
fmap (t f) . t g ≡ getCompose . t (Compose . fmap f . g)

One consequence of this requirement is that a Traversal needs to leave the same number of elements as a candidate for subsequent Traversal that it started with. Another testament to the strength of these laws is that the caveat expressed in section 5.5 of the "Essence of the Iterator Pattern" about exotic Traversable instances that traverse the same entry multiple times was actually already ruled out by the second law in that same paper!

A form of Traversal that can be stored monomorphically in a container.

Wrapped provides isomorphisms to wrap and unwrap newtypes or data types with one constructor.

This class allows us to use zoom in, changing the State supplied by many different Monad transformers, potentially quite deep in a Monad transformer stack.

Delete the value associated with a key in a Map-like container

sans k = at k .~ Nothing

An indexed version of at.

>>> Map.fromList [(1,"world")] ^@. iat 1(1,Just "world")

>>> iat 1 %@~ (\i x -> if odd i then Just "hello" else Nothing) $ Map.emptyfromList [(1,"hello")]

>>> iat 2 %@~ (\i x -> if odd i then Just "hello" else Nothing) $ Map.emptyfromList []

This provides a common notion of a value at an index that is shared by both Ixed and At.

Provides a simple Traversal lets you traverse the value at a given key in a Map or element at an ordinal position in a list or Seq.

A definition of ix for types with an At instance. This is the default if you don't specify a definition for ix.

An indexed version of ix.

>>> Seq.fromList [a,b,c,d] & iix 2 %@~ f'fromList [a,b,f' 2 c,d]

>>> Seq.fromList [a,b,c,d] & iix 2 .@~ hfromList [a,b,h 2,d]

>>> Seq.fromList [a,b,c,d] ^@? iix 2Just (2,c)

>>> Seq.fromList [] ^@? iix 2Nothing

This class provides a simple Lens that lets you view (and modify) information about whether or not a container contains a given Index.

An indexed version of contains.

>>> IntSet.fromList [1,2,3,4] ^@. icontains 3(3,True)

>>> IntSet.fromList [1,2,3,4] ^@. icontains 5(5,False)

>>> IntSet.fromList [1,2,3,4] & icontains 3 %@~ \i x -> if odd i then not x else xfromList [1,2,4]

>>> IntSet.fromList [1,2,3,4] & icontains 3 %@~ \i x -> if even i then not x else xfromList [1,2,3,4]

cons an element onto a container.

>>> cons a [][a]

>>> cons a [b, c][a,b,c]

>>> cons a (Seq.fromList [])fromList [a]

>>> cons a (Seq.fromList [b, c])fromList [a,b,c]

Attempt to extract the left-most element from a container, and a version of the container without that element.

>>> uncons []Nothing

>>> uncons [a, b, c]Just (a,[b,c])

A Traversal reading and writing to the head of a non-empty container.

>>> [a,b,c]^? _headJust a

>>> [a,b,c] & _head .~ d[d,b,c]

>>> [a,b,c] & _head %~ f[f a,b,c]

>>> [] & _head %~ f[]

>>> [1,2,3]^?!_head1

>>> []^?_headNothing

>>> [1,2]^?_headJust 1

>>> [] & _head .~ 1[]

>>> [0] & _head .~ 2[2]

>>> [0,1] & _head .~ 2[2,1]

This isn't limited to lists.

For instance you can also traverse the head of a Seq:

>>> Seq.fromList [a,b,c,d] & _head %~ ffromList [f a,b,c,d]

>>> Seq.fromList [] ^? _headNothing

>>> Seq.fromList [a,b,c,d] ^? _headJust a

_head :: Traversal' [a] a
_head :: Traversal' (Seq a) a
_head :: Traversal' (Vector a) a

A Traversal reading and writing to the tail of a non-empty container.

>>> [a,b] & _tail .~ [c,d,e][a,c,d,e]

>>> [] & _tail .~ [a,b][]

>>> [a,b,c,d,e] & _tail.traverse %~ f[a,f b,f c,f d,f e]

>>> [1,2] & _tail .~ [3,4,5][1,3,4,5]

>>> [] & _tail .~ [1,2][]

>>> [a,b,c]^?_tailJust [b,c]

>>> [1,2]^?!_tail[2]

>>> "hello"^._tail"ello"

>>> ""^._tail""

This isn't limited to lists. For instance you can also Control.Traversable.traverse the tail of a Seq.

>>> Seq.fromList [a,b] & _tail .~ Seq.fromList [c,d,e]fromList [a,c,d,e]

>>> Seq.fromList [a,b,c] ^? _tailJust (fromList [b,c])

>>> Seq.fromList [] ^? _tailNothing

_tail :: Traversal' [a] [a]
_tail :: Traversal' (Seq a) (Seq a)
_tail :: Traversal' (Vector a) (Vector a)

(<|) a value onto the target of a Lens and return the old result.

When you do not need the result of the operation, (<|~) is more flexible.

(<|) a value onto the target of a Lens into your Monad's state and return the old result.

When you do not need the result of the operation, (<|=) is more flexible.

This class provides a way to attach or detach elements on the right side of a structure in a flexible manner.

snoc an element onto a container.

>>> snoc (Seq.fromList []) afromList [a]

>>> snoc (Seq.fromList [b, c]) afromList [b,c,a]

>>> snoc (LazyT.pack "hello") '!'"hello!"

Attempt to extract the right-most element from a container, and a version of the container without that element.

>>> unsnoc (LazyT.pack "hello!")Just ("hello",'!')

>>> unsnoc (LazyT.pack "")Nothing

>>> unsnoc (Seq.fromList [b,c,a])Just (fromList [b,c],a)

>>> unsnoc (Seq.fromList [])Nothing

A Traversal reading and replacing all but the a last element of a non-empty container.

>>> [a,b,c,d]^?_initJust [a,b,c]

>>> []^?_initNothing

>>> [a,b] & _init .~ [c,d,e][c,d,e,b]

>>> [] & _init .~ [a,b][]

>>> [a,b,c,d] & _init.traverse %~ f[f a,f b,f c,d]

>>> [1,2,3]^?_initJust [1,2]

>>> [1,2,3,4]^?!_init[1,2,3]

>>> "hello"^._init"hell"

>>> ""^._init""

_init :: Traversal' [a] [a]
_init :: Traversal' (Seq a) (Seq a)
_init :: Traversal' (Vector a) (Vector a)

A Traversal reading and writing to the last element of a non-empty container.

>>> [a,b,c]^?!_lastc

>>> []^?_lastNothing

>>> [a,b,c] & _last %~ f[a,b,f c]

>>> [1,2]^?_lastJust 2

>>> [] & _last .~ 1[]

>>> [0] & _last .~ 2[2]

>>> [0,1] & _last .~ 2[0,2]

This Traversal is not limited to lists, however. We can also work with other containers, such as a Vector.

>>> Vector.fromList "abcde" ^? _lastJust 'e'

>>> Vector.empty ^? _lastNothing

>>> (Vector.fromList "abcde" & _last .~ 'Q') == Vector.fromList "abcdQ"True

_last :: Traversal' [a] a
_last :: Traversal' (Seq a) a
_last :: Traversal' (Vector a) a

(|>) a value onto the target of a Lens and return the old result.

When you do not need the result of the operation, (|>~) is more flexible.

(|>) a value onto the target of a Lens into your Monad's state and return the old result.

When you do not need the result of the operation, (|>=) is more flexible.

This is an adverb that can be used to modify many other Lens combinators to make them require simple lenses, simple traversals, simple prisms or simple isos as input.

A Simple Equality.

When you see this as an argument to a function, it expects an Equality.

A Simple AnEquality.

Propositional equality. If a :~: b is inhabited by some terminating value, then the type a is the same as the type b. To use this equality in practice, pattern-match on the a :~: b to get out the Refl constructor; in the body of the pattern-match, the compiler knows that a ~ b.

Extract a witness of type Equality.

Substituting types with Equality.

We can use Equality to do substitution into anything.

Equality is symmetric.

Composition with this isomorphism is occasionally useful when your Lens, Control.Lens.Traversal.Traversal or Iso has a constraint on an unused argument to force that argument to agree with the type of a used argument and avoid ScopedTypeVariables or other ugliness.

Construct an Equality from explicit equality evidence.

A Simple version of equality

A version of substEq that provides explicit, rather than implicit, equality evidence.

The opposite of working overEquality is working underEquality.

Recover a "profunctor lens" form of equality. Reverses fromLeibniz.

Convert a "profunctor lens" form of equality to an equality. Reverses overEquality.

The type should be understood as

fromLeibniz :: (forall p. p a b -> p s t) -> Equality s t a b

Convert Leibniz equality to equality. Reverses mapEq in Simple cases.

The type should be understood as

fromLeibniz' :: (forall f. f s -> f a) -> Equality' s a

Provides witness that (s ~ a, b ~ t) holds.

Every IndexedFold is a valid Control.Lens.Fold.Fold and can be used for Getting.