either-n-0.1.0.0: README.md

# either-n

![System F Logo](https://logo.systemf.com.au/systemf-450x450.png)

Data types like `Either` but with more constructors, and optics for the
constructors of any sum type.

Download from [hackage](http://hackage.haskell.org/package/either-n).

## `Either3`

`Either3 a b c` is a value of one of three types:

```haskell
data Either3 a b c
  = First3 a
  | Second3 b
  | Third3 c
```

The `Functor`, `Applicative` and `Monad` instances act on the third type
parameter, so `First3` and `Second3` short-circuit, in the same way `Left`
does for `Either`. The `Bifunctor` instances act on the second and third type
parameters.

## `Either3T`

`Either3T f a b c` is an `Either3` inside a type constructor `f`, in the same
way that `ExceptT e m a` is `m (Either e a)`:

```haskell
newtype Either3T f a b c = Either3T (f (Either3 a b c))
```

Use `_Wrapped` to convert between `Either3T f a b c` and `f (Either3 a b c)`.
The `Monad` instance requires `Monad f`, and `MonadIO`, `MonadFail`,
`MonadState`, `MonadReader`, `MonadWriter`, `MonadError`, `MonadRWS`,
`MonadCont` and `MonadZip` are lifted from `f`. `either3Identity` is the isomorphism between `Either3 a b c` and
`Either3T Identity a b c`.

The type parameters are in the order `f a b c` so that `Either3T f a` is a
`Bifunctor`. As a consequence, `Either3T` has no `MonadTrans` instance.

## Injections

`Data.Lens.Injection` provides the classes `Injection1` to `Injection19`, the
sum-type duals of `Field1` to `Field19` from `lens`. Where `_1` is a lens to
the first field of a product, `_I1` is a prism to the first constructor of a
sum:

```haskell
>>> (Left 1 :: Either Int String) ^? _I1
Just 1

>>> _I2 # True :: Either3 Int Bool String
Second3 True
```

Instances are provided for `Either`, `Maybe`, `Bool`, `Ordering`, lists,
`Identity`, `()`, `Data.Functor.Sum`, `GHC.Generics.:+:`, `Either3` and
`Either3T Identity`. Each class has a default implementation for any type with
a `Generic` instance, so an instance needs no body:

```haskell
data T a = T1 a | T2 | T3 Int Bool
  deriving Generic

instance Injection1 (T a) (T b) a b
instance Injection2 (T a) (T a) () ()
instance Injection3 (T a) (T a) (Int, Bool) (Int, Bool)
```

A constructor with no fields has the focus `()`, a constructor with one field
has that field as its focus, and a constructor with more than one field has
any type with a single constructor with the same fields, such as a tuple, as
its focus.