An Associative HBifunctor can be a Tensor if there is some identity i where t i f is equivalent to just f.

That is, "enhancing" f with t i does nothing.

The methods in this class provide us useful ways of navigating a Tensor t with respect to this property.

The Tensor is essentially the HBifunctor equivalent of Inject, with intro1 and intro2 taking the place of inject.

f is isomorphic to t f (I t): that is, I t is the identity of t, and leaves f unchanged.

g is isomorphic to t (I t) g: that is, I t is the identity of t, and leaves g unchanged.

leftIdentity (intro1 and elim1) for :+: actually does not require Functor. This is the more general version.

rightIdentity (intro2 and elim2) for :+: actually does not require Functor. This is the more general version.

leftIdentity (intro1 and elim1) for :*: actually does not require Functor. This is the more general version.

rightIdentity (intro2 and elim2) for :*: actually does not require Functor. This is the more general version.

A Monoidal t is a Semigroupoidal, in that it provides some type MF t f that is equivalent to one of:

• I a -- 0 times
• f a -- 1 time
• t f f a -- 2 times
• t f (t f f) a -- 3 times
• t f (t f (t f f)) a -- 4 times
• t f (t f (t f (t f f))) a -- 5 times
• .. etc

The difference is that unlike SF t, MF t has the "zero times" value.

This typeclass lets you use a type like ListF in terms of repeated applications of :*:, or Ap in terms of repeated applications of Day, or Free in terms of repeated applications of Comp, etc.

For example, f :*: f can be interpreted as "a free selection of two fs", allowing you to specify "I have to fs that I can use". If you want to specify "I want 0, 1, or many different fs that I can use", you can use ListF f.

At the high level, the thing that Monoidal adds to Semigroupoidal is inL, inR, and nilMF:

inL    :: f a -> t f g a
inR    :: g a -> t f g a
nilMF  :: I a -> MF t f a

which are like the HBifunctor versions of inject: it lets you inject an f into t f g, so you can start doing useful mixing operations with it. nilMF lets you construct an "empty" MF t.

Also useful is:

toMF :: t f f a -> MF t f a

Which converts a t into its aggregate type MF

Convenient alias for the constraint required for inL, inR, pureT, etc.

It's usually a constraint on the target/result context of interpretation that allows you to "exit" or "run" a Monoidal t.

Create the "empty MF@.

If MF t f represents multiple applications of t f with itself, then nilMF gives us "zero applications of f".

Note that t cannot be inferred from the input or output type of nilMF, so this function must always be called with -XTypeApplications:

nilMF @Day :: Identity ~> Ap f
nilMF @Comp :: Identity ~> Free f
nilMF @(:*:) :: Proxy ~> ListF f

Lets us "cons" an application of f to the front of an MF t f.

"Pattern match" on an MF t

An MF t f is either empty, or a single application of t to f and MF t f (the "head" and "tail")

This is analogous to the function uncons :: [a] -> Maybe (a, [a]).

Convenient wrapper over intro1 that lets us introduce an arbitrary functor g to the right of an f.

You can think of this as an HBifunctor analogue of inject.

Convenient wrapper over intro2 that lets us introduce an arbitrary functor f to the right of a g.

You can think of this as an HBifunctor analogue of inject.

Convenient wrapper over elim1 that lets us drop one of the arguments of a Tensor for free, without requiring any extra constraints (like for binterpret).

See prodOutL for a version that does not require Functor f, specifically for :*:.

Convenient wrapper over elim2 that lets us drop one of the arguments of a Tensor for free, without requiring any constraints (like for binterpret).

See prodOutR for a version that does not require Functor g, specifically for :*:.

This is biretract, but taking a C (MF t) constraint instead of a C (SF t) constraint. For example, for Day, it takes an Applicative constraint instead of an Apply constraint.

In an ideal world, this would be not necessary, and we can use biretract. However, sometimes C (MF t) is not an actual subclass of C (SF t) (like Apply and Applicative), even though it should technically always be so.

Note that you should only use this if f doesn't already have the SF constraint (for example, for Day, if f already has an Apply instance). If it does, this could lead to conflicting instances. If f already has the SF instance, just use biretract directly. Only use this with specific, concrete fs.

This is binterpret, but taking a C (MF t) constraint instead of a C (SF t) constraint. For example, for Day, it takes an Applicative constraint instead of an Apply constraint.

In an ideal world, this would be not necessary, and we can use biretract. However, sometimes C (MF t) is not an actual subclass of C (SF t) (like Apply and Applicative), even though it should technically always be so.

Note that you should only use this if f doesn't already have the SF constraint (for example, for Day, if f already has an Apply instance). If it does, this could lead to conflicting instances. If f already has the SF instance, just use biretract directly. Only use this with specific, concrete fs.

outL for :*: actually does not require Functor. This is the more general version.

outR for :*: actually does not require Functor. This is the more general version.

For some t, we have the ability to "statically analyze" the MF t and pattern match and manipulate the structure without ever interpreting or retracting. These are Matchable.

An SF t f is isomorphic to an f consed with an MF t f, like how a NonEmpty a is isomorphic to (a, [a]).

An MF t f is isomorphic to either the empty case (I t) or the non-empty case (SF t f), like how [a] is isomorphic to Maybe (NonEmpty a).