Lens.Family2

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.

Lenses

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

Traversals

^. 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).

Grates

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.

Adapters, Grids, and Prisms

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

Building and Finding Optics

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

Documentation

to :: (s -> a) -> Getter s t a b

to promotes a projection function to a read-only lens called a getter. To demote a lens to a projection function, use the section (^.l) or view l.

>>> (3 :+ 4, "example")^._1.to(abs)
5.0 :+ 0.0

view :: FoldLike a s t a b -> s -> a

view :: Getter s t a b -> s -> a

Demote a lens or getter to a projection function.

view :: Monoid a => Fold s t a b -> s -> a

Returns the monoidal summary of a traversal or a fold.

(^.) :: s -> FoldLike a s t a b -> a infixl 8

(^.) :: s -> Getter s t a b -> a

Access the value referenced by a getter or lens.

(^.) :: Monoid a => s -> Fold s t a b -> a

Access the monoidal summary referenced by a traversal or a fold.

folding :: Foldable f => (s -> f a) -> Fold s t a b

folding promotes a "toList" function to a read-only traversal called a fold.

To demote a traversal or fold to a "toList" function use the section (^..l) or toListOf l.

views :: FoldLike r s t a b -> (a -> r) -> s -> r

views :: Monoid r => Fold s t a b -> (a -> r) -> s -> r

Given a fold or traversal, return the foldMap of all the values using the given function.

views :: Getter s t a b -> (a -> r) -> s -> r

views is not particularly useful for getters or lenses, but given a getter or lens, it returns the referenced value passed through the given function.

views l f s = f (view l s)

(^..) :: s -> Fold s t a b -> [a] infixl 8

Returns a list of all of the referenced values in order.

(^?) :: s -> Fold s t a b -> Maybe a infixl 8

Returns Just the first referenced value. Returns Nothing if there are no referenced values.

toListOf :: Fold s t a b -> s -> [a]

Returns a list of all of the referenced values in order.

allOf :: Fold s t a b -> (a -> Bool) -> s -> Bool

Returns true if all of the referenced values satisfy the given predicate.

anyOf :: Fold s t a b -> (a -> Bool) -> s -> Bool

Returns true if any of the referenced values satisfy the given predicate.

firstOf :: Fold s t a b -> s -> Maybe a

Returns Just the first referenced value. Returns Nothing if there are no referenced values. See ^? for an infix version of firstOf

lastOf :: Fold s t a b -> s -> Maybe a

Returns Just the last referenced value. Returns Nothing if there are no referenced values.

sumOf :: Num a => Fold s t a b -> s -> a

Returns the sum of all the referenced values.

productOf :: Num a => Fold s t a b -> s -> a

Returns the product of all the referenced values.

lengthOf :: Num r => Fold s t a b -> s -> r

Counts the number of references in a traversal or fold for the input.

nullOf :: Fold s t a b -> s -> Bool

Returns true if the number of references in the input is zero.

matching :: Traversal s t a b -> s -> Either t a

Returns Right of the first referenced value. Returns Left the original value when there are no referenced values. In case there are no referenced values, the result might have a fresh type parameter, thereby proving the original value had no referenced values.

over :: Setter s t a b -> (a -> b) -> s -> t

Demote a setter to a semantic editor combinator.

over :: Prism s t a b -> Reviwer s t a b
over :: Grid s t a b -> Grate s t a b
over :: Adapter s t a b -> Grate s t a b

Covert an AdapterLike optic into a GrateLike optic.

(%~) :: Setter s t a b -> (a -> b) -> s -> t infixr 4

Modify all referenced fields.

set :: Setter s t a b -> b -> s -> t

Set all referenced fields to the given value.

(.~) :: Setter s t a b -> b -> s -> t infixr 4

Set all referenced fields to the given value.

review :: GrateLike (Constant () :: Type -> Type) s t a b -> b -> t

review :: Grate s t a b -> b -> t
review :: Reviewer s t a b -> b -> t

zipWithOf :: Grate s t a b -> (a -> a -> b) -> s -> s -> t

Returns a binary instance of a grate.

zipWithOf l f x y = degrating l (k -> f (k x) (k y))

degrating :: Grate s t a b -> ((s -> a) -> b) -> t

Demote a grate to its normal, higher-order function, form.

degrating . grate = id
grate . degrating = id

under :: Resetter s t a b -> (a -> b) -> s -> t

Demote a resetter to a semantic editor combinator.

under :: Prism s t a b -> Traversal s t a b
under :: Grid s t a b -> Traversal s t a b
under :: Adapter s t a b -> Lens s t a b

Covert an AdapterLike optic into a LensLike optic.

