Optic.Getting

Getting

type Getting r s a = (a -> Const r a) -> s -> Const r s

When you see this in a type signature it indicates that you can pass the function a Lens, Getter, Traversal, Fold, Prism, Iso, or one of the indexed variants, and it will just "do the right thing".

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 t and b parameters.

If a function accepts a Getting r s a, then when r is a Monoid, then you can pass a Fold (or Traversal), otherwise you can only pass this a Getter or Lens.

(^.) :: s -> Getting a s a -> a infixl 8

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

>>> (a,b)^._2
b

>>> ("hello","world")^._2
"world"

>>> import Data.Complex
>>> ((0, 1 :+ 2), 3)^._1._2.to magnitude
2.23606797749979

(^.) ::             s -> Getter s a     -> a
(^.) :: Monoid m => s -> Fold s m       -> m
(^.) ::             s -> Iso' s a       -> a
(^.) ::             s -> Lens' s a      -> a
(^.) :: Monoid m => s -> Traversal' s m -> m

view :: MonadReader s m => Getting a s a -> m a

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 value.

view . to ≡ id

>>> view (to f) a
f a

>>> view _2 (1,"hello")
"hello"

>>> view (to succ) 5
6

>>> view (_2._1) ("hello",("world","!!!"))
"world"

As view is commonly used to access the target of a Getter or obtain a monoidal summary of the targets of a Fold, It may be useful to think of it as having one of these more restricted signatures:

view ::             Getter s a     -> s -> a
view :: Monoid m => Fold s m       -> s -> m
view ::             Iso' s a       -> s -> a
view ::             Lens' s a      -> s -> a
view :: Monoid m => Traversal' s m -> s -> m

In a more general setting, such as when working with a Monad transformer stack you can use:

view :: MonadReader s m             => Getter s a     -> m a
view :: (MonadReader s m, Monoid a) => Fold s a       -> m a
view :: MonadReader s m             => Iso' s a       -> m a
view :: MonadReader s m             => Lens' s a      -> m a
view :: (MonadReader s m, Monoid a) => Traversal' s a -> m a

views :: MonadReader s m => LensLike' (Const r :: * -> *) s a -> (a -> r) -> m r

View a function of the value pointed to by a Getter or Lens or the result of folding over the result of mapping the targets of a Fold or Traversal.

views l f ≡ view (l . to f)

>>> views (to f) g a
g (f a)

>>> views _2 length (1,"hello")
5

As views is commonly used to access the target of a Getter or obtain a monoidal summary of the targets of a Fold, It may be useful to think of it as having one of these more restricted signatures:

views ::             Getter s a     -> (a -> r) -> s -> r
views :: Monoid m => Fold s a       -> (a -> m) -> s -> m
views ::             Iso' s a       -> (a -> r) -> s -> r
views ::             Lens' s a      -> (a -> r) -> s -> r
views :: Monoid m => Traversal' s a -> (a -> m) -> s -> m

In a more general setting, such as when working with a Monad transformer stack you can use:

views :: MonadReader s m             => Getter s a     -> (a -> r) -> m r
views :: (MonadReader s m, Monoid r) => Fold s a       -> (a -> r) -> m r
views :: MonadReader s m             => Iso' s a       -> (a -> r) -> m r
views :: MonadReader s m             => Lens' s a      -> (a -> r) -> m r
views :: (MonadReader s m, Monoid r) => Traversal' s a -> (a -> r) -> m r

views :: MonadReader s m => Getting r s a -> (a -> r) -> m r

use :: MonadState s m => Getting a s a -> m a

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.

>>> evalState (use _1) (a,b)
a

>>> evalState (use _1) ("hello","world")
"hello"

use :: MonadState s m             => Getter s a     -> m a
use :: (MonadState s m, Monoid r) => Fold s r       -> m r
use :: MonadState s m             => Iso' s a       -> m a
use :: MonadState s m             => Lens' s a      -> m a
use :: (MonadState s m, Monoid r) => Traversal' s r -> m r

uses :: MonadState s m => LensLike' (Const r :: * -> *) s a -> (a -> r) -> m r

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.

>>> evalState (uses _1 length) ("hello","world")
5

uses :: MonadState s m             => Getter s a     -> (a -> r) -> m r
uses :: (MonadState s m, Monoid r) => Fold s a       -> (a -> r) -> m r
uses :: MonadState s m             => Lens' s a      -> (a -> r) -> m r
uses :: MonadState s m             => Iso' s a       -> (a -> r) -> m r
uses :: (MonadState s m, Monoid r) => Traversal' s a -> (a -> r) -> m r

uses :: MonadState s m => Getting r s t a b -> (a -> r) -> m r