view package:lens

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

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

A Seq is isomorphic to a ViewL

viewl m ≡ m ^. viewL

>>> Seq.fromList [a,b,c] ^. viewL
a :< fromList [b,c]

>>> Seq.empty ^. viewL
EmptyL

>>> EmptyL ^. from viewL
fromList []

>>> review viewL $ a Seq.:< Seq.fromList [b,c]
fromList [a,b,c]

A Seq is isomorphic to a ViewR

viewr m ≡ m ^. viewR

>>> Seq.fromList [a,b,c] ^. viewR
fromList [a,b] :> c

>>> Seq.empty ^. viewR
EmptyR

>>> EmptyR ^. from viewR
fromList []

>>> review viewR $ Seq.fromList [a,b] Seq.:> c
fromList [a,b,c]

This is a limited form of a Prism that can only be used for re operations. Like with a Getter, there are no laws to state for a Review. You can generate a Review by using unto. You can also use any Prism or Iso directly as a Review.

This class is provided mostly for backwards compatibility with lens 3.8, but it can also shorten type signatures.

Retrieve the first index and value targeted by a Fold or Traversal (or Just the result from a Getter or Lens). See also (^@?).

ipreview = view . ipre

This is usually applied in the Reader Monad (->) s.

ipreview :: IndexedGetter i s a     -> s -> Maybe (i, a)
ipreview :: IndexedFold i s a       -> s -> Maybe (i, a)
ipreview :: IndexedLens' i s a      -> s -> Maybe (i, a)
ipreview :: IndexedTraversal' i s a -> s -> Maybe (i, a)

However, it may be useful to think of its full generality when working with a Monad transformer stack:

ipreview :: MonadReader s m => IndexedGetter s a     -> m (Maybe (i, a))
ipreview :: MonadReader s m => IndexedFold s a       -> m (Maybe (i, a))
ipreview :: MonadReader s m => IndexedLens' s a      -> m (Maybe (i, a))
ipreview :: MonadReader s m => IndexedTraversal' s a -> m (Maybe (i, a))

Retrieve a function of the first index and value targeted by an IndexedFold or IndexedTraversal (or Just the result from an IndexedGetter or IndexedLens). See also (^@?).

ipreviews = views . ipre

This is usually applied in the Reader Monad (->) s.

ipreviews :: IndexedGetter i s a     -> (i -> a -> r) -> s -> Maybe r
ipreviews :: IndexedFold i s a       -> (i -> a -> r) -> s -> Maybe r
ipreviews :: IndexedLens' i s a      -> (i -> a -> r) -> s -> Maybe r
ipreviews :: IndexedTraversal' i s a -> (i -> a -> r) -> s -> Maybe r

However, it may be useful to think of its full generality when working with a Monad transformer stack:

ipreviews :: MonadReader s m => IndexedGetter i s a     -> (i -> a -> r) -> m (Maybe r)
ipreviews :: MonadReader s m => IndexedFold i s a       -> (i -> a -> r) -> m (Maybe r)
ipreviews :: MonadReader s m => IndexedLens' i s a      -> (i -> a -> r) -> m (Maybe r)
ipreviews :: MonadReader s m => IndexedTraversal' i s a -> (i -> a -> r) -> m (Maybe r)

View the index and value of an IndexedGetter into the current environment as a pair. When applied to an IndexedFold the result will most likely be a nonsensical monoidal summary of the indices tupled with a monoidal summary of the values and probably not whatever it is you wanted.

View a function of the index and value of an IndexedGetter into the current environment. When applied to an IndexedFold the result will be a monoidal summary instead of a single answer.

iviews ≡ ifoldMapOf

Retrieve the first value targeted by a Fold or Traversal (or Just the result from a Getter or Lens). See also firstOf and ^?, which are similar with some subtle differences (explained below).

listToMaybe . toList ≡ preview folded

preview = view . pre

Unlike ^?, this function uses a MonadReader to read the value to be focused in on. This allows one to pass the value as the last argument by using the MonadReader instance for (->) s However, it may also be used as part of some deeply nested transformer stack. preview uses a monoidal value to obtain the result. This means that it generally has good performance, but can occasionally cause space leaks or even stack overflows on some data types. There is another function, firstOf, which avoids these issues at the cost of a slight constant performance cost and a little less flexibility. It may be helpful to think of preview as having one of the following more specialized types:

preview :: Getter s a     -> s -> Maybe a
preview :: Fold s a       -> s -> Maybe a
preview :: Lens' s a      -> s -> Maybe a
preview :: Iso' s a       -> s -> Maybe a
preview :: Traversal' s a -> s -> Maybe a

preview :: MonadReader s m => Getter s a     -> m (Maybe a)
preview :: MonadReader s m => Fold s a       -> m (Maybe a)
preview :: MonadReader s m => Lens' s a      -> m (Maybe a)
preview :: MonadReader s m => Iso' s a       -> m (Maybe a)
preview :: MonadReader s m => Traversal' s a -> m (Maybe a)

Retrieve a function of the first value targeted by a Fold or Traversal (or Just the result from a Getter or Lens). This is usually applied in the Reader Monad (->) s.

This can be used to turn an Iso or Prism around and view a value (or the current environment) through it the other way.

review ≡ view . re
review . unto ≡ id

>>> review _Left "mustard"
Left "mustard"

>>> review (unto succ) 5
6

Usually review is used in the (->) Monad with a Prism or Iso, in which case it may be useful to think of it as having one of these more restricted type signatures:

review :: Iso' s a   -> a -> s
review :: Prism' s a -> a -> s

However, when working with a Monad transformer stack, it is sometimes useful to be able to review the current environment, in which case it may be beneficial to think of it as having one of these slightly more liberal type signatures:

review :: MonadReader a m => Iso' s a   -> m s
review :: MonadReader a m => Prism' s a -> m s

Coerce a polymorphic Prism to a Review.

reviewing :: Iso s t a b -> Review t b
reviewing :: Prism s t a b -> Review t b

This can be used to turn an Iso or Prism around and view a value (or the current environment) through it the other way, applying a function.

reviews ≡ views . re
reviews (unto f) g ≡ g . f

>>> reviews _Left isRight "mustard"
False

>>> reviews (unto succ) (*2) 3
8

Usually this function is used in the (->) Monad with a Prism or Iso, in which case it may be useful to think of it as having one of these more restricted type signatures:

reviews :: Iso' s a   -> (s -> r) -> a -> r
reviews :: Prism' s a -> (s -> r) -> a -> r

However, when working with a Monad transformer stack, it is sometimes useful to be able to review the current environment, in which case it may be beneficial to think of it as having one of these slightly more liberal type signatures:

reviews :: MonadReader a m => Iso' s a   -> (s -> r) -> m r
reviews :: MonadReader a m => Prism' s a -> (s -> r) -> m r

A Review is a type-restricted form of a Prism that can only be used for writing back via re, review, reuse.