Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
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.
Synopsis
- to :: (s -> a) -> Getter s t a b
- view :: FoldLike a s t a b -> s -> a
- (^.) :: s -> FoldLike a s t a b -> a
- folding :: Foldable f => (s -> f a) -> Fold s t a b
- views :: FoldLike r s t a b -> (a -> r) -> s -> r
- (^..) :: s -> Fold s t a b -> [a]
- (^?) :: s -> Fold s t a b -> Maybe a
- toListOf :: Fold s t a b -> s -> [a]
- allOf :: Fold s t a b -> (a -> Bool) -> s -> Bool
- anyOf :: Fold s t a b -> (a -> Bool) -> s -> Bool
- firstOf :: Fold s t a b -> s -> Maybe a
- lastOf :: Fold s t a b -> s -> Maybe a
- sumOf :: Num a => Fold s t a b -> s -> a
- productOf :: Num a => Fold s t a b -> s -> a
- lengthOf :: Num r => Fold s t a b -> s -> r
- nullOf :: Fold s t a b -> s -> Bool
- matching :: Traversal s t a b -> s -> Either t a
- over :: Setter s t a b -> (a -> b) -> s -> t
- (%~) :: Setter s t a b -> (a -> b) -> s -> t
- set :: Setter s t a b -> b -> s -> t
- (.~) :: Setter s t a b -> b -> s -> t
- review :: GrateLike (Constant () :: Type -> Type) s t a b -> b -> t
- zipWithOf :: Grate s t a b -> (a -> a -> b) -> s -> s -> t
- degrating :: Grate s t a b -> ((s -> a) -> b) -> t
- under :: Resetter s t a b -> (a -> b) -> s -> t
- reset :: Resetter s t a b -> b -> s -> t
- (&) :: s -> (s -> t) -> t
- (+~) :: Num a => Setter s t a a -> a -> s -> t
- (*~) :: Num a => Setter s t a a -> a -> s -> t
- (-~) :: Num a => Setter s t a a -> a -> s -> t
- (//~) :: Fractional a => Setter s t a a -> a -> s -> t
- (&&~) :: Setter s t Bool Bool -> Bool -> s -> t
- (||~) :: Setter s t Bool Bool -> Bool -> s -> t
- (<>~) :: Monoid a => Setter s t a a -> a -> s -> t
- 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)
- class Functor f => Phantom (f :: Type -> Type)
- class (Traversable f, Applicative f) => Identical (f :: Type -> Type)
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
and lens families have type Functor
f => (a -> f a) -> s -> f s
.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
and traversal families have type Applicative
f => (a -> f a) -> s -> f s
.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 used 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
and grate families have type Functor
g => (g a -> a) -> g s -> s
.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
(
and Adapters families have typeFunctor
f,Functor
g) => (g a -> f a) -> g s -> f s(
.Functor
f,Functor
g) => (g (a i) -> f (a j)) -> g (s i) -> f (s j) - Grids have type
(
and Grids families have typeApplicative
f,Functor
g) => (g a -> f a) -> g s -> f s(
.Applicative
f,Functor
g) => (g (a i) -> f (a j)) -> g (s i) -> f (s j) - Prisms have type
(
and Prisms families have typeApplicative
f,Traversable
g) => (g a -> f a) -> g s -> f s(
.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:
Documentation
to :: (s -> a) -> Getter s t a b Source #
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 Source #
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 Source #
Returns a list of all of the referenced values in order.
toListOf :: Fold s t a b -> s -> [a] Source #
Returns a list of all of the referenced values in order.
allOf :: Fold s t a b -> (a -> Bool) -> s -> Bool Source #
Returns true if all of the referenced values satisfy the given predicate.
anyOf :: Fold s t a b -> (a -> Bool) -> s -> Bool Source #
Returns true if any of the referenced values satisfy the given predicate.
productOf :: Num a => Fold s t a b -> s -> a Source #
Returns the product of all the referenced values.
lengthOf :: Num r => Fold s t a b -> s -> r Source #
Counts the number of references in a traversal or fold for the input.
nullOf :: Fold s t a b -> s -> Bool Source #
Returns true if the number of references in the input is zero.
over :: Setter s t a b -> (a -> b) -> s -> t Source #
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 -> b -> s -> t infixr 4 Source #
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 Source #
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 Source #
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 Source #
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.
Pseudo-imperatives
(//~) :: Fractional a => Setter s t a a -> a -> s -> t infixr 4 Source #
(<>~) :: Monoid a => Setter s t a a -> a -> s -> t infixr 4 Source #
Monoidally append a value to all referenced fields.
Types
type Prism s t a b = forall f g. (Applicative f, Traversable g) => AdapterLike f g s t a b Source #
type Prism' s a = forall f g. (Applicative f, Traversable g) => AdapterLike' f g s a Source #
type Traversal s t a b = forall f. Applicative f => LensLike f s t a b Source #
type Traversal' s a = forall f. Applicative f => LensLike' f s a Source #
type Grate' s a = forall g. Functor g => GrateLike' g s a Source #
type Grid s t a b = forall f g. (Applicative f, Functor g) => AdapterLike f g s t a b Source #
type Grid' s a = forall f g. (Applicative f, Functor g) => AdapterLike' f g s a Source #
type Reviewer' s a = forall f. Phantom f => GrateLike' f s a Source #
type GrateLike' (g :: Type -> Type) s a = (g a -> a) -> g s -> s #
Constant functor.
Instances
Generic1 (Constant a :: k -> Type) | |
Bifoldable (Constant :: Type -> Type -> Type) | |
Bifunctor (Constant :: Type -> Type -> Type) | |
Bitraversable (Constant :: Type -> Type -> Type) | |
Defined in Data.Functor.Constant bitraverse :: Applicative f => (a -> f c) -> (b -> f d) -> Constant a b -> f (Constant c d) # | |
Eq2 (Constant :: Type -> Type -> Type) | |
Ord2 (Constant :: Type -> Type -> Type) | |
Defined in Data.Functor.Constant | |
Read2 (Constant :: Type -> Type -> Type) | |
Defined in Data.Functor.Constant 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) | |
Foldable (Constant a :: Type -> Type) | |
Defined in Data.Functor.Constant fold :: Monoid m => Constant a m -> m # foldMap :: Monoid m => (a0 -> m) -> Constant a a0 -> 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 # | |
Eq a => Eq1 (Constant a :: Type -> Type) | |
Ord a => Ord1 (Constant a :: Type -> Type) | |
Defined in Data.Functor.Constant | |
Read a => Read1 (Constant a :: Type -> Type) | |
Defined in Data.Functor.Constant 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) | |
Contravariant (Constant a :: Type -> Type) | |
Traversable (Constant a :: Type -> Type) | |
Defined in Data.Functor.Constant | |
Monoid a => Applicative (Constant a :: Type -> Type) | |
Defined in Data.Functor.Constant | |
Functor (Constant a :: Type -> Type) | |
Phantom (Constant a :: Type -> Type) | |
Defined in Lens.Family.Phantom | |
(Typeable b, Typeable k, Data a) => Data (Constant a b) | |
Defined in Data.Functor.Constant gfoldl :: (forall d b0. Data d => c (d -> b0) -> d -> c b0) -> (forall g. g -> c g) -> Constant a b -> c (Constant a b) # gunfold :: (forall b0 r. Data b0 => c (b0 -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (Constant a b) # toConstr :: Constant a b -> Constr # dataTypeOf :: Constant a b -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (Constant a b)) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (Constant a b)) # gmapT :: (forall b0. Data b0 => b0 -> b0) -> Constant a b -> Constant a b # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Constant a b -> r # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Constant a b -> r # gmapQ :: (forall d. Data d => d -> u) -> Constant a b -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> Constant a b -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Constant a b -> m (Constant a b) # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Constant a b -> m (Constant a b) # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Constant a b -> m (Constant a b) # | |
Monoid a => Monoid (Constant a b) | |
Semigroup a => Semigroup (Constant a b) | |
Generic (Constant a b) | |
Read a => Read (Constant a b) | |
Show a => Show (Constant a b) | |
Eq a => Eq (Constant a b) | |
Ord a => Ord (Constant a b) | |
Defined in Data.Functor.Constant | |
type Rep1 (Constant a :: k -> Type) | |
Defined in Data.Functor.Constant | |
type Rep (Constant a b) | |
Defined in Data.Functor.Constant |
class Functor f => Phantom (f :: Type -> Type) #
coerce
Instances
Phantom (Const a :: Type -> Type) | |
Defined in Lens.Family.Phantom | |
Phantom f => Phantom (AlongsideLeft f a) | |
Defined in Lens.Family.Stock coerce :: AlongsideLeft f a a0 -> AlongsideLeft f a b | |
Phantom f => Phantom (AlongsideRight f a) | |
Defined in Lens.Family.Stock coerce :: AlongsideRight f a a0 -> AlongsideRight f a b | |
Phantom g => Phantom (FromG e g) | |
Defined in Lens.Family.Stock | |
Phantom f => Phantom (Backwards f) | |
Defined in Lens.Family.Phantom | |
Phantom (Constant a :: Type -> Type) | |
Defined in Lens.Family.Phantom | |
Phantom g => Phantom (FromF i j g) | |
Defined in Lens.Family.Stock | |
(Phantom f, Functor g) => Phantom (Compose f g) | |
Defined in Lens.Family.Phantom |