Portability  Rank2Types 

Stability  provisional 
Maintainer  Edward Kmett <ekmett@gmail.com> 
Safe Haskell  SafeInfered 
A
is just any function Getter
a c(a > c)
, which we've flipped
into continuation passing style, (c > r) > a > r
and decorated
with Accessor
to obtain:
typeGetting
r a c = (c >Accessor
r c) > a >Accessor
r a
If we restrict access to knowledge about the type r
and can work for
any d and b, we could get:
typeGetter
a c = forall r.Getting
r a c
But we actually hide the use of Accessor
behind a class Gettable
to error messages from type class resolution rather than at unification
time, where they are much uglier.
typeGetter
a c = forall f.Gettable
f => (c > f c) > a > f a
Everything you can do with a function, you can do with a Getter
, but
note that because of the continuation passing style (.
) composes them
in the opposite order.
Since it is only a function, every Getter
obviously only retrieves a
single value for a given input.
 type Getter a c = forall f. Gettable f => (c > f c) > a > f a
 type Getting r a c = (c > Accessor r c) > a > Accessor r a
 class Functor f => Gettable f where
 coerce :: f a > f b
 newtype Accessor r a = Accessor {
 runAccessor :: r
 to :: (a > c) > Getter a c
 (^.) :: a > Getting c a c > c
 (^$) :: Getting c a c > a > c
 view :: Getting c a c > a > c
 views :: Getting m a c > (c > m) > a > m
 use :: MonadState a m => Getting c a c > m c
 uses :: MonadState a m => Getting e a c > (c > e) > m e
 query :: MonadReader a m => Getting c a c > m c
 queries :: MonadReader a m => Getting e a c > (c > e) > m e
 class (MonadReader b m, MonadReader a n) => Magnify m n b a  m > b, n > a, m a > n, n b > m where
Getters
type Getter a c = forall f. Gettable f => (c > f c) > a > f aSource
A Getter
describes how to retrieve a single value in a way that can be
composed with other lenslike constructions.
Unlike a Lens
a Getter
is readonly. Since a Getter
cannot be used to write back there are no lens laws that can be applied to
it. In fact, it is isomorphic to an arbitrary function from (a > c)
.
Moreover, a Getter
can be used directly as a Fold
,
since it just ignores the Applicative
.
type Getting r a c = (c > Accessor r c) > a > Accessor r aSource
Most Getter
combinators are able to be used with both a Getter
or a
Fold
in limited situations, to do so, they need to be
monomorphic in what we are going to extract with Const
. To be compatible
with Lens
, Traversal
and
Iso
we also restricted choices of the irrelevant b
and
d
parameters.
If a function accepts a
, then when Getting
r a cr
is a Monoid
, then
you can pass a Fold
(or
Traversal
), otherwise you can only pass this a
Getter
or Lens
.
Used instead of Const
to report
No instance of (Settable
Accessor
)
when the user attempts to misuse a Setter
as a
Getter
, rather than a monolithic unification error.
Accessor  

Building Getters
Combinators for Getters and Folds
(^.) :: a > Getting c a c > cSource
View the value pointed to by a Getter
or Lens
or the
result of folding over all the results of a Fold
or
Traversal
that points at a monoidal values.
This is the same operation as view
with the arguments flipped.
The fixity and semantics are such that subsequent field accesses can be
performed with (.
)
>>>
:m + Data.Complex Control.Lens
>>>
((0, 1 :+ 2), 3)^._1._2.to magnitude
2.23606797749979
(^.) :: a >Getter
a c > c (^.) ::Monoid
m => a >Fold
a m > m (^.) :: a >Simple
Iso
a c > c (^.) :: a >Simple
Lens
a c > c (^.) ::Monoid
m => a >Simple
Traversal
a m > m
(^$) :: Getting c a c > a > cSource
View the value pointed to by a Getter
, Iso
or
Lens
or the result of folding over all the results of a
Fold
or Traversal
that points
at a monoidal values.
This is the same operation as view
, only infix.
>>>
import Control.Lens
>>>
_2 ^$ (1, "hello")
"hello"
(^$) ::Getter
a c > a > c (^$) ::Monoid
m =>Fold
a m > a > m (^$) ::Simple
Iso
a c > a > c (^$) ::Simple
Lens
a c > a > c (^$) ::Monoid
m =>Simple
Traversal
a m > a > m
view :: Getting c a c > a > cSource
View the value pointed to by a Getter
, Iso
or
Lens
or the result of folding over all the results of a
Fold
or Traversal
that points
at a monoidal values.
view
.to
=id
>>>
import Control.Lens
>>>
view _2 (1,"hello")
"hello"
It may be useful to think of view
as having these more restrictive
signatures:
view ::Getter
a c > a > c view ::Monoid
m =>Fold
a m > a > m view ::Simple
Iso
a c > a > c view ::Simple
Lens
a c > a > c view ::Monoid
m =>Simple
Traversal
a m > a > m
views :: Getting m a c > (c > m) > a > mSource
View the value of a Getter
, Iso
,
Lens
or the result of folding over the result of mapping
the targets of a Fold
or
Traversal
.
It may be useful to think of views
as having these more restrictive
signatures:
>>>
import Control.Lens
>>>
views _2 length (1,"hello")
5
views ::Getter
a c > (c > d) > a > d views ::Monoid
m =>Fold
a c > (c > m) > a > m views ::Simple
Iso
a c > (c > d) > a > d views ::Simple
Lens
a c > (c > d) > a > d views ::Monoid
m =>Simple
Traversal
a c > (c > m) > a > m
use :: MonadState a m => Getting c a c > m cSource
Use the target of a Lens
, Iso
, or
Getter
in the current state, or use a summary of a
Fold
or Traversal
that points
to a monoidal value.
use ::MonadState
a m =>Getter
a c > m c use :: (MonadState
a m,Monoid
r) =>Fold
a r > m r use ::MonadState
a m =>Simple
Iso
a c > m c use ::MonadState
a m =>Simple
Lens
a c > m c use :: (MonadState
a m,Monoid
r) =>Simple
Traversal
a r > m r
uses :: MonadState a m => Getting e a c > (c > e) > m eSource
Use the target of a Lens
, Iso
or
Getter
in the current state, or use a summary of a
Fold
or Traversal
that
points to a monoidal value.
uses ::MonadState
a m =>Getter
a c > (c > e) > m e uses :: (MonadState
a m,Monoid
r) =>Fold
a c > (c > r) > m r uses ::MonadState
a m =>Simple
Lens
a c > (c > e) > m e uses ::MonadState
a m =>Simple
Iso
a c > (c > e) > m e uses :: (MonadState
a m,Monoid
r) =>Simple
Traversal
a c > (c > r) > m r
query :: MonadReader a m => Getting c a c > m cSource
Query the target of a Lens
, Iso
or
Getter
in the current state, or use a summary of a
Fold
or Traversal
that points
to a monoidal value.
query ::MonadReader
a m =>Getter
a c > m c query :: (MonadReader
a m,Monoid
c) =>Fold
a c > m c query ::MonadReader
a m =>Simple
Iso
a c > m c query ::MonadReader
a m =>Simple
Lens
a c > m c query :: (MonadReader
a m,Monoid
c) =>Simple
Traversal
a c > m c
queries :: MonadReader a m => Getting e a c > (c > e) > m eSource
Use the target of a Lens
, Iso
or
Getter
in the current state, or use a summary of a
Fold
or Traversal
that points
to a monoidal value.
queries ::MonadReader
a m =>Getter
a c > (c > e) > m e queries :: (MonadReader
a m,Monoid
c) =>Fold
a c > (c > e) > m e queries ::MonadReader
a m =>Simple
Iso
a c > (c > e) > m e queries ::MonadReader
a m =>Simple
Lens
a c > (c > e) > m e queries :: (MonadReader
a m,Monoid
c) =>Simple
Traversal
a c > (c > e) > m e
class (MonadReader b m, MonadReader a n) => Magnify m n b a  m > b, n > a, m a > n, n b > m whereSource
This class allows us to use magnify
part of the environment, changing the environment supplied by
many different monad transformers. Unlike focus
this can change the environment of a deeply nested monad transformer.
Also, unlike focus
, this can be used with any valid Getter
, but cannot be used with a Traversal
or Fold
.
magnify :: Getter a b > m c > n cSource
Run a monadic action in a larger environment than it was defined in, using a Getter
.
This acts like local
, but can in many cases change the type of the environment as well.
This is commonly used to lift actions in a simpler Reader monad into a monad with a larger environment type.
This can be used to edit pretty much any monad transformer stack with an environment in it:
magnify ::Getter
a b > (b > c) > a > c magnify ::Getter
a b > RWS a w s c > RWST b w s c magnify ::Getter
a b > ErrorT e (Reader b) c > ErrorT e (Reader a) c magnify ::Getter
a b > ListT (ReaderT b (StateT s)) c > ListT (ReaderT a (StateT s)) c ...
Magnify ((>) b) ((>) a) b a  
Magnify m n b a => Magnify (ListT m) (ListT n) b a  
Magnify m n b a => Magnify (MaybeT m) (MaybeT n) b a  
Magnify m n b a => Magnify (IdentityT m) (IdentityT n) b a  
Magnify m m a a => Magnify (ContT r m) (ContT r m) a a  
(Error e, Magnify m n b a) => Magnify (ErrorT e m) (ErrorT e n) b a  
Monad m => Magnify (ReaderT b m) (ReaderT a m) b a  
Magnify m n b a => Magnify (StateT s m) (StateT s n) b a  
Magnify m n b a => Magnify (StateT s m) (StateT s n) b a  
(Monoid w, Magnify m n b a) => Magnify (WriterT w m) (WriterT w n) b a  
(Monoid w, Magnify m n b a) => Magnify (WriterT w m) (WriterT w n) b a  
(Monad m, Monoid w) => Magnify (RWST b w s m) (RWST a w s m) b a  
(Monad m, Monoid w) => Magnify (RWST b w s m) (RWST a w s m) b a 