lens-3.8.7.3: Lenses, Folds and Traversals

Portability | non-portable
Stability | provisional
Maintainer | Edward Kmett <ekmett@gmail.com>
Safe Haskell | Trustworthy

Control.Lens.Review

Contents

- Reviewing
- Reviewable Profunctors

Description

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

Synopsis

- type Review s t a b = forall p f. (Reviewable p, Settable f) => Overloaded p f s t a b
- type Review' t b = Review t t b b
- type AReview s t a b = Overloaded Reviewed Identity s t a b
- type AReview' t b = AReview t t b b
- unto :: (Reviewable p, Functor f) => (b -> t) -> Overloaded p f s t a b
- re :: AReview s t a b -> Getter b t
- review :: MonadReader b m => AReview s t a b -> m t
- reviews :: MonadReader b m => AReview s t a b -> (t -> r) -> m r
- reuse :: MonadState b m => AReview s t a b -> m t
- reuses :: MonadState b m => AReview s t a b -> (t -> r) -> m r
- (#) :: AReview s t a b -> b -> t
- class Profunctor p => Reviewable p where
  - retagged :: p a b -> p s b

# Reviewing

type Review s t a b = forall p f. (Reviewable p, Settable f) => Overloaded p f s t a b

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

type Review' t b = Review t t b b

A `Simple` `Review`

type AReview s t a b = Overloaded Reviewed Identity s t a b

If you see this in a signature for a function, the function is expecting a `Review` (in practice, this usually means a `Prism`).

type AReview' t b = AReview t t b b

A `Simple` `AReview`

unto :: (Reviewable p, Functor f) => (b -> t) -> Overloaded p f s t a b

An analogue of `to` for `review`.

     unto :: (b -> t) -> Review' t b

re :: AReview s t a b -> Getter b t

Turn a `Prism` or `Iso` around to build a `Getter`.

If you have an `Iso`, `from` is a more powerful version of this function that will return an `Iso` instead of a mere `Getter`.

    >>> 5 ^.re _Left
    Left 5

    >>> 6 ^.re (_Left.unto succ)
    Left 7

     review  ≡ view  . re
     reviews ≡ views . re
     reuse   ≡ use   . re
     reuses  ≡ uses  . re

     re :: Prism s t a b -> Getter b t
     re :: Iso s t a b   -> Getter b t

review :: MonadReader b m => AReview s t a b -> m t

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 one of these more slightly more liberal type signatures may be beneficial to think of it as having:

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

reviews :: MonadReader b m => AReview s t a b -> (t -> r) -> m r

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 one of these more slightly more liberal type signatures may be beneficial to think of it as having:

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

reuse :: MonadState b m => AReview s t a b -> m t

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

     reuse ≡ use . re
     reuse . unto ≡ gets

    >>> evalState (reuse _Left) 5
    Left 5

    >>> evalState (reuse (unto succ)) 5
    6

     reuse :: MonadState a m => Prism' s a -> m s
     reuse :: MonadState a m => Iso' s a   -> m s

reuses :: MonadState b m => AReview s t a b -> (t -> r) -> m r

This can be used to turn an `Iso` or `Prism` around and `use` the current state through it the other way, applying a function.

     reuses ≡ uses . re
     reuses (unto f) g ≡ gets (g . f)

    >>> evalState (reuses _Left isLeft) (5 :: Int)
    True

     reuses :: MonadState a m => Prism' s a -> (s -> r) -> m r
     reuses :: MonadState a m => Iso' s a   -> (s -> r) -> m r

(#) :: AReview s t a b -> b -> t

An infix alias for `review`.

     unto f # x ≡ f x
     l # x ≡ x ^. re l

This is commonly used when using a `Prism` as a smart constructor.

    >>> _Left # 4
    Left 4

But it can be used for any `Prism`

    >>> base 16 # 123
    "7b"

     (#) :: Iso'      s a -> a -> s
     (#) :: Prism'    s a -> a -> s
     (#) :: Review'   s a -> a -> s
     (#) :: Equality' s a -> a -> s

# Reviewable Profunctors

class Profunctor p => Reviewable p where

This provides a dual notion to that of `Gettable`.

Methods

retagged :: p a b -> p s b

Instances

Reviewable Tagged |
Reviewable Reviewed |