lens-family-1.2.1: Lens Families

Safe HaskellSafe
LanguageHaskell98

Lens.Family2.Unchecked

Contents

Description

Caution: Improper use of this module can lead to unexpected behaviour if the preconditions of the functions are not met.

Synopsis

Lenses

A lens family is created by separating a substructure from the rest of its structure by a functor. How to create a lens family is best illustrated by the common example of a field of a record:

data MyRecord a = MyRecord { _myA :: a, _myB :: Int }

-- The use of type variables a and a' allow for polymorphic updates.
myA :: Lens (MyRecord a) (MyRecord a') a a'
myA f (MyRecord a b) = (\a' -> MyRecord a' b) `fmap` (f a)

-- The field _myB is monomorphic, so we can use a 'Lens'' type.
-- However, the structure of the function is exactly the same as for Lens.
myB :: Lens' (MyRecord a) Int
myB f (MyRecord a b) = (\b' -> MyRecord a b') `fmap` (f b)

By following this template you can safely build your own lenses. To use this template, you do not need anything from this module other than the type synonyms Lens and Lens', and even they are optional. See the lens-family-th package to generate this code using Template Haskell.

Note: It is possible to build lenses without even depending on lens-family by expanding away the type synonym.

-- A lens definition that only requires the Haskell "Prelude".
myA :: Functor f => (a -> f a') -> (MyRecord a) -> f (MyRecord a')
myA f (MyRecord a b) = (\a' -> MyRecord a' b) `fmap` (f a)

You can build lenses for more than just fields of records. Any value l :: Lens a a' b b' is well-defined when it satisfies the two van Laarhoven lens laws:

  • l Identity === Identity
  • l (Compose . fmap f . g) === Compose . fmap (l f) . (l g)

The functions lens and iso can also be used to construct lenses. The resulting lenses will be well-defined so long as their preconditions are satisfied.

Traversals

If you have zero or more fields of the same type of a record, a traversal can be used to refer to all of them in order. Multiple references are made by replacing the Functor constraint of lenses with an Applicative constraint. Consider the following example of a record with two Int fields.

data MyRecord = MyRecord { _myA :: Int, _myB :: Int }

-- myInts is a traversal over both fields of MyRecord.
myInts :: Traversal' MyRecord Int
myInts f (MyRecord a b) = MyRecord <$> f a <*> f b

If the record and the referenced fields are parametric, you can can build traversals with polymorphic updating. Consider the following example of a record with two Maybe fields.

data MyRecord a = MyRecord { _myA :: Maybe a, _myB :: Maybe a }

-- myInts is a traversal over both fields of MyRecord.
myMaybes :: Traversal (MyRecord a) (MyRecord a') (Maybe a) (Maybe a')
myMaybes f (MyRecord a b) = MyRecord <$> f a <*> f b

Note: As with lenses, is possible to build traversals without even depending on lens-family-core by expanding away the type synonym.

-- A traversal definition that only requires the Haskell "Prelude".
myMaybes :: Applicative f => (Maybe a -> f (Maybe a')) -> MyRecord a -> f (MyRecord a')
myMaybes f (MyRecord a b) = MyRecord <$> f a <*> f b

Unfortuantely, there are no helper functions for making traversals. You must make them by hand.

Any value t :: Traversal a a' b b' is well-defined when it satisfies the two van Laarhoven traversal laws:

  • t Identity === Identity
  • t (Compose . fmap f . g) === Compose . fmap (t f) . (t g)

traverse is the canonical traversal for various containers.

Documentation

lens Source #

Arguments

:: (a -> b)

getter

-> (a -> b' -> a')

setter

-> Lens a a' b b' 

Build a lens from a getter and setter families.

Caution: In order for the generated lens family to be well-defined, you must ensure that the three lens laws hold:

  • getter (setter a b) === b
  • setter a (getter a) === a
  • setter (setter a b1) b2) === setter a b2

iso Source #

Arguments

:: (a -> b)

yin

-> (b' -> a')

yang

-> Lens a a' b b' 

Build a lens from isomorphism families.

Caution: In order for the generated lens family to be well-defined, you must ensure that the two isomorphism laws hold:

  • yin . yang === id
  • yang . yin === id

setting Source #

Arguments

:: ((b -> b') -> a -> a')

sec (semantic editor combinator)

-> Setter a a' b b' 

setting promotes a "semantic editor combinator" to a modify-only lens. To demote a lens to a semantic edit combinator, use the section (l %~) or over l from Lens.Family2.

>>> setting map . fstL %~ length $ [("The",0),("quick",1),("brown",1),("fox",2)]
[(3,0),(5,1),(5,1),(3,2)]

Caution: In order for the generated setter family to be well-defined, you must ensure that the two functors laws hold:

  • sec id === id
  • sec f . sec g === sec (f . g)

Types

type Lens a a' b b' = forall f. Functor f => LensLike f a a' b b' Source #

type Lens' a b = forall f. Functor f => LensLike' f a b Source #

type Traversal a a' b b' = forall f. Applicative f => LensLike f a a' b b' Source #

type Traversal' a b = forall f. Applicative f => LensLike' f a b Source #

type Setter a a' b b' = forall f. Identical f => LensLike f a a' b b' Source #

type Setter' a b = forall f. Identical f => LensLike' f a b Source #

type LensLike f a a' b b' = (b -> f b') -> a -> f a' #

type LensLike' f a b = (b -> f b) -> a -> f a #

class Applicative f => Identical f #

Minimal complete definition

extract

Instances

Identical Identity 

Methods

extract :: Identity a -> a

Identical f => Identical (Backwards * f) 

Methods

extract :: Backwards * f a -> a

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

Methods

extract :: Compose * * f g a -> a

Re-exports

class Functor f => Applicative f #

A functor with application, providing operations to

  • embed pure expressions (pure), and
  • sequence computations and combine their results (<*>).

A minimal complete definition must include implementations of these functions satisfying the following laws:

identity
pure id <*> v = v
composition
pure (.) <*> u <*> v <*> w = u <*> (v <*> w)
homomorphism
pure f <*> pure x = pure (f x)
interchange
u <*> pure y = pure ($ y) <*> u

The other methods have the following default definitions, which may be overridden with equivalent specialized implementations:

As a consequence of these laws, the Functor instance for f will satisfy

If f is also a Monad, it should satisfy

(which implies that pure and <*> satisfy the applicative functor laws).

Minimal complete definition

pure, (<*>)

Instances

Applicative [] 

Methods

pure :: a -> [a] #

(<*>) :: [a -> b] -> [a] -> [b] #

(*>) :: [a] -> [b] -> [b] #

(<*) :: [a] -> [b] -> [a] #

Applicative Maybe 

Methods

pure :: a -> Maybe a #

(<*>) :: Maybe (a -> b) -> Maybe a -> Maybe b #

(*>) :: Maybe a -> Maybe b -> Maybe b #

(<*) :: Maybe a -> Maybe b -> Maybe a #

Applicative IO 

Methods

pure :: a -> IO a #

(<*>) :: IO (a -> b) -> IO a -> IO b #

(*>) :: IO a -> IO b -> IO b #

(<*) :: IO a -> IO b -> IO a #

Applicative U1 

Methods

pure :: a -> U1 a #

(<*>) :: U1 (a -> b) -> U1 a -> U1 b #

(*>) :: U1 a -> U1 b -> U1 b #

(<*) :: U1 a -> U1 b -> U1 a #

Applicative Par1 

Methods

pure :: a -> Par1 a #

(<*>) :: Par1 (a -> b) -> Par1 a -> Par1 b #

(*>) :: Par1 a -> Par1 b -> Par1 b #

(<*) :: Par1 a -> Par1 b -> Par1 a #

Applicative Identity 

Methods

pure :: a -> Identity a #

(<*>) :: Identity (a -> b) -> Identity a -> Identity b #

(*>) :: Identity a -> Identity b -> Identity b #

(<*) :: Identity a -> Identity b -> Identity a #

Applicative ZipList 

Methods

pure :: a -> ZipList a #

(<*>) :: ZipList (a -> b) -> ZipList a -> ZipList b #

(*>) :: ZipList a -> ZipList b -> ZipList b #

(<*) :: ZipList a -> ZipList b -> ZipList a #

Applicative Dual 

Methods

pure :: a -> Dual a #

(<*>) :: Dual (a -> b) -> Dual a -> Dual b #

(*>) :: Dual a -> Dual b -> Dual b #

(<*) :: Dual a -> Dual b -> Dual a #

Applicative Sum 

Methods

pure :: a -> Sum a #

(<*>) :: Sum (a -> b) -> Sum a -> Sum b #

(*>) :: Sum a -> Sum b -> Sum b #

(<*) :: Sum a -> Sum b -> Sum a #

Applicative Product 

Methods

pure :: a -> Product a #

(<*>) :: Product (a -> b) -> Product a -> Product b #

(*>) :: Product a -> Product b -> Product b #

(<*) :: Product a -> Product b -> Product a #

Applicative First 

Methods

pure :: a -> First a #

(<*>) :: First (a -> b) -> First a -> First b #

(*>) :: First a -> First b -> First b #

(<*) :: First a -> First b -> First a #

Applicative Last 

Methods

pure :: a -> Last a #

(<*>) :: Last (a -> b) -> Last a -> Last b #

(*>) :: Last a -> Last b -> Last b #

(<*) :: Last a -> Last b -> Last a #

Applicative ((->) a) 

Methods

pure :: a -> a -> a #

(<*>) :: (a -> a -> b) -> (a -> a) -> a -> b #

(*>) :: (a -> a) -> (a -> b) -> a -> b #

(<*) :: (a -> a) -> (a -> b) -> a -> a #

Applicative (Either e) 

Methods

pure :: a -> Either e a #

(<*>) :: Either e (a -> b) -> Either e a -> Either e b #

(*>) :: Either e a -> Either e b -> Either e b #

(<*) :: Either e a -> Either e b -> Either e a #

Applicative f => Applicative (Rec1 f) 

Methods

pure :: a -> Rec1 f a #

(<*>) :: Rec1 f (a -> b) -> Rec1 f a -> Rec1 f b #

(*>) :: Rec1 f a -> Rec1 f b -> Rec1 f b #

(<*) :: Rec1 f a -> Rec1 f b -> Rec1 f a #

Monoid a => Applicative ((,) a) 

Methods

pure :: a -> (a, a) #

(<*>) :: (a, a -> b) -> (a, a) -> (a, b) #

(*>) :: (a, a) -> (a, b) -> (a, b) #

(<*) :: (a, a) -> (a, b) -> (a, a) #

Monad m => Applicative (WrappedMonad m) 

Methods

pure :: a -> WrappedMonad m a #

(<*>) :: WrappedMonad m (a -> b) -> WrappedMonad m a -> WrappedMonad m b #

(*>) :: WrappedMonad m a -> WrappedMonad m b -> WrappedMonad m b #

(<*) :: WrappedMonad m a -> WrappedMonad m b -> WrappedMonad m a #

Arrow a => Applicative (ArrowMonad a) 

Methods

pure :: a -> ArrowMonad a a #

(<*>) :: ArrowMonad a (a -> b) -> ArrowMonad a a -> ArrowMonad a b #

(*>) :: ArrowMonad a a -> ArrowMonad a b -> ArrowMonad a b #

(<*) :: ArrowMonad a a -> ArrowMonad a b -> ArrowMonad a a #

Applicative (Proxy *) 

Methods

pure :: a -> Proxy * a #

(<*>) :: Proxy * (a -> b) -> Proxy * a -> Proxy * b #

(*>) :: Proxy * a -> Proxy * b -> Proxy * b #

(<*) :: Proxy * a -> Proxy * b -> Proxy * a #

Applicative m => Applicative (ListT m) 

Methods

pure :: a -> ListT m a #

(<*>) :: ListT m (a -> b) -> ListT m a -> ListT m b #

(*>) :: ListT m a -> ListT m b -> ListT m b #

(<*) :: ListT m a -> ListT m b -> ListT m a #

(Functor m, Monad m) => Applicative (MaybeT m) 

Methods

pure :: a -> MaybeT m a #

(<*>) :: MaybeT m (a -> b) -> MaybeT m a -> MaybeT m b #

(*>) :: MaybeT m a -> MaybeT m b -> MaybeT m b #

(<*) :: MaybeT m a -> MaybeT m b -> MaybeT m a #

(Applicative f, Applicative g) => Applicative ((:*:) f g) 

Methods

pure :: a -> (f :*: g) a #

(<*>) :: (f :*: g) (a -> b) -> (f :*: g) a -> (f :*: g) b #

(*>) :: (f :*: g) a -> (f :*: g) b -> (f :*: g) b #

(<*) :: (f :*: g) a -> (f :*: g) b -> (f :*: g) a #

(Applicative f, Applicative g) => Applicative ((:.:) f g) 

Methods

pure :: a -> (f :.: g) a #

(<*>) :: (f :.: g) (a -> b) -> (f :.: g) a -> (f :.: g) b #

(*>) :: (f :.: g) a -> (f :.: g) b -> (f :.: g) b #

(<*) :: (f :.: g) a -> (f :.: g) b -> (f :.: g) a #

Arrow a => Applicative (WrappedArrow a b) 

Methods

pure :: a -> WrappedArrow a b a #

(<*>) :: WrappedArrow a b (a -> b) -> WrappedArrow a b a -> WrappedArrow a b b #

(*>) :: WrappedArrow a b a -> WrappedArrow a b b -> WrappedArrow a b b #

(<*) :: WrappedArrow a b a -> WrappedArrow a b b -> WrappedArrow a b a #

Monoid m => Applicative (Const * m) 

Methods

pure :: a -> Const * m a #

(<*>) :: Const * m (a -> b) -> Const * m a -> Const * m b #

(*>) :: Const * m a -> Const * m b -> Const * m b #

(<*) :: Const * m a -> Const * m b -> Const * m a #

Applicative f => Applicative (Alt * f) 

Methods

pure :: a -> Alt * f a #

(<*>) :: Alt * f (a -> b) -> Alt * f a -> Alt * f b #

(*>) :: Alt * f a -> Alt * f b -> Alt * f b #

(<*) :: Alt * f a -> Alt * f b -> Alt * f a #

(Monoid c, Monad m) => Applicative (Zooming m c) 

Methods

pure :: a -> Zooming m c a #

(<*>) :: Zooming m c (a -> b) -> Zooming m c a -> Zooming m c b #

(*>) :: Zooming m c a -> Zooming m c b -> Zooming m c b #

(<*) :: Zooming m c a -> Zooming m c b -> Zooming m c a #

Monoid a => Applicative (Constant * a) 

Methods

pure :: a -> Constant * a a #

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

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

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

(Functor m, Monad m) => Applicative (StateT s m) 

Methods

pure :: a -> StateT s m a #

(<*>) :: StateT s m (a -> b) -> StateT s m a -> StateT s m b #

(*>) :: StateT s m a -> StateT s m b -> StateT s m b #

(<*) :: StateT s m a -> StateT s m b -> StateT s m a #

(Functor m, Monad m) => Applicative (StateT s m) 

Methods

pure :: a -> StateT s m a #

(<*>) :: StateT s m (a -> b) -> StateT s m a -> StateT s m b #

(*>) :: StateT s m a -> StateT s m b -> StateT s m b #

(<*) :: StateT s m a -> StateT s m b -> StateT s m a #

Applicative f => Applicative (Backwards * f)

Apply f-actions in the reverse order.

Methods

pure :: a -> Backwards * f a #

(<*>) :: Backwards * f (a -> b) -> Backwards * f a -> Backwards * f b #

(*>) :: Backwards * f a -> Backwards * f b -> Backwards * f b #

(<*) :: Backwards * f a -> Backwards * f b -> Backwards * f a #

(Functor m, Monad m) => Applicative (ExceptT e m) 

Methods

pure :: a -> ExceptT e m a #

(<*>) :: ExceptT e m (a -> b) -> ExceptT e m a -> ExceptT e m b #

(*>) :: ExceptT e m a -> ExceptT e m b -> ExceptT e m b #

(<*) :: ExceptT e m a -> ExceptT e m b -> ExceptT e m a #

(Functor m, Monad m) => Applicative (ErrorT e m) 

Methods

pure :: a -> ErrorT e m a #

(<*>) :: ErrorT e m (a -> b) -> ErrorT e m a -> ErrorT e m b #

(*>) :: ErrorT e m a -> ErrorT e m b -> ErrorT e m b #

(<*) :: ErrorT e m a -> ErrorT e m b -> ErrorT e m a #

(Monoid w, Applicative m) => Applicative (WriterT w m) 

Methods

pure :: a -> WriterT w m a #

(<*>) :: WriterT w m (a -> b) -> WriterT w m a -> WriterT w m b #

(*>) :: WriterT w m a -> WriterT w m b -> WriterT w m b #

(<*) :: WriterT w m a -> WriterT w m b -> WriterT w m a #

(Monoid w, Applicative m) => Applicative (WriterT w m) 

Methods

pure :: a -> WriterT w m a #

(<*>) :: WriterT w m (a -> b) -> WriterT w m a -> WriterT w m b #

(*>) :: WriterT w m a -> WriterT w m b -> WriterT w m b #

(<*) :: WriterT w m a -> WriterT w m b -> WriterT w m a #

Applicative m => Applicative (IdentityT * m) 

Methods

pure :: a -> IdentityT * m a #

(<*>) :: IdentityT * m (a -> b) -> IdentityT * m a -> IdentityT * m b #

(*>) :: IdentityT * m a -> IdentityT * m b -> IdentityT * m b #

(<*) :: IdentityT * m a -> IdentityT * m b -> IdentityT * m a #

Applicative f => Applicative (M1 i c f) 

Methods

pure :: a -> M1 i c f a #

(<*>) :: M1 i c f (a -> b) -> M1 i c f a -> M1 i c f b #

(*>) :: M1 i c f a -> M1 i c f b -> M1 i c f b #

(<*) :: M1 i c f a -> M1 i c f b -> M1 i c f a #

Applicative (ContT k r m) 

Methods

pure :: a -> ContT k r m a #

(<*>) :: ContT k r m (a -> b) -> ContT k r m a -> ContT k r m b #

(*>) :: ContT k r m a -> ContT k r m b -> ContT k r m b #

(<*) :: ContT k r m a -> ContT k r m b -> ContT k r m a #

Applicative m => Applicative (ReaderT * r m) 

Methods

pure :: a -> ReaderT * r m a #

(<*>) :: ReaderT * r m (a -> b) -> ReaderT * r m a -> ReaderT * r m b #

(*>) :: ReaderT * r m a -> ReaderT * r m b -> ReaderT * r m b #

(<*) :: ReaderT * r m a -> ReaderT * r m b -> ReaderT * r m a #

(Applicative f, Applicative g) => Applicative (Compose * * f g) 

Methods

pure :: a -> Compose * * f g a #

(<*>) :: Compose * * f g (a -> b) -> Compose * * f g a -> Compose * * f g b #

(*>) :: Compose * * f g a -> Compose * * f g b -> Compose * * f g b #

(<*) :: Compose * * f g a -> Compose * * f g b -> Compose * * f g a #

(Monoid w, Functor m, Monad m) => Applicative (RWST r w s m) 

Methods

pure :: a -> RWST r w s m a #

(<*>) :: RWST r w s m (a -> b) -> RWST r w s m a -> RWST r w s m b #

(*>) :: RWST r w s m a -> RWST r w s m b -> RWST r w s m b #

(<*) :: RWST r w s m a -> RWST r w s m b -> RWST r w s m a #

(Monoid w, Functor m, Monad m) => Applicative (RWST r w s m) 

Methods

pure :: a -> RWST r w s m a #

(<*>) :: RWST r w s m (a -> b) -> RWST r w s m a -> RWST r w s m b #

(*>) :: RWST r w s m a -> RWST r w s m b -> RWST r w s m b #

(<*) :: RWST r w s m a -> RWST r w s m b -> RWST r w s m a #