# N-ary Functors [](https://hackage.haskell.org/package/n-ary-functor) [](https://travis-ci.org/gelisam/n-ary-functor)
## Using existing instances
[`Functor`](https://hackage.haskell.org/package/base-4.10.1.0/docs/Prelude.html#t:Functor) and [`Bifunctor`](https://hackage.haskell.org/package/base-4.10.1.0/docs/Data-Bifunctor.html#t:Bifunctor) are both in `base`, but what about `Trifunctor`? `Quadrifunctor`? There must be a better solution than creating an infinite tower of typeclasses. Here's the API I managed to implement:
```haskell
> nmap <#> (+1) <#> (+2) $ (0, 0)
(1,2)
> nmap <#> (+1) <#> (+2) <#> (+3) $ (0, 0, 0)
(1,2,3)
> nmap <#> (+1) <#> (+2) <#> (+3) <#> (+4) $ (0, 0, 0, 0)
(1,2,3,4)
```
What about [`Contravariant`](https://www.stackage.org/haddock/lts-14.20/base-4.12.0.0/Data-Functor-Contravariant.html#t:Contravariant) and [`Profunctor`](https://www.stackage.org/haddock/lts-14.20/profunctors-5.3/Data-Profunctor.html#t:Profunctor)? No need to define `Bicontravariant` nor `Noobfunctor`, the `NFunctor` typeclass supports contravariant type-parameters too!
```haskell
> let intToInt = succ
> let intToString = nmap <#> show $ succ
> let stringToString = nmap >#< length <#> show $ succ
> intToInt 3
4
> intToString 3
"4"
> stringToString "foo"
"4"
```
As the examples above demonstrate, n-ary-functor has an equivalent for both the `Functor ((->) a)` instance and the `Profunctor (->)` instance. Even better: when writing your own instance, you only need to define an `NFunctor (->)` instance, and the `NFunctor ((->) a)` instance will be derived for you. `NFunctor ((->) a b)` too, but that's less useful since that `nmap` is just the identity function.
That's not all! Consider a type like `StateT s m a`. The last type parameter is covariant, but what about the first two? Well, `s -> m (a, s)` has both positive and negative occurences of `s`, so you need both an `s -> t` and a `t -> s` function in order to turn a `StateT s m a` into a `StateT t m a`. And what about `m`? You need a natural transformation `forall a. m a -> n a`. Yes, n-ary-functor supports these too!
```haskell
> let stateIntIdentityInt = ((`div` 2) <$> get) >>= lift . Identity
> let stateStringMaybeString = nmap
<#>/>#< (flip replicate '.', length) -- (s -> t, t -> s)
<##> NT (Just . runIdentity) -- NT (forall a. m a -> n a)
<#> show -- a -> b
$ stateIntIdentityInt
> runStateT stateIntIdentityInt 4
Identity (2,4)
> runStateT stateStringMaybeString "four"
Just ("2","....")
```
Notice how even in such a complicated case, no type annotations are needed, as n-ary-functor is written with type inference in mind.
## Defining your own instance
When defining an instance of `NFunctor`, you need to specify the variance of every type parameter using a "variance stack" ending with `(->)`. Here is the instance for `(,,)`, whose three type parameters are covariant:
```haskell
instance NFunctor (,,) where
type VarianceStack (,,) = CovariantT (CovariantT (CovariantT (->)))
nmap = CovariantT $ \f1
-> CovariantT $ \f2
-> CovariantT $ \f3
-> \(x1,x2,x3)
-> (f1 x1, f2 x2, f3 x3)
```
Its `nmap` then receives 3 functions, which it applies to the 3 components of the 3-tuple.
Here is a more complicated instance, that of `StateT`:
```haskell
instance NFunctor StateT where
type VarianceStack StateT = InvariantT (Covariant1T (CovariantT (->)))
nmap = InvariantT $ \(f1, f1')
-> Covariant1T $ \f2
-> CovariantT $ \f3
-> \body
-> StateT $ \s'
-> fmap (f3 *** f1) $ unwrapNT f2 $ runStateT body $ f1' s'
```
The `s` type parameter is "invariant", a standard but confusing name which does _not_ mean that the parameter cannot vary, but rather that we need both an `s -> t` and a `t -> s`. The `m` parameter is covariant, but for a type parameter of kind `* -> *`, so we follow the [convention](http://hackage.haskell.org/package/base-4.11.1.0/docs/Data-Functor-Classes.html) and add a `1` to the name of the variance transformer, hence `Covariant1T`.
## Defining your own variance transformer
We've seen plenty of strange variances already and n-ary-functor provides stranger ones still (can you guess what the `👻#👻` operator does?), but if your type parameters vary in an even more unusual way, you can define your own variance transformer. Here's what the definition of `CovariantT` looks like:
```haskell
newtype CovariantT to f g = CovariantT
{ (<#>) :: forall a b
. (a -> b)
-> f a `to` g b
}
```
One thing which is unusual in that newtype definition is that instead of naming the eliminator `unCovariantT`, we give it the infix name `(<#>)`. See [this blog post](http://gelisam.blogspot.com/2017/12/n-ary-functors.html#ergonomics) for more details on that aspect.
Let's look at the type wrapped by the newtype. `to` is the rest of the variance stack, so in the simplest case, `to` is just `(->)`, in which case the wrapped type is `(a -> b) -> f a -> g b`, which is really close to the type of `fmap`. The reason we produce a `g b` instead of an `f b` is because previous type parameters might already be mapped; for example, in `nmap <#> show <#> show $ (0, 0)`, the overall transformation has type `(,) Int Int -> (,) String String`, so from the point of view of the second `(<#>)`, `f` is `(,) Int` and `g` is `(,) String`.
One last thing is that variance transformers must implement the `VarianceTransformer` typeclass. It simply ensures that there exists a neutral argument, in this case `id`, which doesn't change the type parameter at all.
```haskell
instance VarianceTransformer CovariantT a where
t -#- () = t <#> id
```
### Flavor example
A concrete situation in which you'd want to define your own variance transformer is if you have a DataKind type parameter which corresponds to a number of other types via type families.
```haskell
import qualified Data.ByteString as Strict
import qualified Data.ByteString.Lazy as Lazy
import qualified Data.Text as Strict
import qualified Data.Text.Lazy as Lazy
data Flavor
= Strict
| Lazy
type family ByteString (flavor :: Flavor) :: * where
ByteString 'Lazy = Lazy.ByteString
ByteString 'Strict = Strict.ByteString
type family Text (flavor :: Flavor) :: * where
Text 'Lazy = Lazy.Text
Text 'Strict = Strict.Text
data File (flavor :: Flavor) = File
{ name :: Text flavor
, size :: Int
, contents :: ByteString flavor
}
```
In order to convert a `File 'Lazy` to a `File 'Strict`, we need to map both the underlying `Text 'Lazy` to a `Text 'Strict` and the underlying `ByteString 'Lazy` to a `ByteString 'Strict`. So those are exactly the two functions our custom variance transformer will ask for:
```haskell
newtype FlavorvariantT to f g = FlavorvariantT
{ (😋#😋) :: forall flavor1 flavor2
. ( ByteString flavor1 -> ByteString flavor2
, Text flavor1 -> Text flavor2
)
-> f flavor1 `to` g flavor2
}
instance VarianceTransformer FlavorvariantT a where
t -#- () = t 😋#😋 (id, id)
```
We can now implement our `NFunctor File` instance by specifying that its `flavor` type parameter is flavorvariant.
```haskell
instance NFunctor File where
type VarianceStack File = FlavorvariantT (->)
nmap = FlavorvariantT $ \(f, g)
-> \(File n s c)
-> File (g n) s (f c)
```