lens-3.9.0.2: Lenses, Folds and Traversals

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

Control.Lens.Review

Contents

- Reviewing

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. (Profunctor p, Bifunctor 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 :: (Profunctor p, Bifunctor 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 Bifunctor p where
  - bimap :: (a -> b) -> (c -> d) -> p a c -> p b d
- retagged :: (Profunctor p, Bifunctor p) => p a b -> p s b
- class (Profunctor p, Bifunctor p) => Reviewable p

# Reviewing

type Review s t a b = forall p f. (Profunctor p, Bifunctor 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 :: (Profunctor p, Bifunctor 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

class Bifunctor p where

Minimal definition either `bimap` or `first` and `second`

Formally, the class `Bifunctor` represents a bifunctor from `Hask` -> `Hask`.

Intuitively it is a bifunctor where both the first and second arguments are covariant.

You can define a `Bifunctor` by either defining `bimap` or by defining both `first` and `second`.

If you supply `bimap`, you should ensure that:

    bimap id id ≡ id

If you supply `first` and `second`, ensure:

     first id ≡ id
     second id ≡ id

If you supply both, you should also ensure:

    bimap f g ≡ first f . second g

These ensure by parametricity:

     bimap  (f . g) (h . i) ≡ bimap f h . bimap g i
     first  (f . g) ≡ first  f . first  g
     second (f . g) ≡ second f . second g

Methods

bimap :: (a -> b) -> (c -> d) -> p a c -> p b d

Map over both arguments at the same time.

    bimap f g ≡ first f . second g

Instances

Bifunctor Either |
Bifunctor (,) |
Bifunctor Const |
Bifunctor Reviewed |
Bifunctor ((,,) x) |
Bifunctor (Tagged *) |
Bifunctor ((,,,) x y) |
Bifunctor ((,,,,) x y z) |

retagged :: (Profunctor p, Bifunctor p) => p a b -> p s b

This is a profunctor used internally to implement Review

It plays a role similar to that of `Accessor` or `Const` do for Control.Lens.Getter

class (Profunctor p, Bifunctor p) => Reviewable p

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

Instances

(Profunctor p, Bifunctor p) => Reviewable p |