Control.Lens

This package provides lenses that are compatible with other van Laarhoven lens libraries, while reducing the complexty of the imports.

Lenses produced by this library are compatible with other van Laarhoven lens family libraries, such as lens-family, lens-family-core and lens-family-th, but the API is simpler.

Note: If you merely want your library to provide lenses you may not have to actually import _any_ lens library, for a Lens Bar Foo, just export a function with the signature:

 foo :: Functor f => (Foo -> f Foo) -> Bar -> f Bar

and then you can compose it with other lenses using (.).

This package provides lenses, lens families, setters, setter families, getters, multilenses, multi-getters, and multi-lens families in such a way that they can all be composed automatically with (.).

Lenses

type Lens a b = forall f. Functor f => (b -> f b) -> a -> f a

type LensFamily a b c d = forall f. Functor f => (c -> f d) -> a -> f b

type Getter a b = forall x y z. (b -> Const z x) -> a -> Const z y

type Setter a b = (b -> Identity b) -> a -> Identity a

type SetterFamily a b c d = (c -> Identity d) -> a -> Identity b

type MultiLens a b = forall f. Applicative f => (b -> f b) -> a -> f a

type MultiLensFamily a b c d = forall f. Applicative f => (c -> f d) -> a -> f b

Constructing lenses

makeLenses :: Name -> Q [Dec]

Derive lenses for the record selectors in a single-constructor data declaration, or for the record selector in a newtype declaration. Lenses will only be generated for record fields which are prefixed with an underscore.

Example usage:

 makeLenses ''Foo

makeLensesBy

Arguments

:: (String -> Maybe String)

the name transformer

-> Name

-> Q [Dec]

Derive lenses with the provided name transformation and filtering function. Produce Just lensName to generate a lens of the resultant name, or Nothing to not generate a lens for the input record name.

Example usage:

 makeLensesBy (\n -> Just (n ++ "L")) ''Foo

makeLensesFor :: [(String, String)] -> Name -> Q [Dec]

Derive lenses, specifying explicit pairings of (fieldName, lensName).

Example usage:

 makeLensesFor [("_foo", "fooLens"), ("bar", "lbar")] ''Foo

lens :: Functor f => (a -> c) -> (d -> a -> b) -> (c -> f d) -> a -> f b

Build a lens from a getter and a setter

iso :: Functor f => (a -> c) -> (d -> b) -> (c -> f d) -> a -> f b

Built a lens from an isomorphism or an isomorphism family

clone :: Functor f => ((c -> IndexedStore c d d) -> a -> IndexedStore c d b) -> (c -> f d) -> a -> f b

Cloning a Lens or LensFamily is one way to make sure you arent given something weaker, such as a MultiLens or MultiLensFamily, and can be used as a way to pass around lenses that have to be monomorphic in f.

getting :: (a -> b) -> Getter a b

Build a getter

gettingMany :: Foldable f => (a -> f b) -> MultiGetter a b

Building a multigetter

setting :: ((c -> d) -> a -> b) -> SetterFamily a b c d

Build a setter

Manipulating Values

reading :: ((c -> Const c d) -> a -> Const c b) -> a -> c

Get the value of a Getter, Lens or LensFamily or the fold of a MultiGetter, MultiLens or MultiLensFamily that points at monoidal values.

mapOf, modifying :: ((c -> Identity d) -> a -> Identity b) -> (c -> d) -> a -> b

Modify the target of a Lens, LensFamily or all the targets of a Multilens, MultiLensFamily, Setter or SetterFamily

writing :: ((c -> Identity d) -> a -> Identity b) -> d -> a -> b

Replace the target of a Lens, LensFamily, Setter or SetterFamily

(^.) :: a -> ((c -> Const c d) -> a -> Const c b) -> c

Read a field from a Getter, Lens or LensFamily. The fixity and semantics are such that subsequent field accesses can be performed with (Prelude..) This is the same operation as 'flip reading'

 ghci> ((0, 1 :+ 2), 3)^.fstL.sndL.getting magnitude
 2.23606797749979

(^$) :: ((c -> Const c d) -> a -> Const c b) -> a -> c

Read the value of a Getter, Lens or LensFamily. This is the same operation as reading.

(^%=) :: ((c -> Identity d) -> a -> Identity b) -> (c -> d) -> a -> b

Modifies the target of a Lens, LensFamily, Setter, or SetterFamily.

This is an infix version of mapOf

(^=) :: ((c -> Identity d) -> a -> Identity b) -> d -> a -> b

Replaces the target(s) of a Lens, LensFamily, Setter or SetterFamily.

This is an infix version of writing

(^+=) :: Num c => ((c -> Identity c) -> a -> Identity a) -> c -> a -> a

Increment the target(s) of a numerically valued Lens or Setter'

 ghci> fstL ^+= 1 $ (1,2)
 (2,2)

(^-=) :: Num c => ((c -> Identity c) -> a -> Identity a) -> c -> a -> a

