A Projection l is a 0-or-1 target Traversal that can also be turned around with remit to obtain a Getter in the opposite direction, such that in addition to the Traversal laws, we also have

x ^. remit l ^? l ≡ Just x

lengthOf l x <= 1

It may help to think of this as a Iso that can be partial in one direction.

Every Projection is a valid Traversal.

Every Iso is a valid Projection.

For example, you might have a Simple Projection Integer Natural allows you to always go from a Natural to an Integer, and provide you with tools to check if an Integer is a Natural and/or to edit one if it is.

 nat :: Simple Projection Integer Natural
 nat = projected toInteger $ \ i ->
    if i < 0
    then Left i
    else Right (fromInteger i)

Now we can ask if an Integer is a Natural.

>>> 5^?nat
Just 5

>>> (-5)^?nat
Nothing

We can update the ones that are:

>>> (-3,4) & both.nat *~ 2
(-3,8)

And we can then convert from a Natural to an Integer.

>>> 5 ^. remit nat -- :: Natural
5

Similarly we can use a Projection to traverse the left half of an Either:

>>> Left "hello" & _left %~ length
Left 5

or to construct an Either:

>>> 5^.remit _left
Left 5

such that if you query it with the Projection, you will get your original input back.

>>> 5^.remit _left ^? _left
Just 5

Another interesting way to think of a Projection is as the categorical dual of a Lens a co-Lens, so to speak. This is what permits the construction of outside.

Used to provide overloading of projections.

An instance of Projective is a Category with a canonical mapping to it from the category of embedding-projection pairs over Haskell types.

Clone a Projection so that you can reuse the same monomorphically typed Projection for different purposes.

See cloneLens and cloneTraversal for examples of why you might want to do this.

Turn a Projection 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 ^.remit _left
Left 5

 remit :: Projection s t a b -> Getter b t
 remit :: Iso s t a b        -> Getter b t

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

review ≡ view . remit

>>> review _left "mustard"
Left "mustard"

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

 review :: Simple Iso s a        -> a -> s
 review :: Simple Projection 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 => Simple Iso s a        -> m s
 review :: MonadReader a m => Simple Projection s a -> m s

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

reviews ≡ views . remit

>>> reviews _left isRight "mustard"
False

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

 reviews :: Simple Iso s a        -> (s -> r) -> a -> r
 reviews :: Simple Projection 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 => Simple Iso s a        -> (s -> r) -> m r
 reviews :: MonadReader a m => Simple Projection s a -> (s -> r) -> m r

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

reuse ≡ use . remit

>>> evalState (reuse _left) 5
Left 5

 reuse :: MonadState a m => Simple Projection s a -> m s
 reuse :: MonadState a m => Simple Iso s a        -> m s

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

reuses ≡ uses . remit

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

 reuses :: MonadState a m => Simple Projection s a -> (s -> r) -> m r
 reuses :: MonadState a m => Simple Iso s a        -> (s -> r) -> m r

Use a Projection as a kind of first-class pattern.

outside :: Projection s t a b -> Lens (t -> r) (s -> r) (b -> r) (a -> r)

Use a Projection to work over part of a structure.

Given a pair of projections, project sums.

Viewing a Projection as a co-lens, this combinator can be seen to be dual to alongside.

This projection provides a traversal for tweaking the left-hand value of an Either:

>>> over _left (+1) (Left 2)
Left 3

>>> over _left (+1) (Right 2)
Right 2

>>> Right 42 ^._left :: String
""

>>> Left "hello" ^._left
"hello"

It also can be turned around to obtain the embedding into the Left half of an Either

>>> 5^.remit _left
Left 5

traverse the right-hand value of an Either:

_right ≡ traverse

Unfortunately the instance for Traversable (Either c) is still missing from base, so this can't just be traverse

>>> over _right (+1) (Left 2)
Left 2

>>> over _right (+1) (Right 2)
Right 3

>>> Right "hello" ^._right
"hello"

>>> Left "hello" ^._right :: [Double]
[]

It also can be turned around to obtain the embedding into the Left half of an Either

>>> 5^.remit _right
Right 5

A Simple Projection.