Note: this function is unrelated to the lens package's under function.

reset :: Resetter s t a b -> b -> s -> t

Set all referenced fields to the given value.

(&) :: s -> (s -> t) -> t infixl 1

A flipped version of ($).

Pseudo-imperatives

(+~) :: Num a => Setter s t a a -> a -> s -> t infixr 4

(*~) :: Num a => Setter s t a a -> a -> s -> t infixr 4

(-~) :: Num a => Setter s t a a -> a -> s -> t infixr 4

(//~) :: Fractional a => Setter s t a a -> a -> s -> t infixr 4

(&&~) :: Setter s t Bool Bool -> Bool -> s -> t infixr 4

(||~) :: Setter s t Bool Bool -> Bool -> s -> t infixr 4

(<>~) :: Monoid a => Setter s t a a -> a -> s -> t infixr 4

Monoidally append a value to all referenced fields.

Types

type Adapter s t a b = forall f g. (Functor f, Functor g) => AdapterLike f g s t a b

type Adapter' s a = forall f g. (Functor f, Functor g) => AdapterLike' f g s a

type Prism s t a b = forall f g. (Applicative f, Traversable g) => AdapterLike f g s t a b

type Prism' s a = forall f g. (Applicative f, Traversable g) => AdapterLike' f g s a

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

type Lens' s a = forall f. Functor f => LensLike' f s a

type Traversal s t a b = forall f. Applicative f => LensLike f s t a b

type Traversal' s a = forall f. Applicative f => LensLike' f s a

type Setter s t a b = forall f. Identical f => LensLike f s t a b

type Setter' s a = forall f. Identical f => LensLike' f s a

type Getter s t a b = forall f. Phantom f => LensLike f s t a b

type Getter' s a = forall f. Phantom f => LensLike' f s a

type Fold s t a b = forall f. (Phantom f, Applicative f) => LensLike f s t a b

type Fold' s a = forall f. (Phantom f, Applicative f) => LensLike' f s a

type Grate s t a b = forall g. Functor g => GrateLike g s t a b

type Grate' s a = forall g. Functor g => GrateLike' g s a

type Grid s t a b = forall f g. (Applicative f, Functor g) => AdapterLike f g s t a b

type Grid' s a = forall f g. (Applicative f, Functor g) => AdapterLike' f g s a

type Reviewer s t a b = forall f. Phantom f => GrateLike f s t a b

type Reviewer' s a = forall f. Phantom f => GrateLike' f s a

type AdapterLike (f :: Type -> Type) (g :: Type -> Type) s t a b = (g a -> f b) -> g s -> f t

type AdapterLike' (f :: Type -> Type) (g :: Type -> Type) s a = (g a -> f a) -> g s -> f s

type LensLike (f :: Type -> Type) s t a b = (a -> f b) -> s -> f t

type LensLike' (f :: Type -> Type) s a = (a -> f a) -> s -> f s

type GrateLike (g :: Type -> Type) s t a b = (g a -> b) -> g s -> t

type GrateLike' (g :: Type -> Type) s a = (g a -> a) -> g s -> s

type FoldLike r s t a b = LensLike (Constant r :: Type -> Type) s t a b

type FoldLike' r s a = LensLike' (Constant r :: Type -> Type) s a

data Constant a (b :: k) :: forall k. Type -> k -> Type

Constant functor.

Instances

Bitraversable (Constant :: Type -> Type -> Type)

Defined in Data.Functor.Constant

Methods

bitraverse :: Applicative f => (a -> f c) -> (b -> f d) -> Constant a b -> f (Constant c d)

Bifoldable (Constant :: Type -> Type -> Type)

Defined in Data.Functor.Constant

Methods

bifold :: Monoid m => Constant m m -> m

bifoldMap :: Monoid m => (a -> m) -> (b -> m) -> Constant a b -> m

bifoldr :: (a -> c -> c) -> (b -> c -> c) -> c -> Constant a b -> c

bifoldl :: (c -> a -> c) -> (c -> b -> c) -> c -> Constant a b -> c

Bifunctor (Constant :: Type -> Type -> Type)

Defined in Data.Functor.Constant

Methods

bimap :: (a -> b) -> (c -> d) -> Constant a c -> Constant b d

first :: (a -> b) -> Constant a c -> Constant b c

second :: (b -> c) -> Constant a b -> Constant a c

Eq2 (Constant :: Type -> Type -> Type)

Defined in Data.Functor.Constant

Methods

liftEq2 :: (a -> b -> Bool) -> (c -> d -> Bool) -> Constant a c -> Constant b d -> Bool

Ord2 (Constant :: Type -> Type -> Type)

Defined in Data.Functor.Constant

Methods

liftCompare2 :: (a -> b -> Ordering) -> (c -> d -> Ordering) -> Constant a c -> Constant b d -> Ordering

Read2 (Constant :: Type -> Type -> Type)

Defined in Data.Functor.Constant

Methods

liftReadsPrec2 :: (Int -> ReadS a) -> ReadS [a] -> (Int -> ReadS b) -> ReadS [b] -> Int -> ReadS (Constant a b)

liftReadList2 :: (Int -> ReadS a) -> ReadS [a] -> (Int -> ReadS b) -> ReadS [b] -> ReadS [Constant a b]

liftReadPrec2 :: ReadPrec a -> ReadPrec [a] -> ReadPrec b -> ReadPrec [b] -> ReadPrec (Constant a b)

liftReadListPrec2 :: ReadPrec a -> ReadPrec [a] -> ReadPrec b -> ReadPrec [b] -> ReadPrec [Constant a b]

Show2 (Constant :: Type -> Type -> Type)

Defined in Data.Functor.Constant

Methods

liftShowsPrec2 :: (Int -> a -> ShowS) -> ([a] -> ShowS) -> (Int -> b -> ShowS) -> ([b] -> ShowS) -> Int -> Constant a b -> ShowS

liftShowList2 :: (Int -> a -> ShowS) -> ([a] -> ShowS) -> (Int -> b -> ShowS) -> ([b] -> ShowS) -> [Constant a b] -> ShowS

Functor (Constant a :: Type -> Type)

Defined in Data.Functor.Constant

Methods

fmap :: (a0 -> b) -> Constant a a0 -> Constant a b

(<$) :: a0 -> Constant a b -> Constant a a0

Monoid a => Applicative (Constant a :: Type -> Type)

Defined in Data.Functor.Constant

Methods

pure :: a0 -> Constant a a0

(<*>) :: Constant a (a0 -> b) -> Constant a a0 -> Constant a b

liftA2 :: (a0 -> b -> c) -> Constant a a0 -> Constant a b -> Constant a c

(*>) :: Constant a a0 -> Constant a b -> Constant a b

(<*) :: Constant a a0 -> Constant a b -> Constant a a0

Foldable (Constant a :: Type -> Type)

Defined in Data.Functor.Constant

Methods

fold :: Monoid m => Constant a m -> m

foldMap :: Monoid m => (a0 -> m) -> Constant a a0 -> m

foldr :: (a0 -> b -> b) -> b -> Constant a a0 -> b

foldr' :: (a0 -> b -> b) -> b -> Constant a a0 -> b

foldl :: (b -> a0 -> b) -> b -> Constant a a0 -> b

foldl' :: (b -> a0 -> b) -> b -> Constant a a0 -> b

foldr1 :: (a0 -> a0 -> a0) -> Constant a a0 -> a0

foldl1 :: (a0 -> a0 -> a0) -> Constant a a0 -> a0

toList :: Constant a a0 -> [a0]

null :: Constant a a0 -> Bool

length :: Constant a a0 -> Int

elem :: Eq a0 => a0 -> Constant a a0 -> Bool

maximum :: Ord a0 => Constant a a0 -> a0

minimum :: Ord a0 => Constant a a0 -> a0

sum :: Num a0 => Constant a a0 -> a0

product :: Num a0 => Constant a a0 -> a0

Traversable (Constant a :: Type -> Type)

Defined in Data.Functor.Constant

Methods

traverse :: Applicative f => (a0 -> f b) -> Constant a a0 -> f (Constant a b)

sequenceA :: Applicative f => Constant a (f a0) -> f (Constant a a0)

mapM :: Monad m => (a0 -> m b) -> Constant a a0 -> m (Constant a b)

sequence :: Monad m => Constant a (m a0) -> m (Constant a a0)

Contravariant (Constant a :: Type -> Type)

Defined in Data.Functor.Constant

Methods

contramap :: (a0 -> b) -> Constant a b -> Constant a a0

(>$) :: b -> Constant a b -> Constant a a0

Eq a => Eq1 (Constant a :: Type -> Type)

Defined in Data.Functor.Constant

Methods

liftEq :: (a0 -> b -> Bool) -> Constant a a0 -> Constant a b -> Bool

Ord a => Ord1 (Constant a :: Type -> Type)

Defined in Data.Functor.Constant

Methods

liftCompare :: (a0 -> b -> Ordering) -> Constant a a0 -> Constant a b -> Ordering

Read a => Read1 (Constant a :: Type -> Type)

Defined in Data.Functor.Constant

Methods

liftReadsPrec :: (Int -> ReadS a0) -> ReadS [a0] -> Int -> ReadS (Constant a a0)

liftReadList :: (Int -> ReadS a0) -> ReadS [a0] -> ReadS [Constant a a0]

liftReadPrec :: ReadPrec a0 -> ReadPrec [a0] -> ReadPrec (Constant a a0)

liftReadListPrec :: ReadPrec a0 -> ReadPrec [a0] -> ReadPrec [Constant a a0]

Show a => Show1 (Constant a :: Type -> Type)

Defined in Data.Functor.Constant

Methods

liftShowsPrec :: (Int -> a0 -> ShowS) -> ([a0] -> ShowS) -> Int -> Constant a a0 -> ShowS

liftShowList :: (Int -> a0 -> ShowS) -> ([a0] -> ShowS) -> [Constant a a0] -> ShowS

Phantom (Constant a :: Type -> Type)

Defined in Lens.Family.Phantom

Methods

coerce :: Constant a a0 -> Constant a b

Eq a => Eq (Constant a b)

Defined in Data.Functor.Constant

Methods

(==) :: Constant a b -> Constant a b -> Bool

(/=) :: Constant a b -> Constant a b -> Bool

Ord a => Ord (Constant a b)

Defined in Data.Functor.Constant

Methods

compare :: Constant a b -> Constant a b -> Ordering

(<) :: Constant a b -> Constant a b -> Bool

(<=) :: Constant a b -> Constant a b -> Bool

(>) :: Constant a b -> Constant a b -> Bool

(>=) :: Constant a b -> Constant a b -> Bool

max :: Constant a b -> Constant a b -> Constant a b

min :: Constant a b -> Constant a b -> Constant a b

Read a => Read (Constant a b)

Defined in Data.Functor.Constant

Methods

readsPrec :: Int -> ReadS (Constant a b)

readList :: ReadS [Constant a b]

readPrec :: ReadPrec (Constant a b)

readListPrec :: ReadPrec [Constant a b]

Show a => Show (Constant a b)

Defined in Data.Functor.Constant

Methods

showsPrec :: Int -> Constant a b -> ShowS

show :: Constant a b -> String

showList :: [Constant a b] -> ShowS

Semigroup a => Semigroup (Constant a b)

Defined in Data.Functor.Constant

Methods

(<>) :: Constant a b -> Constant a b -> Constant a b

sconcat :: NonEmpty (Constant a b) -> Constant a b

stimes :: Integral b0 => b0 -> Constant a b -> Constant a b

Monoid a => Monoid (Constant a b)

Defined in Data.Functor.Constant

Methods

mempty :: Constant a b

mappend :: Constant a b -> Constant a b -> Constant a b

mconcat :: [Constant a b] -> Constant a b

class Functor f => Phantom (f :: Type -> Type)

Minimal complete definition

coerce

Instances

Phantom (Const a :: Type -> Type)

Defined in Lens.Family.Phantom

Methods

coerce :: Const a a0 -> Const a b

Phantom f => Phantom (AlongsideLeft f a)

Defined in Lens.Family.Stock

Methods

coerce :: AlongsideLeft f a a0 -> AlongsideLeft f a b

Phantom f => Phantom (AlongsideRight f a)

Defined in Lens.Family.Stock

Methods

coerce :: AlongsideRight f a a0 -> AlongsideRight f a b

Phantom g => Phantom (FromG e g)

Defined in Lens.Family.Stock

Methods

coerce :: FromG e g a -> FromG e g b

Phantom f => Phantom (Backwards f)

Defined in Lens.Family.Phantom

Methods

coerce :: Backwards f a -> Backwards f b

Phantom (Constant a :: Type -> Type)

Defined in Lens.Family.Phantom

Methods

coerce :: Constant a a0 -> Constant a b

Phantom g => Phantom (FromF i j g)

Defined in Lens.Family.Stock

Methods

coerce :: FromF i j g a -> FromF i j g b

(Phantom f, Functor g) => Phantom (Compose f g)

Defined in Lens.Family.Phantom

Methods

coerce :: Compose f g a -> Compose f g b

class (Traversable f, Applicative f) => Identical (f :: Type -> Type)

Minimal complete definition

extract

Instances

Identical Identity

Defined in Lens.Family.Identical

Methods

extract :: Identity a -> a

Identical f => Identical (Backwards f)

Defined in Lens.Family.Identical

Methods

extract :: Backwards f a -> a

(Identical f, Identical g) => Identical (Compose f g)

Defined in Lens.Family.Identical

Methods

extract :: Compose f g a -> a