Decrement the target(s) of a numerically valued Lens or Setter

 ghci> fstL ^-= 2 $ (1,2)
 (-1,2)

(^*=) :: Num c => ((c -> Identity c) -> a -> Identity a) -> c -> a -> a

Multiply the target(s) of a numerically valued Lens or Setter'

 ghci> sndL ^*= 4 $ (1,2)
 (1,8)

(^/=) :: Fractional c => ((c -> Identity c) -> a -> Identity a) -> c -> a -> a

Divide the target(s) of a numerically valued Lens or Setter

(^||=) :: ((Bool -> Identity Bool) -> a -> Identity a) -> Bool -> a -> a

Logically || the target(s) of a Bool-valued Lens or Setter

(^&&=) :: ((Bool -> Identity Bool) -> a -> Identity a) -> Bool -> a -> a

Logically && the target(s) of a Bool-valued Lens or Setter

Manipulating State

access :: MonadState a m => ((c -> Const c d) -> a -> Const c b) -> m c

Access a field of a state monad

class Focus st where

This class allows us to use focus on a number of different monad transformers.

Methods

focus :: Monad m => ((b -> Focusing m c b) -> a -> Focusing m c a) -> st b m c -> st a m c

Use a lens to lift an operation with simpler context into a larger context

Instances

Focus ReaderT

We can focus Reader environments, too!

Focus StateT

Focus StateT

(%=) :: MonadState a m => Setter a b -> (b -> b) -> m ()

Modify the value of a field in our monadic state

(~=) :: MonadState a m => Setter a b -> b -> m ()

Set the value of a field in our monadic state

(%%=) :: MonadState a m => ((b -> (c, b)) -> a -> (c, a)) -> (b -> (c, b)) -> m c

Modify the value of a field in our monadic state and return some information about it

(+=) :: (MonadState a m, Num b) => Setter a b -> b -> m ()

Modify a numeric field in our monadic state by adding to it

(-=) :: (MonadState a m, Num b) => Setter a b -> b -> m ()

Modify a numeric field in our monadic state by subtracting from it

(*=) :: (MonadState a m, Num b) => Setter a b -> b -> m ()

Modify a numeric field in our monadic state by multiplying it

