This is the main module for end-users of lens-families. If you are not building your own optics such as lenses, traversals, grates, etc., but just using optics made by others, this is the only module you need.

This module provides ^. for accessing fields and .~ and %~ for setting and modifying fields. Lenses are composed with . from the Prelude and id is the identity lens.

Lens composition in this library enjoys the following identities.

• x^.l1.l2 === x^.l1^.l2

• l1.l2 %~ f === l1 %~ l2 %~ f

The identity lens behaves as follows.

• x^.id === x

• id %~ f === f

The & operator, allows for a convenient way to sequence record updating:

record & l1 .~ value1 & l2 .~ value2

Lenses are implemented in van Laarhoven style. Lenses have type Functor f => (a -> f a) -> s -> f s and lens families have type Functor f => (a i -> f (a j)) -> s i -> f (s j).

Keep in mind that lenses and lens families can be used directly for functorial updates. For example, _2 id gives you strength.

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

Here is an example of code that uses the Maybe functor to preserves sharing during update when possible.

-- | 'sharedUpdate' returns the *identical* object if the update doesn't change anything.
-- This is useful for preserving sharing.
sharedUpdate :: Eq a => LensLike' Maybe s a -> (a -> a) -> s -> s
sharedUpdate l f s = fromMaybe s (l f' s)
 where
  f' a | b == a    = Nothing
       | otherwise = Just b
   where
    b = f a

^. can be used with traversals to access monoidal fields. The result will be a mconcat of all the fields referenced. The various fooOf functions can be used to access different monoidal summaries of some kinds of values.

^? can be used to access the first value of a traversal. Nothing is returned when the traversal has no references.

^.. can be used with a traversals and will return a list of all fields referenced.

When .~ is used with a traversal, all referenced fields will be set to the same value, and when %~ is used with a traversal, all referenced fields will be modified with the same function.

A variant of ^? call matching returns Either a Right value which is the first value of the traversal, or a Left value which is a "proof" that the traversal has no elements. The "proof" consists of the original input structure, but in the case of polymorphic families, the type parameter is replaced with a fresh type variable, thus proving that the type parameter was unused.

Like all optics, traversals can be composed with ., and because every lens is automatically a traversal, lenses and traversals can be composed with . yielding a traversal.

Traversals are implemented in van Laarhoven style. Traversals have type Applicative f => (a -> f a) -> s -> f s and traversal families have type Applicative f => (a i -> f (a j)) -> s i -> f (s j).

zipWithOf can be used with grates to zip two structure together provided a binary operation.

under can be to modify each value in a structure according to a function. This works analogous to how over works for lenses and traversals.

review can be used with grates to construct a constant grate from a single value. This is like a 0-ary zipWith function.

degrating can be used to build higher arity zipWithOf functions:

zipWith3Of :: AGrate s t a b -> (a -> a -> a -> b) -> s -> s -> s -> t
zipWith3Of l f s1 s2 s3 = degrating l (\k -> f (k s1) (k s2) (k s3))

Like all optics, grates can be composed with ., and id is the identity grate.

Grates are implemented in van Laarhoven style.

Grates have type Functor g => (g a -> a) -> g s -> s and grate families have type Functor g => (g (a i) -> a j) -> g (s i) -> s j.

Keep in mind that grates and grate families can be used directly for functorial zipping. For example,

both sum :: Num a => [(a, a)] -> (a, a)

will take a list of pairs return the sum of the first components and the sum of the second components. For another example,

cod id :: Functor f => f (r -> a) -> r -> f a

will turn a functor full of functions into a function returning a functor full of results.

The Adapter, Prism, and Grid optics are all AdapterLike optics and typically not used directly, but either converted to a LensLike optic using under, or into a GrateLike optic using over. See under and over for details about which conversions are possible.

These optics are implemented in van Laarhoven style.

• Adapters have type (Functor f, Functor g) => (g a -> f a) -> g s -> f s and Adapters families have type (Functor f, Functor g) => (g (a i) -> f (a j)) -> g (s i) -> f (s j).
• Grids have type (Applicative f, Functor g) => (g a -> f a) -> g s -> f s and Grids families have type (Applicative f, Functor g) => (g (a i) -> f (a j)) -> g (s i) -> f (s j).
• Prisms have type (Applicative f, Traversable g) => (g a -> f a) -> g s -> f s and Prisms families have type (Applicative f, Traversable g) => (g (a i) -> f (a j)) -> g (s i) -> f (s j).

Keep in mind that these optics and their families can sometimes be used directly, without using over and under. Sometimes you can take advantage of the fact that

   LensLike f (g s) t (g a) b
  ==
   AdapterLike f g s t a b
  ==
   GrateLike g s (f t) a (f b)

For example, if you have a grid for your structure to another type that has an Arbitray instance, such as grid from a custom word type to Bool, e.g. myWordBitVector :: (Applicative f, Functor g) => AdapterLike' f g MyWord Bool, you can use the grid to create an Arbitrary instance for your structure by directly applying review:

instance Arbitrary MyWord where
  arbitrary = review myWordBitVector arbitrary

To build your own optics, see Lens.Family2.Unchecked.

For stock optics, see Lens.Family2.Stock.

References:

• http://www.twanvl.nl/blog/haskell/cps-functional-references
• http://r6.ca/blog/20120623T104901Z.html
• http://comonad.com/reader/2012/mirrored-lenses/
• http://conal.net/blog/posts/semantic-editor-combinators
• https://r6research.livejournal.com/28050.html