(//=) :: (MonadState a m, Fractional b) => Setter a b -> b -> m ()

Modify a numeric field in our monadic state by dividing it

(||=) :: MonadState a m => Setter a Bool -> Bool -> m ()

Modify a boolean field in our monadic state by computing its logical || with another value.

(&&=) :: MonadState a m => Setter a Bool -> Bool -> m ()

Modify a boolean field in our monadic state by computing its logical && with another value.

Lenses and LensFamilies

fstL :: LensFamily (a, c) (b, c) a b

This is a lens family that can change the value (and type) of the first field of a pair.

sndL :: LensFamily (c, a) (c, b) a b

As fstL, but for the second field of a pair.

keyL :: Ord k => k -> Lens (Map k v) (Maybe v)

This lens can be used to read, write or delete a member of a Map.

 ghci> Map.fromList [("hello",12)] ^. keyL "hello"
 Just 12

intKeyL :: Int -> Lens (IntMap v) (Maybe v)

This lens can be used to read, write or delete a member of an IntMap.

 ghci> IntMap.fromList [(1,"hello")]  ^. keyL 1
 Just "hello"

 ghci> keyL 2 ^= "goodbye" $ IntMap.fromList [(1,"hello")]
 fromList [(1,"hello"),(2,"goodbye")]

memberL :: Ord k => k -> Lens (Set k) Bool

This lens can be used to read, write or delete a member of a Set

 ghci> memberL 3 ^= False $ Set.fromList [1,2,3,4]
 fromList [1,2,4]

intMemberL :: Int -> Lens IntSet Bool

This lens can be used to read, write or delete a member of an IntSet

 ghci> intMemberL 3 ^= False $ IntSet.fromList [1,2,3,4]
 fromList [1,2,4]

identityL :: LensFamily (Identity a) (Identity b) a b

This lens can be used to access the contents of the Identity monad

atL :: Eq e => e -> Lens (e -> a) a

This lens can be used to change the result of a function but only where the arguments match the key given.

MultiGetters

folded :: Foldable f => MultiGetter (f a) a

MultiGetter combinators

foldMapOf :: Monoid m => ((c -> Const m d) -> a -> Const m b) -> (c -> m) -> a -> m

 foldMapOf :: Monoid m => MultiGetter a b -> (b -> m) -> a -> m

foldrOf :: ((c -> Const (Endo e) d) -> a -> Const (Endo e) b) -> (c -> e -> e) -> e -> a -> e

 foldrOf :: MultiGetter a b -> (b -> c -> c) -> c -> a -> c

foldOf :: Monoid m => ((m -> Const m n) -> a -> Const m b) -> a -> m

 foldOf :: Monoid m => MultiGetter a m -> a -> m

toListOf :: ((c -> Const [c] d) -> a -> Const [c] b) -> a -> [c]

 toListOf :: MultiGetter a b -> a -> [b]

anyOf :: ((c -> Const Any d) -> a -> Const Any b) -> (c -> Bool) -> a -> Bool

 anyOf :: MultiGetter a b -> (b -> Bool) -> a -> Bool

allOf :: ((c -> Const All d) -> a -> Const All b) -> (c -> Bool) -> a -> Bool

 allOf :: MultiGetter a b -> (b -> Bool) -> a -> Bool

andOf :: ((Bool -> Const All d) -> a -> Const All b) -> a -> Bool

orOf :: ((Bool -> Const Any d) -> a -> Const Any b) -> a -> Bool

productOf :: Num c => ((c -> Const (Product c) d) -> a -> Const (Product c) b) -> a -> c

sumOf :: Num c => ((c -> Const (Sum c) d) -> a -> Const (Sum c) b) -> a -> c

traverseOf_ :: Applicative f => ((c -> Const (Traversal f) d) -> a -> Const (Traversal f) b) -> (c -> f e) -> a -> f ()

 traverseOf_ :: Applicative f => MultiGetter a b -> (b -> f c) -> a -> f ()

forOf_ :: Applicative f => ((c -> Const (Traversal f) d) -> a -> Const (Traversal f) b) -> a -> (c -> f e) -> f ()

 forOf_ :: Applicative f => MultiGetter a b -> a -> (b -> f c) -> f ()

sequenceAOf_ :: Applicative f => ((f () -> Const (Traversal f) d) -> a -> Const (Traversal f) e) -> a -> f ()

 sequenceAOf_ :: Applicative f => MultiGetter a (f ()) -> a -> f ()

mapMOf_ :: Monad m => ((c -> Const (Traversal (WrappedMonad m)) d) -> a -> Const (Traversal (WrappedMonad m)) b) -> (c -> m e) -> a -> m ()

 mapMOf_ :: Monad m => MultiGetter a b -> (b -> m c) -> a -> m ()

forMOf_ :: Monad m => ((c -> Const (Traversal (WrappedMonad m)) d) -> a -> Const (Traversal (WrappedMonad m)) b) -> a -> (c -> m e) -> m ()

 forMOf_ :: Monad m => MultiGetter a b -> a -> (b -> m c) -> m ()

sequenceOf_ :: Monad m => ((m c -> Const (Traversal (WrappedMonad m)) d) -> a -> Const (Traversal (WrappedMonad m)) b) -> a -> m ()

 sequenceOf_ :: Monad m => MultiGetter a (m b) -> a -> m ()

asumOf :: Alternative f => ((f c -> Const (Endo (f c)) d) -> a -> Const (Endo (f c)) b) -> a -> f c

The sum of a collection of actions, generalizing concatOf.

msumOf :: MonadPlus m => ((m c -> Const (Endo (m c)) d) -> a -> Const (Endo (m c)) b) -> a -> m c

The sum of a collection of actions, generalizing concatOf.

concatMapOf :: ((c -> Const [e] d) -> a -> Const [e] b) -> (c -> [e]) -> a -> [e]

concatMapOf :: MultiGetter a c -> (c -> [e]) -> a -> [e]

concatOf :: (([e] -> Const [e] d) -> a -> Const [e] b) -> a -> [e]

elemOf :: Eq c => ((c -> Const Any d) -> a -> Const Any b) -> c -> a -> Bool

notElemOf :: Eq c => ((c -> Const Any d) -> a -> Const Any b) -> c -> a -> Bool

MultiLenses

constML :: Applicative f => (c -> f d) -> a -> f a

This is the partial lens that never succeeds at returning any values

keyML :: (Applicative f, Ord k) => k -> (v -> f v) -> Map k v -> f (Map k v)

intKeyML :: Applicative f => Int -> (v -> f v) -> IntMap v -> f (IntMap v)

headML :: Applicative f => (a -> f a) -> [a] -> f [a]

tailML :: Applicative f => ([a] -> f [a]) -> [a] -> f [a]

leftML :: Applicative f => (a -> f b) -> Either a c -> f (Either b c)

elementML :: (Applicative f, Traversable t) => Int -> (a -> f a) -> t a -> f (t a)

MultiLens combinators

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

mapMOf :: Monad m => ((c -> WrappedMonad m d) -> a -> WrappedMonad m b) -> (c -> m d) -> a -> m b

sequenceAOf :: Applicative f => ((f b -> f (f b)) -> a -> f b) -> a -> f b

sequenceOf :: Monad m => ((m b -> WrappedMonad m (m b)) -> a -> WrappedMonad m b) -> a -> m b

Implementation details

data IndexedStore c d a

Instances

Functor (IndexedStore c d)

data Focusing m c a

Instances

Monad m => Functor (Focusing m c)

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

data Traversal f

Instances

Applicative f => Monoid (Traversal f)