-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Tools for functor combinator-based program design
--   
--   Tools for working with <i>functor combinators</i>: types that take
--   functors (or other indexed types) and returns a new functor that
--   "enhances" or "mixes" them in some way. In the process, you can design
--   featureful programs by composing smaller "primitives" using basic
--   unversal combinators.
--   
--   The main entry point is <a>Data.Functor.Combinators</a>, but more
--   fine-grained functionality and extra combinators (some of them
--   re-implementations for compatibility) are available in other modules
--   as well.
--   
--   This library does not define new functor combinators for the most
--   part, but rather re-exports them from different parts of the Haskell
--   ecosystem and provides a uniform interface.
--   
--   See the README for a quick overview, and also
--   <a>https://blog.jle.im/entry/functor-combinatorpedia.html</a> for an
--   in-depth dive into the motivation behind functor combinator-driven
--   development, examples of the functor combinators in this library, and
--   details about how to use these abstractions!
@package functor-combinators
@version 0.4.0.0


-- | The church-encoded <a>Freer</a> Monad. Basically provides the free
--   monad in a way that is compatible with <a>HFunctor</a> and
--   <a>Interpret</a>. We also have the "semigroup" version <a>Free1</a>,
--   which is the free <a>Bind</a>.
--   
--   The module also provides a version of <a>:.:</a> (or <a>Compose</a>),
--   <a>Comp</a>, in a way that is compatible with <a>HBifunctor</a> and
--   the related typeclasses.
module Control.Monad.Freer.Church

-- | A <tt><a>Free</a> f</tt> is <tt>f</tt> enhanced with "sequential
--   binding" capabilities. It allows you to sequence multiple <tt>f</tt>s
--   one after the other, and also to determine "what <tt>f</tt> to
--   sequence" based on the result of the computation so far.
--   
--   Essentially, you can think of this as "giving <tt>f</tt> a
--   <a>Monad</a> instance", with all that that entails (<a>return</a>,
--   <a>&gt;&gt;=</a>, etc.).
--   
--   Lift <tt>f</tt> into it with <tt><a>inject</a> :: f a -&gt; Free f
--   a</tt>. When you finally want to "use" it, you can interpret it into
--   any monadic context:
--   
--   <pre>
--   <a>interpret</a>
--       :: <a>Monad</a> g
--       =&gt; (forall x. f x -&gt; g x)
--       -&gt; <a>Free</a> f a
--       -&gt; g a
--   </pre>
--   
--   Structurally, this is equivalent to many "nested" f's. A value of type
--   <tt><a>Free</a> f a</tt> is either:
--   
--   <ul>
--   <li><pre>a</pre></li>
--   <li><pre>f a</pre></li>
--   <li><pre>f (f a)</pre></li>
--   <li><pre>f (f (f a))</pre></li>
--   <li>.. etc.</li>
--   </ul>
--   
--   Under the hood, this is the Church-encoded Freer monad. It's
--   <a>Free</a>, or <a>F</a>, but in a way that is compatible with
--   <a>HFunctor</a> and <a>Interpret</a>.
newtype Free f a
Free :: (forall r. (a -> r) -> (forall s. f s -> (s -> r) -> r) -> r) -> Free f a
[runFree] :: Free f a -> forall r. (a -> r) -> (forall s. f s -> (s -> r) -> r) -> r

-- | Convert a <tt><a>Free</a> f</tt> into any instance of
--   <tt><a>MonadFree</a> f</tt>.
reFree :: (MonadFree f m, Functor f) => Free f a -> m a

-- | Lift an <tt>f</tt> into <tt><a>Free</a> f</tt>, so you can use it as a
--   <a>Monad</a>.
--   
--   This is <a>inject</a>.
liftFree :: f ~> Free f

-- | Interpret a <tt><a>Free</a> f</tt> into a context <tt>g</tt>, provided
--   that <tt>g</tt> has a <a>Monad</a> instance.
--   
--   This is <a>interpret</a>.
interpretFree :: Monad g => (f ~> g) -> Free f ~> g

-- | Extract the <tt>f</tt>s back "out" of a <tt><a>Free</a> f</tt>,
--   utilizing its <a>Monad</a> instance.
--   
--   This is <a>retract</a>.
retractFree :: Monad f => Free f ~> f

-- | Swap out the underlying functor over a <a>Free</a>. This preserves all
--   of the structure of the <a>Free</a>.
hoistFree :: (f ~> g) -> Free f ~> Free g

-- | Recursively fold down a <a>Free</a> by handling the <a>pure</a> case
--   and the nested/wrapped case.
--   
--   This is a catamorphism.
--   
--   This requires <tt><a>Functor</a> f</tt>; see <a>foldFree'</a> and
--   <a>foldFreeC</a> for a version that doesn't require <tt><a>Functor</a>
--   f</tt>.
foldFree :: Functor f => (a -> r) -> (f r -> r) -> Free f a -> r

-- | A version of <a>foldFree</a> that doesn't require <tt><a>Functor</a>
--   f</tt>, by taking a RankN folding function. This is essentially a
--   flipped <a>runFree</a>.
foldFree' :: (a -> r) -> (forall s. f s -> (s -> r) -> r) -> Free f a -> r

-- | A version of <a>foldFree</a> that doesn't require <tt><a>Functor</a>
--   f</tt>, by folding over a <a>Coyoneda</a> instead.
foldFreeC :: (a -> r) -> (Coyoneda f r -> r) -> Free f a -> r

-- | The Free <a>Bind</a>. Imbues any functor <tt>f</tt> with a <a>Bind</a>
--   instance.
--   
--   Conceptually, this is "<a>Free</a> without pure". That is, while
--   normally <tt><a>Free</a> f a</tt> is an <tt>a</tt>, a <tt>f a</tt>, a
--   <tt>f (f a)</tt>, etc., a <tt><a>Free1</a> f a</tt> is an <tt>f
--   a</tt>, <tt>f (f a)</tt>, <tt>f (f (f a))</tt>, etc. It's a
--   <a>Free</a> with "at least one layer of <tt>f</tt>", excluding the
--   <tt>a</tt> case.
--   
--   It can be useful as the semigroup formed by <a>:.:</a> (functor
--   composition): Sometimes we want an <tt>f :.: f</tt>, or an <tt>f :.: f
--   :.: f</tt>, or an <tt>f :.: f :.: f :.: f</tt>...just as long as we
--   have at least one <tt>f</tt>.
newtype Free1 f a
Free1 :: (forall r. (forall s. f s -> (s -> a) -> r) -> (forall s. f s -> (s -> r) -> r) -> r) -> Free1 f a
[runFree1] :: Free1 f a -> forall r. (forall s. f s -> (s -> a) -> r) -> (forall s. f s -> (s -> r) -> r) -> r

-- | Constructor matching on the case that a <tt><a>Free1</a> f</tt>
--   consists of just a single un-nested <tt>f</tt>. Used as a part of the
--   <a>Show</a> and <a>Read</a> instances.
pattern DoneF1 :: Functor f => f a -> Free1 f a

-- | Constructor matching on the case that a <tt><a>Free1</a> f</tt> is a
--   nested <tt>f (<a>Free1</a> f a)</tt>. Used as a part of the
--   <a>Show</a> and <a>Read</a> instances.
--   
--   As a constructor, this is equivalent to <a>wrap</a>.
pattern MoreF1 :: Functor f => f (Free1 f a) -> Free1 f a

-- | Convert a <tt><a>Free1</a> f</tt> into any instance of
--   <tt><a>MonadFree</a> f</tt>.
reFree1 :: (MonadFree f m, Functor f) => Free1 f a -> m a

-- | <tt><a>Free1</a> f</tt> is a special subset of <tt><a>Free</a> f</tt>
--   that consists of at least one nested <tt>f</tt>. This converts it back
--   into the "bigger" type.
--   
--   See <a>free1Comp</a> for a version that preserves the "one nested
--   layer" property.
toFree :: Free1 f ~> Free f

-- | Inject an <tt>f</tt> into a <tt><a>Free1</a> f</tt>
liftFree1 :: f ~> Free1 f

-- | Interpret the <tt><a>Free1</a> f</tt> in some context <tt>g</tt>,
--   provided that <tt>g</tt> has a <a>Bind</a> instance. Since we always
--   have at least one <tt>f</tt>, we will always have at least one
--   <tt>g</tt>, so we do not need a full <a>Monad</a> constraint.
interpretFree1 :: Bind g => (f ~> g) -> Free1 f ~> g

-- | Retract the <tt>f</tt> out of a <tt><a>Free1</a> f</tt>, as long as
--   the <tt>f</tt> implements <a>Bind</a>. Since we always have at least
--   one <tt>f</tt>, we do not need a full <a>Monad</a> constraint.
retractFree1 :: Bind f => Free1 f ~> f

-- | Map the underlying functor under a <a>Free1</a>.
hoistFree1 :: (f ~> g) -> Free1 f ~> Free1 g

-- | Because a <tt><a>Free1</a> f</tt> is just a <tt><a>Free</a> f</tt>
--   with at least one nested layer of <tt>f</tt>, this function converts
--   it back into the one-nested-<tt>f</tt> format.
free1Comp :: Free1 f ~> Comp f (Free f)

-- | A <tt><a>Free1</a> f</tt> is either a single un-nested <tt>f</tt>, or
--   a <tt>f</tt> nested with another <tt><a>Free1</a> f</tt>. This decides
--   which is the case.
matchFree1 :: forall f. Functor f => Free1 f ~> (f :+: Comp f (Free1 f))

-- | Recursively fold down a <a>Free1</a> by handling the single <tt>f</tt>
--   case and the nested/wrapped case.
--   
--   This is a catamorphism.
--   
--   This requires <tt><a>Functor</a> f</tt>; see <a>foldFree'</a> and
--   <a>foldFreeC</a> for a version that doesn't require <tt><a>Functor</a>
--   f</tt>.
foldFree1 :: Functor f => (f a -> r) -> (f r -> r) -> Free1 f a -> r

-- | A version of <a>foldFree1</a> that doesn't require <tt><a>Functor</a>
--   f</tt>, by taking a RankN folding function. This is essentially a
--   flipped <a>runFree</a>.
foldFree1' :: (forall s. f s -> (s -> a) -> r) -> (forall s. f s -> (s -> r) -> r) -> Free1 f a -> r

-- | A version of <a>foldFree1</a> that doesn't require <tt><a>Functor</a>
--   f</tt>, by folding over a <a>Coyoneda</a> instead.
foldFree1C :: (Coyoneda f a -> r) -> (Coyoneda f r -> r) -> Free1 f a -> r

-- | Functor composition. <tt><a>Comp</a> f g a</tt> is equivalent to <tt>f
--   (g a)</tt>, and the <a>Comp</a> pattern synonym is a way of getting
--   the <tt>f (g a)</tt> in a <tt><a>Comp</a> f g a</tt>.
--   
--   For example, <tt><a>Maybe</a> (<a>IO</a> <a>Bool</a>)</tt> is
--   <tt><a>Comp</a> <a>Maybe</a> <a>IO</a> <a>Bool</a></tt>.
--   
--   This is mostly useful for its typeclass instances: in particular,
--   <a>Functor</a>, <a>Applicative</a>, <a>HBifunctor</a>, and
--   <a>Monoidal</a>.
--   
--   This is essentially a version of <a>:.:</a> and <a>Compose</a> that
--   allows for an <a>HBifunctor</a> instance.
--   
--   It is slightly less performant. Using <tt><a>comp</a> .
--   <a>unComp</a></tt> every once in a while will concretize a <a>Comp</a>
--   value (if you have <tt><a>Functor</a> f</tt>) and remove some
--   indirection if you have a lot of chained operations.
--   
--   The "free monoid" over <a>Comp</a> is <a>Free</a>, and the "free
--   semigroup" over <a>Comp</a> is <a>Free1</a>.
data Comp f g a
(:>>=) :: f x -> (x -> g a) -> Comp f g a

-- | Pattern match on and construct a <tt><a>Comp</a> f g a</tt> as if it
--   were <tt>f (g a)</tt>.
pattern Comp :: Functor f => f (g a) -> Comp f g a

-- | "Smart constructor" for <a>Comp</a> that doesn't require
--   <tt><a>Functor</a> f</tt>.
comp :: f (g a) -> Comp f g a
instance GHC.Base.Functor g => GHC.Base.Functor (Control.Monad.Freer.Church.Comp f g)
instance (Data.Functor.Bind.Class.Apply f, Data.Functor.Bind.Class.Apply g) => Data.Functor.Bind.Class.Apply (Control.Monad.Freer.Church.Comp f g)
instance (GHC.Base.Applicative f, GHC.Base.Applicative g) => GHC.Base.Applicative (Control.Monad.Freer.Church.Comp f g)
instance (Data.Foldable.Foldable f, Data.Foldable.Foldable g) => Data.Foldable.Foldable (Control.Monad.Freer.Church.Comp f g)
instance (Data.Traversable.Traversable f, Data.Traversable.Traversable g) => Data.Traversable.Traversable (Control.Monad.Freer.Church.Comp f g)
instance (GHC.Base.Alternative f, GHC.Base.Alternative g) => GHC.Base.Alternative (Control.Monad.Freer.Church.Comp f g)
instance (Data.Functor.Alt.Alt f, Data.Functor.Alt.Alt g) => Data.Functor.Alt.Alt (Control.Monad.Freer.Church.Comp f g)
instance (Data.Functor.Plus.Plus f, Data.Functor.Plus.Plus g) => Data.Functor.Plus.Plus (Control.Monad.Freer.Church.Comp f g)
instance (GHC.Base.Functor f, Data.Functor.Classes.Show1 f, Data.Functor.Classes.Show1 g) => Data.Functor.Classes.Show1 (Control.Monad.Freer.Church.Comp f g)
instance (GHC.Base.Functor f, Data.Functor.Classes.Show1 f, Data.Functor.Classes.Show1 g, GHC.Show.Show a) => GHC.Show.Show (Control.Monad.Freer.Church.Comp f g a)
instance (GHC.Base.Functor f, Data.Functor.Classes.Read1 f, Data.Functor.Classes.Read1 g) => Data.Functor.Classes.Read1 (Control.Monad.Freer.Church.Comp f g)
instance (GHC.Base.Functor f, Data.Functor.Classes.Read1 f, Data.Functor.Classes.Read1 g, GHC.Read.Read a) => GHC.Read.Read (Control.Monad.Freer.Church.Comp f g a)
instance (GHC.Base.Functor f, Data.Functor.Classes.Eq1 f, Data.Functor.Classes.Eq1 g) => Data.Functor.Classes.Eq1 (Control.Monad.Freer.Church.Comp f g)
instance (GHC.Base.Functor f, Data.Functor.Classes.Ord1 f, Data.Functor.Classes.Ord1 g) => Data.Functor.Classes.Ord1 (Control.Monad.Freer.Church.Comp f g)
instance (GHC.Base.Functor f, Data.Functor.Classes.Eq1 f, Data.Functor.Classes.Eq1 g, GHC.Classes.Eq a) => GHC.Classes.Eq (Control.Monad.Freer.Church.Comp f g a)
instance (GHC.Base.Functor f, Data.Functor.Classes.Ord1 f, Data.Functor.Classes.Ord1 g, GHC.Classes.Ord a) => GHC.Classes.Ord (Control.Monad.Freer.Church.Comp f g a)
instance GHC.Base.Functor (Control.Monad.Freer.Church.Free1 f)
instance Data.Functor.Bind.Class.Apply (Control.Monad.Freer.Church.Free1 f)
instance Data.Functor.Bind.Class.Bind (Control.Monad.Freer.Church.Free1 f)
instance Data.Foldable.Foldable f => Data.Foldable.Foldable (Control.Monad.Freer.Church.Free1 f)
instance Data.Traversable.Traversable f => Data.Traversable.Traversable (Control.Monad.Freer.Church.Free1 f)
instance Data.Semigroup.Foldable.Class.Foldable1 f => Data.Semigroup.Foldable.Class.Foldable1 (Control.Monad.Freer.Church.Free1 f)
instance Data.Semigroup.Traversable.Class.Traversable1 f => Data.Semigroup.Traversable.Class.Traversable1 (Control.Monad.Freer.Church.Free1 f)
instance (GHC.Base.Functor f, Data.Functor.Classes.Eq1 f) => Data.Functor.Classes.Eq1 (Control.Monad.Freer.Church.Free1 f)
instance (GHC.Base.Functor f, Data.Functor.Classes.Ord1 f) => Data.Functor.Classes.Ord1 (Control.Monad.Freer.Church.Free1 f)
instance (GHC.Base.Functor f, Data.Functor.Classes.Eq1 f, GHC.Classes.Eq a) => GHC.Classes.Eq (Control.Monad.Freer.Church.Free1 f a)
instance (GHC.Base.Functor f, Data.Functor.Classes.Ord1 f, GHC.Classes.Ord a) => GHC.Classes.Ord (Control.Monad.Freer.Church.Free1 f a)
instance (GHC.Base.Functor f, Data.Functor.Classes.Show1 f) => Data.Functor.Classes.Show1 (Control.Monad.Freer.Church.Free1 f)
instance (GHC.Base.Functor f, Data.Functor.Classes.Show1 f, GHC.Show.Show a) => GHC.Show.Show (Control.Monad.Freer.Church.Free1 f a)
instance (GHC.Base.Functor f, Data.Functor.Classes.Read1 f) => Data.Functor.Classes.Read1 (Control.Monad.Freer.Church.Free1 f)
instance (GHC.Base.Functor f, Data.Functor.Classes.Read1 f, GHC.Read.Read a) => GHC.Read.Read (Control.Monad.Freer.Church.Free1 f a)
instance GHC.Base.Functor (Control.Monad.Freer.Church.Free f)
instance Data.Functor.Bind.Class.Apply (Control.Monad.Freer.Church.Free f)
instance GHC.Base.Applicative (Control.Monad.Freer.Church.Free f)
instance Data.Pointed.Pointed (Control.Monad.Freer.Church.Free f)
instance Data.Functor.Bind.Class.Bind (Control.Monad.Freer.Church.Free f)
instance GHC.Base.Monad (Control.Monad.Freer.Church.Free f)
instance Control.Monad.Free.Class.MonadFree f (Control.Monad.Freer.Church.Free f)
instance Data.Foldable.Foldable f => Data.Foldable.Foldable (Control.Monad.Freer.Church.Free f)
instance Data.Traversable.Traversable f => Data.Traversable.Traversable (Control.Monad.Freer.Church.Free f)
instance (GHC.Base.Functor f, Data.Functor.Classes.Eq1 f) => Data.Functor.Classes.Eq1 (Control.Monad.Freer.Church.Free f)
instance (GHC.Base.Functor f, Data.Functor.Classes.Ord1 f) => Data.Functor.Classes.Ord1 (Control.Monad.Freer.Church.Free f)
instance (GHC.Base.Functor f, Data.Functor.Classes.Eq1 f, GHC.Classes.Eq a) => GHC.Classes.Eq (Control.Monad.Freer.Church.Free f a)
instance (GHC.Base.Functor f, Data.Functor.Classes.Ord1 f, GHC.Classes.Ord a) => GHC.Classes.Ord (Control.Monad.Freer.Church.Free f a)
instance (GHC.Base.Functor f, Data.Functor.Classes.Show1 f) => Data.Functor.Classes.Show1 (Control.Monad.Freer.Church.Free f)
instance (GHC.Base.Functor f, Data.Functor.Classes.Show1 f, GHC.Show.Show a) => GHC.Show.Show (Control.Monad.Freer.Church.Free f a)
instance (GHC.Base.Functor f, Data.Functor.Classes.Read1 f) => Data.Functor.Classes.Read1 (Control.Monad.Freer.Church.Free f)
instance (GHC.Base.Functor f, Data.Functor.Classes.Read1 f, GHC.Read.Read a) => GHC.Read.Read (Control.Monad.Freer.Church.Free f a)


-- | Types describing isomorphisms between two functors, and functions to
--   manipulate them.
module Control.Natural.IsoF
type (f :: k -> Type) ~> (g :: k -> Type) = forall (x :: k). () => f x -> g x

-- | The type of an isomorphism between two functors. <tt>f
--   <a>&lt;~&gt;</a> g</tt> means that <tt>f</tt> and <tt>g</tt> are
--   isomorphic to each other.
--   
--   We can effectively <i>use</i> an <tt>f &lt;~&gt; g</tt> with:
--   
--   <pre>
--   <a>viewF</a>   :: (f &lt;~&gt; g) -&gt; f a -&gt; g a
--   <a>reviewF</a> :: (f &lt;~&gt; g) -&gt; g a -&gt; a a
--   </pre>
--   
--   Use <a>viewF</a> to extract the "<tt>f</tt> to <tt>g</tt>" function,
--   and <a>reviewF</a> to extract the "<tt>g</tt> to <tt>f</tt>" function.
--   Reviewing and viewing the same value (or vice versa) leaves the value
--   unchanged.
--   
--   One nice thing is that we can compose isomorphisms using <a>.</a> from
--   <a>Prelude</a>:
--   
--   <pre>
--   (<a>.</a>) :: f &lt;~&gt; g
--       -&gt; g &lt;~&gt; h
--       -&gt; f &lt;~&gt; h
--   </pre>
--   
--   Another nice thing about this representation is that we have the
--   "identity" isomorphism by using <a>id</a> from <a>Prelude</a>.
--   
--   <pre>
--   <a>id</a> :: f <a>&lt;~&gt;</a> g
--   </pre>
--   
--   As a convention, most isomorphisms have form "X-ing", where the
--   forwards function is "ing". For example, we have:
--   
--   <pre>
--   <a>splittingSF</a> :: <a>Monoidal</a> t =&gt; <a>SF</a> t a <a>&lt;~&gt;</a> t f (<a>MF</a> t f)
--   <a>splitSF</a>     :: Monoidal t =&gt; SF t a  <a>~&gt;</a> t f (MF t f)
--   </pre>
type f <~> g = forall p a. Profunctor p => p (g a) (g a) -> p (f a) (f a)
infixr 0 <~>

-- | Create an <tt>f <a>&lt;~&gt;</a> g</tt> by providing both legs of the
--   isomorphism (the <tt>f a -&gt; g a</tt> and the <tt>g a -&gt; f
--   a</tt>.
isoF :: (f ~> g) -> (g ~> f) -> f <~> g

-- | An isomorphism between two functors that are coercible/have the same
--   internal representation. Useful for newtype wrappers.
coercedF :: forall f g. (forall x. Coercible (f x) (g x), forall x. Coercible (g x) (f x)) => f <~> g

-- | Use a <a>&lt;~&gt;</a> by retrieving the "forward" function:
--   
--   <pre>
--   <a>viewF</a>   :: (f <a>~</a> g) -&gt; f a -&gt; g a
--   </pre>
viewF :: (f <~> g) -> f ~> g

-- | Use a <a>&lt;~&gt;</a> by retrieving the "backwards" function:
--   
--   <pre>
--   <a>viewF</a>   :: (f <a>~</a> g) -&gt; f a -&gt; g a
--   </pre>
reviewF :: (f <~> g) -> g ~> f

-- | Lift a function <tt>g a ~&gt; g a</tt> to be a function <tt>f a -&gt;
--   f a</tt>, given an isomorphism between the two.
--   
--   One neat thing is that <tt><a>overF</a> i id == id</tt>.
overF :: (f <~> g) -> (g ~> g) -> f ~> f

-- | Reverse an isomorphism.
--   
--   <pre>
--   <a>viewF</a>   (<a>fromF</a> i) == <a>reviewF</a> i
--   <a>reviewF</a> (<a>fromF</a> i) == <a>viewF</a> i
--   </pre>
fromF :: forall (f :: Type -> Type) (g :: Type -> Type). () => (f <~> g) -> g <~> f


-- | The contravariant counterpart of <a>Apply</a>: like <a>Divisible</a>,
--   but without <a>conquer</a>. This is only a part of this library
--   currently for compatibility, until it is (hopefully) merged into
--   <i>semigroupoids</i>.
module Data.Functor.Contravariant.Divise

-- | The contravariant analogue of <a>Apply</a>; it is <a>Divisible</a>
--   without <a>conquer</a>.
--   
--   If one thinks of <tt>f a</tt> as a consumer of <tt>a</tt>s, then
--   <a>divise</a> allows one to handle the consumption of a value by
--   splitting it between two consumers that consume separate parts of
--   <tt>a</tt>.
--   
--   <a>divise</a> takes the "splitting" method and the two sub-consumers,
--   and returns the wrapped/combined consumer.
--   
--   All instances of <a>Divisible</a> should be instances of <a>Divise</a>
--   with <tt><a>divise</a> = <a>divide</a></tt>.
--   
--   The guarantee that a function polymorphic over of <tt><a>Divise</a>
--   f</tt> provides that <tt><a>Divisible</a> f</tt> doesn't that any
--   input consumed will be passed to at least one sub-consumer; it won't
--   potentially disappear into the void, as is possible if <a>conquer</a>
--   is available.
--   
--   Mathematically, a functor being an instance of <a>Divise</a> means
--   that it is "semgroupoidal" with respect to the contravariant (tupling)
--   Day convolution. That is, it is possible to define a function <tt>(f
--   <tt>Day</tt> f) a -&gt; f a</tt> in a way that is associative.
class Contravariant f => Divise f

-- | Takes a "splitting" method and the two sub-consumers, and returns the
--   wrapped/combined consumer.
divise :: Divise f => (a -> (b, c)) -> f b -> f c -> f a

-- | Combine a consumer of <tt>a</tt> with a consumer of <tt>b</tt> to get
--   a consumer of <tt>(a, b)</tt>.
--   
--   <pre>
--   <a>divised</a> = <a>divise</a> <a>id</a>
--   </pre>
divised :: Divise f => f a -> f b -> f (a, b)

-- | The Contravariant version of <a>&lt;|&gt;</a>: split the same input
--   over two different consumers.
(<:>) :: Divise f => f a -> f a -> f a

-- | Convenient helper function to build up a <a>Divise</a> by splitting
--   input across many different <tt>f a</tt>s. Most useful when used
--   alongside <a>contramap</a>:
--   
--   <pre>
--   dsum1 $ contramap get1 x
--      :| [ contramap get2 y
--         , contramap get3 z
--         ]
--   </pre>
dsum1 :: (Foldable1 t, Divise f) => t (f a) -> f a

-- | Wrap a <a>Divisible</a> to be used as a member of <a>Divise</a>
newtype WrappedDivisible f a
WrapDivisible :: f a -> WrappedDivisible f a
[unwrapDivisible] :: WrappedDivisible f a -> f a
instance Data.Functor.Contravariant.Contravariant f => Data.Functor.Contravariant.Contravariant (Data.Functor.Contravariant.Divise.WrappedDivisible f)
instance Data.Functor.Contravariant.Divisible.Divisible f => Data.Functor.Contravariant.Divise.Divise (Data.Functor.Contravariant.Divise.WrappedDivisible f)
instance GHC.Base.Semigroup r => Data.Functor.Contravariant.Divise.Divise (Data.Functor.Contravariant.Op r)
instance GHC.Base.Semigroup m => Data.Functor.Contravariant.Divise.Divise (Data.Functor.Const.Const m)
instance GHC.Base.Semigroup m => Data.Functor.Contravariant.Divise.Divise (Data.Functor.Constant.Constant m)
instance Data.Functor.Contravariant.Divise.Divise Data.Functor.Contravariant.Comparison
instance Data.Functor.Contravariant.Divise.Divise Data.Functor.Contravariant.Equivalence
instance Data.Functor.Contravariant.Divise.Divise Data.Functor.Contravariant.Predicate
instance Data.Functor.Contravariant.Divise.Divise Data.Proxy.Proxy
instance Data.Functor.Contravariant.Divise.Divise f => Data.Functor.Contravariant.Divise.Divise (Data.Semigroup.Internal.Alt f)
instance Data.Functor.Contravariant.Divise.Divise GHC.Generics.U1
instance Data.Functor.Contravariant.Divise.Divise GHC.Generics.V1
instance Data.Functor.Contravariant.Divise.Divise f => Data.Functor.Contravariant.Divise.Divise (GHC.Generics.Rec1 f)
instance Data.Functor.Contravariant.Divise.Divise f => Data.Functor.Contravariant.Divise.Divise (GHC.Generics.M1 i c f)
instance (Data.Functor.Contravariant.Divise.Divise f, Data.Functor.Contravariant.Divise.Divise g) => Data.Functor.Contravariant.Divise.Divise (f GHC.Generics.:*: g)
instance (Data.Functor.Bind.Class.Apply f, Data.Functor.Contravariant.Divise.Divise g) => Data.Functor.Contravariant.Divise.Divise (f GHC.Generics.:.: g)
instance Data.Functor.Contravariant.Divise.Divise f => Data.Functor.Contravariant.Divise.Divise (Control.Applicative.Backwards.Backwards f)
instance Data.Functor.Contravariant.Divise.Divise m => Data.Functor.Contravariant.Divise.Divise (Control.Monad.Trans.Error.ErrorT e m)
instance Data.Functor.Contravariant.Divise.Divise m => Data.Functor.Contravariant.Divise.Divise (Control.Monad.Trans.Except.ExceptT e m)
instance Data.Functor.Contravariant.Divise.Divise f => Data.Functor.Contravariant.Divise.Divise (Control.Monad.Trans.Identity.IdentityT f)
instance Data.Functor.Contravariant.Divise.Divise m => Data.Functor.Contravariant.Divise.Divise (Control.Monad.Trans.List.ListT m)
instance Data.Functor.Contravariant.Divise.Divise m => Data.Functor.Contravariant.Divise.Divise (Control.Monad.Trans.Maybe.MaybeT m)
instance Data.Functor.Contravariant.Divise.Divise m => Data.Functor.Contravariant.Divise.Divise (Control.Monad.Trans.Reader.ReaderT r m)
instance Data.Functor.Contravariant.Divise.Divise m => Data.Functor.Contravariant.Divise.Divise (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance Data.Functor.Contravariant.Divise.Divise m => Data.Functor.Contravariant.Divise.Divise (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance Data.Functor.Contravariant.Divise.Divise m => Data.Functor.Contravariant.Divise.Divise (Control.Monad.Trans.State.Lazy.StateT s m)
instance Data.Functor.Contravariant.Divise.Divise m => Data.Functor.Contravariant.Divise.Divise (Control.Monad.Trans.State.Strict.StateT s m)
instance Data.Functor.Contravariant.Divise.Divise m => Data.Functor.Contravariant.Divise.Divise (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance Data.Functor.Contravariant.Divise.Divise m => Data.Functor.Contravariant.Divise.Divise (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance (Data.Functor.Bind.Class.Apply f, Data.Functor.Contravariant.Divise.Divise g) => Data.Functor.Contravariant.Divise.Divise (Data.Functor.Compose.Compose f g)
instance (Data.Functor.Contravariant.Divise.Divise f, Data.Functor.Contravariant.Divise.Divise g) => Data.Functor.Contravariant.Divise.Divise (Data.Functor.Product.Product f g)
instance Data.Functor.Contravariant.Divise.Divise f => Data.Functor.Contravariant.Divise.Divise (Data.Functor.Reverse.Reverse f)


-- | The contravariant counterpart of <a>Alt</a>: like <a>Decidable</a>,
--   but without <a>loss</a> or a superclass constraint on
--   <a>Divisible</a>. This is only a part of this library currently for
--   compatibility, until it is (hopefully) merged into
--   <i>semigroupoids</i>.
module Data.Functor.Contravariant.Decide

-- | The contravariant analogue of <a>Alt</a>.
--   
--   If one thinks of <tt>f a</tt> as a consumer of <tt>a</tt>s, then
--   <a>decide</a> allows one to handle the consumption of a value by
--   choosing to handle it via exactly one of two independent consumers. It
--   redirects the input completely into one of two consumers.
--   
--   <a>decide</a> takes the "decision" method and the two potential
--   consumers, and returns the wrapped/combined consumer.
--   
--   Mathematically, a functor being an instance of <a>Decide</a> means
--   that it is "semgroupoidal" with respect to the contravariant
--   "either-based" Day convolution (<tt>data EitherDay f g a = forall b c.
--   EitherDay (f b) (g c) (a -&gt; Either b c)</tt>). That is, it is
--   possible to define a function <tt>(f <tt>EitherDay</tt> f) a -&gt; f
--   a</tt> in a way that is associative.
class Contravariant f => Decide f

-- | Takes the "decision" method and the two potential consumers, and
--   returns the wrapped/combined consumer.
decide :: Decide f => (a -> Either b c) -> f b -> f c -> f a

-- | For <tt><a>decided</a> x y</tt>, the resulting <tt>f (<a>Either</a> b
--   c)</tt> will direct <a>Left</a>s to be consumed by <tt>x</tt>, and
--   <a>Right</a>s to be consumed by y.
decided :: Decide f => f b -> f c -> f (Either b c)
instance Data.Functor.Contravariant.Divisible.Decidable f => Data.Functor.Contravariant.Decide.Decide (Data.Functor.Contravariant.Divise.WrappedDivisible f)
instance Data.Functor.Contravariant.Decide.Decide Data.Functor.Contravariant.Comparison
instance Data.Functor.Contravariant.Decide.Decide Data.Functor.Contravariant.Equivalence
instance Data.Functor.Contravariant.Decide.Decide Data.Functor.Contravariant.Predicate
instance Data.Functor.Contravariant.Decide.Decide (Data.Functor.Contravariant.Op r)
instance Data.Functor.Contravariant.Decide.Decide f => Data.Functor.Contravariant.Decide.Decide (Data.Semigroup.Internal.Alt f)
instance Data.Functor.Contravariant.Decide.Decide GHC.Generics.U1
instance Data.Functor.Contravariant.Decide.Decide GHC.Generics.V1
instance Data.Functor.Contravariant.Decide.Decide f => Data.Functor.Contravariant.Decide.Decide (GHC.Generics.Rec1 f)
instance Data.Functor.Contravariant.Decide.Decide f => Data.Functor.Contravariant.Decide.Decide (GHC.Generics.M1 i c f)
instance (Data.Functor.Contravariant.Decide.Decide f, Data.Functor.Contravariant.Decide.Decide g) => Data.Functor.Contravariant.Decide.Decide (f GHC.Generics.:*: g)
instance (Data.Functor.Bind.Class.Apply f, Data.Functor.Contravariant.Decide.Decide g) => Data.Functor.Contravariant.Decide.Decide (f GHC.Generics.:.: g)
instance Data.Functor.Contravariant.Decide.Decide f => Data.Functor.Contravariant.Decide.Decide (Control.Applicative.Backwards.Backwards f)
instance Data.Functor.Contravariant.Decide.Decide f => Data.Functor.Contravariant.Decide.Decide (Control.Monad.Trans.Identity.IdentityT f)
instance Data.Functor.Contravariant.Decide.Decide m => Data.Functor.Contravariant.Decide.Decide (Control.Monad.Trans.Reader.ReaderT r m)
instance Data.Functor.Contravariant.Decide.Decide m => Data.Functor.Contravariant.Decide.Decide (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance Data.Functor.Contravariant.Decide.Decide m => Data.Functor.Contravariant.Decide.Decide (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance Data.Functor.Contravariant.Divise.Divise m => Data.Functor.Contravariant.Decide.Decide (Control.Monad.Trans.List.ListT m)
instance Data.Functor.Contravariant.Divise.Divise m => Data.Functor.Contravariant.Decide.Decide (Control.Monad.Trans.Maybe.MaybeT m)
instance Data.Functor.Contravariant.Decide.Decide m => Data.Functor.Contravariant.Decide.Decide (Control.Monad.Trans.State.Lazy.StateT s m)
instance Data.Functor.Contravariant.Decide.Decide m => Data.Functor.Contravariant.Decide.Decide (Control.Monad.Trans.State.Strict.StateT s m)
instance Data.Functor.Contravariant.Decide.Decide m => Data.Functor.Contravariant.Decide.Decide (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance Data.Functor.Contravariant.Decide.Decide m => Data.Functor.Contravariant.Decide.Decide (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance (Data.Functor.Bind.Class.Apply f, Data.Functor.Contravariant.Decide.Decide g) => Data.Functor.Contravariant.Decide.Decide (Data.Functor.Compose.Compose f g)
instance (Data.Functor.Contravariant.Decide.Decide f, Data.Functor.Contravariant.Decide.Decide g) => Data.Functor.Contravariant.Decide.Decide (Data.Functor.Product.Product f g)
instance Data.Functor.Contravariant.Decide.Decide f => Data.Functor.Contravariant.Decide.Decide (Data.Functor.Reverse.Reverse f)
instance Data.Functor.Contravariant.Decide.Decide Data.Proxy.Proxy


-- | The contravariant counterpart of <a>Plus</a>: like <a>Decidable</a>,
--   but without needing a <a>Divisible</a> constraint. This is only a part
--   of this library currently for compatibility, until it is (hopefully)
--   merged into <i>semigroupoids</i>.
module Data.Functor.Contravariant.Conclude

-- | The contravariant analogue of <a>Plus</a>. Adds on to <a>Decide</a>
--   the ability to express a combinator that rejects all input, to act as
--   the dead-end. Essentially <a>Decidable</a> without a superclass
--   constraint on <a>Divisible</a>.
--   
--   If one thinks of <tt>f a</tt> as a consumer of <tt>a</tt>s, then
--   <a>conclude</a> defines a consumer that cannot ever receive <i>any</i>
--   input.
--   
--   Conclude acts as an identity with <a>decide</a>, because any decision
--   that involves <a>conclude</a> must necessarily <i>always</i> pick the
--   other option.
--   
--   That is, for, say,
--   
--   <pre>
--   <a>decide</a> f x <a>concluded</a>
--   </pre>
--   
--   <tt>f</tt> is the deciding function that picks which of the inputs of
--   <tt>decide</tt> to direct input to; in the situation above, <tt>f</tt>
--   must <i>always</i> direct all input to <tt>x</tt>, and never
--   <a>concluded</a>.
--   
--   Mathematically, a functor being an instance of <a>Decide</a> means
--   that it is "monoidal" with respect to the contravariant "either-based"
--   Day convolution described in the documentation of <a>Decide</a>. On
--   top of <a>Decide</a>, it adds a way to construct an "identity"
--   <tt>conclude</tt> where <tt>decide f x (conclude q) == x</tt>, and
--   <tt>decide g (conclude r) y == y</tt>.
class Decide f => Conclude f

-- | The consumer that cannot ever receive <i>any</i> input.
conclude :: Conclude f => (a -> Void) -> f a

-- | A potentially more meaningful form of <a>conclude</a>, the consumer
--   that cannot ever receive <i>any</i> input. That is because it expects
--   only input of type <a>Void</a>, but such a type has no values.
--   
--   <pre>
--   <a>concluded</a> = <a>conclude</a> <a>id</a>
--   </pre>
concluded :: Conclude f => f Void
instance Data.Functor.Contravariant.Divisible.Decidable f => Data.Functor.Contravariant.Conclude.Conclude (Data.Functor.Contravariant.Divise.WrappedDivisible f)
instance Data.Functor.Contravariant.Conclude.Conclude Data.Functor.Contravariant.Comparison
instance Data.Functor.Contravariant.Conclude.Conclude Data.Functor.Contravariant.Equivalence
instance Data.Functor.Contravariant.Conclude.Conclude Data.Functor.Contravariant.Predicate
instance Data.Functor.Contravariant.Conclude.Conclude (Data.Functor.Contravariant.Op r)
instance Data.Functor.Contravariant.Conclude.Conclude Data.Proxy.Proxy
instance Data.Functor.Contravariant.Conclude.Conclude f => Data.Functor.Contravariant.Conclude.Conclude (Data.Semigroup.Internal.Alt f)
instance Data.Functor.Contravariant.Conclude.Conclude GHC.Generics.U1
instance Data.Functor.Contravariant.Conclude.Conclude f => Data.Functor.Contravariant.Conclude.Conclude (GHC.Generics.Rec1 f)
instance Data.Functor.Contravariant.Conclude.Conclude f => Data.Functor.Contravariant.Conclude.Conclude (GHC.Generics.M1 i c f)
instance (Data.Functor.Contravariant.Conclude.Conclude f, Data.Functor.Contravariant.Conclude.Conclude g) => Data.Functor.Contravariant.Conclude.Conclude (f GHC.Generics.:*: g)
instance (Data.Functor.Bind.Class.Apply f, GHC.Base.Applicative f, Data.Functor.Contravariant.Conclude.Conclude g) => Data.Functor.Contravariant.Conclude.Conclude (f GHC.Generics.:.: g)
instance Data.Functor.Contravariant.Conclude.Conclude f => Data.Functor.Contravariant.Conclude.Conclude (Control.Applicative.Backwards.Backwards f)
instance Data.Functor.Contravariant.Conclude.Conclude f => Data.Functor.Contravariant.Conclude.Conclude (Control.Monad.Trans.Identity.IdentityT f)
instance Data.Functor.Contravariant.Conclude.Conclude m => Data.Functor.Contravariant.Conclude.Conclude (Control.Monad.Trans.Reader.ReaderT r m)
instance Data.Functor.Contravariant.Conclude.Conclude m => Data.Functor.Contravariant.Conclude.Conclude (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance Data.Functor.Contravariant.Conclude.Conclude m => Data.Functor.Contravariant.Conclude.Conclude (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance (Data.Functor.Contravariant.Divisible.Divisible m, Data.Functor.Contravariant.Divise.Divise m) => Data.Functor.Contravariant.Conclude.Conclude (Control.Monad.Trans.List.ListT m)
instance (Data.Functor.Contravariant.Divisible.Divisible m, Data.Functor.Contravariant.Divise.Divise m) => Data.Functor.Contravariant.Conclude.Conclude (Control.Monad.Trans.Maybe.MaybeT m)
instance Data.Functor.Contravariant.Conclude.Conclude m => Data.Functor.Contravariant.Conclude.Conclude (Control.Monad.Trans.State.Lazy.StateT s m)
instance Data.Functor.Contravariant.Conclude.Conclude m => Data.Functor.Contravariant.Conclude.Conclude (Control.Monad.Trans.State.Strict.StateT s m)
instance Data.Functor.Contravariant.Conclude.Conclude m => Data.Functor.Contravariant.Conclude.Conclude (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance Data.Functor.Contravariant.Conclude.Conclude m => Data.Functor.Contravariant.Conclude.Conclude (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance (Data.Functor.Bind.Class.Apply f, GHC.Base.Applicative f, Data.Functor.Contravariant.Conclude.Conclude g) => Data.Functor.Contravariant.Conclude.Conclude (Data.Functor.Compose.Compose f g)
instance (Data.Functor.Contravariant.Conclude.Conclude f, Data.Functor.Contravariant.Conclude.Conclude g) => Data.Functor.Contravariant.Conclude.Conclude (Data.Functor.Product.Product f g)
instance Data.Functor.Contravariant.Conclude.Conclude f => Data.Functor.Contravariant.Conclude.Conclude (Data.Functor.Reverse.Reverse f)


-- | Working with non-standard typeclasses like <a>Plus</a>, <a>Apply</a>,
--   <a>Bind</a>, and <a>Pointed</a> will sometimes cause problems when
--   using with libraries that do not provide instances, even though their
--   types already are instances of <a>Alternative</a> or
--   <a>Applicative</a> or <a>Monad</a>.
--   
--   This module provides unsafe methods to "promote" <a>Applicative</a>
--   instances to <a>Apply</a>, <a>Alternative</a> to <a>Plus</a>, etc.
--   
--   They are unsafe in the sense that if those types <i>already</i> have
--   those instances, this will cause overlapping instances errors or
--   problems with coherence. Because of this, you should always use these
--   with <i>specific</i> <tt>f</tt>s, and never in a polymorphic way over
--   <tt>f</tt>.
module Data.Functor.Combinator.Unsafe

-- | For any <tt><a>Alternative</a> f</tt>, produce a value that would
--   require <tt><a>Plus</a> f</tt>.
--   
--   Always use with concrete and specific <tt>f</tt> only, and never use
--   with any <tt>f</tt> that already has a <a>Plus</a> instance.
--   
--   See documentation for <a>upgradeC</a> for example usages.
--   
--   The <a>Proxy</a> argument allows you to specify which specific
--   <tt>f</tt> you want to enhance. You can pass in something like
--   <tt><a>Proxy</a> @MyFunctor</tt>.
unsafePlus :: forall f proxy r. Alternative f => proxy f -> (Plus f => r) -> r

-- | For any <tt><a>Applicative</a> f</tt>, produce a value that would
--   require <tt><a>Apply</a> f</tt>.
--   
--   Always use with concrete and specific <tt>f</tt> only, and never use
--   with any <tt>f</tt> that already has a <a>Apply</a> instance.
--   
--   See documentation for <a>upgradeC</a> for example usages.
--   
--   The <a>Proxy</a> argument allows you to specify which specific
--   <tt>f</tt> you want to enhance. You can pass in something like
--   <tt><a>Proxy</a> @MyFunctor</tt>.
unsafeApply :: forall f proxy r. Applicative f => proxy f -> (Apply f => r) -> r

-- | For any <tt><a>Monad</a> f</tt>, produce a value that would require
--   <tt><a>Bind</a> f</tt>.
--   
--   Always use with concrete and specific <tt>f</tt> only, and never use
--   with any <tt>f</tt> that already has a <a>Bind</a> instance.
--   
--   See documentation for <a>upgradeC</a> for example usages.
--   
--   The <a>Proxy</a> argument allows you to specify which specific
--   <tt>f</tt> you want to enhance. You can pass in something like
--   <tt><a>Proxy</a> @MyFunctor</tt>.
unsafeBind :: forall f proxy r. Monad f => proxy f -> (Bind f => r) -> r

-- | For any <tt><a>Applicative</a> f</tt>, produce a value that would
--   require <tt><a>Pointed</a> f</tt>.
--   
--   Always use with concrete and specific <tt>f</tt> only, and never use
--   with any <tt>f</tt> that already has a <a>Pointed</a> instance.
--   
--   See documentation for <a>upgradeC</a> for example usages.
--   
--   The <a>Proxy</a> argument allows you to specify which specific
--   <tt>f</tt> you want to enhance. You can pass in something like
--   <tt><a>Proxy</a> @MyFunctor</tt>.
unsafePointed :: forall f proxy r. Applicative f => proxy f -> (Pointed f => r) -> r

-- | For any <tt><a>Decidable</a> f</tt>, produce a value that would
--   require <tt><a>Conclude</a> f</tt>.
--   
--   Always use with concrete and specific <tt>f</tt> only, and never use
--   with any <tt>f</tt> that already has a <a>Conclude</a> instance.
--   
--   See documentation for <a>upgradeC</a> for example usages.
--   
--   The <a>Proxy</a> argument allows you to specify which specific
--   <tt>f</tt> you want to enhance. You can pass in something like
--   <tt><a>Proxy</a> @MyFunctor</tt>.
unsafeConclude :: forall f proxy r. Decidable f => proxy f -> (Conclude f => r) -> r

-- | For any <tt><a>Divisible</a> f</tt>, produce a value that would
--   require <tt><a>Divise</a> f</tt>.
--   
--   Always use with concrete and specific <tt>f</tt> only, and never use
--   with any <tt>f</tt> that already has a <a>Divise</a> instance.
--   
--   See documentation for <a>upgradeC</a> for example usages.
--   
--   The <a>Proxy</a> argument allows you to specify which specific
--   <tt>f</tt> you want to enhance. You can pass in something like
--   <tt><a>Proxy</a> @MyFunctor</tt>.
unsafeDivise :: forall f proxy r. Divisible f => proxy f -> (Divise f => r) -> r
instance GHC.Base.Applicative f => Data.Pointed.Pointed (Data.Functor.Combinator.Unsafe.PointMe f)


-- | This module provides functor combinators that are the fixed points of
--   applications of <a>:+:</a> and <a>These1</a>. They are useful for
--   their <a>Interpret</a> instances, along with their relationship to the
--   <a>Monoidal</a> instances of <a>:+:</a> and <a>These1</a>.
module Control.Applicative.Step

-- | An <tt>f a</tt>, along with a <a>Natural</a> index.
--   
--   <pre>
--   <a>Step</a> f a ~ (<a>Natural</a>, f a)
--   Step f   ~ ((,) Natural) <a>:.:</a> f       -- functor composition
--   </pre>
--   
--   It is the fixed point of infinite applications of <a>:+:</a> (functor
--   sums).
--   
--   Intuitively, in an infinite <tt>f :+: f :+: f :+: f ...</tt>, you have
--   exactly one <tt>f</tt> <i>somewhere</i>. A <tt><a>Step</a> f a</tt>
--   has that <tt>f</tt>, with a <a>Natural</a> giving you "where" the
--   <tt>f</tt> is in the long chain.
--   
--   Can be useful for using with the <a>Monoidal</a> instance of
--   <a>:+:</a>.
--   
--   <a>interpret</a>ing it requires no constraint on the target context.
--   
--   Note that this type and its instances equivalent to <tt><a>EnvT</a>
--   (<a>Sum</a> <a>Natural</a>)</tt>.
data Step f a
Step :: Natural -> f a -> Step f a
[stepPos] :: Step f a -> Natural
[stepVal] :: Step f a -> f a

-- | A non-empty map of <a>Natural</a> to <tt>f a</tt>. Basically, contains
--   multiple <tt>f a</tt>s, each at a given <a>Natural</a> index.
--   
--   <pre>
--   Steps f a ~ <a>Map</a> <a>Natural</a> (f a)
--   Steps f   ~ <a>Map</a> <a>Natural</a> <a>:.:</a> f       -- functor composition
--   </pre>
--   
--   It is the fixed point of applications of <a>TheseT</a>.
--   
--   You can think of this as an infinite sparse array of <tt>f a</tt>s.
--   
--   Intuitively, in an infinite <tt>f `TheseT` f `TheseT` f `TheseT` f
--   ...</tt>, each of those infinite positions may have an <tt>f</tt> in
--   them. However, because of the at-least-one nature of <a>TheseT</a>, we
--   know we have at least one f at one position <i>somewhere</i>.
--   
--   A <tt><a>Steps</a> f a</tt> has potentially many <tt>f</tt>s, each
--   stored at a different <a>Natural</a> position, with the guaruntee that
--   at least one <tt>f</tt> exists.
--   
--   Can be useful for using with the <a>Monoidal</a> instance of
--   <a>TheseT</a>.
--   
--   <a>interpret</a>ing it requires at least an <a>Alt</a> instance in the
--   target context, since we have to handle potentially more than one
--   <tt>f</tt>.
--   
--   This type is essentailly the same as <tt><a>NEMapF</a> (<a>Sum</a>
--   <a>Natural</a>)</tt> (except with a different <a>Semigroup</a>
--   instance).
newtype Steps f a
Steps :: NEMap Natural (f a) -> Steps f a
[getSteps] :: Steps f a -> NEMap Natural (f a)

-- | An <tt>f a</tt>, along with a <a>Bool</a> flag
--   
--   <pre>
--   <a>Flagged</a> f a ~ (<a>Bool</a>, f a)
--   Flagged f   ~ ((,) Bool) <a>:.:</a> f       -- functor composition
--   </pre>
--   
--   Creation with <a>inject</a> or <a>pure</a> uses <a>False</a> as the
--   boolean.
--   
--   You can think of it as an <tt>f a</tt> that is "flagged" with a
--   boolean value, and that value can indicuate whether or not it is
--   "pure" (made with <a>inject</a> or <a>pure</a>) as <a>False</a>, or
--   "impure" (made from some other source) as <a>True</a>. However,
--   <a>False</a> may be always created directly, of course, using the
--   constructor.
--   
--   You can think of it like a <a>Step</a> that is either 0 or 1, as well.
--   
--   <a>interpret</a>ing it requires no constraint on the target context.
--   
--   This type is equivalent (along with its instances) to:
--   
--   <ul>
--   <li><pre><a>HLift</a> <a>IdentityT</a></pre></li>
--   <li><pre><a>EnvT</a> <a>Any</a></pre></li>
--   </ul>
data Flagged f a
Flagged :: Bool -> f a -> Flagged f a
[flaggedFlag] :: Flagged f a -> Bool
[flaggedVal] :: Flagged f a -> f a

-- | Unshift an item into a <a>Step</a>. Because a <tt><a>Step</a> f</tt>
--   is <tt>f :+: f :+: f :+: f :+: ...</tt> forever, this basically conses
--   an additional possibility of <tt>f</tt> to the beginning of it all.
--   
--   You can think of it as reassociating
--   
--   <pre>
--   f :+: ( f :+: f :+: f :+: ...)
--   </pre>
--   
--   into
--   
--   <pre>
--   f :+: f :+: f :+: f :+: ...
--   </pre>
--   
--   <pre>
--   <a>stepUp</a> (<a>L1</a> "hello")
--   -- <a>Step</a> 0 "hello"
--   stepUp (<a>R1</a> (Step 1 "hello"))
--   -- Step 2 "hello"
--   </pre>
--   
--   Forms an isomorphism with <a>stepDown</a> (see <a>stepping</a>).
stepUp :: (f :+: Step f) ~> Step f

-- | Pop off the first item in a <a>Step</a>. Because a <tt><a>Step</a>
--   f</tt> is <tt>f :+: f :+: f :+: ...</tt> forever, this matches on the
--   first branch.
--   
--   You can think of it as reassociating
--   
--   <pre>
--   f :+: f :+: f :+: f :+: ...
--   </pre>
--   
--   into
--   
--   <pre>
--   f :+: ( f :+: f :+: f :+: ...)
--   </pre>
--   
--   <pre>
--   <a>stepDown</a> (<a>Step</a> 2 "hello")
--   -- <a>R1</a> (Step 1 "hello")
--   stepDown (Step 0 "hello")
--   -- <a>L1</a> "hello"
--   </pre>
--   
--   Forms an isomorphism with <a>stepUp</a> (see <a>stepping</a>).
stepDown :: Step f ~> (f :+: Step f)

-- | "Uncons and cons" an <tt>f</tt> branch before a <a>Step</a>. This is
--   basically a witness that <a>stepDown</a> and <a>stepUp</a> form an
--   isomorphism.
stepping :: Step f <~> (f :+: Step f)

-- | Unshift an item into a <a>Steps</a>. Because a <tt><a>Steps</a> f</tt>
--   is <tt>f <a>These1</a> f <a>These1</a> f <a>These1</a> f <a>These1</a>
--   ...</tt> forever, this basically conses an additional possibility of
--   <tt>f</tt> to the beginning of it all.
--   
--   You can think of it as reassociating
--   
--   <pre>
--   f <a>These1</a> ( f <a>These1</a> f <a>These1</a> f <a>These1</a> ...)
--   </pre>
--   
--   into
--   
--   <pre>
--   f <a>These1</a> f <a>These1</a> f <a>These1</a> f <a>These1</a> ...
--   </pre>
--   
--   If you give:
--   
--   <ul>
--   <li><a>This1</a>, then it returns a singleton <a>Steps</a> with one
--   item at index 0</li>
--   <li><a>That1</a>, then it shifts every item in the given <a>Steps</a>
--   up one index.</li>
--   <li><a>These1</a>, then it shifts every item in the given <a>Steps</a>
--   up one index, and adds the given item (the <tt>f</tt>) at index
--   zero.</li>
--   </ul>
--   
--   Forms an isomorphism with <a>stepDown</a> (see <a>stepping</a>).
stepsUp :: These1 f (Steps f) ~> Steps f

-- | Pop off the first item in a <a>Steps</a>. Because a <tt><a>Steps</a>
--   f</tt> is <tt>f <a>These1</a> f <a>These1</a> f <a>These1</a> ...</tt>
--   forever, this matches on the first branch.
--   
--   You can think of it as reassociating
--   
--   <pre>
--   f <a>These1</a> f <a>These1</a> f <a>These1</a> f <a>These1</a> ...
--   </pre>
--   
--   into
--   
--   <pre>
--   f <a>These1</a> ( f <a>These1</a> f <a>These1</a> f <a>These1</a> ...)
--   </pre>
--   
--   It returns:
--   
--   <ul>
--   <li><a>This1</a> if the first item is the <i>only</i> item in the
--   <a>Steps</a></li>
--   <li><a>That1</a> if the first item in the <a>Steps</a> is empty, but
--   there are more items left. The extra items are all shfited down.</li>
--   <li><a>These1</a> if the first item in the <a>Steps</a> exists, and
--   there are also more items left. The extra items are all shifted
--   down.</li>
--   </ul>
--   
--   Forms an isomorphism with <a>stepsUp</a> (see <a>steppings</a>).
stepsDown :: Steps f ~> These1 f (Steps f)

-- | "Uncons and cons" an <tt>f</tt> branch before a <a>Steps</a>. This is
--   basically a witness that <a>stepsDown</a> and <a>stepsUp</a> form an
--   isomorphism.
steppings :: Steps f <~> These1 f (Steps f)

-- | We have a natural transformation between <a>V1</a> and any other
--   functor <tt>f</tt> with no constraints.
absurd1 :: V1 a -> f a

-- | <tt><a>Void2</a> a b</tt> is uninhabited for all <tt>a</tt> and
--   <tt>b</tt>.
data Void2 a b

-- | If you treat a <tt><a>Void2</a> f a</tt> as a functor combinator, then
--   <a>absurd2</a> lets you convert from a <tt><a>Void2</a> f a</tt> into
--   a <tt>t f a</tt> for any functor combinator <tt>t</tt>.
absurd2 :: Void2 f a -> t f a

-- | <tt><a>Void3</a> a b</tt> is uninhabited for all <tt>a</tt> and
--   <tt>b</tt>.
data Void3 a b c

-- | If you treat a <tt><a>Void3</a> f a</tt> as a binary functor
--   combinator, then <a>absurd3</a> lets you convert from a
--   <tt><a>Void3</a> f a</tt> into a <tt>t f a</tt> for any functor
--   combinator <tt>t</tt>.
absurd3 :: Void3 f g a -> t f g a
instance forall k1 k2 (a :: k1) (b :: k2). Data.Functor.Classes.Ord1 (Control.Applicative.Step.Void3 a b)
instance forall k1 k2 k3 (a :: k1) (b :: k2) (c :: k3). GHC.Base.Semigroup (Control.Applicative.Step.Void3 a b c)
instance forall k1 k2 (a :: k1) (b :: k2). Data.Functor.Alt.Alt (Control.Applicative.Step.Void3 a b)
instance forall k1 k2 (a :: k1) (b :: k2). Data.Functor.Bind.Class.Bind (Control.Applicative.Step.Void3 a b)
instance forall k1 k2 (a :: k1) (b :: k2). Data.Functor.Bind.Class.Apply (Control.Applicative.Step.Void3 a b)
instance forall k1 k2 (a :: k1) (b :: k2). Data.Functor.Contravariant.Contravariant (Control.Applicative.Step.Void3 a b)
instance forall k1 k2 (a :: k1) (b :: k2). Data.Functor.Invariant.Invariant (Control.Applicative.Step.Void3 a b)
instance forall k1 k2 (a :: k1) (b :: k2). Data.Functor.Classes.Eq1 (Control.Applicative.Step.Void3 a b)
instance forall k1 k2 (a :: k1) (b :: k2). Data.Functor.Classes.Read1 (Control.Applicative.Step.Void3 a b)
instance forall k1 k2 (a :: k1) (b :: k2). Data.Functor.Classes.Show1 (Control.Applicative.Step.Void3 a b)
instance forall k1 (a :: k1) k2 (b :: k2) k3 (c :: k3). (Data.Typeable.Internal.Typeable a, Data.Typeable.Internal.Typeable b, Data.Typeable.Internal.Typeable c, Data.Typeable.Internal.Typeable k1, Data.Typeable.Internal.Typeable k2, Data.Typeable.Internal.Typeable k3) => Data.Data.Data (Control.Applicative.Step.Void3 a b c)
instance forall k1 (a :: k1) k2 (b :: k2) k3 (c :: k3). GHC.Generics.Generic (Control.Applicative.Step.Void3 a b c)
instance forall k1 (a :: k1) k2 (b :: k2). Data.Traversable.Traversable (Control.Applicative.Step.Void3 a b)
instance forall k1 (a :: k1) k2 (b :: k2). Data.Foldable.Foldable (Control.Applicative.Step.Void3 a b)
instance forall k1 (a :: k1) k2 (b :: k2). GHC.Base.Functor (Control.Applicative.Step.Void3 a b)
instance forall k1 (a :: k1) k2 (b :: k2) k3 (c :: k3). GHC.Classes.Ord (Control.Applicative.Step.Void3 a b c)
instance forall k1 (a :: k1) k2 (b :: k2) k3 (c :: k3). GHC.Classes.Eq (Control.Applicative.Step.Void3 a b c)
instance forall k1 (a :: k1) k2 (b :: k2) k3 (c :: k3). GHC.Read.Read (Control.Applicative.Step.Void3 a b c)
instance forall k1 (a :: k1) k2 (b :: k2) k3 (c :: k3). GHC.Show.Show (Control.Applicative.Step.Void3 a b c)
instance forall k (a :: k). Data.Functor.Classes.Ord1 (Control.Applicative.Step.Void2 a)
instance forall k1 k2 (a :: k1) (b :: k2). GHC.Base.Semigroup (Control.Applicative.Step.Void2 a b)
instance forall k (a :: k). Data.Functor.Alt.Alt (Control.Applicative.Step.Void2 a)
instance forall k (a :: k). Data.Functor.Bind.Class.Bind (Control.Applicative.Step.Void2 a)
instance forall k (a :: k). Data.Functor.Bind.Class.Apply (Control.Applicative.Step.Void2 a)
instance forall k (a :: k). Data.Functor.Contravariant.Contravariant (Control.Applicative.Step.Void2 a)
instance forall k (a :: k). Data.Functor.Invariant.Invariant (Control.Applicative.Step.Void2 a)
instance forall k (a :: k). Data.Functor.Classes.Eq1 (Control.Applicative.Step.Void2 a)
instance forall k (a :: k). Data.Functor.Classes.Read1 (Control.Applicative.Step.Void2 a)
instance forall k (a :: k). Data.Functor.Classes.Show1 (Control.Applicative.Step.Void2 a)
instance forall k1 (a :: k1) k2 (b :: k2). (Data.Typeable.Internal.Typeable a, Data.Typeable.Internal.Typeable b, Data.Typeable.Internal.Typeable k1, Data.Typeable.Internal.Typeable k2) => Data.Data.Data (Control.Applicative.Step.Void2 a b)
instance forall k1 (a :: k1) k2 (b :: k2). GHC.Generics.Generic (Control.Applicative.Step.Void2 a b)
instance forall k (a :: k). Data.Traversable.Traversable (Control.Applicative.Step.Void2 a)
instance forall k (a :: k). Data.Foldable.Foldable (Control.Applicative.Step.Void2 a)
instance forall k (a :: k). GHC.Base.Functor (Control.Applicative.Step.Void2 a)
instance forall k1 (a :: k1) k2 (b :: k2). GHC.Classes.Ord (Control.Applicative.Step.Void2 a b)
instance forall k1 (a :: k1) k2 (b :: k2). GHC.Classes.Eq (Control.Applicative.Step.Void2 a b)
instance forall k1 (a :: k1) k2 (b :: k2). GHC.Read.Read (Control.Applicative.Step.Void2 a b)
instance forall k1 (a :: k1) k2 (b :: k2). GHC.Show.Show (Control.Applicative.Step.Void2 a b)
instance Data.Functor.Classes.Ord1 f => Data.Functor.Classes.Ord1 (Control.Applicative.Step.Flagged f)
instance GHC.Base.Applicative f => GHC.Base.Applicative (Control.Applicative.Step.Flagged f)
instance Data.Pointed.Pointed f => Data.Pointed.Pointed (Control.Applicative.Step.Flagged f)
instance Data.Semigroup.Foldable.Class.Foldable1 f => Data.Semigroup.Foldable.Class.Foldable1 (Control.Applicative.Step.Flagged f)
instance Data.Semigroup.Traversable.Class.Traversable1 f => Data.Semigroup.Traversable.Class.Traversable1 (Control.Applicative.Step.Flagged f)
instance Data.Functor.Classes.Eq1 f => Data.Functor.Classes.Eq1 (Control.Applicative.Step.Flagged f)
instance Data.Functor.Classes.Read1 f => Data.Functor.Classes.Read1 (Control.Applicative.Step.Flagged f)
instance Data.Functor.Classes.Show1 f => Data.Functor.Classes.Show1 (Control.Applicative.Step.Flagged f)
instance forall k (f :: k -> *) (a :: k). (Data.Typeable.Internal.Typeable a, Data.Typeable.Internal.Typeable f, Data.Typeable.Internal.Typeable k, Data.Data.Data (f a)) => Data.Data.Data (Control.Applicative.Step.Flagged f a)
instance forall k (f :: k -> *) (a :: k). GHC.Generics.Generic (Control.Applicative.Step.Flagged f a)
instance Data.Traversable.Traversable f => Data.Traversable.Traversable (Control.Applicative.Step.Flagged f)
instance Data.Foldable.Foldable f => Data.Foldable.Foldable (Control.Applicative.Step.Flagged f)
instance GHC.Base.Functor f => GHC.Base.Functor (Control.Applicative.Step.Flagged f)
instance forall k (f :: k -> *) (a :: k). GHC.Classes.Ord (f a) => GHC.Classes.Ord (Control.Applicative.Step.Flagged f a)
instance forall k (f :: k -> *) (a :: k). GHC.Classes.Eq (f a) => GHC.Classes.Eq (Control.Applicative.Step.Flagged f a)
instance forall k (f :: k -> *) (a :: k). GHC.Read.Read (f a) => GHC.Read.Read (Control.Applicative.Step.Flagged f a)
instance forall k (f :: k -> *) (a :: k). GHC.Show.Show (f a) => GHC.Show.Show (Control.Applicative.Step.Flagged f a)
instance Data.Functor.Classes.Ord1 f => Data.Functor.Classes.Ord1 (Control.Applicative.Step.Steps f)
instance Data.Semigroup.Foldable.Class.Foldable1 f => Data.Semigroup.Foldable.Class.Foldable1 (Control.Applicative.Step.Steps f)
instance Data.Semigroup.Traversable.Class.Traversable1 f => Data.Semigroup.Traversable.Class.Traversable1 (Control.Applicative.Step.Steps f)
instance forall k (f :: k -> *) (a :: k). GHC.Base.Semigroup (Control.Applicative.Step.Steps f a)
instance Data.Functor.Contravariant.Contravariant f => Data.Functor.Contravariant.Contravariant (Control.Applicative.Step.Steps f)
instance Data.Functor.Invariant.Invariant f => Data.Functor.Invariant.Invariant (Control.Applicative.Step.Steps f)
instance GHC.Base.Functor f => Data.Functor.Alt.Alt (Control.Applicative.Step.Steps f)
instance Data.Pointed.Pointed f => Data.Pointed.Pointed (Control.Applicative.Step.Steps f)
instance Data.Functor.Classes.Eq1 f => Data.Functor.Classes.Eq1 (Control.Applicative.Step.Steps f)
instance Data.Functor.Classes.Read1 f => Data.Functor.Classes.Read1 (Control.Applicative.Step.Steps f)
instance Data.Functor.Classes.Show1 f => Data.Functor.Classes.Show1 (Control.Applicative.Step.Steps f)
instance forall k (f :: k -> *) (a :: k). (Data.Typeable.Internal.Typeable a, Data.Typeable.Internal.Typeable f, Data.Typeable.Internal.Typeable k, Data.Data.Data (f a)) => Data.Data.Data (Control.Applicative.Step.Steps f a)
instance forall k (f :: k -> *) (a :: k). GHC.Generics.Generic (Control.Applicative.Step.Steps f a)
instance Data.Traversable.Traversable f => Data.Traversable.Traversable (Control.Applicative.Step.Steps f)
instance Data.Foldable.Foldable f => Data.Foldable.Foldable (Control.Applicative.Step.Steps f)
instance GHC.Base.Functor f => GHC.Base.Functor (Control.Applicative.Step.Steps f)
instance forall k (f :: k -> *) (a :: k). GHC.Classes.Ord (f a) => GHC.Classes.Ord (Control.Applicative.Step.Steps f a)
instance forall k (f :: k -> *) (a :: k). GHC.Classes.Eq (f a) => GHC.Classes.Eq (Control.Applicative.Step.Steps f a)
instance forall k (f :: k -> *) (a :: k). GHC.Read.Read (f a) => GHC.Read.Read (Control.Applicative.Step.Steps f a)
instance forall k (f :: k -> *) (a :: k). GHC.Show.Show (f a) => GHC.Show.Show (Control.Applicative.Step.Steps f a)
instance Data.Functor.Classes.Ord1 f => Data.Functor.Classes.Ord1 (Control.Applicative.Step.Step f)
instance Data.Functor.Bind.Class.Apply f => Data.Functor.Bind.Class.Apply (Control.Applicative.Step.Step f)
instance GHC.Base.Applicative f => GHC.Base.Applicative (Control.Applicative.Step.Step f)
instance Data.Functor.Contravariant.Contravariant f => Data.Functor.Contravariant.Contravariant (Control.Applicative.Step.Step f)
instance Data.Functor.Contravariant.Divisible.Divisible f => Data.Functor.Contravariant.Divisible.Divisible (Control.Applicative.Step.Step f)
instance Data.Functor.Contravariant.Divise.Divise f => Data.Functor.Contravariant.Divise.Divise (Control.Applicative.Step.Step f)
instance Data.Functor.Contravariant.Decide.Decide f => Data.Functor.Contravariant.Decide.Decide (Control.Applicative.Step.Step f)
instance Data.Functor.Contravariant.Conclude.Conclude f => Data.Functor.Contravariant.Conclude.Conclude (Control.Applicative.Step.Step f)
instance Data.Functor.Contravariant.Divisible.Decidable f => Data.Functor.Contravariant.Divisible.Decidable (Control.Applicative.Step.Step f)
instance Data.Functor.Invariant.Invariant f => Data.Functor.Invariant.Invariant (Control.Applicative.Step.Step f)
instance Data.Pointed.Pointed f => Data.Pointed.Pointed (Control.Applicative.Step.Step f)
instance Data.Semigroup.Foldable.Class.Foldable1 f => Data.Semigroup.Foldable.Class.Foldable1 (Control.Applicative.Step.Step f)
instance Data.Semigroup.Traversable.Class.Traversable1 f => Data.Semigroup.Traversable.Class.Traversable1 (Control.Applicative.Step.Step f)
instance Data.Functor.Classes.Eq1 f => Data.Functor.Classes.Eq1 (Control.Applicative.Step.Step f)
instance Data.Functor.Classes.Read1 f => Data.Functor.Classes.Read1 (Control.Applicative.Step.Step f)
instance Data.Functor.Classes.Show1 f => Data.Functor.Classes.Show1 (Control.Applicative.Step.Step f)
instance forall k (f :: k -> *) (a :: k). (Data.Typeable.Internal.Typeable a, Data.Typeable.Internal.Typeable f, Data.Typeable.Internal.Typeable k, Data.Data.Data (f a)) => Data.Data.Data (Control.Applicative.Step.Step f a)
instance forall k (f :: k -> *) (a :: k). GHC.Generics.Generic (Control.Applicative.Step.Step f a)
instance Data.Traversable.Traversable f => Data.Traversable.Traversable (Control.Applicative.Step.Step f)
instance Data.Foldable.Foldable f => Data.Foldable.Foldable (Control.Applicative.Step.Step f)
instance GHC.Base.Functor f => GHC.Base.Functor (Control.Applicative.Step.Step f)
instance forall k (f :: k -> *) (a :: k). GHC.Classes.Ord (f a) => GHC.Classes.Ord (Control.Applicative.Step.Step f a)
instance forall k (f :: k -> *) (a :: k). GHC.Classes.Eq (f a) => GHC.Classes.Eq (Control.Applicative.Step.Step f a)
instance forall k (f :: k -> *) (a :: k). GHC.Read.Read (f a) => GHC.Read.Read (Control.Applicative.Step.Step f a)
instance forall k (f :: k -> *) (a :: k). GHC.Show.Show (f a) => GHC.Show.Show (Control.Applicative.Step.Step f a)


-- | This module provides functor combinators that are wrappers over lists
--   or maybes of <tt>f a</tt>s, especially for their <a>Interpret</a>
--   instances.
--   
--   Each one transforms a functor into some product of itself. For
--   example, <tt><a>NonEmptyF</a> f</tt> represents <tt>f <a>:*:</a>
--   f</tt>, or <tt>f :*: f :*: f</tt>, or <tt>f :*: f :*: f :*: f</tt>,
--   etc.
module Control.Applicative.ListF

-- | A list of <tt>f a</tt>s. Can be used to describe a product of many
--   different values of type <tt>f a</tt>.
--   
--   This is the Free <a>Plus</a>.
--   
--   Incidentally, if used with a <a>Contravariant</a> <tt>f</tt>, this is
--   instead the free <a>Divisible</a>.
newtype ListF f a
ListF :: [f a] -> ListF f a
[runListF] :: ListF f a -> [f a]

-- | Map a function over the inside of a <a>ListF</a>.
mapListF :: ([f a] -> [g b]) -> ListF f a -> ListF g b

-- | A non-empty list of <tt>f a</tt>s. Can be used to describe a product
--   between many different possible values of type <tt>f a</tt>.
--   
--   Essentially:
--   
--   <pre>
--   <a>NonEmptyF</a> f
--       ~ f                          -- one f
--     <a>:+:</a> (f <a>:*:</a> f)              -- two f's
--     :+: (f :*: f :*: f)            -- three f's
--     :+: (f :*: f :*: f :*: f)      -- four f's
--     :+: ...                        -- etc.
--   </pre>
--   
--   This is the Free <a>Plus</a> on any <a>Functor</a> <tt>f</tt>.
--   
--   Incidentally, if used with a <a>Contravariant</a> <tt>f</tt>, this is
--   instead the free <a>Divise</a>.
newtype NonEmptyF f a
NonEmptyF :: NonEmpty (f a) -> NonEmptyF f a
[runNonEmptyF] :: NonEmptyF f a -> NonEmpty (f a)

-- | Treat a <tt><a>NonEmptyF</a> f</tt> as a product between an <tt>f</tt>
--   and a <tt><a>ListF</a> f</tt>.
--   
--   <a>nonEmptyProd</a> is the record accessor.
pattern ProdNonEmpty :: (f :*: ListF f) a -> NonEmptyF f a

-- | Map a function over the inside of a <a>NonEmptyF</a>.
mapNonEmptyF :: (NonEmpty (f a) -> NonEmpty (g b)) -> NonEmptyF f a -> NonEmptyF g b

-- | Convert a <a>NonEmptyF</a> into a <a>ListF</a> with at least one item.
toListF :: NonEmptyF f ~> ListF f

-- | Convert a <a>ListF</a> either a <a>NonEmptyF</a>, or a <a>Proxy</a> in
--   the case that the list was empty.
fromListF :: ListF f ~> (Proxy :+: NonEmptyF f)

-- | A maybe <tt>f a</tt>.
--   
--   Can be useful for describing a "an <tt>f a</tt> that may or may not be
--   there".
--   
--   This is the free structure for a "fail"-like typeclass that would only
--   have <tt>zero :: f a</tt>.
newtype MaybeF f a
MaybeF :: Maybe (f a) -> MaybeF f a
[runMaybeF] :: MaybeF f a -> Maybe (f a)

-- | Map a function over the inside of a <a>MaybeF</a>.
mapMaybeF :: (Maybe (f a) -> Maybe (g b)) -> MaybeF f a -> MaybeF g b

-- | Convert a <a>ListF</a> into a <a>MaybeF</a> containing the first <tt>f
--   a</tt> in the list, if it exists.
listToMaybeF :: ListF f ~> MaybeF f

-- | Convert a <a>MaybeF</a> into a <a>ListF</a> with zero or one items.
maybeToListF :: MaybeF f ~> ListF f

-- | A map of <tt>f a</tt>s, indexed by keys of type <tt>k</tt>. It can be
--   useful for represeting a product of many different values of type
--   <tt>f a</tt>, each "at" a different <tt>k</tt> location.
--   
--   Can be considered a combination of <a>EnvT</a> and <a>ListF</a>, in a
--   way --- a <tt><a>MapF</a> k f a</tt> is like a <tt><a>ListF</a>
--   (<a>EnvT</a> k f) a</tt> with unique (and ordered) keys.
--   
--   One use case might be to extend a schema with many "options", indexed
--   by some string.
--   
--   For example, if you had a command line argument parser for a single
--   command
--   
--   <pre>
--   data Command a
--   </pre>
--   
--   Then you can represent a command line argument parser for
--   <i>multiple</i> named commands with
--   
--   <pre>
--   type Commands = <a>MapF</a> <a>String</a> Command
--   </pre>
--   
--   See <a>NEMapF</a> for a non-empty variant, if you want to enforce that
--   your bag has at least one <tt>f a</tt>.
newtype MapF k f a
MapF :: Map k (f a) -> MapF k f a
[runMapF] :: MapF k f a -> Map k (f a)

-- | A non-empty map of <tt>f a</tt>s, indexed by keys of type <tt>k</tt>.
--   It can be useful for represeting a product of many different values of
--   type <tt>f a</tt>, each "at" a different <tt>k</tt> location, where
--   you need to have at least one <tt>f a</tt> at all times.
--   
--   Can be considered a combination of <a>EnvT</a> and <a>NonEmptyF</a>,
--   in a way --- an <tt><a>NEMapF</a> k f a</tt> is like a
--   <tt><a>NonEmptyF</a> (<a>EnvT</a> k f) a</tt> with unique (and
--   ordered) keys.
--   
--   See <a>MapF</a> for some use cases.
newtype NEMapF k f a
NEMapF :: NEMap k (f a) -> NEMapF k f a
[runNEMapF] :: NEMapF k f a -> NEMap k (f a)
instance (GHC.Classes.Ord k, Data.Functor.Classes.Ord1 f) => Data.Functor.Classes.Ord1 (Control.Applicative.ListF.NEMapF k f)
instance (GHC.Classes.Ord k, GHC.Read.Read k, Data.Functor.Classes.Read1 f) => Data.Functor.Classes.Read1 (Control.Applicative.ListF.NEMapF k f)
instance Data.Semigroup.Foldable.Class.Foldable1 f => Data.Semigroup.Foldable.Class.Foldable1 (Control.Applicative.ListF.NEMapF k f)
instance Data.Semigroup.Traversable.Class.Traversable1 f => Data.Semigroup.Traversable.Class.Traversable1 (Control.Applicative.ListF.NEMapF k f)
instance (GHC.Classes.Ord k, Data.Functor.Alt.Alt f) => GHC.Base.Semigroup (Control.Applicative.ListF.NEMapF k f a)
instance (GHC.Base.Functor f, GHC.Classes.Ord k) => Data.Functor.Alt.Alt (Control.Applicative.ListF.NEMapF k f)
instance (GHC.Base.Monoid k, Data.Pointed.Pointed f) => Data.Pointed.Pointed (Control.Applicative.ListF.NEMapF k f)
instance (GHC.Classes.Eq k, Data.Functor.Classes.Eq1 f) => Data.Functor.Classes.Eq1 (Control.Applicative.ListF.NEMapF k f)
instance (GHC.Show.Show k, Data.Functor.Classes.Show1 f) => Data.Functor.Classes.Show1 (Control.Applicative.ListF.NEMapF k f)
instance forall k1 k2 (f :: k2 -> *) (a :: k2). (Data.Typeable.Internal.Typeable a, Data.Typeable.Internal.Typeable f, Data.Typeable.Internal.Typeable k2, Data.Data.Data k1, Data.Data.Data (f a), GHC.Classes.Ord k1) => Data.Data.Data (Control.Applicative.ListF.NEMapF k1 f a)
instance forall k1 k2 (f :: k2 -> *) (a :: k2). GHC.Generics.Generic (Control.Applicative.ListF.NEMapF k1 f a)
instance Data.Traversable.Traversable f => Data.Traversable.Traversable (Control.Applicative.ListF.NEMapF k f)
instance Data.Foldable.Foldable f => Data.Foldable.Foldable (Control.Applicative.ListF.NEMapF k f)
instance GHC.Base.Functor f => GHC.Base.Functor (Control.Applicative.ListF.NEMapF k f)
instance forall k1 k2 (f :: k2 -> *) (a :: k2). (GHC.Classes.Ord k1, GHC.Classes.Ord (f a)) => GHC.Classes.Ord (Control.Applicative.ListF.NEMapF k1 f a)
instance forall k1 k2 (f :: k2 -> *) (a :: k2). (GHC.Classes.Eq k1, GHC.Classes.Eq (f a)) => GHC.Classes.Eq (Control.Applicative.ListF.NEMapF k1 f a)
instance forall k1 k2 (f :: k2 -> *) (a :: k2). (GHC.Classes.Ord k1, GHC.Read.Read k1, GHC.Read.Read (f a)) => GHC.Read.Read (Control.Applicative.ListF.NEMapF k1 f a)
instance forall k1 k2 (f :: k2 -> *) (a :: k2). (GHC.Show.Show k1, GHC.Show.Show (f a)) => GHC.Show.Show (Control.Applicative.ListF.NEMapF k1 f a)
instance (GHC.Classes.Ord k, Data.Functor.Classes.Ord1 f) => Data.Functor.Classes.Ord1 (Control.Applicative.ListF.MapF k f)
instance (GHC.Classes.Ord k, GHC.Read.Read k, Data.Functor.Classes.Read1 f) => Data.Functor.Classes.Read1 (Control.Applicative.ListF.MapF k f)
instance (GHC.Classes.Ord k, Data.Functor.Alt.Alt f) => GHC.Base.Semigroup (Control.Applicative.ListF.MapF k f a)
instance (GHC.Classes.Ord k, Data.Functor.Alt.Alt f) => GHC.Base.Monoid (Control.Applicative.ListF.MapF k f a)
instance (GHC.Base.Functor f, GHC.Classes.Ord k) => Data.Functor.Alt.Alt (Control.Applicative.ListF.MapF k f)
instance (GHC.Base.Functor f, GHC.Classes.Ord k) => Data.Functor.Plus.Plus (Control.Applicative.ListF.MapF k f)
instance (GHC.Base.Monoid k, Data.Pointed.Pointed f) => Data.Pointed.Pointed (Control.Applicative.ListF.MapF k f)
instance (GHC.Classes.Eq k, Data.Functor.Classes.Eq1 f) => Data.Functor.Classes.Eq1 (Control.Applicative.ListF.MapF k f)
instance (GHC.Show.Show k, Data.Functor.Classes.Show1 f) => Data.Functor.Classes.Show1 (Control.Applicative.ListF.MapF k f)
instance forall k1 k2 (f :: k2 -> *) (a :: k2). (Data.Typeable.Internal.Typeable a, Data.Typeable.Internal.Typeable f, Data.Typeable.Internal.Typeable k2, Data.Data.Data k1, Data.Data.Data (f a), GHC.Classes.Ord k1) => Data.Data.Data (Control.Applicative.ListF.MapF k1 f a)
instance forall k1 k2 (f :: k2 -> *) (a :: k2). GHC.Generics.Generic (Control.Applicative.ListF.MapF k1 f a)
instance Data.Traversable.Traversable f => Data.Traversable.Traversable (Control.Applicative.ListF.MapF k f)
instance Data.Foldable.Foldable f => Data.Foldable.Foldable (Control.Applicative.ListF.MapF k f)
instance GHC.Base.Functor f => GHC.Base.Functor (Control.Applicative.ListF.MapF k f)
instance forall k1 k2 (f :: k2 -> *) (a :: k2). (GHC.Classes.Ord k1, GHC.Classes.Ord (f a)) => GHC.Classes.Ord (Control.Applicative.ListF.MapF k1 f a)
instance forall k1 k2 (f :: k2 -> *) (a :: k2). (GHC.Classes.Eq k1, GHC.Classes.Eq (f a)) => GHC.Classes.Eq (Control.Applicative.ListF.MapF k1 f a)
instance forall k1 k2 (f :: k2 -> *) (a :: k2). (GHC.Classes.Ord k1, GHC.Read.Read k1, GHC.Read.Read (f a)) => GHC.Read.Read (Control.Applicative.ListF.MapF k1 f a)
instance forall k1 k2 (f :: k2 -> *) (a :: k2). (GHC.Show.Show k1, GHC.Show.Show (f a)) => GHC.Show.Show (Control.Applicative.ListF.MapF k1 f a)
instance Data.Functor.Classes.Ord1 f => Data.Functor.Classes.Ord1 (Control.Applicative.ListF.MaybeF f)
instance GHC.Base.Applicative f => GHC.Base.Applicative (Control.Applicative.ListF.MaybeF f)
instance GHC.Base.Functor f => Data.Functor.Alt.Alt (Control.Applicative.ListF.MaybeF f)
instance GHC.Base.Functor f => Data.Functor.Plus.Plus (Control.Applicative.ListF.MaybeF f)
instance GHC.Base.Applicative f => GHC.Base.Alternative (Control.Applicative.ListF.MaybeF f)
instance Data.Functor.Contravariant.Contravariant f => Data.Functor.Contravariant.Contravariant (Control.Applicative.ListF.MaybeF f)
instance Data.Functor.Invariant.Invariant f => Data.Functor.Invariant.Invariant (Control.Applicative.ListF.MaybeF f)
instance Data.Functor.Contravariant.Contravariant f => Data.Functor.Contravariant.Divise.Divise (Control.Applicative.ListF.MaybeF f)
instance Data.Functor.Contravariant.Contravariant f => Data.Functor.Contravariant.Divisible.Divisible (Control.Applicative.ListF.MaybeF f)
instance Data.Functor.Contravariant.Decide.Decide f => Data.Functor.Contravariant.Decide.Decide (Control.Applicative.ListF.MaybeF f)
instance Data.Functor.Contravariant.Conclude.Conclude f => Data.Functor.Contravariant.Conclude.Conclude (Control.Applicative.ListF.MaybeF f)
instance Data.Functor.Contravariant.Divisible.Decidable f => Data.Functor.Contravariant.Divisible.Decidable (Control.Applicative.ListF.MaybeF f)
instance forall k (f :: k -> *) (a :: k). GHC.Base.Semigroup (Control.Applicative.ListF.MaybeF f a)
instance forall k (f :: k -> *) (a :: k). GHC.Base.Monoid (Control.Applicative.ListF.MaybeF f a)
instance Data.Pointed.Pointed f => Data.Pointed.Pointed (Control.Applicative.ListF.MaybeF f)
instance Data.Functor.Classes.Eq1 f => Data.Functor.Classes.Eq1 (Control.Applicative.ListF.MaybeF f)
instance Data.Functor.Classes.Read1 f => Data.Functor.Classes.Read1 (Control.Applicative.ListF.MaybeF f)
instance Data.Functor.Classes.Show1 f => Data.Functor.Classes.Show1 (Control.Applicative.ListF.MaybeF f)
instance forall k (f :: k -> *) (a :: k). (Data.Typeable.Internal.Typeable a, Data.Typeable.Internal.Typeable f, Data.Typeable.Internal.Typeable k, Data.Data.Data (f a)) => Data.Data.Data (Control.Applicative.ListF.MaybeF f a)
instance forall k (f :: k -> *) (a :: k). GHC.Generics.Generic (Control.Applicative.ListF.MaybeF f a)
instance Data.Traversable.Traversable f => Data.Traversable.Traversable (Control.Applicative.ListF.MaybeF f)
instance Data.Foldable.Foldable f => Data.Foldable.Foldable (Control.Applicative.ListF.MaybeF f)
instance GHC.Base.Functor f => GHC.Base.Functor (Control.Applicative.ListF.MaybeF f)
instance forall k (f :: k -> *) (a :: k). GHC.Classes.Ord (f a) => GHC.Classes.Ord (Control.Applicative.ListF.MaybeF f a)
instance forall k (f :: k -> *) (a :: k). GHC.Classes.Eq (f a) => GHC.Classes.Eq (Control.Applicative.ListF.MaybeF f a)
instance forall k (f :: k -> *) (a :: k). GHC.Read.Read (f a) => GHC.Read.Read (Control.Applicative.ListF.MaybeF f a)
instance forall k (f :: k -> *) (a :: k). GHC.Show.Show (f a) => GHC.Show.Show (Control.Applicative.ListF.MaybeF f a)
instance Data.Functor.Classes.Ord1 f => Data.Functor.Classes.Ord1 (Control.Applicative.ListF.NonEmptyF f)
instance GHC.Base.Applicative f => GHC.Base.Applicative (Control.Applicative.ListF.NonEmptyF f)
instance GHC.Base.Functor f => Data.Functor.Alt.Alt (Control.Applicative.ListF.NonEmptyF f)
instance Data.Functor.Contravariant.Contravariant f => Data.Functor.Contravariant.Contravariant (Control.Applicative.ListF.NonEmptyF f)
instance Data.Functor.Invariant.Invariant f => Data.Functor.Invariant.Invariant (Control.Applicative.ListF.NonEmptyF f)
instance Data.Functor.Contravariant.Contravariant f => Data.Functor.Contravariant.Divise.Divise (Control.Applicative.ListF.NonEmptyF f)
instance Data.Functor.Contravariant.Decide.Decide f => Data.Functor.Contravariant.Decide.Decide (Control.Applicative.ListF.NonEmptyF f)
instance forall k (f :: k -> *) (a :: k). GHC.Base.Semigroup (Control.Applicative.ListF.NonEmptyF f a)
instance Data.Pointed.Pointed f => Data.Pointed.Pointed (Control.Applicative.ListF.NonEmptyF f)
instance Data.Functor.Classes.Eq1 f => Data.Functor.Classes.Eq1 (Control.Applicative.ListF.NonEmptyF f)
instance Data.Functor.Classes.Read1 f => Data.Functor.Classes.Read1 (Control.Applicative.ListF.NonEmptyF f)
instance Data.Functor.Classes.Show1 f => Data.Functor.Classes.Show1 (Control.Applicative.ListF.NonEmptyF f)
instance forall k (f :: k -> *) (a :: k). (Data.Typeable.Internal.Typeable a, Data.Typeable.Internal.Typeable f, Data.Typeable.Internal.Typeable k, Data.Data.Data (f a)) => Data.Data.Data (Control.Applicative.ListF.NonEmptyF f a)
instance forall k (f :: k -> *) (a :: k). GHC.Generics.Generic (Control.Applicative.ListF.NonEmptyF f a)
instance Data.Traversable.Traversable f => Data.Traversable.Traversable (Control.Applicative.ListF.NonEmptyF f)
instance Data.Foldable.Foldable f => Data.Foldable.Foldable (Control.Applicative.ListF.NonEmptyF f)
instance GHC.Base.Functor f => GHC.Base.Functor (Control.Applicative.ListF.NonEmptyF f)
instance forall k (f :: k -> *) (a :: k). GHC.Classes.Ord (f a) => GHC.Classes.Ord (Control.Applicative.ListF.NonEmptyF f a)
instance forall k (f :: k -> *) (a :: k). GHC.Classes.Eq (f a) => GHC.Classes.Eq (Control.Applicative.ListF.NonEmptyF f a)
instance forall k (f :: k -> *) (a :: k). GHC.Read.Read (f a) => GHC.Read.Read (Control.Applicative.ListF.NonEmptyF f a)
instance forall k (f :: k -> *) (a :: k). GHC.Show.Show (f a) => GHC.Show.Show (Control.Applicative.ListF.NonEmptyF f a)
instance Data.Functor.Classes.Ord1 f => Data.Functor.Classes.Ord1 (Control.Applicative.ListF.ListF f)
instance Data.Functor.Bind.Class.Apply f => Data.Functor.Bind.Class.Apply (Control.Applicative.ListF.ListF f)
instance GHC.Base.Applicative f => GHC.Base.Applicative (Control.Applicative.ListF.ListF f)
instance GHC.Base.Functor f => Data.Functor.Alt.Alt (Control.Applicative.ListF.ListF f)
instance GHC.Base.Functor f => Data.Functor.Plus.Plus (Control.Applicative.ListF.ListF f)
instance GHC.Base.Applicative f => GHC.Base.Alternative (Control.Applicative.ListF.ListF f)
instance forall k (f :: k -> *) (a :: k). GHC.Base.Semigroup (Control.Applicative.ListF.ListF f a)
instance forall k (f :: k -> *) (a :: k). GHC.Base.Monoid (Control.Applicative.ListF.ListF f a)
instance Data.Pointed.Pointed f => Data.Pointed.Pointed (Control.Applicative.ListF.ListF f)
instance Data.Functor.Contravariant.Contravariant f => Data.Functor.Contravariant.Contravariant (Control.Applicative.ListF.ListF f)
instance Data.Functor.Invariant.Invariant f => Data.Functor.Invariant.Invariant (Control.Applicative.ListF.ListF f)
instance Data.Functor.Contravariant.Contravariant f => Data.Functor.Contravariant.Divise.Divise (Control.Applicative.ListF.ListF f)
instance Data.Functor.Contravariant.Contravariant f => Data.Functor.Contravariant.Divisible.Divisible (Control.Applicative.ListF.ListF f)
instance Data.Functor.Contravariant.Decide.Decide f => Data.Functor.Contravariant.Decide.Decide (Control.Applicative.ListF.ListF f)
instance Data.Functor.Contravariant.Conclude.Conclude f => Data.Functor.Contravariant.Conclude.Conclude (Control.Applicative.ListF.ListF f)
instance Data.Functor.Contravariant.Divisible.Decidable f => Data.Functor.Contravariant.Divisible.Decidable (Control.Applicative.ListF.ListF f)
instance Data.Functor.Classes.Eq1 f => Data.Functor.Classes.Eq1 (Control.Applicative.ListF.ListF f)
instance Data.Functor.Classes.Read1 f => Data.Functor.Classes.Read1 (Control.Applicative.ListF.ListF f)
instance Data.Functor.Classes.Show1 f => Data.Functor.Classes.Show1 (Control.Applicative.ListF.ListF f)
instance forall k (f :: k -> *) (a :: k). (Data.Typeable.Internal.Typeable a, Data.Typeable.Internal.Typeable f, Data.Typeable.Internal.Typeable k, Data.Data.Data (f a)) => Data.Data.Data (Control.Applicative.ListF.ListF f a)
instance forall k (f :: k -> *) (a :: k). GHC.Generics.Generic (Control.Applicative.ListF.ListF f a)
instance Data.Traversable.Traversable f => Data.Traversable.Traversable (Control.Applicative.ListF.ListF f)
instance Data.Foldable.Foldable f => Data.Foldable.Foldable (Control.Applicative.ListF.ListF f)
instance GHC.Base.Functor f => GHC.Base.Functor (Control.Applicative.ListF.ListF f)
instance forall k (f :: k -> *) (a :: k). GHC.Classes.Ord (f a) => GHC.Classes.Ord (Control.Applicative.ListF.ListF f a)
instance forall k (f :: k -> *) (a :: k). GHC.Classes.Eq (f a) => GHC.Classes.Eq (Control.Applicative.ListF.ListF f a)
instance forall k (f :: k -> *) (a :: k). GHC.Read.Read (f a) => GHC.Read.Read (Control.Applicative.ListF.ListF f a)
instance forall k (f :: k -> *) (a :: k). GHC.Show.Show (f a) => GHC.Show.Show (Control.Applicative.ListF.ListF f a)


-- | Provides <a>Night</a>, a form of the day convolution that is
--   contravariant and splits on <a>Either</a>.
module Data.Functor.Contravariant.Night

-- | A pairing of contravariant functors to create a new contravariant
--   functor that represents the "choice" between the two.
--   
--   A <tt><a>Night</a> f g a</tt> is a contravariant "consumer" of
--   <tt>a</tt>, and it does this by either feeding the <tt>a</tt> to
--   <tt>f</tt>, or feeding the <tt>a</tt> to <tt>g</tt>. Which one it
--   gives it to happens at runtime depending <i>what</i> <tt>a</tt> is
--   actually given.
--   
--   For example, if we have <tt>x :: f a</tt> (a consumer of <tt>a</tt>s)
--   and <tt>y :: g b</tt> (a consumer of <tt>b</tt>s), then
--   <tt><a>night</a> x y :: <a>Night</a> f g (<a>Either</a> a b)</tt>.
--   This is a consumer of <tt><a>Either</a> a b</tt>s, and it consumes
--   <a>Left</a> branches by feeding it to <tt>x</tt>, and <a>Right</a>
--   branches by feeding it to <tt>y</tt>.
--   
--   Mathematically, this is a contravariant day convolution, except with a
--   different choice of bifunctor (<a>Either</a>) than the typical one we
--   talk about in Haskell (which uses <tt>(,)</tt>). Therefore, it is an
--   alternative to the typical <a>Day</a> convolution --- hence, the name
--   <a>Night</a>.
data Night :: (Type -> Type) -> (Type -> Type) -> (Type -> Type)
[Night] :: f b -> g c -> (a -> Either b c) -> Night f g a

-- | Inject into a <a>Night</a>.
--   
--   <tt><a>night</a> x y</tt> is a consumer of <tt><a>Either</a> a b</tt>;
--   <a>Left</a> will be passed to <tt>x</tt>, and <a>Right</a> will be
--   passed to <tt>y</tt>.
night :: f a -> g b -> Night f g (Either a b)

-- | Interpret out of a <a>Night</a> into any instance of <a>Decide</a> by
--   providing two interpreting functions.
runNight :: Decide h => (f ~> h) -> (g ~> h) -> Night f g ~> h

-- | Squash the two items in a <a>Night</a> using their natural
--   <a>Decide</a> instances.
necide :: Decide f => Night f f ~> f

-- | <a>Night</a> is associative.
assoc :: Night f (Night g h) ~> Night (Night f g) h

-- | <a>Night</a> is associative.
unassoc :: Night (Night f g) h ~> Night f (Night g h)

-- | The two sides of a <a>Night</a> can be swapped.
swapped :: Night f g ~> Night g f

-- | Hoist a function over the left side of a <a>Night</a>.
trans1 :: (f ~> h) -> Night f g ~> Night h g

-- | Hoist a function over the right side of a <a>Night</a>.
trans2 :: (g ~> h) -> Night f g ~> Night f h

-- | The left identity of <a>Night</a> is <a>Not</a>; this is one side of
--   that isomorphism.
intro1 :: g ~> Night Not g

-- | The right identity of <a>Night</a> is <a>Not</a>; this is one side of
--   that isomorphism.
intro2 :: f ~> Night f Not

-- | The left identity of <a>Night</a> is <a>Not</a>; this is one side of
--   that isomorphism.
elim1 :: Contravariant g => Night Not g ~> g

-- | The right identity of <a>Night</a> is <a>Not</a>; this is one side of
--   that isomorphism.
elim2 :: Contravariant f => Night f Not ~> f

-- | A value of type <tt><a>Not</a> a</tt> is "proof" that <tt>a</tt> is
--   uninhabited.
newtype Not a
Not :: (a -> Void) -> Not a
[refute] :: Not a -> a -> Void

-- | A useful shortcut for a common usage: <a>Void</a> is always not so.
refuted :: Not Void
instance Data.Functor.Contravariant.Contravariant Data.Functor.Contravariant.Night.Not
instance Data.Functor.Invariant.Invariant Data.Functor.Contravariant.Night.Not
instance GHC.Base.Semigroup (Data.Functor.Contravariant.Night.Not a)
instance Data.Functor.Contravariant.Contravariant (Data.Functor.Contravariant.Night.Night f g)
instance Data.Functor.Invariant.Invariant (Data.Functor.Contravariant.Night.Night f g)


-- | Contains the classes <a>Inply</a> and <a>Inplicative</a>, the
--   invariant counterparts to <tt>Apply</tt><i><tt>Divise</tt> and
--   <a>Applicative</a></i><tt>Divisible</tt>.
module Data.Functor.Invariant.Inplicative

-- | The invariant counterpart of <tt>Apply</tt> and <tt>Divise</tt>.
--   
--   Conceptually you can think of <tt>Apply</tt> as, given a way to
--   "combine" <tt>a</tt> and <tt>b</tt> to <tt>c</tt>, lets you merge
--   <tt>f a</tt> (producer of <tt>a</tt>) and <tt>f b</tt> (producer of
--   <tt>b</tt>) into a <tt>f c</tt> (producer of <tt>c</tt>).
--   <tt>Divise</tt> can be thought of as, given a way to "split" a
--   <tt>c</tt> into an <tt>a</tt> and a <tt>b</tt>, lets you merge <tt>f
--   a</tt> (consumer of <tt>a</tt>) and <tt>f b</tt> (consumder of
--   <tt>b</tt>) into a <tt>f c</tt> (consumer of <tt>c</tt>).
--   
--   <a>Inply</a>, for <a>gather</a>, requires both a combining function
--   and a splitting function in order to merge <tt>f b</tt> (producer and
--   consumer of <tt>b</tt>) and <tt>f c</tt> (producer and consumer of
--   <tt>c</tt>) into a <tt>f a</tt>. You can think of it as, for the <tt>f
--   a</tt>, it "splits" the a into <tt>b</tt> and <tt>c</tt> with the
--   <tt>a -&gt; (b, c)</tt>, feeds it to the original <tt>f b</tt> and
--   <tt>f c</tt>, and then re-combines the output back into a <tt>a</tt>
--   with the <tt>b -&gt; c -&gt; a</tt>.
class Invariant f => Inply f

-- | Like <tt>&lt;.&gt;</tt>, <a>&lt;*&gt;</a>, <tt>divise</tt>, or
--   <tt>divide</tt>, but requires both a splitting and a recombining
--   function. <tt>&lt;.&gt;</tt> and <a>&lt;*&gt;</a> require only a
--   combining function, and <tt>divise</tt> and <tt>divide</tt> require
--   only a splitting function.
--   
--   It is used to merge <tt>f b</tt> (producer and consumer of <tt>b</tt>)
--   and <tt>f c</tt> (producer and consumer of <tt>c</tt>) into a <tt>f
--   a</tt>. You can think of it as, for the <tt>f a</tt>, it "splits" the
--   a into <tt>b</tt> and <tt>c</tt> with the <tt>a -&gt; (b, c)</tt>,
--   feeds it to the original <tt>f b</tt> and <tt>f c</tt>, and then
--   re-combines the output back into a <tt>a</tt> with the <tt>b -&gt; c
--   -&gt; a</tt>.
--   
--   An important property is that it will always use <tt>both</tt> of the
--   ccomponents given in order to fulfil its job. If you gather an <tt>f
--   a</tt> and an <tt>f b</tt> into an <tt>f c</tt>, in order to
--   consume/produdce the <tt>c</tt>, it will always use both the <tt>f
--   a</tt> or the <tt>f b</tt> -- exactly one of them.
gather :: Inply f => (b -> c -> a) -> (a -> (b, c)) -> f b -> f c -> f a

-- | A simplified version of <a>gather</a> that combines into a tuple. You
--   can then use <a>invmap</a> to reshape it into the proper shape.
gathered :: Inply f => f a -> f b -> f (a, b)

-- | The invariant counterpart of <a>Applicative</a> and
--   <tt>Divisible</tt>.
--   
--   The main important action is described in <a>Inply</a>, but this adds
--   <a>knot</a>, which is the counterpart to <a>pure</a> and
--   <tt>conquer</tt>. It's the identity to <a>gather</a>; if combine two
--   <tt>f a</tt>s with <a>gather</a>, and one of them is <a>knot</a>, it
--   will leave the structure unchanged.
--   
--   Conceptually, if you think of <a>gather</a> as "splitting and
--   re-combining" along multiple forks, then <a>knot</a> introduces a fork
--   that is never taken.
class Inply f => Inplicative f
knot :: Inplicative f => a -> f a

-- | Interpret out of a contravariant <a>Day</a> into any instance of
--   <a>Inply</a> by providing two interpreting functions.
--   
--   This should go in <a>Data.Functor.Invariant.Day</a>, but that module
--   is in a different package.
runDay :: Inply h => (f ~> h) -> (g ~> h) -> Day f g ~> h

-- | Squash the two items in a <a>Day</a> using their natural <a>Inply</a>
--   instances.
--   
--   This should go in <a>Data.Functor.Invariant.Day</a>, but that module
--   is in a different package.
dather :: Inply f => Day f f ~> f

-- | Convenient wrapper to build up an <a>Inplicative</a> instance by
--   providing each component of it. This makes it much easier to build up
--   longer chains because you would only need to write the
--   splitting/joining functions in one place.
--   
--   For example, if you had a data type
--   
--   <pre>
--   data MyType = MT Int Bool String
--   </pre>
--   
--   and an invariant functor and <a>Inplicative</a> instance <tt>Prim</tt>
--   (representing, say, a bidirectional parser, where <tt>Prim Int</tt> is
--   a bidirectional parser for an <a>Int</a><tt>), then you could assemble
--   a bidirectional parser for a </tt>MyType@ using:
--   
--   <pre>
--   invmap ((MyType x y z) -&gt; I x :* I y :* I z :* Nil)
--          ((I x :* I y :* I z :* Nil) -&gt; MyType x y z) $
--     concatInplicative $ intPrim
--                      :* boolPrim
--                      :* stringPrim
--                      :* Nil
--   </pre>
--   
--   Some notes on usefulness depending on how many components you have:
--   
--   <ul>
--   <li>If you have 0 components, use <a>knot</a> directly.</li>
--   <li>If you have 1 component, use <tt>inject</tt> directly.</li>
--   <li>If you have 2 components, use <a>gather</a> directly.</li>
--   <li>If you have 3 or more components, these combinators may be useful;
--   otherwise you'd need to manually peel off tuples one-by-one.</li>
--   </ul>
concatInplicative :: Inplicative f => NP f as -> f (NP I as)

-- | A version of <a>concatInplicative</a> for non-empty <a>NP</a>, but
--   only requiring an <a>Inply</a> instance.
concatInply :: Inply f => NP f (a : as) -> f (NP I (a : as))

-- | A version of <a>concatInplicative</a> using <a>XRec</a> from
--   <i>vinyl</i> instead of <a>NP</a> from <i>sop-core</i>. This can be
--   more convenient because it doesn't require manual unwrapping/wrapping
--   of components.
concatInplicativeRec :: Inplicative f => Rec f as -> f (XRec Identity as)

-- | A version of <a>concatInply</a> using <a>XRec</a> from <i>vinyl</i>
--   instead of <a>NP</a> from <i>sop-core</i>. This can be more convenient
--   because it doesn't require manual unwrapping/wrapping of components.
concatInplyRec :: Inply f => Rec f (a : as) -> f (XRec Identity (a : as))


-- | Contains the classes <a>Inalt</a> and <a>Inplus</a>, the invariant
--   counterparts to <tt>Alt</tt><i><tt>Plus</tt> and
--   <tt>Decide</tt></i><tt>Conclude</tt> and
--   <tt>Alternative</tt>/<tt>Decidable</tt>.
module Data.Functor.Invariant.Internative

-- | The invariant counterpart of <tt>Alt</tt> and <tt>Decide</tt>.
--   
--   Conceptually you can think of <tt>Alt</tt> as, given a way to "inject"
--   <tt>a</tt> and <tt>b</tt> as <tt>c</tt>, lets you merge <tt>f a</tt>
--   (producer of <tt>a</tt>) and <tt>f b</tt> (producer of <tt>b</tt>)
--   into a <tt>f c</tt> (producer of <tt>c</tt>), in an "either-or"
--   fashion. <tt>Decide</tt> can be thought of as, given a way to
--   "discriminate" a <tt>c</tt> as either a <tt>a</tt> or a <tt>b</tt>,
--   lets you merge <tt>f a</tt> (consumer of <tt>a</tt>) and <tt>f b</tt>
--   (consumder of <tt>b</tt>) into a <tt>f c</tt> (consumer of <tt>c</tt>)
--   in an "either-or" forking fashion (split the <tt>c</tt> into
--   <tt>a</tt> or <tt>b</tt>, and use the appropriate handler).
--   
--   <a>Inalt</a>, for <a>swerve</a>, requires both an injecting function
--   and a choosing function in order to merge <tt>f b</tt> (producer and
--   consumer of <tt>b</tt>) and <tt>f c</tt> (producer and consumer of
--   <tt>c</tt>) into a <tt>f a</tt> in an either-or manner. You can think
--   of it as, for the <tt>f a</tt>, it "chooses" if the <tt>a</tt> is
--   actually a <tt>b</tt> or a <tt>c</tt> with the <tt>a -&gt;
--   <a>Either</a> b c</tt>, feeds it to either the original <tt>f b</tt>
--   or the original <tt>f c</tt>, and then re-injects the output back into
--   a <tt>a</tt> with the <tt>b -&gt; a</tt> or the <tt>c -&gt; a</tt>.
class Invariant f => Inalt f

-- | Like <tt>&lt;!&gt;</tt>, <tt>decide</tt>, or <tt>choose</tt>, but
--   requires both an injecting and a choosing function.
--   
--   It is used to merge <tt>f b</tt> (producer and consumer of <tt>b</tt>)
--   and <tt>f c</tt> (producer and consumer of <tt>c</tt>) into a <tt>f
--   a</tt> in an either-or manner. You can think of it as, for the <tt>f
--   a</tt>, it "chooses" if the <tt>a</tt> is actually a <tt>b</tt> or a
--   <tt>c</tt> with the <tt>a -&gt; <a>Either</a> b c</tt>, feeds it to
--   either the original <tt>f b</tt> or the original <tt>f c</tt>, and
--   then re-injects the output back into a <tt>a</tt> with the <tt>b -&gt;
--   a</tt> or the <tt>c -&gt; a</tt>.
--   
--   An important property is that it will only ever use exactly
--   <tt>one</tt> of the options given in order to fulfil its job. If you
--   swerve an <tt>f a</tt> and an <tt>f b</tt> into an <tt>f c</tt>, in
--   order to consume/produdce the <tt>c</tt>, it will only use either the
--   <tt>f a</tt> or the <tt>f b</tt> -- exactly one of them.
swerve :: Inalt f => (b -> a) -> (c -> a) -> (a -> Either b c) -> f b -> f c -> f a

-- | A simplified version of <tt>swerive</tt> that splits to and from an
--   <a>Either</a>. You can then use <a>invmap</a> to reshape it into the
--   proper shape.
swerved :: Inalt f => f a -> f b -> f (Either a b)

-- | The invariant counterpart of <tt>Alt</tt> and <tt>Conclude</tt>.
--   
--   The main important action is described in <a>Inalt</a>, but this adds
--   <a>reject</a>, which is the counterpart to <tt>empty</tt> and
--   <tt>conclude</tt> and <tt>conquer</tt>. It's the identity to
--   <a>swerve</a>; if combine two <tt>f a</tt>s with <a>swerve</a>, and
--   one of them is <a>reject</a>, then that banch will never be taken.
--   
--   Conceptually, if you think of <a>swerve</a> as "choosing one path and
--   re-injecting back", then <a>reject</a> introduces a branch that is
--   impossible to take.
class Inalt f => Inplus f
reject :: Inplus f => (a -> Void) -> f a

-- | The invariant counterpart to <tt>Alternative</tt> and
--   <tt>Decidable</tt>: represents a combination of both
--   <a>Applicative</a> and <tt>Alt</tt>, or <tt>Divisible</tt> and
--   <tt>Conclude</tt>. There are laws?
class (Inplus f, Inplicative f) => Internative f

-- | Convenient wrapper to build up an <a>Inplus</a> instance on by
--   providing each branch of it. This makes it much easier to build up
--   longer chains because you would only need to write the
--   splitting/joining functions in one place.
--   
--   For example, if you had a data type
--   
--   <pre>
--   data MyType = MTI Int | MTB Bool | MTS String
--   </pre>
--   
--   and an invariant functor and <a>Inplus</a> instance <tt>Prim</tt>
--   (representing, say, a bidirectional parser, where <tt>Prim Int</tt> is
--   a bidirectional parser for an <a>Int</a><tt>), then you could assemble
--   a bidirectional parser for a </tt>MyType@ using:
--   
--   <pre>
--   invmap (case MTI x -&gt; Z (I x); MTB y -&gt; S (Z (I y)); MTS z -&gt; S (S (Z (I z))))
--          (case Z (I x) -&gt; MTI x; S (Z (I y)) -&gt; MTB y; S (S (Z (I z))) -&gt; MTS z) $
--     concatInplus $ intPrim
--                 :* boolPrim
--                 :* stringPrim
--                 :* Nil
--   </pre>
--   
--   Some notes on usefulness depending on how many components you have:
--   
--   <ul>
--   <li>If you have 0 components, use <a>reject</a> directly.</li>
--   <li>If you have 1 component, use <tt>inject</tt> directly.</li>
--   <li>If you have 2 components, use <a>swerve</a> directly.</li>
--   <li>If you have 3 or more components, these combinators may be useful;
--   otherwise you'd need to manually peel off eithers one-by-one.</li>
--   </ul>
concatInplus :: Inplus f => NP f as -> f (NS I as)

-- | A version of <a>concatInplus</a> for non-empty <a>NP</a>, but only
--   requiring an <a>Inalt</a> instance.
concatInalt :: Inalt f => NP f (a : as) -> f (NS I (a : as))


-- | Provides an <a>Invariant</a> version of a Day convolution over
--   <a>Either</a>.
module Data.Functor.Invariant.Night

-- | A pairing of invariant functors to create a new invariant functor that
--   represents the "choice" between the two.
--   
--   A <tt><a>Night</a> f g a</tt> is a invariant "consumer" and "producer"
--   of <tt>a</tt>, and it does this by either feeding the <tt>a</tt> to
--   <tt>f</tt>, or feeding the <tt>a</tt> to <tt>g</tt>, and then
--   collecting the result from whichever one it was fed to. Which decision
--   of which path to takes happens at runtime depending <i>what</i>
--   <tt>a</tt> is actually given.
--   
--   For example, if we have <tt>x :: f a</tt> and <tt>y :: g b</tt>, then
--   <tt><a>night</a> x y :: <a>Night</a> f g (<a>Either</a> a b)</tt>.
--   This is a consumer/producer of <tt><a>Either</a> a b</tt>s, and it
--   consumes <a>Left</a> branches by feeding it to <tt>x</tt>, and
--   <a>Right</a> branches by feeding it to <tt>y</tt>. It then passes back
--   the single result from the one of the two that was chosen.
--   
--   Mathematically, this is a invariant day convolution, except with a
--   different choice of bifunctor (<a>Either</a>) than the typical one we
--   talk about in Haskell (which uses <tt>(,)</tt>). Therefore, it is an
--   alternative to the typical <a>Day</a> convolution --- hence, the name
--   <a>Night</a>.
data Night :: (Type -> Type) -> (Type -> Type) -> (Type -> Type)
[Night] :: f b -> g c -> (b -> a) -> (c -> a) -> (a -> Either b c) -> Night f g a

-- | A value of type <tt><a>Not</a> a</tt> is "proof" that <tt>a</tt> is
--   uninhabited.
newtype Not a
Not :: (a -> Void) -> Not a
[refute] :: Not a -> a -> Void

-- | A useful shortcut for a common usage: <a>Void</a> is always not so.
refuted :: Not Void

-- | Pair two invariant actions together into a <a>Night</a>; assigns the
--   first one to <a>Left</a> inputs and outputs and the second one to
--   <a>Right</a> inputs and outputs.
night :: f a -> g b -> Night f g (Either a b)

-- | Interpret out of a <a>Night</a> into any instance of <a>Inalt</a> by
--   providing two interpreting functions.
runNight :: Inalt h => (f ~> h) -> (g ~> h) -> Night f g ~> h

-- | Squash the two items in a <a>Night</a> using their natural
--   <a>Inalt</a> instances.
nerve :: Inalt f => Night f f ~> f

-- | Interpret the covariant part of a <a>Night</a> into a target context
--   <tt>h</tt>, as long as the context is an instance of <a>Alt</a>. The
--   <a>Alt</a> is used to combine results back together, chosen by
--   <a>&lt;!&gt;</a>.
runNightAlt :: forall f g h. Alt h => (f ~> h) -> (g ~> h) -> Night f g ~> h

-- | Interpret the contravariant part of a <a>Night</a> into a target
--   context <tt>h</tt>, as long as the context is an instance of
--   <a>Decide</a>. The <a>Decide</a> is used to pick which part to feed
--   the input to.
runNightDecide :: forall f g h. Decide h => (f ~> h) -> (g ~> h) -> Night f g ~> h

-- | Convert an invariant <a>Night</a> into the covariant version, dropping
--   the contravariant part.
--   
--   Note that there is no covariant version of <a>Night</a> defined in any
--   common library, so we use an equivalent type (if <tt>f</tt> and
--   <tt>g</tt> are <a>Functor</a>s) <tt>f <a>:*:</a> g</tt>.
toCoNight :: (Functor f, Functor g) => Night f g ~> (f :*: g)

-- | Convert an invariant <a>Night</a> into the covariant version, dropping
--   the contravariant part.
--   
--   This version does not require a <a>Functor</a> constraint because it
--   converts to the coyoneda-wrapped product, which is more accurately the
--   covariant <a>Night</a> convolution.
toCoNight_ :: Night f g ~> (Coyoneda f :*: Coyoneda g)

-- | Convert an invariant <a>Night</a> into the contravariant version,
--   dropping the covariant part.
toContraNight :: Night f g ~> Night f g

-- | <a>Night</a> is associative.
assoc :: Night f (Night g h) ~> Night (Night f g) h

-- | <a>Night</a> is associative.
unassoc :: Night (Night f g) h ~> Night f (Night g h)

-- | The left identity of <a>Night</a> is <a>Not</a>; this is one side of
--   that isomorphism.
intro1 :: g ~> Night Not g

-- | The right identity of <a>Night</a> is <a>Not</a>; this is one side of
--   that isomorphism.
intro2 :: f ~> Night f Not

-- | The left identity of <a>Night</a> is <a>Not</a>; this is one side of
--   that isomorphism.
elim1 :: Invariant g => Night Not g ~> g

-- | The right identity of <a>Night</a> is <a>Not</a>; this is one side of
--   that isomorphism.
elim2 :: Invariant f => Night f Not ~> f

-- | The two sides of a <a>Night</a> can be swapped.
swapped :: Night f g ~> Night g f

-- | Hoist a function over the left side of a <a>Night</a>.
trans1 :: (f ~> h) -> Night f g ~> Night h g

-- | Hoist a function over the right side of a <a>Night</a>.
trans2 :: (g ~> h) -> Night f g ~> Night f h
instance Data.Functor.Invariant.Invariant (Data.Functor.Invariant.Night.Night f g)


-- | This module provides abstractions for working with unary functor
--   combinators.
--   
--   Principally, it defines the <a>HFunctor</a> itself, as well as some
--   classes that expose extra functionality that some <a>HFunctor</a>s
--   have (<a>Inject</a> and <a>HBind</a>).
--   
--   See <a>Data.HFunctor.Interpret</a> for tools to use <a>HFunctor</a>s
--   as functor combinators that can represent interpretable schemas, and
--   <a>Data.HBifunctor</a> for an abstraction over <i>binary</i> functor
--   combinators.
module Data.HFunctor

-- | An <a>HFunctor</a> can be thought of a unary "functor transformer" ---
--   a basic functor combinator. It takes a functor as input and returns a
--   functor as output.
--   
--   It "enhances" a functor with extra structure (sort of like how a monad
--   transformer enhances a <a>Monad</a> with extra structure).
--   
--   As a uniform inteface, we can "swap the underlying functor" (also
--   sometimes called "hoisting"). This is what <a>hmap</a> does: it lets
--   us swap out the <tt>f</tt> in a <tt>t f</tt> for a <tt>t g</tt>.
--   
--   For example, the free monad <a>Free</a> takes a <a>Functor</a> and
--   returns a new <a>Functor</a>. In the process, it provides a monadic
--   structure over <tt>f</tt>. <a>hmap</a> lets us turn a <tt><a>Free</a>
--   f</tt> into a <tt><a>Free</a> g</tt>: a monad built over <tt>f</tt>
--   can be turned into a monad built over <tt>g</tt>.
--   
--   For the ability to move in and out of the enhanced functor, see
--   <a>Inject</a> and <a>Interpret</a>.
--   
--   This class is similar to <a>MFunctor</a> from
--   <a>Control.Monad.Morph</a>, but instances must work without a
--   <a>Monad</a> constraint.
--   
--   This class is also found in the <i>hschema</i> library with the same
--   name.
class HFunctor t

-- | If we can turn an <tt>f</tt> into a <tt>g</tt>, then we can turn a
--   <tt>t f</tt> into a <tt>t g</tt>.
--   
--   It must be the case that
--   
--   <pre>
--   <a>hmap</a> <a>id</a> == id
--   </pre>
--   
--   Essentially, <tt>t f</tt> adds some "extra structure" to <tt>f</tt>.
--   <a>hmap</a> must swap out the functor, <i>without affecting the added
--   structure</i>.
--   
--   For example, <tt><a>ListF</a> f a</tt> is essentially a list of <tt>f
--   a</tt>s. If we <a>hmap</a> to swap out the <tt>f a</tt>s for <tt>g
--   a</tt>s, then we must ensure that the "added structure" (here, the
--   number of items in the list, and the ordering of those items) remains
--   the same. So, <a>hmap</a> must preserve the number of items in the
--   list, and must maintain the ordering.
--   
--   The law <tt><a>hmap</a> <a>id</a> == id</tt> is a way of formalizing
--   this property.
hmap :: HFunctor t => (f ~> g) -> t f ~> t g

-- | Lift an isomorphism over an <a>HFunctor</a>.
--   
--   Essentailly, if <tt>f</tt> and <tt>g</tt> are isomorphic, then so are
--   <tt>t f</tt> and <tt>t g</tt>.
overHFunctor :: HFunctor t => (f <~> g) -> t f <~> t g

-- | A typeclass for <a>HFunctor</a>s where you can "inject" an <tt>f
--   a</tt> into a <tt>t f a</tt>:
--   
--   <pre>
--   <a>inject</a> :: f a -&gt; t f a
--   </pre>
--   
--   If you think of <tt>t f a</tt> as an "enhanced <tt>f</tt>", then
--   <a>inject</a> allows you to use an <tt>f</tt> as its enhanced form.
--   
--   With the exception of directly pattern matching on the result,
--   <a>inject</a> itself is not too useful in the general case without
--   <a>Interpret</a> to allow us to interpret or retrieve back the
--   <tt>f</tt>.
class HFunctor t => Inject t

-- | Lift from <tt>f</tt> into the enhanced <tt>t f</tt> structure.
--   Analogous to <a>lift</a> from <a>MonadTrans</a>.
--   
--   Note that this lets us "lift" a <tt>f a</tt>; if you want to lift an
--   <tt>a</tt> with <tt>a -&gt; t f a</tt>, check if <tt>t f</tt> is an
--   instance of <a>Applicative</a> or <a>Pointed</a>.
inject :: Inject t => f ~> t f

-- | <a>HBind</a> is effectively a "higher-order <a>Monad</a>", in the
--   sense that <a>HFunctor</a> is a "higher-order <a>Functor</a>".
--   
--   It can be considered a typeclass for <a>HFunctor</a>s that you can
--   bind continuations to, nautral<i>universal over all
--   <tt>f</tt></i>functors. They work "for all functors" you lift, without
--   requiring any constraints.
--   
--   It is very similar to <a>Interpret</a>, except <a>Interpret</a> has
--   the ability to constrain the contexts to some typeclass.
--   
--   The main law is that binding <a>inject</a> should leave things
--   unchanged:
--   
--   <pre>
--   <a>hbind</a> <a>inject</a> == <a>id</a>
--   </pre>
--   
--   But <a>hbind</a> should also be associatiatve, in a way that makes
--   
--   <pre>
--   <a>hjoin</a> . hjoin
--      = hjoin . <a>hmap</a> hjoin
--   </pre>
--   
--   That is, squishing a <tt>t (t (t f)) a</tt> into a <tt>t f a</tt> can
--   be done "inside" first, then "outside", or "outside" first, then
--   "inside".
--   
--   Note that these laws are different from the <a>Interpret</a> laws, so
--   we often have instances where <a>hbind</a> and <a>interpret</a>
--   (though they both may typecheck) produce different behavior.
--   
--   This class is similar to <a>MMonad</a> from
--   <a>Control.Monad.Morph</a>, but instances must work without a
--   <a>Monad</a> constraint.
class Inject t => HBind t

-- | Bind a continuation to a <tt>t f</tt> into some context <tt>g</tt>.
hbind :: HBind t => (f ~> t g) -> t f ~> t g

-- | Collapse a nested <tt>t (t f)</tt> into a single <tt>t f</tt>.
hjoin :: HBind t => t (t f) ~> t f

-- | The functor combinator that forgets all structure in the input.
--   Ignores the input structure and stores no information.
--   
--   Acts like the "zero" with respect to functor combinator composition.
--   
--   <pre>
--   <a>ComposeT</a> ProxyF f      ~ ProxyF
--   <a>ComposeT</a> f      ProxyF ~ ProxyF
--   </pre>
--   
--   It can be <a>inject</a>ed into (losing all information), but it is
--   impossible to ever <a>retract</a> or <a>interpret</a> it.
--   
--   This is essentially <tt><a>ConstF</a> ()</tt>.
data ProxyF f a
ProxyF :: ProxyF f a

-- | Functor combinator that forgets all structure on the input, and
--   instead stores a value of type <tt>e</tt>.
--   
--   Like <a>ProxyF</a>, acts like a "zero" with functor combinator
--   composition.
--   
--   It can be <a>inject</a>ed into (losing all information), but it is
--   impossible to ever <a>retract</a> or <a>interpret</a> it.
data ConstF e f a
ConstF :: e -> ConstF e f a
[getConstF] :: ConstF e f a -> e

-- | An "<a>HFunctor</a> combinator" that enhances an <a>HFunctor</a> with
--   the ability to hold a single <tt>f a</tt>. This is the higher-order
--   analogue of <a>Lift</a>.
--   
--   You can think of it as a free <a>Inject</a> for any <tt>f</tt>.
--   
--   Note that <tt><a>HLift</a> <a>IdentityT</a></tt> is equivalent to
--   <tt><a>EnvT</a> <a>Any</a></tt>.
data HLift t f a
HPure :: f a -> HLift t f a
HOther :: t f a -> HLift t f a

-- | A higher-level <a>retract</a> to get a <tt>t f a</tt> back out of an
--   <tt><a>HLift</a> t f a</tt>, provided <tt>t</tt> is an instance of
--   <a>Inject</a>.
--   
--   This witnesses the fact that <a>HLift</a> is the "Free <a>Inject</a>".
retractHLift :: Inject t => HLift t f a -> t f a

-- | An "<a>HFunctor</a> combinator" that turns an <a>HFunctor</a> into
--   potentially infinite nestings of that <a>HFunctor</a>.
--   
--   An <tt><a>HFree</a> t f a</tt> is either <tt>f a</tt>, <tt>t f a</tt>,
--   <tt>t (t f) a</tt>, <tt>t (t (t f)) a</tt>, etc.
--   
--   This effectively turns <tt>t</tt> into a tree with <tt>t</tt>
--   branches.
--   
--   One particularly useful usage is with <a>MapF</a>. For example if you
--   had a data type representing a command line command parser:
--   
--   <pre>
--   data Command a
--   </pre>
--   
--   You could represent "many possible named commands" using
--   
--   <pre>
--   type Commands = <a>MapF</a> <a>String</a> Command
--   </pre>
--   
--   And you can represent multiple <i>nested</i> named commands using:
--   
--   <pre>
--   type NestedCommands = <a>HFree</a> (<a>MapF</a> <a>String</a>)
--   </pre>
--   
--   This has an <a>Interpret</a> instance, but it can be more useful to
--   use via direct pattern matching, or through
--   
--   <pre>
--   <a>foldHFree</a>
--       :: <a>HBifunctor</a> t
--       =&gt; f <a>~&gt;</a> g
--       -&gt; t g ~&gt; g
--       -&gt; HFree t f ~&gt; g
--   </pre>
--   
--   which requires no extra constriant on <tt>g</tt>, and lets you
--   consider each branch separately.
--   
--   This can be considered the higher-oder analogue of <a>Free</a>; it is
--   the free <a>HBind</a> for any <tt><a>HFunctor</a> t</tt>.
--   
--   Note that <tt><a>HFree</a> <a>IdentityT</a></tt> is equivalent to
--   <a>Step</a>.
data HFree t f a
HReturn :: f a -> HFree t f a
HJoin :: t (HFree t f) a -> HFree t f a

-- | Recursively fold down an <a>HFree</a> into a single <tt>g</tt> result,
--   by handling each branch. Can be more useful than <a>interpret</a>
--   because it allows you to treat each branch separately, and also does
--   not require any constraint on <tt>g</tt>.
--   
--   This is the catamorphism on <a>HFree</a>.
foldHFree :: forall t f g. HFunctor t => (f ~> g) -> (t g ~> g) -> HFree t f ~> g

-- | A higher-level <a>retract</a> to get a <tt>t f a</tt> back out of an
--   <tt><a>HFree</a> t f a</tt>, provided <tt>t</tt> is an instance of
--   <a>Bind</a>.
--   
--   This witnesses the fact that <a>HFree</a> is the "Free <a>Bind</a>".
retractHFree :: HBind t => HFree t f a -> t f a

-- | A useful wrapper over the common pattern of
--   fmap-before-inject/inject-and-fmap.
injectMap :: (Inject t, Functor f) => (a -> b) -> f a -> t f b

-- | A useful wrapper over the common pattern of
--   contramap-before-inject/inject-and-contramap.
injectContramap :: (Inject t, Contravariant f) => (a -> b) -> f b -> t f a
instance (GHC.Base.Functor f, GHC.Base.Functor (t f)) => GHC.Base.Functor (Data.HFunctor.HLift t f)
instance forall k (f :: k -> *) (a :: k) (t :: (k -> *) -> k -> *). (GHC.Show.Show (f a), GHC.Show.Show (t f a)) => GHC.Show.Show (Data.HFunctor.HLift t f a)
instance forall k (f :: k -> *) (a :: k) (t :: (k -> *) -> k -> *). (GHC.Read.Read (f a), GHC.Read.Read (t f a)) => GHC.Read.Read (Data.HFunctor.HLift t f a)
instance forall k (f :: k -> *) (a :: k) (t :: (k -> *) -> k -> *). (GHC.Classes.Eq (f a), GHC.Classes.Eq (t f a)) => GHC.Classes.Eq (Data.HFunctor.HLift t f a)
instance forall k (f :: k -> *) (a :: k) (t :: (k -> *) -> k -> *). (GHC.Classes.Ord (f a), GHC.Classes.Ord (t f a)) => GHC.Classes.Ord (Data.HFunctor.HLift t f a)
instance (GHC.Base.Functor f, GHC.Base.Functor (t (Data.HFunctor.HFree t f))) => GHC.Base.Functor (Data.HFunctor.HFree t f)
instance Data.HFunctor.HBind Data.Functor.Coyoneda.Coyoneda
instance Data.HFunctor.HBind Control.Applicative.Free.Ap
instance Data.HFunctor.HBind Control.Applicative.ListF.ListF
instance Data.HFunctor.HBind Control.Applicative.ListF.NonEmptyF
instance Data.HFunctor.HBind Control.Applicative.ListF.MaybeF
instance Data.HFunctor.HBind Control.Applicative.Step.Step
instance Data.HFunctor.HBind Control.Applicative.Step.Flagged
instance Data.Functor.Alt.Alt f => Data.HFunctor.HBind (Data.Functor.These.These1 f)
instance Data.Functor.Plus.Plus f => Data.HFunctor.HBind ((GHC.Generics.:*:) f)
instance Data.Functor.Plus.Plus f => Data.HFunctor.HBind (Data.Functor.Product.Product f)
instance forall k (f :: k -> *). Data.HFunctor.HBind ((GHC.Generics.:+:) f)
instance forall k (f :: k -> *). Data.HFunctor.HBind (Data.Functor.Sum.Sum f)
instance Data.HFunctor.HBind (GHC.Generics.M1 i c)
instance Data.HFunctor.HBind Control.Alternative.Free.Alt
instance Data.HFunctor.HBind Control.Monad.Freer.Church.Free
instance Data.HFunctor.HBind Control.Monad.Freer.Church.Free1
instance Data.HFunctor.HBind Control.Applicative.Free.Final.Ap
instance Data.HFunctor.HBind Control.Applicative.Free.Fast.Ap
instance Data.HFunctor.HBind Control.Monad.Trans.Identity.IdentityT
instance Data.HFunctor.HBind Control.Applicative.Lift.Lift
instance Data.HFunctor.HBind Data.Functor.Bind.Class.MaybeApply
instance Data.HFunctor.HBind Control.Applicative.Backwards.Backwards
instance Data.HFunctor.HBind Data.Functor.Bind.Class.WrappedApplicative
instance Data.HFunctor.HBind Data.Functor.Reverse.Reverse
instance Data.HFunctor.HBind Data.HFunctor.ProxyF
instance GHC.Base.Monoid e => Data.HFunctor.HBind (Control.Comonad.Trans.Env.EnvT e)
instance forall k (t :: (k -> *) -> k -> *). (Data.HFunctor.HBind t, Data.HFunctor.Inject t) => Data.HFunctor.HBind (Data.HFunctor.HLift t)
instance forall k (t :: (k -> *) -> k -> *). Data.HFunctor.Internal.HFunctor t => Data.HFunctor.HBind (Data.HFunctor.HFree t)
instance Data.HFunctor.Inject Data.Functor.Coyoneda.Coyoneda
instance Data.HFunctor.Inject Data.Functor.Contravariant.Coyoneda.Coyoneda
instance Data.HFunctor.Inject Control.Applicative.Free.Ap
instance Data.HFunctor.Inject Control.Applicative.ListF.ListF
instance Data.HFunctor.Inject Control.Applicative.ListF.NonEmptyF
instance Data.HFunctor.Inject Control.Applicative.ListF.MaybeF
instance GHC.Base.Monoid k2 => Data.HFunctor.Inject (Control.Applicative.ListF.NEMapF k2)
instance GHC.Base.Monoid k2 => Data.HFunctor.Inject (Control.Applicative.ListF.MapF k2)
instance Data.HFunctor.Inject Control.Applicative.Step.Step
instance Data.HFunctor.Inject Control.Applicative.Step.Steps
instance Data.HFunctor.Inject Control.Applicative.Step.Flagged
instance Data.HFunctor.Inject (Data.Functor.These.These1 f)
instance GHC.Base.Applicative f => Data.HFunctor.Inject (Control.Monad.Freer.Church.Comp f)
instance GHC.Base.Applicative f => Data.HFunctor.Inject ((GHC.Generics.:.:) f)
instance Data.Functor.Plus.Plus f => Data.HFunctor.Inject ((GHC.Generics.:*:) f)
instance Data.Functor.Plus.Plus f => Data.HFunctor.Inject (Data.Functor.Product.Product f)
instance forall k (f :: k -> *). Data.HFunctor.Inject ((GHC.Generics.:+:) f)
instance forall k (f :: k -> *). Data.HFunctor.Inject (Data.Functor.Sum.Sum f)
instance Data.HFunctor.Inject (GHC.Generics.M1 i c)
instance Data.HFunctor.Inject Control.Alternative.Free.Alt
instance Data.HFunctor.Inject Control.Monad.Freer.Church.Free
instance Data.HFunctor.Inject Control.Monad.Freer.Church.Free1
instance Data.HFunctor.Inject Control.Applicative.Free.Final.Ap
instance Data.HFunctor.Inject Control.Applicative.Free.Fast.Ap
instance Data.HFunctor.Inject Control.Monad.Trans.Identity.IdentityT
instance Data.HFunctor.Inject Control.Applicative.Lift.Lift
instance Data.HFunctor.Inject Data.Functor.Bind.Class.MaybeApply
instance Data.HFunctor.Inject Control.Applicative.Backwards.Backwards
instance Data.HFunctor.Inject Data.Functor.Bind.Class.WrappedApplicative
instance Data.HFunctor.Inject (Control.Monad.Trans.Reader.ReaderT r)
instance GHC.Base.Monoid e => Data.HFunctor.Inject (Control.Comonad.Trans.Env.EnvT e)
instance Data.HFunctor.Inject Data.Functor.Reverse.Reverse
instance Data.HFunctor.Inject Data.HFunctor.ProxyF
instance GHC.Base.Monoid e => Data.HFunctor.Inject (Data.HFunctor.ConstF e)
instance (Data.HFunctor.Inject s, Data.HFunctor.Inject t) => Data.HFunctor.Inject (Control.Monad.Trans.Compose.ComposeT s t)
instance forall k (t :: (k -> *) -> k -> *). Data.HFunctor.Internal.HFunctor t => Data.HFunctor.Inject (Data.HFunctor.HLift t)
instance forall k (t :: (k -> *) -> k -> *). Data.HFunctor.Internal.HFunctor t => Data.HFunctor.Inject (Data.HFunctor.HFree t)
instance (Data.Functor.Contravariant.Contravariant f, Data.Functor.Contravariant.Contravariant (t (Data.HFunctor.HFree t f))) => Data.Functor.Contravariant.Contravariant (Data.HFunctor.HFree t f)
instance (Data.Functor.Invariant.Invariant f, Data.Functor.Invariant.Invariant (t (Data.HFunctor.HFree t f))) => Data.Functor.Invariant.Invariant (Data.HFunctor.HFree t f)
instance (Data.Functor.Classes.Show1 (t (Data.HFunctor.HFree t f)), Data.Functor.Classes.Show1 f) => Data.Functor.Classes.Show1 (Data.HFunctor.HFree t f)
instance (Data.Functor.Classes.Show1 (t (Data.HFunctor.HFree t f)), Data.Functor.Classes.Show1 f, GHC.Show.Show a) => GHC.Show.Show (Data.HFunctor.HFree t f a)
instance forall k (t :: (k -> *) -> k -> *). Data.HFunctor.Internal.HFunctor t => Data.HFunctor.Internal.HFunctor (Data.HFunctor.HFree t)
instance (Data.Functor.Classes.Show1 (t f), Data.Functor.Classes.Show1 f) => Data.Functor.Classes.Show1 (Data.HFunctor.HLift t f)
instance (Data.Functor.Classes.Eq1 (t f), Data.Functor.Classes.Eq1 f) => Data.Functor.Classes.Eq1 (Data.HFunctor.HLift t f)
instance (Data.Functor.Classes.Ord1 (t f), Data.Functor.Classes.Ord1 f) => Data.Functor.Classes.Ord1 (Data.HFunctor.HLift t f)
instance forall k (t :: (k -> *) -> k -> *). Data.HFunctor.Internal.HFunctor t => Data.HFunctor.Internal.HFunctor (Data.HFunctor.HLift t)
instance (Data.Functor.Contravariant.Contravariant f, Data.Functor.Contravariant.Contravariant (t f)) => Data.Functor.Contravariant.Contravariant (Data.HFunctor.HLift t f)
instance (Data.Functor.Invariant.Invariant f, Data.Functor.Invariant.Invariant (t f)) => Data.Functor.Invariant.Invariant (Data.HFunctor.HLift t f)
instance forall k e (f :: k). GHC.Classes.Ord e => Data.Functor.Classes.Ord1 (Data.HFunctor.ConstF e f)
instance forall k e (f :: k). Data.Functor.Contravariant.Contravariant (Data.HFunctor.ConstF e f)
instance forall k e (f :: k). GHC.Base.Monoid e => Data.Functor.Contravariant.Divisible.Divisible (Data.HFunctor.ConstF e f)
instance forall k e (f :: k). GHC.Base.Semigroup e => Data.Functor.Contravariant.Divise.Divise (Data.HFunctor.ConstF e f)
instance forall k e (f :: k). Data.Functor.Invariant.Invariant (Data.HFunctor.ConstF e f)
instance Data.HFunctor.Internal.HFunctor (Data.HFunctor.ConstF e)
instance forall k e (f :: k). GHC.Classes.Eq e => Data.Functor.Classes.Eq1 (Data.HFunctor.ConstF e f)
instance forall k e (f :: k). GHC.Read.Read e => Data.Functor.Classes.Read1 (Data.HFunctor.ConstF e f)
instance forall k e (f :: k). GHC.Show.Show e => Data.Functor.Classes.Show1 (Data.HFunctor.ConstF e f)
instance forall e k1 (f :: k1) k2 (a :: k2). (Data.Typeable.Internal.Typeable f, Data.Typeable.Internal.Typeable a, Data.Typeable.Internal.Typeable k1, Data.Typeable.Internal.Typeable k2, Data.Data.Data e) => Data.Data.Data (Data.HFunctor.ConstF e f a)
instance forall e k1 (f :: k1) k2 (a :: k2). GHC.Generics.Generic (Data.HFunctor.ConstF e f a)
instance forall e k (f :: k). Data.Traversable.Traversable (Data.HFunctor.ConstF e f)
instance forall e k (f :: k). Data.Foldable.Foldable (Data.HFunctor.ConstF e f)
instance forall e k (f :: k). GHC.Base.Functor (Data.HFunctor.ConstF e f)
instance forall e k1 (f :: k1) k2 (a :: k2). GHC.Classes.Ord e => GHC.Classes.Ord (Data.HFunctor.ConstF e f a)
instance forall e k1 (f :: k1) k2 (a :: k2). GHC.Classes.Eq e => GHC.Classes.Eq (Data.HFunctor.ConstF e f a)
instance forall e k1 (f :: k1) k2 (a :: k2). GHC.Read.Read e => GHC.Read.Read (Data.HFunctor.ConstF e f a)
instance forall e k1 (f :: k1) k2 (a :: k2). GHC.Show.Show e => GHC.Show.Show (Data.HFunctor.ConstF e f a)
instance forall k (f :: k). Data.Functor.Classes.Ord1 (Data.HFunctor.ProxyF f)
instance forall k (f :: k). Data.Functor.Contravariant.Contravariant (Data.HFunctor.ProxyF f)
instance forall k (f :: k). Data.Functor.Contravariant.Divisible.Divisible (Data.HFunctor.ProxyF f)
instance forall k (f :: k). Data.Functor.Contravariant.Divise.Divise (Data.HFunctor.ProxyF f)
instance forall k (f :: k). Data.Functor.Contravariant.Decide.Decide (Data.HFunctor.ProxyF f)
instance forall k (f :: k). Data.Functor.Contravariant.Conclude.Conclude (Data.HFunctor.ProxyF f)
instance forall k (f :: k). Data.Functor.Contravariant.Divisible.Decidable (Data.HFunctor.ProxyF f)
instance forall k (f :: k). Data.Functor.Invariant.Invariant (Data.HFunctor.ProxyF f)
instance Data.HFunctor.Internal.HFunctor Data.HFunctor.ProxyF
instance forall k (f :: k). Data.Functor.Classes.Eq1 (Data.HFunctor.ProxyF f)
instance forall k (f :: k). Data.Functor.Classes.Read1 (Data.HFunctor.ProxyF f)
instance forall k (f :: k). Data.Functor.Classes.Show1 (Data.HFunctor.ProxyF f)
instance forall k1 (f :: k1) k2 (a :: k2). (Data.Typeable.Internal.Typeable f, Data.Typeable.Internal.Typeable a, Data.Typeable.Internal.Typeable k1, Data.Typeable.Internal.Typeable k2) => Data.Data.Data (Data.HFunctor.ProxyF f a)
instance forall k1 (f :: k1) k2 (a :: k2). GHC.Generics.Generic (Data.HFunctor.ProxyF f a)
instance forall k (f :: k). Data.Traversable.Traversable (Data.HFunctor.ProxyF f)
instance forall k (f :: k). Data.Foldable.Foldable (Data.HFunctor.ProxyF f)
instance forall k (f :: k). GHC.Base.Functor (Data.HFunctor.ProxyF f)
instance forall k1 (f :: k1) k2 (a :: k2). GHC.Classes.Ord (Data.HFunctor.ProxyF f a)
instance forall k1 (f :: k1) k2 (a :: k2). GHC.Classes.Eq (Data.HFunctor.ProxyF f a)
instance forall k1 (f :: k1) k2 (a :: k2). GHC.Read.Read (Data.HFunctor.ProxyF f a)
instance forall k1 (f :: k1) k2 (a :: k2). GHC.Show.Show (Data.HFunctor.ProxyF f a)


-- | This module provides tools for working with unary functor combinators
--   that represent interpretable schemas.
--   
--   These are types <tt>t</tt> that take a functor <tt>f</tt> and return a
--   new functor <tt>t f</tt>, enhancing <tt>f</tt> with new structure and
--   abilities.
--   
--   For these, we have:
--   
--   <pre>
--   <a>inject</a> :: f a -&gt; t f a
--   </pre>
--   
--   which lets you "lift" an <tt>f a</tt> into its transformed version,
--   and also:
--   
--   <pre>
--   <a>interpret</a>
--       :: C t g
--       =&gt; (forall x. f a -&gt; g a)
--       -&gt; t f a
--       -&gt; g a
--   </pre>
--   
--   that lets you "interpret" a <tt>t f a</tt> into a context <tt>g
--   a</tt>, essentially "running" the computaiton that it encodes. The
--   context is required to have a typeclass constraints that reflects what
--   is "required" to be able to run a functor combinator.
--   
--   Every single instance provides different tools. Check out the instance
--   list for a nice list of useful combinators, or also the README for a
--   high-level rundown.
--   
--   See <a>Data.Functor.Tensor</a> for binary functor combinators that mix
--   together two or more different functors.
module Data.HFunctor.Interpret

-- | An <a>Interpret</a> lets us move in and out of the "enhanced"
--   <a>Functor</a> (<tt>t f</tt>) and the functor it enhances
--   (<tt>f</tt>). An instance <tt><a>Interpret</a> t f</tt> means we have
--   <tt>t f a -&gt; f a</tt>.
--   
--   For example, <tt><a>Free</a> f</tt> is <tt>f</tt> enhanced with
--   monadic structure. We get:
--   
--   <pre>
--   <a>inject</a>    :: f a -&gt; <a>Free</a> f a
--   <a>interpret</a> :: <a>Monad</a> m =&gt; (forall x. f x -&gt; m x) -&gt; <a>Free</a> f a -&gt; m a
--   </pre>
--   
--   <a>inject</a> will let us use our <tt>f</tt> inside the enhanced
--   <tt><a>Free</a> f</tt>. <a>interpret</a> will let us "extract" the
--   <tt>f</tt> from a <tt><a>Free</a> f</tt> if we can give an
--   <i>interpreting function</i> that interprets <tt>f</tt> into some
--   target <a>Monad</a>.
--   
--   We enforce that:
--   
--   <pre>
--   <a>interpret</a> id . <a>inject</a> == id
--   -- or
--   <a>retract</a> . <a>inject</a> == id
--   </pre>
--   
--   That is, if we lift a value into our structure, then immediately
--   interpret it out as itself, it should lave the value unchanged.
--   
--   Note that instances of this class are <i>intended</i> to be written
--   with <tt>t</tt> as a fixed type constructor, and <tt>f</tt> to be
--   allowed to vary freely:
--   
--   <pre>
--   instance Monad f =&gt; Interpret Free f
--   </pre>
--   
--   Any other sort of instance and it's easy to run into problems with
--   type inference. If you want to write an instance that's "polymorphic"
--   on tensor choice, use the <a>WrapHF</a> newtype wrapper over a type
--   variable, where the second argument also uses a type constructor:
--   
--   <pre>
--   instance Interpret (WrapHF t) (MyFunctor t)
--   </pre>
--   
--   This will prevent problems with overloaded instances.
class Inject t => Interpret t f

-- | Remove the <tt>f</tt> out of the enhanced <tt>t f</tt> structure,
--   provided that <tt>f</tt> satisfies the necessary constraints. If it
--   doesn't, it needs to be properly <a>interpret</a>ed out.
retract :: Interpret t f => t f ~> f

-- | Given an "interpeting function" from <tt>f</tt> to <tt>g</tt>,
--   interpret the <tt>f</tt> out of the <tt>t f</tt> into a final context
--   <tt>g</tt>.
interpret :: Interpret t f => (g ~> f) -> t g ~> f

-- | A convenient flipped version of <a>interpret</a>.
forI :: Interpret t f => t g a -> (g ~> f) -> f a

-- | Useful wrapper over <a>interpret</a> to allow you to directly extract
--   a value <tt>b</tt> out of the <tt>t f a</tt>, if you can convert <tt>f
--   x</tt> into <tt>b</tt>.
--   
--   Note that depending on the constraints on <tt>f</tt> in
--   <tt><a>Interpret</a> t f</tt>, you may have extra constraints on
--   <tt>b</tt>.
--   
--   <ul>
--   <li>If <tt>f</tt> is unconstrained, there are no constraints on
--   <tt>b</tt></li>
--   <li>If <tt>f</tt> must be <a>Apply</a>, <a>Alt</a>, <a>Divise</a>, or
--   <a>Decide</a>, <tt>b</tt> needs to be an instance of
--   <a>Semigroup</a>.</li>
--   <li>If <tt>f</tt> is <a>Applicative</a>, <a>Plus</a>,
--   <a>Divisible</a>, or <a>Conclude</a>, <tt>b</tt> needs to be an
--   instance of <a>Monoid</a></li>
--   </ul>
--   
--   For some constraints (like <a>Monad</a>), this will not be usable.
--   
--   <pre>
--   -- get the length of the <tt>Map String</tt> in the <a>Step</a>.
--   <a>icollect</a> length
--        :: Step (Map String) Bool
--        -&gt; Int
--   </pre>
--   
--   Note that in many cases, you can also use <a>hfoldMap</a> and
--   <a>hfoldMap1</a>.
iget :: Interpret t (AltConst b) => (forall x. f x -> b) -> t f a -> b

-- | Useful wrapper over <a>iget</a> to allow you to collect a <tt>b</tt>
--   from all instances of <tt>f</tt> inside a <tt>t f a</tt>.
--   
--   Will work if there is an instance of <tt><a>Interpret</a> t
--   (<a>AltConst</a> m)</tt> if <tt><a>Monoid</a> m</tt>, which will be
--   the case if the constraint on the target functor is <a>Functor</a>,
--   <a>Apply</a>, <a>Applicative</a>, <a>Alt</a>, <a>Plus</a>,
--   <a>Decide</a>, <a>Divisible</a>, <a>Decide</a>, <a>Conclude</a>, or
--   unconstrained.
--   
--   <pre>
--   -- get the lengths of all <tt>Map String</tt>s in the <a>Ap</a>.
--   <a>icollect</a> length
--        :: Ap (Map String) Bool
--        -&gt; [Int]
--   </pre>
--   
--   Note that in many cases, you can also use <a>htoList</a>.
icollect :: (forall m. Monoid m => Interpret t (AltConst m)) => (forall x. f x -> b) -> t f a -> [b]

-- | Useful wrapper over <a>iget</a> to allow you to collect a <tt>b</tt>
--   from all instances of <tt>f</tt> inside a <tt>t f a</tt>, into a
--   non-empty collection of <tt>b</tt>s.
--   
--   Will work if there is an instance of <tt><a>Interpret</a> t
--   (<a>AltConst</a> m)</tt> if <tt><a>Semigroup</a> m</tt>, which will be
--   the case if the constraint on the target functor is <a>Functor</a>,
--   <a>Apply</a>, <a>Alt</a>, <a>Divise</a>, <a>Decide</a>, or
--   unconstrained.
--   
--   <pre>
--   -- get the lengths of all <tt>Map String</tt>s in the <a>Ap</a>.
--   <a>icollect1</a> length
--        :: Ap1 (Map String) Bool
--        -&gt; <a>NonEmpty</a> Int
--   </pre>
--   
--   Note that in many cases, you can also use <a>htoNonEmpty</a>.
icollect1 :: (forall m. Semigroup m => Interpret t (AltConst m)) => (forall x. f x -> b) -> t f a -> NonEmpty b

-- | Useful wrapper over <a>interpret</a> to allow you to do an "effectful"
--   <a>hmap</a>.
--   
--   This can be useful in some situations, but if you want to do this,
--   it's probably better to just use <a>htraverse</a>, which is a more
--   principled system for effectful hmapping.
itraverse :: (Functor h, Interpret t (Comp h (t g))) => (forall x. f x -> h (g x)) -> t f a -> h (t g a)

-- | Useful wrapper over <a>interpret</a> to allow you to directly consume
--   a value of type <tt>a</tt> with a <tt>t f a</tt> to create a
--   <tt>b</tt>. Do this by supplying the method by which each component
--   <tt>f x</tt> can consume an <tt>x</tt>. This works for contravariant
--   functor combinators, where <tt>t f a</tt> can be interpreted as a
--   consumer of <tt>a</tt>s.
--   
--   Note that depending on the constraints on <tt>f</tt> in
--   <tt><a>Interpret</a> t f</tt>, you may have extra constraints on
--   <tt>b</tt>.
--   
--   <ul>
--   <li>If <tt>f</tt> is unconstrained, <a>Decide</a>, or <a>Conclude</a>,
--   there are no constraints on <tt>b</tt>. This will be the case for
--   combinators like contravariant <a>Coyoneda</a>, <tt>Dec</tt>,
--   <tt>Dec1</tt>.</li>
--   <li>If <tt>f</tt> must be <a>Divise</a>, <tt>b</tt> needs to be an
--   instance of <a>Semigroup</a>. This will be the case for combinators
--   like <tt>Div1</tt>.</li>
--   <li>If <tt>f</tt> is <a>Divisible</a>, <tt>b</tt> needs to be an
--   instance of <a>Monoid</a>. This will be the case for combinators like
--   <tt>Div</tt>.</li>
--   </ul>
--   
--   For any <a>Functor</a> or <a>Invariant</a> constraint, this is not
--   usable.
iapply :: Interpret t (Op b) => (forall x. f x -> x -> b) -> t f a -> a -> b

-- | Useful wrapper over <a>interpret</a> to allow you to directly consume
--   a value of type <tt>a</tt> with a <tt>t f a</tt> to create a
--   <tt>b</tt>, and create a list of all the <tt>b</tt>s created by all
--   the <tt>f</tt>s. Do this by supplying the method by which each
--   component <tt>f x</tt> can consume an <tt>x</tt>. This works for
--   contravariant functor combinators, where <tt>t f a</tt> can be
--   interpreted as a consumer of <tt>a</tt>s.
--   
--   Will work if there is an instance of <tt><a>Interpret</a> t (<a>Op</a>
--   m)</tt> if <tt><a>Monoid</a> m</tt>, which will be the case if the
--   constraint on the target functor is <a>Contravariant</a>,
--   <a>Decide</a>, <a>Conclude</a>, <a>Divise</a>, <a>Divisible</a>, or
--   unconstrained.
--   
--   Note that this is really only useful outside of <a>iapply</a> for
--   <tt>Div</tt> and <tt>Div1</tt>, where a <tt><tt>Div</tt> f</tt> which
--   is a collection of many different <tt>f</tt>s consuming types of
--   different values. You can use this with <tt>Dec</tt> and <tt>Dec1</tt>
--   and the contravarient <a>Coyoneda</a> as well, but those would always
--   just give you a singleton list, so you might as well use
--   <a>iapply</a>. This is really only here for completion alongside
--   <a>icollect</a>, or if you define your own custom functor combinators.
ifanout :: (forall m. Monoid m => Interpret t (Op m)) => (forall x. f x -> x -> b) -> t f a -> a -> [b]

-- | Useful wrapper over <a>interpret</a> to allow you to directly consume
--   a value of type <tt>a</tt> with a <tt>t f a</tt> to create a
--   <tt>b</tt>, and create a list of all the <tt>b</tt>s created by all
--   the <tt>f</tt>s. Do this by supplying the method by which each
--   component <tt>f x</tt> can consume an <tt>x</tt>. This works for
--   contravariant functor combinators, where <tt>t f a</tt> can be
--   interpreted as a consumer of <tt>a</tt>s.
--   
--   Will work if there is an instance of <tt><a>Interpret</a> t (<a>Op</a>
--   m)</tt> if <tt><a>Monoid</a> m</tt>, which will be the case if the
--   constraint on the target functor is <a>Contravariant</a>,
--   <a>Decide</a>, <a>Divise</a>, or unconstrained.
--   
--   Note that this is really only useful outside of <a>iapply</a> and
--   <a>ifanout</a> for <tt>Div1</tt>, where a <tt><tt>Div1</tt> f</tt>
--   which is a collection of many different <tt>f</tt>s consuming types of
--   different values. You can use this with <tt>Dec</tt> and <tt>Dec1</tt>
--   and the contravarient <a>Coyoneda</a> as well, but those would always
--   just give you a singleton list, so you might as well use
--   <a>iapply</a>. This is really only here for completion alongside
--   <a>icollect1</a>, or if you define your own custom functor
--   combinators.
ifanout1 :: (forall m. Semigroup m => Interpret t (Op m)) => (forall x. f x -> x -> b) -> t f a -> a -> NonEmpty b

-- | (Deprecated) Old name for <a>getI</a>; will be removed in a future
--   version.

-- | <i>Deprecated: Use iget instead</i>
getI :: Interpret t (AltConst b) => (forall x. f x -> b) -> t f a -> b

-- | (Deprecated) Old name for <a>icollect</a>; will be removed in a future
--   version.

-- | <i>Deprecated: Use icollect instead</i>
collectI :: (forall m. Monoid m => Interpret t (AltConst m)) => (forall x. f x -> b) -> t f a -> [b]

-- | A version of <a>Const</a> that supports <a>Alt</a>, <a>Plus</a>,
--   <a>Decide</a>, and <a>Conclude</a> instances. It does this by avoiding
--   having an <a>Alternative</a> or <a>Decidable</a> instance, which
--   causes all sorts of problems with the interactions between
--   <a>Alternative</a>/<a>Applicative</a> and
--   <a>Decidable</a>/<a>Divisible</a>.
newtype AltConst w a
AltConst :: w -> AltConst w a
[getAltConst] :: AltConst w a -> w

-- | A constraint on <tt>a</tt> for both <tt>c a</tt> and <tt>d a</tt>.
--   Requiring <tt><a>AndC</a> <a>Show</a> <a>Eq</a> a</tt> is the same as
--   requiring <tt>(<a>Show</a> a, <a>Eq</a> a)</tt>.
class (c a, d a) => AndC c d a

-- | A newtype wrapper meant to be used to define polymorphic
--   <a>Interpret</a> instances. See documentation for <a>Interpret</a> for
--   more information.
--   
--   Please do not ever define an instance of <a>Interpret</a> "naked" on
--   the second parameter:
--   
--   <pre>
--   instance Interpret (WrapHF t) f
--   </pre>
--   
--   As that would globally ruin everything using <a>WrapHF</a>.
newtype WrapHF t f a
WrapHF :: t f a -> WrapHF t f a
[unwrapHF] :: WrapHF t f a -> t f a
instance forall w k (a :: k). (Data.Typeable.Internal.Typeable a, Data.Typeable.Internal.Typeable k, Data.Data.Data w) => Data.Data.Data (Data.HFunctor.Interpret.AltConst w a)
instance Data.Traversable.Traversable (Data.HFunctor.Interpret.AltConst w)
instance Data.Foldable.Foldable (Data.HFunctor.Interpret.AltConst w)
instance GHC.Base.Functor (Data.HFunctor.Interpret.AltConst w)
instance forall w k (a :: k). GHC.Generics.Generic (Data.HFunctor.Interpret.AltConst w a)
instance forall w k (a :: k). GHC.Classes.Ord w => GHC.Classes.Ord (Data.HFunctor.Interpret.AltConst w a)
instance forall w k (a :: k). GHC.Classes.Eq w => GHC.Classes.Eq (Data.HFunctor.Interpret.AltConst w a)
instance forall w k (a :: k). GHC.Show.Show w => GHC.Show.Show (Data.HFunctor.Interpret.AltConst w a)
instance forall k1 k2 (t :: k1 -> k2 -> *) (f :: k1) (a :: k2). (Data.Typeable.Internal.Typeable f, Data.Typeable.Internal.Typeable a, Data.Typeable.Internal.Typeable t, Data.Typeable.Internal.Typeable k1, Data.Typeable.Internal.Typeable k2, Data.Data.Data (t f a)) => Data.Data.Data (Data.HFunctor.Interpret.WrapHF t f a)
instance forall k1 k2 (t :: k1 -> k2 -> *) (f :: k1) (a :: k2). GHC.Generics.Generic (Data.HFunctor.Interpret.WrapHF t f a)
instance forall k (t :: k -> * -> *) (f :: k). Data.Traversable.Traversable (t f) => Data.Traversable.Traversable (Data.HFunctor.Interpret.WrapHF t f)
instance forall k (t :: k -> * -> *) (f :: k). Data.Foldable.Foldable (t f) => Data.Foldable.Foldable (Data.HFunctor.Interpret.WrapHF t f)
instance forall k (t :: k -> * -> *) (f :: k). GHC.Base.Functor (t f) => GHC.Base.Functor (Data.HFunctor.Interpret.WrapHF t f)
instance forall k1 k2 (t :: k1 -> k2 -> *) (f :: k1) (a :: k2). GHC.Classes.Ord (t f a) => GHC.Classes.Ord (Data.HFunctor.Interpret.WrapHF t f a)
instance forall k1 k2 (t :: k1 -> k2 -> *) (f :: k1) (a :: k2). GHC.Classes.Eq (t f a) => GHC.Classes.Eq (Data.HFunctor.Interpret.WrapHF t f a)
instance forall k1 k2 (t :: k1 -> k2 -> *) (f :: k1) (a :: k2). GHC.Read.Read (t f a) => GHC.Read.Read (Data.HFunctor.Interpret.WrapHF t f a)
instance forall k1 k2 (t :: k1 -> k2 -> *) (f :: k1) (a :: k2). GHC.Show.Show (t f a) => GHC.Show.Show (Data.HFunctor.Interpret.WrapHF t f a)
instance forall k (t :: k -> * -> *) (f :: k). Data.Functor.Classes.Show1 (t f) => Data.Functor.Classes.Show1 (Data.HFunctor.Interpret.WrapHF t f)
instance forall k (t :: k -> * -> *) (f :: k). Data.Functor.Classes.Eq1 (t f) => Data.Functor.Classes.Eq1 (Data.HFunctor.Interpret.WrapHF t f)
instance forall k (t :: k -> * -> *) (f :: k). Data.Functor.Classes.Ord1 (t f) => Data.Functor.Classes.Ord1 (Data.HFunctor.Interpret.WrapHF t f)
instance forall k1 k2 (t :: (k1 -> *) -> k2 -> *). Data.HFunctor.Internal.HFunctor t => Data.HFunctor.Internal.HFunctor (Data.HFunctor.Interpret.WrapHF t)
instance forall k (t :: (k -> *) -> k -> *). Data.HFunctor.Inject t => Data.HFunctor.Inject (Data.HFunctor.Interpret.WrapHF t)
instance forall k (t :: (k -> *) -> k -> *). Data.HFunctor.HBind t => Data.HFunctor.HBind (Data.HFunctor.Interpret.WrapHF t)
instance forall k (c :: k -> GHC.Types.Constraint) (a :: k) (d :: k -> GHC.Types.Constraint). (c a, d a) => Data.HFunctor.Interpret.AndC c d a
instance GHC.Show.Show w => Data.Functor.Classes.Show1 (Data.HFunctor.Interpret.AltConst w)
instance GHC.Classes.Eq w => Data.Functor.Classes.Eq1 (Data.HFunctor.Interpret.AltConst w)
instance GHC.Classes.Ord w => Data.Functor.Classes.Ord1 (Data.HFunctor.Interpret.AltConst w)
instance Data.Functor.Contravariant.Contravariant (Data.HFunctor.Interpret.AltConst w)
instance Data.Functor.Invariant.Invariant (Data.HFunctor.Interpret.AltConst w)
instance GHC.Base.Semigroup w => Data.Functor.Bind.Class.Apply (Data.HFunctor.Interpret.AltConst w)
instance GHC.Base.Monoid w => GHC.Base.Applicative (Data.HFunctor.Interpret.AltConst w)
instance GHC.Base.Semigroup w => Data.Functor.Alt.Alt (Data.HFunctor.Interpret.AltConst w)
instance GHC.Base.Monoid w => Data.Functor.Plus.Plus (Data.HFunctor.Interpret.AltConst w)
instance GHC.Base.Semigroup w => Data.Functor.Contravariant.Divise.Divise (Data.HFunctor.Interpret.AltConst w)
instance GHC.Base.Monoid w => Data.Functor.Contravariant.Divisible.Divisible (Data.HFunctor.Interpret.AltConst w)
instance GHC.Base.Semigroup w => Data.Functor.Contravariant.Decide.Decide (Data.HFunctor.Interpret.AltConst w)
instance GHC.Base.Monoid w => Data.Functor.Contravariant.Conclude.Conclude (Data.HFunctor.Interpret.AltConst w)
instance GHC.Base.Functor f => Data.HFunctor.Interpret.Interpret Data.Functor.Coyoneda.Coyoneda f
instance Data.Functor.Contravariant.Contravariant f => Data.HFunctor.Interpret.Interpret Data.Functor.Contravariant.Coyoneda.Coyoneda f
instance GHC.Base.Applicative f => Data.HFunctor.Interpret.Interpret Control.Applicative.Free.Ap f
instance Data.Functor.Plus.Plus f => Data.HFunctor.Interpret.Interpret Control.Applicative.ListF.ListF f
instance Data.Functor.Alt.Alt f => Data.HFunctor.Interpret.Interpret Control.Applicative.ListF.NonEmptyF f
instance Data.Functor.Plus.Plus f => Data.HFunctor.Interpret.Interpret Control.Applicative.ListF.MaybeF f
instance (GHC.Base.Monoid k, Data.Functor.Plus.Plus f) => Data.HFunctor.Interpret.Interpret (Control.Applicative.ListF.MapF k) f
instance (GHC.Base.Monoid k, Data.Functor.Alt.Alt f) => Data.HFunctor.Interpret.Interpret (Control.Applicative.ListF.NEMapF k) f
instance forall k (f :: k -> *). Data.HFunctor.Interpret.Interpret Control.Applicative.Step.Step f
instance Data.Functor.Alt.Alt f => Data.HFunctor.Interpret.Interpret Control.Applicative.Step.Steps f
instance forall k (f :: k -> *). Data.HFunctor.Interpret.Interpret Control.Applicative.Step.Flagged f
instance Data.Functor.Plus.Plus f => Data.HFunctor.Interpret.Interpret (Data.Functor.These.These1 g) f
instance GHC.Base.Alternative f => Data.HFunctor.Interpret.Interpret Control.Alternative.Free.Alt f
instance Data.Functor.Plus.Plus g => Data.HFunctor.Interpret.Interpret ((GHC.Generics.:*:) g) f
instance Data.Functor.Plus.Plus g => Data.HFunctor.Interpret.Interpret (Data.Functor.Product.Product g) f
instance Data.Functor.Plus.Plus f => Data.HFunctor.Interpret.Interpret ((GHC.Generics.:+:) g) f
instance Data.Functor.Plus.Plus f => Data.HFunctor.Interpret.Interpret (Data.Functor.Sum.Sum g) f
instance forall k i (c :: GHC.Generics.Meta) (f :: k -> *). Data.HFunctor.Interpret.Interpret (GHC.Generics.M1 i c) f
instance GHC.Base.Monad f => Data.HFunctor.Interpret.Interpret Control.Monad.Freer.Church.Free f
instance Data.Functor.Bind.Class.Bind f => Data.HFunctor.Interpret.Interpret Control.Monad.Freer.Church.Free1 f
instance GHC.Base.Applicative f => Data.HFunctor.Interpret.Interpret Control.Applicative.Free.Final.Ap f
instance GHC.Base.Applicative f => Data.HFunctor.Interpret.Interpret Control.Applicative.Free.Fast.Ap f
instance forall k (f :: k -> *). Data.HFunctor.Interpret.Interpret Control.Monad.Trans.Identity.IdentityT f
instance Data.Pointed.Pointed f => Data.HFunctor.Interpret.Interpret Control.Applicative.Lift.Lift f
instance Data.Pointed.Pointed f => Data.HFunctor.Interpret.Interpret Data.Functor.Bind.Class.MaybeApply f
instance forall k (f :: k -> *). Data.HFunctor.Interpret.Interpret Control.Applicative.Backwards.Backwards f
instance Data.HFunctor.Interpret.Interpret Data.Functor.Bind.Class.WrappedApplicative f
instance Control.Monad.Reader.Class.MonadReader r f => Data.HFunctor.Interpret.Interpret (Control.Monad.Trans.Reader.ReaderT r) f
instance GHC.Base.Monoid e => Data.HFunctor.Interpret.Interpret (Control.Comonad.Trans.Env.EnvT e) f
instance forall k (f :: k -> *). Data.HFunctor.Interpret.Interpret Data.Functor.Reverse.Reverse f
instance (Data.HFunctor.Interpret.Interpret s f, Data.HFunctor.Interpret.Interpret t f) => Data.HFunctor.Interpret.Interpret (Control.Monad.Trans.Compose.ComposeT s t) f
instance forall k (t :: (k -> *) -> k -> *) (f :: k -> *). Data.HFunctor.Interpret.Interpret t f => Data.HFunctor.Interpret.Interpret (Data.HFunctor.HLift t) f
instance forall k (t :: (k -> *) -> k -> *) (f :: k -> *). Data.HFunctor.Interpret.Interpret t f => Data.HFunctor.Interpret.Interpret (Data.HFunctor.HFree t) f


-- | Provides a "higher-order" version of <a>Traversable</a> and
--   <a>Traversable1</a>, in the same way that <a>HFunctor</a> is a
--   higher-order version of <a>Functor</a>.
--   
--   Note that in theory we could have <tt>HFoldable</tt> as well, in the
--   hierarchy, to represent something that does not have an
--   <a>HFunctor</a> instance. But it is not clear exactly why it would be
--   useful as an abstraction. This may be added in the future if use cases
--   pop up. For the most part, the things you would want to do with an
--   <tt>HFoldable</tt>, you could do with <a>hfoldMap</a> or <a>iget</a>;
--   it could in theory be useful for things without <a>HTraversable</a> or
--   <a>Interpret</a> instances, but it isn't clear what those instances
--   might be.
--   
--   For instances of <a>Interpret</a>, there is some overlap with the
--   functionality of <a>iget</a>, <a>icollect</a>, and <a>icollect1</a>.
module Data.HFunctor.HTraversable

-- | A higher-kinded version of <a>Traversable</a>, in the same way that
--   <a>HFunctor</a> is the higher-kinded version of <a>Functor</a>. Gives
--   you an "effectful" <a>hmap</a>, in the same way that <a>traverse</a>
--   gives you an effectful <a>fmap</a>.
--   
--   The typical analogues of <a>Traversable</a> laws apply.
class HFunctor t => HTraversable t

-- | An "effectful" <a>hmap</a>, in the same way that <a>traverse</a> is an
--   effectful <a>fmap</a>.
htraverse :: (HTraversable t, Applicative h) => (forall x. f x -> h (g x)) -> t f a -> h (t g a)

-- | A wrapper over a common pattern of "inverting" layers of a functor
--   combinator.
hsequence :: (HTraversable t, Applicative h) => t (h :.: f) a -> h (t f a)

-- | Collect all the <tt>f x</tt>s inside a <tt>t f a</tt> into a monoidal
--   result using a projecting function.
--   
--   See <a>iget</a>.
hfoldMap :: (HTraversable t, Monoid m) => (forall x. f x -> m) -> t f a -> m

-- | Collect all the <tt>f x</tt>s inside a <tt>t f a</tt> into a list,
--   using a projecting function.
--   
--   See <a>icollect</a>.
htoList :: HTraversable t => (forall x. f x -> b) -> t f a -> [b]

-- | An implementation of <a>hmap</a> defined using <a>htraverse</a>.
hmapDefault :: HTraversable t => (f ~> g) -> t f ~> t g

-- | A flipped version of <a>htraverse</a>.
hfor :: (HTraversable t, Applicative h) => t f a -> (forall x. f x -> h (g x)) -> h (t g a)

-- | A higher-kinded version of <a>Traversable1</a>, in the same way that
--   <a>HFunctor</a> is the higher-kinded version of <a>Functor</a>. Gives
--   you an "effectful" <a>hmap</a>, in the same way that <a>traverse1</a>
--   gives you an effectful <a>fmap</a>, guaranteeing at least one item.
--   
--   The typical analogues of <a>Traversable1</a> laws apply.
class HTraversable t => HTraversable1 t

-- | An "effectful" <a>hmap</a>, in the same way that <a>traverse1</a> is
--   an effectful <a>fmap</a>, guaranteeing at least one item.
htraverse1 :: (HTraversable1 t, Apply h) => (forall x. f x -> h (g x)) -> t f a -> h (t g a)

-- | A wrapper over a common pattern of "inverting" layers of a functor
--   combinator that always contains at least one <tt>f</tt> item.
hsequence1 :: (HTraversable1 t, Apply h) => t (h :.: f) a -> h (t f a)

-- | Collect all the <tt>f x</tt>s inside a <tt>t f a</tt> into a
--   semigroupoidal result using a projecting function.
--   
--   See <a>iget</a>.
hfoldMap1 :: (HTraversable1 t, Semigroup m) => (forall x. f x -> m) -> t f a -> m

-- | Collect all the <tt>f x</tt>s inside a <tt>t f a</tt> into a non-empty
--   list, using a projecting function.
--   
--   See <a>icollect1</a>.
htoNonEmpty :: HTraversable1 t => (forall x. f x -> b) -> t f a -> NonEmpty b

-- | A flipped version of <a>htraverse1</a>.
hfor1 :: (HTraversable1 t, Apply h) => t f a -> (forall x. f x -> h (g x)) -> h (t g a)
instance Data.HFunctor.HTraversable.HTraversable1 Data.Functor.Coyoneda.Coyoneda
instance Data.HFunctor.HTraversable.HTraversable1 Data.Functor.Contravariant.Coyoneda.Coyoneda
instance Data.HFunctor.HTraversable.HTraversable1 Control.Applicative.ListF.NonEmptyF
instance Data.HFunctor.HTraversable.HTraversable1 (Control.Applicative.ListF.NEMapF k2)
instance Data.HFunctor.HTraversable.HTraversable1 Control.Applicative.Step.Step
instance Data.HFunctor.HTraversable.HTraversable1 Control.Applicative.Step.Steps
instance Data.HFunctor.HTraversable.HTraversable1 Control.Applicative.Step.Flagged
instance Data.HFunctor.HTraversable.HTraversable1 Control.Monad.Trans.Maybe.MaybeT
instance Data.HFunctor.HTraversable.HTraversable1 Control.Monad.Trans.Identity.IdentityT
instance Data.HFunctor.HTraversable.HTraversable1 Data.Functor.Reverse.Reverse
instance Data.Semigroup.Traversable.Class.Traversable1 f => Data.HFunctor.HTraversable.HTraversable1 ((GHC.Generics.:.:) f)
instance Data.HFunctor.HTraversable.HTraversable1 (GHC.Generics.M1 i c)
instance Data.HFunctor.HTraversable.HTraversable1 Control.Applicative.Step.Void2
instance Data.HFunctor.HTraversable.HTraversable1 (Control.Comonad.Trans.Env.EnvT e)
instance Data.HFunctor.HTraversable.HTraversable1 Data.SOP.NS.NS
instance Data.HFunctor.HTraversable.HTraversable1 (Data.Functor.Day.Day f)
instance Data.HFunctor.HTraversable.HTraversable1 (Data.Functor.Invariant.Day.Day f)
instance Data.HFunctor.HTraversable.HTraversable1 (Data.Functor.Invariant.Night.Night f)
instance forall k (f :: k -> *). Data.HFunctor.HTraversable.HTraversable1 ((GHC.Generics.:*:) f)
instance forall k (f :: k -> *). Data.HFunctor.HTraversable.HTraversable1 (Data.Functor.Product.Product f)
instance forall k (t :: (k -> *) -> k -> *). Data.HFunctor.HTraversable.HTraversable1 t => Data.HFunctor.HTraversable.HTraversable1 (Data.HFunctor.HLift t)
instance forall k (t :: (k -> *) -> k -> *). Data.HFunctor.HTraversable.HTraversable1 t => Data.HFunctor.HTraversable.HTraversable1 (Data.HFunctor.HFree t)
instance Data.HFunctor.HTraversable.HTraversable Data.Functor.Coyoneda.Coyoneda
instance Data.HFunctor.HTraversable.HTraversable Data.Functor.Contravariant.Coyoneda.Coyoneda
instance Data.HFunctor.HTraversable.HTraversable Control.Applicative.Free.Ap
instance Data.HFunctor.HTraversable.HTraversable Control.Applicative.ListF.ListF
instance Data.HFunctor.HTraversable.HTraversable Control.Applicative.ListF.NonEmptyF
instance Data.HFunctor.HTraversable.HTraversable Control.Applicative.ListF.MaybeF
instance Data.HFunctor.HTraversable.HTraversable (Control.Applicative.ListF.MapF k2)
instance Data.HFunctor.HTraversable.HTraversable (Control.Applicative.ListF.NEMapF k2)
instance Data.HFunctor.HTraversable.HTraversable Control.Alternative.Free.Alt
instance Data.HFunctor.HTraversable.HTraversable Control.Alternative.Free.AltF
instance Data.HFunctor.HTraversable.HTraversable Control.Applicative.Step.Step
instance Data.HFunctor.HTraversable.HTraversable Control.Applicative.Step.Steps
instance Data.HFunctor.HTraversable.HTraversable Control.Applicative.Step.Flagged
instance Data.HFunctor.HTraversable.HTraversable Control.Monad.Trans.Maybe.MaybeT
instance Data.HFunctor.HTraversable.HTraversable Control.Applicative.Free.Fast.Ap
instance Data.HFunctor.HTraversable.HTraversable Control.Applicative.Free.Final.Ap
instance Data.HFunctor.HTraversable.HTraversable Control.Monad.Trans.Identity.IdentityT
instance Data.HFunctor.HTraversable.HTraversable Control.Applicative.Lift.Lift
instance Data.HFunctor.HTraversable.HTraversable Data.Functor.Bind.Class.MaybeApply
instance Data.HFunctor.HTraversable.HTraversable Control.Applicative.Backwards.Backwards
instance Data.HFunctor.HTraversable.HTraversable Data.Functor.Bind.Class.WrappedApplicative
instance Data.HFunctor.HTraversable.HTraversable Data.Tagged.Tagged
instance Data.HFunctor.HTraversable.HTraversable Data.Functor.Reverse.Reverse
instance (Data.HFunctor.HTraversable.HTraversable s, Data.HFunctor.HTraversable.HTraversable t) => Data.HFunctor.HTraversable.HTraversable (Control.Monad.Trans.Compose.ComposeT s t)
instance Data.Traversable.Traversable f => Data.HFunctor.HTraversable.HTraversable ((GHC.Generics.:.:) f)
instance Data.HFunctor.HTraversable.HTraversable (GHC.Generics.M1 i c)
instance Data.HFunctor.HTraversable.HTraversable Control.Applicative.Step.Void2
instance Data.HFunctor.HTraversable.HTraversable (Control.Comonad.Trans.Env.EnvT e)
instance Data.HFunctor.HTraversable.HTraversable Data.Vinyl.Core.Rec
instance Data.HFunctor.HTraversable.HTraversable Data.Vinyl.CoRec.CoRec
instance Data.HFunctor.HTraversable.HTraversable Data.SOP.NP.NP
instance Data.HFunctor.HTraversable.HTraversable Data.SOP.NS.NS
instance Data.HFunctor.HTraversable.HTraversable (Data.Functor.Day.Day f)
instance Data.HFunctor.HTraversable.HTraversable (Data.Functor.Invariant.Day.Day f)
instance Data.HFunctor.HTraversable.HTraversable (Data.Functor.Invariant.Night.Night f)
instance forall k (f :: k -> *). Data.HFunctor.HTraversable.HTraversable ((GHC.Generics.:*:) f)
instance forall k (f :: k -> *). Data.HFunctor.HTraversable.HTraversable ((GHC.Generics.:+:) f)
instance forall k (f :: k -> *). Data.HFunctor.HTraversable.HTraversable (Data.Functor.Product.Product f)
instance forall k (f :: k -> *). Data.HFunctor.HTraversable.HTraversable (Data.Functor.Sum.Sum f)
instance forall k1 k2 (f :: k1 -> *). Data.HFunctor.HTraversable.HTraversable (Data.Bifunctor.Joker.Joker f)
instance Data.HFunctor.HTraversable.HTraversable (Data.Functor.These.These1 f)
instance forall k1 k2 k3 (f :: k1). Data.HFunctor.HTraversable.HTraversable (Control.Applicative.Step.Void3 f)
instance Data.HFunctor.HTraversable.HTraversable Data.HFunctor.ProxyF
instance Data.HFunctor.HTraversable.HTraversable (Data.HFunctor.ConstF e)
instance forall k (t :: (k -> *) -> k -> *). Data.HFunctor.HTraversable.HTraversable t => Data.HFunctor.HTraversable.HTraversable (Data.HFunctor.HLift t)
instance forall k (t :: (k -> *) -> k -> *). Data.HFunctor.HTraversable.HTraversable t => Data.HFunctor.HTraversable.HTraversable (Data.HFunctor.HFree t)


-- | This module provides an abstraction for "two-argument functor
--   combinators", <a>HBifunctor</a>, as well as some useful combinators.
module Data.HBifunctor

-- | A <a>HBifunctor</a> is like an <a>HFunctor</a>, but it enhances
--   <i>two</i> different functors instead of just one.
--   
--   Usually, it enhaces them "together" in some sort of combining way.
--   
--   This typeclass provides a uniform instance for "swapping out" or
--   "hoisting" the enhanced functors. We can hoist the first one with
--   <a>hleft</a>, the second one with <a>hright</a>, or both at the same
--   time with <a>hbimap</a>.
--   
--   For example, the <tt>f :*: g</tt> type gives us "both <tt>f</tt> and
--   <tt>g</tt>":
--   
--   <pre>
--   data (f <a>:*:</a> g) a = f a :*: g a
--   </pre>
--   
--   It combines both <tt>f</tt> and <tt>g</tt> into a unified structure
--   --- here, it does it by providing both <tt>f</tt> and <tt>g</tt>.
--   
--   The single law is:
--   
--   <pre>
--   <a>hbimap</a> <a>id</a> id == id
--   </pre>
--   
--   This ensures that <a>hleft</a>, <a>hright</a>, and <a>hbimap</a> do
--   not affect the structure that <tt>t</tt> adds on top of the underlying
--   functors.
class HBifunctor (t :: (k -> Type) -> (k -> Type) -> k -> Type)

-- | Swap out the first transformed functor.
hleft :: HBifunctor t => (f ~> j) -> t f g ~> t j g

-- | Swap out the second transformed functor.
hright :: HBifunctor t => (g ~> l) -> t f g ~> t f l

-- | Swap out both transformed functors at the same time.
hbimap :: HBifunctor t => (f ~> j) -> (g ~> l) -> t f g ~> t j l

-- | Useful newtype to allow us to derive an <a>HFunctor</a> instance from
--   any instance of <a>HBifunctor</a>, using -XDerivingVia.
--   
--   For example, because we have <tt>instance <a>HBifunctor</a>
--   <a>Day</a></tt>, we can write:
--   
--   <pre>
--   deriving via (<a>WrappedHBifunctor</a> <a>Day</a> f) instance <a>HFunctor</a> (<a>Day</a> f)
--   </pre>
--   
--   to give us an automatic <a>HFunctor</a> instance and save us some
--   work.
newtype WrappedHBifunctor t (f :: k -> Type) (g :: k -> Type) (a :: k)
WrapHBifunctor :: t f g a -> WrappedHBifunctor t (f :: k -> Type) (g :: k -> Type) (a :: k)
[unwrapHBifunctor] :: WrappedHBifunctor t (f :: k -> Type) (g :: k -> Type) (a :: k) -> t f g a

-- | Lift two isomorphisms on each side of a bifunctor to become an
--   isomorphism between the two bifunctor applications.
--   
--   Basically, if <tt>f</tt> and <tt>f'</tt> are isomorphic, and
--   <tt>g</tt> and <tt>g'</tt> are isomorphic, then <tt>t f g</tt> is
--   isomorphic to <tt>t f' g'</tt>.
overHBifunctor :: HBifunctor t => (f <~> f') -> (g <~> g') -> t f g <~> t f' g'

-- | An <a>HBifunctor</a> that ignores its second input. Like a <a>:+:</a>
--   with no <a>R1</a>/right branch.
--   
--   This is <a>Joker</a> from <a>Data.Bifunctors.Joker</a>, but given a
--   more sensible name for its purpose.
newtype LeftF f g a
LeftF :: f a -> LeftF f g a
[runLeftF] :: LeftF f g a -> f a

-- | An <a>HBifunctor</a> that ignores its first input. Like a <a>:+:</a>
--   with no <a>L1</a>/left branch.
--   
--   In its polykinded form (on <tt>f</tt>), it is essentially a
--   higher-order version of <a>Tagged</a>.
newtype RightF f g a
RightF :: g a -> RightF f g a
[runRightF] :: RightF f g a -> g a
instance forall k (g :: * -> *) (f :: k). Data.Functor.Classes.Ord1 g => Data.Functor.Classes.Ord1 (Data.HBifunctor.RightF f g)
instance Data.HFunctor.Internal.HBifunctor Data.HBifunctor.RightF
instance forall k1 k2 (g :: k1). Data.HFunctor.Internal.HFunctor (Data.HBifunctor.RightF g)
instance forall k1 k2 (g :: k1). Data.HFunctor.Inject (Data.HBifunctor.RightF g)
instance forall k1 k2 (g :: k1). Data.HFunctor.HTraversable.HTraversable (Data.HBifunctor.RightF g)
instance forall k1 k2 (g :: k1). Data.HFunctor.HBind (Data.HBifunctor.RightF g)
instance forall k1 k2 (g :: k1) (f :: k2 -> *). Data.HFunctor.Interpret.Interpret (Data.HBifunctor.RightF g) f
instance forall k (g :: * -> *) (f :: k). Data.Functor.Classes.Eq1 g => Data.Functor.Classes.Eq1 (Data.HBifunctor.RightF f g)
instance forall k (g :: * -> *) (f :: k). Data.Functor.Classes.Read1 g => Data.Functor.Classes.Read1 (Data.HBifunctor.RightF f g)
instance forall k (g :: * -> *) (f :: k). Data.Functor.Classes.Show1 g => Data.Functor.Classes.Show1 (Data.HBifunctor.RightF f g)
instance forall k1 (f :: k1) k2 (g :: k2 -> *) (a :: k2). (Data.Typeable.Internal.Typeable f, Data.Typeable.Internal.Typeable a, Data.Typeable.Internal.Typeable g, Data.Typeable.Internal.Typeable k1, Data.Typeable.Internal.Typeable k2, Data.Data.Data (g a)) => Data.Data.Data (Data.HBifunctor.RightF f g a)
instance forall k1 (f :: k1) k2 (g :: k2 -> *) (a :: k2). GHC.Generics.Generic (Data.HBifunctor.RightF f g a)
instance forall k (f :: k) (g :: * -> *). Data.Traversable.Traversable g => Data.Traversable.Traversable (Data.HBifunctor.RightF f g)
instance forall k (f :: k) (g :: * -> *). Data.Foldable.Foldable g => Data.Foldable.Foldable (Data.HBifunctor.RightF f g)
instance forall k (f :: k) (g :: * -> *). GHC.Base.Functor g => GHC.Base.Functor (Data.HBifunctor.RightF f g)
instance forall k1 (f :: k1) k2 (g :: k2 -> *) (a :: k2). GHC.Classes.Ord (g a) => GHC.Classes.Ord (Data.HBifunctor.RightF f g a)
instance forall k1 (f :: k1) k2 (g :: k2 -> *) (a :: k2). GHC.Classes.Eq (g a) => GHC.Classes.Eq (Data.HBifunctor.RightF f g a)
instance forall k1 (f :: k1) k2 (g :: k2 -> *) (a :: k2). GHC.Read.Read (g a) => GHC.Read.Read (Data.HBifunctor.RightF f g a)
instance forall k1 (f :: k1) k2 (g :: k2 -> *) (a :: k2). GHC.Show.Show (g a) => GHC.Show.Show (Data.HBifunctor.RightF f g a)
instance Data.Traversable.Traversable f => Data.Bitraversable.Bitraversable (Data.HBifunctor.LeftF f)
instance GHC.Base.Applicative f => Data.Biapplicative.Biapplicative (Data.HBifunctor.LeftF f)
instance Data.HFunctor.Internal.HBifunctor Data.HBifunctor.LeftF
instance forall k1 k2 (f :: k1 -> *). Data.HFunctor.Internal.HFunctor (Data.HBifunctor.LeftF f)
instance forall k1 k2 (f :: k1 -> *). Data.HFunctor.HTraversable.HTraversable (Data.HBifunctor.LeftF f)
instance Data.Foldable.Foldable f => Data.Bifoldable.Bifoldable (Data.HBifunctor.LeftF f)
instance GHC.Base.Functor f => Data.Bifunctor.Bifunctor (Data.HBifunctor.LeftF f)
instance forall k (f :: * -> *) (g :: k). Data.Functor.Classes.Ord1 f => Data.Functor.Classes.Ord1 (Data.HBifunctor.LeftF f g)
instance forall k (f :: * -> *) (g :: k). Data.Functor.Classes.Eq1 f => Data.Functor.Classes.Eq1 (Data.HBifunctor.LeftF f g)
instance forall k (f :: * -> *) (g :: k). Data.Functor.Classes.Read1 f => Data.Functor.Classes.Read1 (Data.HBifunctor.LeftF f g)
instance forall k (f :: * -> *) (g :: k). Data.Functor.Classes.Show1 f => Data.Functor.Classes.Show1 (Data.HBifunctor.LeftF f g)
instance forall k1 (f :: k1 -> *) k2 (g :: k2) (a :: k1). (Data.Typeable.Internal.Typeable g, Data.Typeable.Internal.Typeable a, Data.Typeable.Internal.Typeable f, Data.Typeable.Internal.Typeable k1, Data.Typeable.Internal.Typeable k2, Data.Data.Data (f a)) => Data.Data.Data (Data.HBifunctor.LeftF f g a)
instance forall k1 (f :: k1 -> *) k2 (g :: k2) (a :: k1). GHC.Generics.Generic (Data.HBifunctor.LeftF f g a)
instance forall (f :: * -> *) k (g :: k). Data.Traversable.Traversable f => Data.Traversable.Traversable (Data.HBifunctor.LeftF f g)
instance forall (f :: * -> *) k (g :: k). Data.Foldable.Foldable f => Data.Foldable.Foldable (Data.HBifunctor.LeftF f g)
instance forall (f :: * -> *) k (g :: k). GHC.Base.Functor f => GHC.Base.Functor (Data.HBifunctor.LeftF f g)
instance forall k1 (f :: k1 -> *) k2 (g :: k2) (a :: k1). GHC.Classes.Ord (f a) => GHC.Classes.Ord (Data.HBifunctor.LeftF f g a)
instance forall k1 (f :: k1 -> *) k2 (g :: k2) (a :: k1). GHC.Classes.Eq (f a) => GHC.Classes.Eq (Data.HBifunctor.LeftF f g a)
instance forall k1 (f :: k1 -> *) k2 (g :: k2) (a :: k1). GHC.Read.Read (f a) => GHC.Read.Read (Data.HBifunctor.LeftF f g a)
instance forall k1 (f :: k1 -> *) k2 (g :: k2) (a :: k1). GHC.Show.Show (f a) => GHC.Show.Show (Data.HBifunctor.LeftF f g a)


-- | Provides free structures for the various typeclasses of the
--   <a>Divisible</a> hierarchy.
module Data.Functor.Contravariant.Divisible.Free

-- | The free <a>Divisible</a>. Used to sequence multiple contravariant
--   consumers, splitting out the input across all consumers.
--   
--   This type is essentially <a>ListF</a>; the only reason why it has to
--   exist separately outside of <a>ListF</a> is because the current
--   typeclass hierarchy isn't compatible with both the covariant
--   <a>Interpret</a> instance (requiring <tt>Plus</tt>) and the
--   contravariant <a>Interpret</a> instance (requiring <a>Divisible</a>).
--   
--   The wrapping in <a>Coyoneda</a> is also to provide a usable
--   <a>Associative</a> instance for the contravariant <a>Day</a>.
newtype Div f a
Div :: [Coyoneda f a] -> Div f a
[unDiv] :: Div f a -> [Coyoneda f a]

-- | Pattern matching on an empty <a>Div</a>.
--   
--   Before v0.3.3.0, this used to be the concrete constructor of
--   <a>Div</a>. After, it is now an abstract pattern.
pattern Conquer :: Div f a

-- | Pattern matching on a non-empty <a>Div</a>, exposing the raw
--   <tt>f</tt> instead of having it wrapped in a <a>Coyoneda</a>. This is
--   the analogue of <a>Pure</a> and essentially treats the "cons" of the
--   <a>Div</a> as a contravariant day convolution.
--   
--   Before v0.3.3.0, this used to be the concrete constructor of
--   <a>Div</a>. After, it is now an abstract pattern.
pattern Divide :: (a -> (b, c)) -> f b -> Div f c -> Div f a

-- | Map over the undering context in a <a>Div</a>.
hoistDiv :: forall f g. (f ~> g) -> Div f ~> Div g

-- | Inject a single action in <tt>f</tt> into a <tt><a>Div</a> f</tt>.
liftDiv :: f ~> Div f

-- | Interpret a <a>Div</a> into a context <tt>g</tt>, provided <tt>g</tt>
--   is <a>Divisible</a>.
runDiv :: forall f g. Divisible g => (f ~> g) -> Div f ~> g

-- | <a>Div</a> is isomorphic to <a>ListF</a> for contravariant <tt>f</tt>.
--   This witnesses one way of that isomorphism.
divListF :: forall f. Contravariant f => Div f ~> ListF f

-- | <a>Div</a> is isomorphic to <a>ListF</a> for contravariant <tt>f</tt>.
--   This witnesses one way of that isomorphism.
listFDiv :: ListF f ~> Div f

-- | The free <a>Divise</a>: a non-empty version of <a>Div</a>.
--   
--   This type is essentially <a>NonEmptyF</a>; the only reason why it has
--   to exist separately outside of <a>NonEmptyF</a> is because the current
--   typeclass hierarchy isn't compatible with both the covariant
--   <a>Interpret</a> instance (requiring <tt>Plus</tt>) and the
--   contravariant <a>Interpret</a> instance (requiring <a>Divisible</a>).
--   
--   The wrapping in <a>Coyoneda</a> is also to provide a usable
--   <a>Associative</a> instance for the contravariant <a>Day</a>.
newtype Div1 f a
Div1 :: NonEmpty (Coyoneda f a) -> Div1 f a
[unDiv1] :: Div1 f a -> NonEmpty (Coyoneda f a)

-- | Pattern matching on a <a>Div1</a>, exposing the raw <tt>f</tt> instead
--   of having it wrapped in a <a>Coyoneda</a>. This is the analogue of
--   <a>Ap1</a> and essentially treats the "cons" of the <a>Div1</a> as a
--   contravariant day convolution.
--   
--   Before v0.3.3.0, this used to be the concrete constructor of
--   <a>Div1</a>. After, it is now an abstract pattern.
pattern Div1_ :: (a -> (b, c)) -> f b -> Div f c -> Div1 f a

-- | Map over the underlying context in a <a>Div1</a>.
hoistDiv1 :: (f ~> g) -> Div1 f ~> Div1 g

-- | Inject a single action in <tt>f</tt> into a <tt><a>Div</a> f</tt>.
liftDiv1 :: f ~> Div1 f

-- | A <a>Div1</a> is a "non-empty" <a>Div</a>; this function "forgets" the
--   non-empty property and turns it back into a normal <a>Div</a>.
toDiv :: Div1 f ~> Div f

-- | Interpret a <a>Div1</a> into a context <tt>g</tt>, provided <tt>g</tt>
--   is <a>Divise</a>.
runDiv1 :: Divise g => (f ~> g) -> Div1 f ~> g

-- | <a>Div1</a> is isomorphic to <a>NonEmptyF</a> for contravariant
--   <tt>f</tt>. This witnesses one way of that isomorphism.
div1NonEmptyF :: Contravariant f => Div1 f ~> NonEmptyF f

-- | <a>Div1</a> is isomorphic to <a>NonEmptyF</a> for contravariant
--   <tt>f</tt>. This witnesses one way of that isomorphism.
nonEmptyFDiv1 :: NonEmptyF f ~> Div1 f

-- | The free <a>Decide</a>. Used to aggregate multiple possible consumers,
--   directing the input into an appropriate consumer.
data Dec :: (Type -> Type) -> Type -> Type
[Lose] :: (a -> Void) -> Dec f a
[Choose] :: (a -> Either b c) -> f b -> Dec f c -> Dec f a

-- | Map over the underlying context in a <a>Dec</a>.
hoistDec :: forall f g. (f ~> g) -> Dec f ~> Dec g

-- | Inject a single action in <tt>f</tt> into a <tt><a>Dec</a> f</tt>.
liftDec :: f ~> Dec f

-- | Interpret a <a>Dec</a> into a context <tt>g</tt>, provided <tt>g</tt>
--   is <a>Conclude</a>.
runDec :: forall f g. Conclude g => (f ~> g) -> Dec f ~> g

-- | The free <a>Decide</a>: a non-empty version of <a>Dec</a>.
data Dec1 :: (Type -> Type) -> Type -> Type
[Dec1] :: (a -> Either b c) -> f b -> Dec f c -> Dec1 f a

-- | Map over the undering context in a <a>Dec1</a>.
hoistDec1 :: forall f g. (f ~> g) -> Dec1 f ~> Dec1 g

-- | Inject a single action in <tt>f</tt> into a <tt><a>Dec1</a> f</tt>.
liftDec1 :: f ~> Dec1 f

-- | A <a>Dec1</a> is a "non-empty" <a>Dec</a>; this function "forgets" the
--   non-empty property and turns it back into a normal <a>Dec</a>.
toDec :: Dec1 f a -> Dec f a

-- | Interpret a <a>Dec1</a> into a context <tt>g</tt>, provided <tt>g</tt>
--   is <a>Decide</a>.
runDec1 :: Decide g => (f ~> g) -> Dec1 f ~> g
instance Data.HFunctor.Inject Data.Functor.Contravariant.Divisible.Free.Div
instance Data.HFunctor.Internal.HFunctor Data.Functor.Contravariant.Divisible.Free.Div
instance Data.Functor.Contravariant.Divisible.Divisible (Data.Functor.Contravariant.Divisible.Free.Div f)
instance Data.Functor.Contravariant.Divise.Divise (Data.Functor.Contravariant.Divisible.Free.Div f)
instance Data.Functor.Contravariant.Contravariant (Data.Functor.Contravariant.Divisible.Free.Div f)
instance Data.HFunctor.Inject Data.Functor.Contravariant.Divisible.Free.Div1
instance Data.HFunctor.Internal.HFunctor Data.Functor.Contravariant.Divisible.Free.Div1
instance Data.Functor.Contravariant.Divise.Divise (Data.Functor.Contravariant.Divisible.Free.Div1 f)
instance Data.Functor.Contravariant.Contravariant (Data.Functor.Contravariant.Divisible.Free.Div1 f)
instance Data.Functor.Contravariant.Contravariant (Data.Functor.Contravariant.Divisible.Free.Dec1 f)
instance Data.Functor.Invariant.Invariant (Data.Functor.Contravariant.Divisible.Free.Dec1 f)
instance Data.Functor.Contravariant.Decide.Decide (Data.Functor.Contravariant.Divisible.Free.Dec1 f)
instance Data.HFunctor.Internal.HFunctor Data.Functor.Contravariant.Divisible.Free.Dec1
instance Data.HFunctor.Inject Data.Functor.Contravariant.Divisible.Free.Dec1
instance Data.Functor.Contravariant.Decide.Decide f => Data.HFunctor.Interpret.Interpret Data.Functor.Contravariant.Divisible.Free.Dec1 f
instance Data.HFunctor.HTraversable.HTraversable Data.Functor.Contravariant.Divisible.Free.Dec1
instance Data.HFunctor.HTraversable.HTraversable1 Data.Functor.Contravariant.Divisible.Free.Dec1
instance Data.Functor.Contravariant.Contravariant (Data.Functor.Contravariant.Divisible.Free.Dec f)
instance Data.Functor.Invariant.Invariant (Data.Functor.Contravariant.Divisible.Free.Dec f)
instance Data.Functor.Contravariant.Decide.Decide (Data.Functor.Contravariant.Divisible.Free.Dec f)
instance Data.Functor.Contravariant.Conclude.Conclude (Data.Functor.Contravariant.Divisible.Free.Dec f)
instance Data.HFunctor.Internal.HFunctor Data.Functor.Contravariant.Divisible.Free.Dec
instance Data.HFunctor.Inject Data.Functor.Contravariant.Divisible.Free.Dec
instance Data.Functor.Contravariant.Conclude.Conclude f => Data.HFunctor.Interpret.Interpret Data.Functor.Contravariant.Divisible.Free.Dec f
instance Data.HFunctor.HTraversable.HTraversable Data.Functor.Contravariant.Divisible.Free.Dec
instance Data.HFunctor.HTraversable.HTraversable Data.Functor.Contravariant.Divisible.Free.Div1
instance Data.HFunctor.HTraversable.HTraversable1 Data.Functor.Contravariant.Divisible.Free.Div1
instance Data.Functor.Invariant.Invariant (Data.Functor.Contravariant.Divisible.Free.Div1 f)
instance Data.Functor.Contravariant.Divise.Divise f => Data.HFunctor.Interpret.Interpret Data.Functor.Contravariant.Divisible.Free.Div1 f
instance Data.HFunctor.HTraversable.HTraversable Data.Functor.Contravariant.Divisible.Free.Div
instance Data.Functor.Invariant.Invariant (Data.Functor.Contravariant.Divisible.Free.Div f)
instance Data.Functor.Contravariant.Divisible.Divisible f => Data.HFunctor.Interpret.Interpret Data.Functor.Contravariant.Divisible.Free.Div f


-- | The free <a>Apply</a>. Provides <a>Ap1</a> and various utility
--   methods. See <a>Ap1</a> for more details.
--   
--   Ideally <a>Ap1</a> would be in the <i>free</i> package. However, it is
--   defined here for now.
module Data.Functor.Apply.Free

-- | One or more <tt>f</tt>s convolved with itself.
--   
--   Essentially:
--   
--   <pre>
--   <a>Ap1</a> f
--       ~ f                            -- one f
--     <a>:+:</a> (f `<a>Day</a>` f)          -- two f's
--     :+: (f `Day` f `Day` f)           -- three f's
--     :+: (f `Day` f `Day` f `Day` f)  -- four f's
--     :+: ...                          -- etc.
--   </pre>
--   
--   Useful if you want to promote an <tt>f</tt> to a situation with "at
--   least one <tt>f</tt> sequenced with itself".
--   
--   Mostly useful for its <a>HFunctor</a> and <a>Interpret</a> instance,
--   along with its relationship with <a>Ap</a> and <a>Day</a>.
--   
--   This is the free <a>Apply</a> --- Basically a "non-empty" <a>Ap</a>.
--   
--   The construction here is based on <a>Ap</a>, similar to now
--   <a>NonEmpty</a> is built on list.
data Ap1 :: (Type -> Type) -> Type -> Type
[Ap1] :: f a -> Ap f (a -> b) -> Ap1 f b

-- | An <tt><a>Ap1</a> f</tt> is just a <tt><a>Day</a> f (<a>Ap</a>
--   f)</tt>. This bidirectional pattern synonym lets you treat it as such.
pattern DayAp1 :: Day f (Ap f) a -> Ap1 f a

-- | An <a>Ap1</a> is a "non-empty" <a>Ap</a>; this function "forgets" the
--   non-empty property and turns it back into a normal <a>Ap</a>.
toAp :: Ap1 f ~> Ap f

-- | Convert an <a>Ap</a> into an <a>Ap1</a> if possible. If the <a>Ap</a>
--   was "empty", return the <a>Pure</a> value instead.
fromAp :: Ap f ~> (Identity :+: Ap1 f)

-- | Embed an <tt>f</tt> into <a>Ap1</a>.
liftAp1 :: f ~> Ap1 f

-- | Extract the <tt>f</tt> out of the <a>Ap1</a>.
--   
--   <pre>
--   <a>retractAp1</a> . <a>liftAp1</a> == id
--   </pre>
retractAp1 :: Apply f => Ap1 f ~> f

-- | Interpret an <tt><a>Ap</a> f</tt> into some <a>Apply</a> context
--   <tt>g</tt>.
runAp1 :: Apply g => (f ~> g) -> Ap1 f ~> g
instance GHC.Base.Functor (Data.Functor.Apply.Free.Ap1 f)
instance Data.Functor.Invariant.Invariant (Data.Functor.Apply.Free.Ap1 f)
instance Data.Functor.Bind.Class.Apply (Data.Functor.Apply.Free.Ap1 f)
instance Data.HFunctor.Internal.HFunctor Data.Functor.Apply.Free.Ap1
instance Data.HFunctor.Inject Data.Functor.Apply.Free.Ap1
instance Data.HFunctor.HBind Data.Functor.Apply.Free.Ap1
instance Data.HFunctor.HTraversable.HTraversable Data.Functor.Apply.Free.Ap1
instance Data.HFunctor.HTraversable.HTraversable1 Data.Functor.Apply.Free.Ap1
instance Data.Functor.Bind.Class.Apply f => Data.HFunctor.Interpret.Interpret Data.Functor.Apply.Free.Ap1 f


-- | This module provides tools for working with binary functor combinators
--   that represent interpretable schemas.
--   
--   These are types <tt><a>HBifunctor</a> t</tt> that take two functors
--   <tt>f</tt> and <tt>g</tt> and returns a new functor <tt>t f g</tt>,
--   that "mixes together" <tt>f</tt> and <tt>g</tt> in some way.
--   
--   The high-level usage of this is
--   
--   <pre>
--   <a>biretract</a> :: <a>SemigroupIn</a> t f =&gt; t f f ~&gt; f
--   </pre>
--   
--   which lets you fully "mix" together the two input functors.
--   
--   <pre>
--   <a>biretract</a> :: (f <a>:+:</a> f) a -&gt; f a
--   biretract :: <a>Plus</a> f =&gt; (f <a>:*:</a> f) a -&gt; f a
--   biretract :: <a>Applicative</a> f =&gt; <a>Day</a> f f a -&gt; f a
--   biretract :: <a>Monad</a> f =&gt; <a>Comp</a> f f a -&gt; f a
--   </pre>
--   
--   See <a>Data.HBifunctor.Tensor</a> for the next stage of structure in
--   tensors and moving in and out of them.
module Data.HBifunctor.Associative

-- | An <a>HBifunctor</a> where it doesn't matter which binds first is
--   <a>Associative</a>. Knowing this gives us a lot of power to rearrange
--   the internals of our <a>HFunctor</a> at will.
--   
--   For example, for the functor product:
--   
--   <pre>
--   data (f <a>:*:</a> g) a = f a :*: g a
--   </pre>
--   
--   We know that <tt>f :*: (g :*: h)</tt> is the same as <tt>(f :*: g) :*:
--   h</tt>.
--   
--   Formally, we can say that <tt>t</tt> enriches a the category of
--   endofunctors with semigroup strcture: it turns our endofunctor
--   category into a "semigroupoidal category".
--   
--   Different instances of <tt>t</tt> each enrich the endofunctor category
--   in different ways, giving a different semigroupoidal category.
class (HBifunctor t, Inject (NonEmptyBy t)) => Associative t where {
    
    -- | The "semigroup functor combinator" generated by <tt>t</tt>.
    --   
    --   A value of type <tt>NonEmptyBy t f a</tt> is <i>equivalent</i> to one
    --   of:
    --   
    --   <ul>
    --   <li><pre>f a</pre></li>
    --   <li><pre>t f f a</pre></li>
    --   <li><pre>t f (t f f) a</pre></li>
    --   <li><pre>t f (t f (t f f)) a</pre></li>
    --   <li><pre>t f (t f (t f (t f f))) a</pre></li>
    --   <li>.. etc</li>
    --   </ul>
    --   
    --   For example, for <a>:*:</a>, we have <a>NonEmptyF</a>. This is
    --   because:
    --   
    --   <pre>
    --   x             ~ <a>NonEmptyF</a> (x <a>:|</a> [])      ~ <a>inject</a> x
    --   x <a>:*:</a> y       ~ NonEmptyF (x :| [y])     ~ <a>toNonEmptyBy</a> (x :*: y)
    --   x :*: y :*: z ~ NonEmptyF (x :| [y,z])
    --   -- etc.
    --   </pre>
    --   
    --   You can create an "singleton" one with <a>inject</a>, or else one from
    --   a single <tt>t f f</tt> with <a>toNonEmptyBy</a>.
    --   
    --   See <a>ListBy</a> for a "possibly empty" version of this type.
    type family NonEmptyBy t :: (Type -> Type) -> Type -> Type;
    
    -- | A description of "what type of Functor" this tensor is expected to be
    --   applied to. This should typically always be either <a>Functor</a>,
    --   <a>Contravariant</a>, or <a>Invariant</a>.
    type family FunctorBy t :: (Type -> Type) -> Constraint;
    type FunctorBy t = Unconstrained;
}

-- | The isomorphism between <tt>t f (t g h) a</tt> and <tt>t (t f g) h
--   a</tt>. To use this isomorphism, see <a>assoc</a> and <a>disassoc</a>.
associating :: (Associative t, FunctorBy t f, FunctorBy t g, FunctorBy t h) => t f (t g h) <~> t (t f g) h

-- | If a <tt><a>NonEmptyBy</a> t f</tt> represents multiple applications
--   of <tt>t f</tt> to itself, then we can also "append" two
--   <tt><a>NonEmptyBy</a> t f</tt>s applied to themselves into one giant
--   <tt><a>NonEmptyBy</a> t f</tt> containing all of the <tt>t f</tt>s.
--   
--   Note that this essentially gives an instance for
--   <tt><a>SemigroupIn</a> t (NonEmptyBy t f)</tt>, for any functor
--   <tt>f</tt>.
appendNE :: Associative t => t (NonEmptyBy t f) (NonEmptyBy t f) ~> NonEmptyBy t f

-- | If a <tt><a>NonEmptyBy</a> t f</tt> represents multiple applications
--   of <tt>t f</tt> to itself, then we can split it based on whether or
--   not it is just a single <tt>f</tt> or at least one top-level
--   application of <tt>t f</tt>.
--   
--   Note that you can recursively "unroll" a <a>NonEmptyBy</a> completely
--   into a <a>Chain1</a> by using <a>unrollNE</a>.
matchNE :: (Associative t, FunctorBy t f) => NonEmptyBy t f ~> (f :+: t f (NonEmptyBy t f))

-- | Prepend an application of <tt>t f</tt> to the front of a
--   <tt><a>NonEmptyBy</a> t f</tt>.
consNE :: Associative t => t f (NonEmptyBy t f) ~> NonEmptyBy t f

-- | Embed a direct application of <tt>f</tt> to itself into a
--   <tt><a>NonEmptyBy</a> t f</tt>.
toNonEmptyBy :: Associative t => t f f ~> NonEmptyBy t f

-- | Reassociate an application of <tt>t</tt>.
assoc :: (Associative t, FunctorBy t f, FunctorBy t g, FunctorBy t h) => t f (t g h) ~> t (t f g) h

-- | Reassociate an application of <tt>t</tt>.
disassoc :: (Associative t, FunctorBy t f, FunctorBy t g, FunctorBy t h) => t (t f g) h ~> t f (t g h)

-- | For different <tt><a>Associative</a> t</tt>, we have functors
--   <tt>f</tt> that we can "squash", using <a>biretract</a>:
--   
--   <pre>
--   t f f ~&gt; f
--   </pre>
--   
--   This gives us the ability to squash applications of <tt>t</tt>.
--   
--   Formally, if we have <tt><a>Associative</a> t</tt>, we are enriching
--   the category of endofunctors with semigroup structure, turning it into
--   a semigroupoidal category. Different choices of <tt>t</tt> give
--   different semigroupoidal categories.
--   
--   A functor <tt>f</tt> is known as a "semigroup in the (semigroupoidal)
--   category of endofunctors on <tt>t</tt>" if we can <a>biretract</a>:
--   
--   <pre>
--   t f f ~&gt; f
--   </pre>
--   
--   This gives us a few interesting results in category theory, which you
--   can stil reading about if you don't care:
--   
--   <ul>
--   <li><i>All</i> functors are semigroups in the semigroupoidal category
--   on <a>:+:</a></li>
--   <li>The class of functors that are semigroups in the semigroupoidal
--   category on <a>:*:</a> is exactly the functors that are instances of
--   <a>Alt</a>.</li>
--   <li>The class of functors that are semigroups in the semigroupoidal
--   category on <a>Day</a> is exactly the functors that are instances of
--   <a>Apply</a>.</li>
--   <li>The class of functors that are semigroups in the semigroupoidal
--   category on <a>Comp</a> is exactly the functors that are instances of
--   <a>Bind</a>.</li>
--   </ul>
--   
--   Note that instances of this class are <i>intended</i> to be written
--   with <tt>t</tt> as a fixed type constructor, and <tt>f</tt> to be
--   allowed to vary freely:
--   
--   <pre>
--   instance Bind f =&gt; SemigroupIn Comp f
--   </pre>
--   
--   Any other sort of instance and it's easy to run into problems with
--   type inference. If you want to write an instance that's "polymorphic"
--   on tensor choice, use the <a>WrapHBF</a> newtype wrapper over a type
--   variable, where the second argument also uses a type constructor:
--   
--   <pre>
--   instance SemigroupIn (WrapHBF t) (MyFunctor t i)
--   </pre>
--   
--   This will prevent problems with overloaded instances.
class (Associative t, FunctorBy t f) => SemigroupIn t f

-- | The <a>HBifunctor</a> analogy of <a>retract</a>. It retracts
--   <i>both</i> <tt>f</tt>s into a single <tt>f</tt>, effectively fully
--   mixing them together.
--   
--   This function makes <tt>f</tt> a semigroup in the category of
--   endofunctors with respect to tensor <tt>t</tt>.
biretract :: SemigroupIn t f => t f f ~> f

-- | The <a>HBifunctor</a> analogy of <a>retract</a>. It retracts
--   <i>both</i> <tt>f</tt>s into a single <tt>f</tt>, effectively fully
--   mixing them together.
--   
--   This function makes <tt>f</tt> a semigroup in the category of
--   endofunctors with respect to tensor <tt>t</tt>.
biretract :: (SemigroupIn t f, Interpret (NonEmptyBy t) f) => t f f ~> f

-- | The <a>HBifunctor</a> analogy of <a>interpret</a>. It takes two
--   interpreting functions, and mixes them together into a target functor
--   <tt>h</tt>.
--   
--   Note that this is useful in the poly-kinded case, but it is not
--   possible to define generically for all <a>SemigroupIn</a> because it
--   only is defined for <tt>Type -&gt; Type</tt> inputes. See <a>!+!</a>
--   for a version that is poly-kinded for <a>:+:</a> in specific.
binterpret :: SemigroupIn t f => (g ~> f) -> (h ~> f) -> t g h ~> f

-- | The <a>HBifunctor</a> analogy of <a>interpret</a>. It takes two
--   interpreting functions, and mixes them together into a target functor
--   <tt>h</tt>.
--   
--   Note that this is useful in the poly-kinded case, but it is not
--   possible to define generically for all <a>SemigroupIn</a> because it
--   only is defined for <tt>Type -&gt; Type</tt> inputes. See <a>!+!</a>
--   for a version that is poly-kinded for <a>:+:</a> in specific.
binterpret :: (SemigroupIn t f, Interpret (NonEmptyBy t) f) => (g ~> f) -> (h ~> f) -> t g h ~> f

-- | An <tt><a>NonEmptyBy</a> t f</tt> represents the successive
--   application of <tt>t</tt> to <tt>f</tt>, over and over again. So, that
--   means that an <tt><a>NonEmptyBy</a> t f</tt> must either be a single
--   <tt>f</tt>, or an <tt>t f (NonEmptyBy t f)</tt>.
--   
--   <a>matchingNE</a> states that these two are isomorphic. Use
--   <a>matchNE</a> and <tt><a>inject</a> <a>!*!</a> <a>consNE</a></tt> to
--   convert between one and the other.
matchingNE :: (Associative t, FunctorBy t f) => NonEmptyBy t f <~> (f :+: t f (NonEmptyBy t f))

-- | An implementation of <a>retract</a> that works for any instance of
--   <tt><a>SemigroupIn</a> t</tt> for <tt><a>NonEmptyBy</a> t</tt>.
--   
--   Can be useful as a default implementation if you already have
--   <a>SemigroupIn</a> implemented.
retractNE :: forall t f. SemigroupIn t f => NonEmptyBy t f ~> f

-- | An implementation of <a>interpret</a> that works for any instance of
--   <tt><a>SemigroupIn</a> t</tt> for <tt><a>NonEmptyBy</a> t</tt>.
--   
--   Can be useful as a default implementation if you already have
--   <a>SemigroupIn</a> implemented.
interpretNE :: forall t g f. SemigroupIn t f => (g ~> f) -> NonEmptyBy t g ~> f

-- | Useful wrapper over <a>binterpret</a> to allow you to directly extract
--   a value <tt>b</tt> out of the <tt>t f g a</tt>, if you can convert an
--   <tt>f x</tt> and <tt>g x</tt> into <tt>b</tt>.
--   
--   Note that depending on the constraints on <tt>h</tt> in
--   <tt><a>SemigroupIn</a> t h</tt>, you may have extra constraints on
--   <tt>b</tt>.
--   
--   <ul>
--   <li>If <tt>h</tt> is unconstrained, there are no constraints on
--   <tt>b</tt></li>
--   <li>If <tt>h</tt> must be <a>Apply</a>, <a>Alt</a>, <a>Divise</a>, or
--   <a>Decide</a>, <tt>b</tt> needs to be an instance of
--   <a>Semigroup</a></li>
--   <li>If <tt>h</tt> is <a>Applicative</a>, <a>Plus</a>,
--   <a>Divisible</a>, or <a>Conclude</a>, <tt>b</tt> needs to be an
--   instance of <a>Monoid</a></li>
--   </ul>
--   
--   For some constraints (like <a>Monad</a>), this will not be usable.
--   
--   <pre>
--   -- Return the length of either the list, or the Map, depending on which
--   --   one s in the <a>+</a>
--   <a>biget</a> <a>length</a> length
--       :: ([] :+: <a>Map</a> <a>Int</a>) <a>Char</a>
--       -&gt; Int
--   
--   -- Return the length of both the list and the map, added together
--   <a>biget</a> (<a>Sum</a> . length) (Sum . length)
--       :: <a>Day</a> [] (Map Int) Char
--       -&gt; Sum Int
--   </pre>
biget :: SemigroupIn t (AltConst b) => (forall x. f x -> b) -> (forall x. g x -> b) -> t f g a -> b

-- | Useful wrapper over <a>binterpret</a> to allow you to directly extract
--   a value <tt>b</tt> out of the <tt>t f g a</tt>, if you can convert an
--   <tt>f x</tt> and <tt>g x</tt> into <tt>b</tt>, given an <tt>x</tt>
--   input.
--   
--   Note that depending on the constraints on <tt>h</tt> in
--   <tt><a>SemigroupIn</a> t h</tt>, you may have extra constraints on
--   <tt>b</tt>.
--   
--   <ul>
--   <li>If <tt>h</tt> is unconstrained, there are no constraints on
--   <tt>b</tt></li>
--   <li>If <tt>h</tt> must be <a>Divise</a>, or <tt>Divisible</tt>,
--   <tt>b</tt> needs to be an instance of <a>Semigroup</a></li>
--   <li>If <tt>h</tt> must be <tt>Divisible</tt>, then <tt>b</tt> needs to
--   be an instance of <a>Monoid</a>.</li>
--   </ul>
--   
--   For some constraints (like <a>Monad</a>), this will not be usable.
biapply :: SemigroupIn t (Op b) => (forall x. f x -> x -> b) -> (forall x. g x -> x -> b) -> t f g a -> a -> b

-- | Infix alias for <a>binterpret</a>
--   
--   Note that this is useful in the poly-kinded case, but it is not
--   possible to define generically for all <a>SemigroupIn</a> because it
--   only is defined for <tt>Type -&gt; Type</tt> inputes. See <a>!+!</a>
--   for a version that is poly-kinded for <a>:+:</a> in specific.
(!*!) :: SemigroupIn t h => (f ~> h) -> (g ~> h) -> t f g ~> h
infixr 5 !*!

-- | Infix alias for <a>biget</a>
--   
--   <pre>
--   -- Return the length of either the list, or the Map, depending on which
--   --   one s in the <a>+</a>
--   <a>length</a> <a>!$!</a> length
--       :: ([] :+: <a>Map</a> <a>Int</a>) <a>Char</a>
--       -&gt; Int
--   
--   -- Return the length of both the list and the map, added together
--   <a>Sum</a> . length !$! Sum . length
--       :: <a>Day</a> [] (Map Int) Char
--       -&gt; Sum Int
--   </pre>
(!$!) :: SemigroupIn t (AltConst b) => (forall x. f x -> b) -> (forall x. g x -> b) -> t f g a -> b
infixr 5 !$!

-- | A version of <a>!*!</a> specifically for <a>:+:</a> that is
--   poly-kinded
(!+!) :: (f ~> h) -> (g ~> h) -> (f :+: g) ~> h
infixr 5 !+!

-- | A newtype wrapper meant to be used to define polymorphic
--   <a>SemigroupIn</a> instances. See documentation for <a>SemigroupIn</a>
--   for more information.
--   
--   Please do not ever define an instance of <a>SemigroupIn</a> "naked" on
--   the second parameter:
--   
--   <pre>
--   instance SemigroupIn (WrapHBF t) f
--   </pre>
--   
--   As that would globally ruin everything using <a>WrapHBF</a>.
newtype WrapHBF t f g a
WrapHBF :: t f g a -> WrapHBF t f g a
[unwrapHBF] :: WrapHBF t f g a -> t f g a

-- | Any <tt><a>NonEmptyBy</a> t f</tt> is a <tt><a>SemigroupIn</a> t</tt>
--   if we have <tt><a>Associative</a> t</tt>. This newtype wrapper
--   witnesses that fact. We require a newtype wrapper to avoid overlapping
--   instances.
newtype WrapNE t f a
WrapNE :: NonEmptyBy t f a -> WrapNE t f a
[unwrapNE] :: WrapNE t f a -> NonEmptyBy t f a
instance forall k1 k2 k3 (t :: k1 -> k2 -> k3 -> *) (f :: k1) (g :: k2) (a :: k3). (Data.Typeable.Internal.Typeable f, Data.Typeable.Internal.Typeable g, Data.Typeable.Internal.Typeable a, Data.Typeable.Internal.Typeable t, Data.Typeable.Internal.Typeable k1, Data.Typeable.Internal.Typeable k2, Data.Typeable.Internal.Typeable k3, Data.Data.Data (t f g a)) => Data.Data.Data (Data.HBifunctor.Associative.WrapHBF t f g a)
instance forall k1 k2 k3 (t :: k1 -> k2 -> k3 -> *) (f :: k1) (g :: k2) (a :: k3). GHC.Generics.Generic (Data.HBifunctor.Associative.WrapHBF t f g a)
instance forall k1 k2 (t :: k1 -> k2 -> * -> *) (f :: k1) (g :: k2). Data.Traversable.Traversable (t f g) => Data.Traversable.Traversable (Data.HBifunctor.Associative.WrapHBF t f g)
instance forall k1 k2 (t :: k1 -> k2 -> * -> *) (f :: k1) (g :: k2). Data.Foldable.Foldable (t f g) => Data.Foldable.Foldable (Data.HBifunctor.Associative.WrapHBF t f g)
instance forall k1 k2 (t :: k1 -> k2 -> * -> *) (f :: k1) (g :: k2). GHC.Base.Functor (t f g) => GHC.Base.Functor (Data.HBifunctor.Associative.WrapHBF t f g)
instance forall k1 k2 k3 (t :: k1 -> k2 -> k3 -> *) (f :: k1) (g :: k2) (a :: k3). GHC.Classes.Ord (t f g a) => GHC.Classes.Ord (Data.HBifunctor.Associative.WrapHBF t f g a)
instance forall k1 k2 k3 (t :: k1 -> k2 -> k3 -> *) (f :: k1) (g :: k2) (a :: k3). GHC.Classes.Eq (t f g a) => GHC.Classes.Eq (Data.HBifunctor.Associative.WrapHBF t f g a)
instance forall k1 k2 k3 (t :: k1 -> k2 -> k3 -> *) (f :: k1) (g :: k2) (a :: k3). GHC.Read.Read (t f g a) => GHC.Read.Read (Data.HBifunctor.Associative.WrapHBF t f g a)
instance forall k1 k2 k3 (t :: k1 -> k2 -> k3 -> *) (f :: k1) (g :: k2) (a :: k3). GHC.Show.Show (t f g a) => GHC.Show.Show (Data.HBifunctor.Associative.WrapHBF t f g a)
instance forall k (t :: (k -> *) -> (k -> *) -> k -> *) (f :: k -> *). Data.HFunctor.Internal.HBifunctor t => Data.HFunctor.Internal.HFunctor (Data.HBifunctor.Associative.WrapHBF t f)
instance GHC.Base.Functor (Data.HBifunctor.Associative.NonEmptyBy t f) => GHC.Base.Functor (Data.HBifunctor.Associative.WrapNE t f)
instance Data.Functor.Contravariant.Contravariant (Data.HBifunctor.Associative.NonEmptyBy t f) => Data.Functor.Contravariant.Contravariant (Data.HBifunctor.Associative.WrapNE t f)
instance Data.Functor.Invariant.Invariant (Data.HBifunctor.Associative.NonEmptyBy t f) => Data.Functor.Invariant.Invariant (Data.HBifunctor.Associative.WrapNE t f)
instance (Data.HBifunctor.Associative.Associative t, Data.HBifunctor.Associative.FunctorBy t f, Data.HBifunctor.Associative.FunctorBy t (Data.HBifunctor.Associative.WrapNE t f)) => Data.HBifunctor.Associative.SemigroupIn (Data.HBifunctor.Associative.WrapHBF t) (Data.HBifunctor.Associative.WrapNE t f)
instance forall k1 k2 (t :: k1 -> k2 -> * -> *) (f :: k1) (g :: k2). Data.Functor.Classes.Show1 (t f g) => Data.Functor.Classes.Show1 (Data.HBifunctor.Associative.WrapHBF t f g)
instance forall k1 k2 (t :: k1 -> k2 -> * -> *) (f :: k1) (g :: k2). Data.Functor.Classes.Eq1 (t f g) => Data.Functor.Classes.Eq1 (Data.HBifunctor.Associative.WrapHBF t f g)
instance forall k1 k2 (t :: k1 -> k2 -> * -> *) (f :: k1) (g :: k2). Data.Functor.Classes.Ord1 (t f g) => Data.Functor.Classes.Ord1 (Data.HBifunctor.Associative.WrapHBF t f g)
instance forall k (t :: (k -> *) -> (k -> *) -> k -> *). Data.HFunctor.Internal.HBifunctor t => Data.HFunctor.Internal.HBifunctor (Data.HBifunctor.Associative.WrapHBF t)
instance Data.HBifunctor.Associative.Associative t => Data.HBifunctor.Associative.Associative (Data.HBifunctor.Associative.WrapHBF t)
instance Data.Functor.Alt.Alt f => Data.HBifunctor.Associative.SemigroupIn (GHC.Generics.:*:) f
instance Data.Functor.Alt.Alt f => Data.HBifunctor.Associative.SemigroupIn Data.Functor.Product.Product f
instance Data.Functor.Bind.Class.Apply f => Data.HBifunctor.Associative.SemigroupIn Data.Functor.Day.Day f
instance Data.Functor.Contravariant.Divise.Divise f => Data.HBifunctor.Associative.SemigroupIn Data.Functor.Contravariant.Day.Day f
instance Data.Functor.Invariant.Inplicative.Inply f => Data.HBifunctor.Associative.SemigroupIn Data.Functor.Invariant.Day.Day f
instance Data.Functor.Invariant.Internative.Inalt f => Data.HBifunctor.Associative.SemigroupIn Data.Functor.Invariant.Night.Night f
instance Data.Functor.Contravariant.Decide.Decide f => Data.HBifunctor.Associative.SemigroupIn Data.Functor.Contravariant.Night.Night f
instance Data.HBifunctor.Associative.SemigroupIn (GHC.Generics.:+:) f
instance Data.HBifunctor.Associative.SemigroupIn Data.Functor.Sum.Sum f
instance Data.Functor.Alt.Alt f => Data.HBifunctor.Associative.SemigroupIn Data.Functor.These.These1 f
instance Data.HBifunctor.Associative.SemigroupIn Control.Applicative.Step.Void3 f
instance Data.Functor.Bind.Class.Bind f => Data.HBifunctor.Associative.SemigroupIn Control.Monad.Freer.Church.Comp f
instance Data.HBifunctor.Associative.SemigroupIn Data.Bifunctor.Joker.Joker f
instance Data.HBifunctor.Associative.SemigroupIn Data.HBifunctor.LeftF f
instance Data.HBifunctor.Associative.SemigroupIn Data.HBifunctor.RightF f
instance Data.HBifunctor.Associative.Associative (GHC.Generics.:*:)
instance Data.HBifunctor.Associative.Associative Data.Functor.Product.Product
instance Data.HBifunctor.Associative.Associative Data.Functor.Day.Day
instance Data.HBifunctor.Associative.Associative Data.Functor.Contravariant.Day.Day
instance Data.HBifunctor.Associative.Associative Data.Functor.Invariant.Day.Day
instance Data.HBifunctor.Associative.Associative Data.Functor.Invariant.Night.Night
instance Data.HBifunctor.Associative.Associative Data.Functor.Contravariant.Night.Night
instance Data.HBifunctor.Associative.Associative (GHC.Generics.:+:)
instance Data.HBifunctor.Associative.Associative Data.Functor.Sum.Sum
instance Data.HBifunctor.Associative.Associative Data.Functor.These.These1
instance Data.HBifunctor.Associative.Associative Control.Applicative.Step.Void3
instance Data.HBifunctor.Associative.Associative Control.Monad.Freer.Church.Comp
instance Data.HBifunctor.Associative.Associative Data.Bifunctor.Joker.Joker
instance Data.HBifunctor.Associative.Associative Data.HBifunctor.LeftF
instance Data.HBifunctor.Associative.Associative Data.HBifunctor.RightF


-- | This module provides tools for working with binary functor
--   combinators.
--   
--   <a>Data.Functor.HFunctor</a> deals with <i>single</i> functor
--   combinators (transforming a single functor). This module provides
--   tools for working with combinators that combine and mix two functors
--   "together".
--   
--   The binary analog of <a>HFunctor</a> is <a>HBifunctor</a>: we can map
--   a structure-transforming function over both of the transformed
--   functors.
--   
--   <a>Tensor</a> gives some extra properties of your binary functor
--   combinator: associativity and identity (see docs for <a>Tensor</a> for
--   more details).
--   
--   The binary analog of <a>Interpret</a> is <a>MonoidIn</a>. If your
--   combinator <tt>t</tt> and target functor <tt>f</tt> is an instance of
--   <tt><a>MonoidIn</a> t f</tt>, it means you can "interpret" out of your
--   tensored values, and also "generate" values of <tt>f</tt>.
--   
--   <pre>
--   <a>biretract</a> :: (f <a>:+:</a> f) a -&gt; f a
--   <a>pureT</a>     :: <a>V1</a> a -&gt; f a
--   
--   biretract :: <a>Plus</a> f =&gt; (f <a>:*:</a> f) a -&gt; f a
--   pureT     :: Plus f =&gt; <a>Proxy</a> a -&gt; f a
--   
--   biretract :: <a>Applicative</a> f =&gt; <a>Day</a> f f a -&gt; f a
--   pureT     :: Applicative f =&gt; <a>Identity</a> a -&gt; f a
--   
--   biretract :: <a>Monad</a> f =&gt; <a>Comp</a> f f a -&gt; f a
--   pureT     :: Monad f =&gt; <a>Identity</a> a -&gt; f a
--   </pre>
module Data.HBifunctor.Tensor

-- | An <a>Associative</a> <a>HBifunctor</a> can be a <a>Tensor</a> if
--   there is some identity <tt>i</tt> where <tt>t i f</tt> and <tt>t f
--   i</tt> are equivalent to just <tt>f</tt>.
--   
--   That is, "enhancing" <tt>f</tt> with <tt>t i</tt> does nothing.
--   
--   The methods in this class provide us useful ways of navigating a
--   <tt><a>Tensor</a> t</tt> with respect to this property.
--   
--   The <a>Tensor</a> is essentially the <a>HBifunctor</a> equivalent of
--   <a>Inject</a>, with <a>intro1</a> and <a>intro2</a> taking the place
--   of <a>inject</a>.
--   
--   Formally, we can say that <tt>t</tt> enriches a the category of
--   endofunctors with monoid strcture: it turns our endofunctor category
--   into a "monoidal category".
--   
--   Different instances of <tt>t</tt> each enrich the endofunctor category
--   in different ways, giving a different monoidal category.
class (Associative t, Inject (ListBy t)) => Tensor t i | t -> i where {
    
    -- | The "monoidal functor combinator" induced by <tt>t</tt>.
    --   
    --   A value of type <tt>ListBy t f a</tt> is <i>equivalent</i> to one of:
    --   
    --   <ul>
    --   <li><tt>I a</tt> -- zero fs</li>
    --   <li><tt>f a</tt> -- one f</li>
    --   <li><tt>t f f a</tt> -- two fs</li>
    --   <li><tt>t f (t f f) a</tt> -- three fs</li>
    --   <li><pre>t f (t f (t f f)) a</pre></li>
    --   <li><pre>t f (t f (t f (t f f))) a</pre></li>
    --   <li>.. etc</li>
    --   </ul>
    --   
    --   For example, for <a>:*:</a>, we have <tt>ListF</tt>. This is because:
    --   
    --   <pre>
    --   <tt>Proxy</tt>         ~ <tt>ListF</tt> []         ~ <a>nilLB</a> @(<a>:*:</a>)
    --   x             ~ ListF [x]        ~ <a>inject</a> x
    --   x :*: y       ~ ListF [x,y]      ~ <a>toListBy</a> (x :*: y)
    --   x :*: y :*: z ~ ListF [x,y,z]
    --   -- etc.
    --   </pre>
    --   
    --   You can create an "empty" one with <a>nilLB</a>, a "singleton" one
    --   with <a>inject</a>, or else one from a single <tt>t f f</tt> with
    --   <a>toListBy</a>.
    --   
    --   See <a>NonEmptyBy</a> for a "non-empty" version of this type.
    type family ListBy t :: (Type -> Type) -> Type -> Type;
}

-- | Because <tt>t f (I t)</tt> is equivalent to <tt>f</tt>, we can always
--   "insert" <tt>f</tt> into <tt>t f (I t)</tt>.
--   
--   This is analogous to <a>inject</a> from <a>Inject</a>, but for
--   <a>HBifunctor</a>s.
intro1 :: Tensor t i => f ~> t f i

-- | Because <tt>t (I t) g</tt> is equivalent to <tt>f</tt>, we can always
--   "insert" <tt>g</tt> into <tt>t (I t) g</tt>.
--   
--   This is analogous to <a>inject</a> from <a>Inject</a>, but for
--   <a>HBifunctor</a>s.
intro2 :: Tensor t i => g ~> t i g

-- | Witnesses the property that <tt>i</tt> is the identity of <tt>t</tt>:
--   <tt>t f i</tt> always leaves <tt>f</tt> unchanged, so we can always
--   just drop the <tt>i</tt>.
elim1 :: (Tensor t i, FunctorBy t f) => t f i ~> f

-- | Witnesses the property that <tt>i</tt> is the identity of <tt>t</tt>:
--   <tt>t i g</tt> always leaves <tt>g</tt> unchanged, so we can always
--   just drop the <tt>i t</tt>.
elim2 :: (Tensor t i, FunctorBy t g) => t i g ~> g

-- | If a <tt><a>ListBy</a> t f</tt> represents multiple applications of
--   <tt>t f</tt> to itself, then we can also "append" two
--   <tt><a>ListBy</a> t f</tt>s applied to themselves into one giant
--   <tt><a>ListBy</a> t f</tt> containing all of the <tt>t f</tt>s.
--   
--   Note that this essentially gives an instance for
--   <tt><a>SemigroupIn</a> t (ListBy t f)</tt>, for any functor
--   <tt>f</tt>; this is witnessed by <tt>WrapLB</tt>.
appendLB :: Tensor t i => t (ListBy t f) (ListBy t f) ~> ListBy t f

-- | Lets you convert an <tt><a>NonEmptyBy</a> t f</tt> into a single
--   application of <tt>f</tt> to <tt><a>ListBy</a> t f</tt>.
--   
--   Analogous to a function <tt><a>NonEmpty</a> a -&gt; (a, [a])</tt>
--   
--   Note that this is not reversible in general unless we have
--   <tt><tt>Matchable</tt> t</tt>.
splitNE :: Tensor t i => NonEmptyBy t f ~> t f (ListBy t f)

-- | An <tt><a>ListBy</a> t f</tt> is either empty, or a single application
--   of <tt>t</tt> to <tt>f</tt> and <tt>ListBy t f</tt> (the "head" and
--   "tail"). This witnesses that isomorphism.
--   
--   To <i>use</i> this property, see <a>nilLB</a>, <a>consLB</a>, and
--   <a>unconsLB</a>.
splittingLB :: Tensor t i => ListBy t f <~> (i :+: t f (ListBy t f))

-- | Embed a direct application of <tt>f</tt> to itself into a
--   <tt><a>ListBy</a> t f</tt>.
toListBy :: Tensor t i => t f f ~> ListBy t f

-- | <tt><a>NonEmptyBy</a> t f</tt> is "one or more <tt>f</tt>s", and
--   <tt>'ListBy t f</tt> is "zero or more <tt>f</tt>s". This function lets
--   us convert from one to the other.
--   
--   This is analogous to a function <tt><a>NonEmpty</a> a -&gt; [a]</tt>.
--   
--   Note that because <tt>t</tt> is not inferrable from the input or
--   output type, you should call this using <i>-XTypeApplications</i>:
--   
--   <pre>
--   <a>fromNE</a> @(<a>:*:</a>) :: <tt>NonEmptyF</tt> f a -&gt; <tt>ListF</tt> f a
--   fromNE @<tt>Comp</tt>  :: <tt>Free1</tt> f a -&gt; <tt>Free</tt> f a
--   </pre>
fromNE :: Tensor t i => NonEmptyBy t f ~> ListBy t f

-- | <tt>f</tt> is isomorphic to <tt>t f i</tt>: that is, <tt>i</tt> is the
--   identity of <tt>t</tt>, and leaves <tt>f</tt> unchanged.
rightIdentity :: (Tensor t i, FunctorBy t f) => f <~> t f i

-- | <tt>g</tt> is isomorphic to <tt>t i g</tt>: that is, <tt>i</tt> is the
--   identity of <tt>t</tt>, and leaves <tt>g</tt> unchanged.
leftIdentity :: (Tensor t i, FunctorBy t g) => g <~> t i g

-- | <a>leftIdentity</a> (<a>intro1</a> and <a>elim1</a>) for <a>:+:</a>
--   actually does not require <a>Functor</a>. This is the more general
--   version.
sumLeftIdentity :: f <~> (V1 :+: f)

-- | <a>rightIdentity</a> (<a>intro2</a> and <a>elim2</a>) for <a>:+:</a>
--   actually does not require <a>Functor</a>. This is the more general
--   version.
sumRightIdentity :: f <~> (f :+: V1)

-- | <a>leftIdentity</a> (<a>intro1</a> and <a>elim1</a>) for <a>:*:</a>
--   actually does not require <a>Functor</a>. This is the more general
--   version.
prodLeftIdentity :: f <~> (Proxy :*: f)

-- | <a>rightIdentity</a> (<a>intro2</a> and <a>elim2</a>) for <a>:*:</a>
--   actually does not require <a>Functor</a>. This is the more general
--   version.
prodRightIdentity :: g <~> (g :*: Proxy)

-- | This class effectively gives us a way to generate a value of <tt>f
--   a</tt> based on an <tt>i a</tt>, for <tt><a>Tensor</a> t i</tt>.
--   Having this ability makes a lot of interesting functions possible when
--   used with <a>biretract</a> from <a>SemigroupIn</a> that weren't
--   possible without it: it gives us a "base case" for recursion in a lot
--   of cases.
--   
--   Essentially, we get an <tt>i ~&gt; f</tt>, <a>pureT</a>, where we can
--   introduce an <tt>f a</tt> as long as we have an <tt>i a</tt>.
--   
--   Formally, if we have <tt><a>Tensor</a> t i</tt>, we are enriching the
--   category of endofunctors with monoid structure, turning it into a
--   monoidal category. Different choices of <tt>t</tt> give different
--   monoidal categories.
--   
--   A functor <tt>f</tt> is known as a "monoid in the (monoidal) category
--   of endofunctors on <tt>t</tt>" if we can <a>biretract</a>:
--   
--   <pre>
--   t f f ~&gt; f
--   </pre>
--   
--   and also <a>pureT</a>:
--   
--   <pre>
--   i ~&gt; f
--   </pre>
--   
--   This gives us a few interesting results in category theory, which you
--   can stil reading about if you don't care:
--   
--   <ul>
--   <li><i>All</i> functors are monoids in the monoidal category on
--   <a>:+:</a></li>
--   <li>The class of functors that are monoids in the monoidal category on
--   <a>:*:</a> is exactly the functors that are instances of
--   <a>Plus</a>.</li>
--   <li>The class of functors that are monoids in the monoidal category on
--   <a>Day</a> is exactly the functors that are instances of
--   <a>Applicative</a>.</li>
--   <li>The class of functors that are monoids in the monoidal category on
--   <a>Comp</a> is exactly the functors that are instances of
--   <a>Monad</a>.</li>
--   </ul>
--   
--   This is the meaning behind the common adage, "monads are just monoids
--   in the category of endofunctors". It means that if you enrich the
--   category of endofunctors to be monoidal with <a>Comp</a>, then the
--   class of functors that are monoids in that monoidal category are
--   exactly what monads are. However, the adage is a little misleading:
--   there are many other ways to enrich the category of endofunctors to be
--   monoidal, and <a>Comp</a> is just one of them. Similarly, the class of
--   functors that are monoids in the category of endofunctors enriched by
--   <a>Day</a> are <a>Applicative</a>.
--   
--   Note that instances of this class are <i>intended</i> to be written
--   with <tt>t</tt> and <tt>i</tt> to be fixed type constructors, and
--   <tt>f</tt> to be allowed to vary freely:
--   
--   <pre>
--   instance Monad f =&gt; MonoidIn Comp Identity f
--   </pre>
--   
--   Any other sort of instance and it's easy to run into problems with
--   type inference. If you want to write an instance that's "polymorphic"
--   on tensor choice, use the <a>WrapHBF</a> and <a>WrapF</a> newtype
--   wrappers over type variables, where the third argument also uses a
--   type constructor:
--   
--   <pre>
--   instance MonoidIn (WrapHBF t) (WrapF i) (MyFunctor t i)
--   </pre>
--   
--   This will prevent problems with overloaded instances.
class (Tensor t i, SemigroupIn t f) => MonoidIn t i f

-- | If we have an <tt>i</tt>, we can generate an <tt>f</tt> based on how
--   it interacts with <tt>t</tt>.
--   
--   Specialized (and simplified), this type is:
--   
--   <pre>
--   <a>pureT</a> @<a>Day</a>   :: <a>Applicative</a> f =&gt; <a>Identity</a> a -&gt; f a  -- <a>pure</a>
--   pureT @<a>Comp</a>  :: <a>Monad</a> f =&gt; Identity a -&gt; f a        -- <a>return</a>
--   pureT @(<a>:*:</a>) :: <a>Plus</a> f =&gt; <a>Proxy</a> a -&gt; f a            -- <a>zero</a>
--   </pre>
--   
--   Note that because <tt>t</tt> appears nowhere in the input or output
--   types, you must always use this with explicit type application syntax
--   (like <tt>pureT @Day</tt>)
--   
--   Along with <a>biretract</a>, this function makes <tt>f</tt> a monoid
--   in the category of endofunctors with respect to tensor <tt>t</tt>.
pureT :: MonoidIn t i f => i ~> f

-- | If we have an <tt>i</tt>, we can generate an <tt>f</tt> based on how
--   it interacts with <tt>t</tt>.
--   
--   Specialized (and simplified), this type is:
--   
--   <pre>
--   <a>pureT</a> @<a>Day</a>   :: <a>Applicative</a> f =&gt; <a>Identity</a> a -&gt; f a  -- <a>pure</a>
--   pureT @<a>Comp</a>  :: <a>Monad</a> f =&gt; Identity a -&gt; f a        -- <a>return</a>
--   pureT @(<a>:*:</a>) :: <a>Plus</a> f =&gt; <a>Proxy</a> a -&gt; f a            -- <a>zero</a>
--   </pre>
--   
--   Note that because <tt>t</tt> appears nowhere in the input or output
--   types, you must always use this with explicit type application syntax
--   (like <tt>pureT @Day</tt>)
--   
--   Along with <a>biretract</a>, this function makes <tt>f</tt> a monoid
--   in the category of endofunctors with respect to tensor <tt>t</tt>.
pureT :: (MonoidIn t i f, Interpret (ListBy t) f) => i ~> f

-- | Create the "empty <a>ListBy</a>".
--   
--   If <tt><a>ListBy</a> t f</tt> represents multiple applications of
--   <tt>t f</tt> with itself, then <tt>nilLB</tt> gives us "zero
--   applications of <tt>f</tt>".
--   
--   Note that <tt>t</tt> cannot be inferred from the input or output type
--   of <a>nilLB</a>, so this function must always be called with
--   -XTypeApplications:
--   
--   <pre>
--   <a>nilLB</a> @<tt>Day</tt> :: <tt>Identity</tt> <a>~&gt;</a> <tt>Ap</tt> f
--   nilLB @<tt>Comp</tt> :: Identity ~&gt; <tt>Free</tt> f
--   nilLB @(<a>:*:</a>) :: <tt>Proxy</tt> ~&gt; <tt>ListF</tt> f
--   </pre>
--   
--   Note that this essentially gives an instance for <tt><tt>MonoidIn</tt>
--   t i (ListBy t f)</tt>, for any functor <tt>f</tt>; this is witnessed
--   by <tt>WrapLB</tt>.
nilLB :: forall t i f. Tensor t i => i ~> ListBy t f

-- | Lets us "cons" an application of <tt>f</tt> to the front of an
--   <tt><a>ListBy</a> t f</tt>.
consLB :: Tensor t i => t f (ListBy t f) ~> ListBy t f

-- | "Pattern match" on an <tt><a>ListBy</a> t</tt>
--   
--   An <tt><a>ListBy</a> t f</tt> is either empty, or a single application
--   of <tt>t</tt> to <tt>f</tt> and <tt>ListBy t f</tt> (the "head" and
--   "tail")
--   
--   This is analogous to the function <tt><a>uncons</a> :: [a] -&gt; Maybe
--   (a, [a])</tt>.
unconsLB :: Tensor t i => ListBy t f ~> (i :+: t f (ListBy t f))

-- | An implementation of <a>retract</a> that works for any instance of
--   <tt><a>MonoidIn</a> t i</tt> for <tt><a>ListBy</a> t</tt>.
--   
--   Can be useful as a default implementation if you already have
--   <a>MonoidIn</a> implemented.
retractLB :: forall t i f. MonoidIn t i f => ListBy t f ~> f

-- | An implementation of <a>interpret</a> that works for any instance of
--   <tt><a>MonoidIn</a> t i</tt> for <tt><a>ListBy</a> t</tt>.
--   
--   Can be useful as a default implementation if you already have
--   <a>MonoidIn</a> implemented.
interpretLB :: forall t i g f. MonoidIn t i f => (g ~> f) -> ListBy t g ~> f

-- | Convenient wrapper over <a>intro1</a> that lets us introduce an
--   arbitrary functor <tt>g</tt> to the right of an <tt>f</tt>.
--   
--   You can think of this as an <a>HBifunctor</a> analogue of
--   <a>inject</a>.
inL :: forall t i f g. MonoidIn t i g => f ~> t f g

-- | Convenient wrapper over <a>intro2</a> that lets us introduce an
--   arbitrary functor <tt>f</tt> to the right of a <tt>g</tt>.
--   
--   You can think of this as an <a>HBifunctor</a> analogue of
--   <a>inject</a>.
inR :: forall t i f g. MonoidIn t i f => g ~> t f g

-- | Convenient wrapper over <a>elim1</a> that lets us drop one of the
--   arguments of a <a>Tensor</a> for free, without requiring any extra
--   constraints (like for <a>binterpret</a>).
--   
--   See <a>prodOutL</a> for a version that does not require
--   <tt><a>Functor</a> f</tt>, specifically for <a>:*:</a>.
outL :: (Tensor t Proxy, FunctorBy t f) => t f g ~> f

-- | Convenient wrapper over <a>elim2</a> that lets us drop one of the
--   arguments of a <a>Tensor</a> for free, without requiring any
--   constraints (like for <a>binterpret</a>).
--   
--   See <a>prodOutR</a> for a version that does not require
--   <tt><a>Functor</a> g</tt>, specifically for <a>:*:</a>.
outR :: (Tensor t Proxy, FunctorBy t g) => t f g ~> g

-- | A poly-kinded version of <a>outL</a> for <a>:*:</a>.
prodOutL :: (f :*: g) ~> f

-- | A poly-kinded version of <a>outR</a> for <a>:*:</a>.
prodOutR :: (f :*: g) ~> g

-- | A newtype wrapper meant to be used to define polymorphic
--   <a>MonoidIn</a> instances. See documentation for <a>MonoidIn</a> for
--   more information.
--   
--   Please do not ever define an instance of <a>MonoidIn</a> "naked" on
--   the third parameter:
--   
--   <pre>
--   instance MonidIn (WrapHBF t) (WrapF i) f
--   </pre>
--   
--   As that would globally ruin everything using <a>WrapHBF</a>.
newtype WrapF f a
WrapF :: f a -> WrapF f a
[unwrapF] :: WrapF f a -> f a

-- | Any <tt><a>ListBy</a> t f</tt> is a <tt><a>SemigroupIn</a> t</tt> and
--   a <tt><a>MonoidIn</a> t i</tt>, if we have <tt><a>Tensor</a> t i</tt>.
--   This newtype wrapper witnesses that fact. We require a newtype wrapper
--   to avoid overlapping instances.
newtype WrapLB t f a
WrapLB :: ListBy t f a -> WrapLB t f a
[unwrapLB] :: WrapLB t f a -> ListBy t f a

-- | For some <tt>t</tt>, we have the ability to "statically analyze" the
--   <tt><a>ListBy</a> t</tt> and pattern match and manipulate the
--   structure without ever interpreting or retracting. These are
--   <a>Matchable</a>.
class Tensor t i => Matchable t i

-- | The inverse of <a>splitNE</a>. A consing of <tt>f</tt> to
--   <tt><a>ListBy</a> t f</tt> is non-empty, so it can be represented as
--   an <tt><a>NonEmptyBy</a> t f</tt>.
--   
--   This is analogous to a function <tt><a>uncurry</a> (<a>:|</a>) :: (a,
--   [a]) -&gt; <a>NonEmpty</a> a</tt>.
unsplitNE :: (Matchable t i, FunctorBy t f) => t f (ListBy t f) ~> NonEmptyBy t f

-- | "Pattern match" on an <tt><a>ListBy</a> t f</tt>: it is either empty,
--   or it is non-empty (and so can be an <tt><a>NonEmptyBy</a> t f</tt>).
--   
--   This is analgous to a function <tt><a>nonEmpty</a> :: [a] -&gt; Maybe
--   (<a>NonEmpty</a> a)</tt>.
--   
--   Note that because <tt>t</tt> cannot be inferred from the input or
--   output type, you should use this with <i>-XTypeApplications</i>:
--   
--   <pre>
--   <a>matchLB</a> @<a>Day</a> :: <a>Ap</a> f a -&gt; (<a>Identity</a> :+: <a>Ap1</a> f) a
--   </pre>
--   
--   Note that you can recursively "unroll" a <a>ListBy</a> completely into
--   a <a>Chain</a> by using <a>unrollLB</a>.
matchLB :: (Matchable t i, FunctorBy t f) => ListBy t f ~> (i :+: NonEmptyBy t f)

-- | An <tt><a>NonEmptyBy</a> t f</tt> is isomorphic to an <tt>f</tt>
--   consed with an <tt><a>ListBy</a> t f</tt>, like how a
--   <tt><a>NonEmpty</a> a</tt> is isomorphic to <tt>(a, [a])</tt>.
splittingNE :: (Matchable t i, FunctorBy t f) => NonEmptyBy t f <~> t f (ListBy t f)

-- | An <tt><a>ListBy</a> t f</tt> is isomorphic to either the empty case
--   (<tt>i</tt>) or the non-empty case (<tt><a>NonEmptyBy</a> t f</tt>),
--   like how <tt>[a]</tt> is isomorphic to <tt><a>Maybe</a>
--   (<a>NonEmpty</a> a)</tt>.
matchingLB :: forall t i f. (Matchable t i, FunctorBy t f) => ListBy t f <~> (i :+: NonEmptyBy t f)
instance forall k (f :: k -> *) (a :: k). (Data.Typeable.Internal.Typeable a, Data.Typeable.Internal.Typeable f, Data.Typeable.Internal.Typeable k, Data.Data.Data (f a)) => Data.Data.Data (Data.HBifunctor.Tensor.WrapF f a)
instance forall k (f :: k -> *) (a :: k). GHC.Generics.Generic (Data.HBifunctor.Tensor.WrapF f a)
instance Data.Traversable.Traversable f => Data.Traversable.Traversable (Data.HBifunctor.Tensor.WrapF f)
instance Data.Foldable.Foldable f => Data.Foldable.Foldable (Data.HBifunctor.Tensor.WrapF f)
instance GHC.Base.Functor f => GHC.Base.Functor (Data.HBifunctor.Tensor.WrapF f)
instance forall k (f :: k -> *) (a :: k). GHC.Classes.Ord (f a) => GHC.Classes.Ord (Data.HBifunctor.Tensor.WrapF f a)
instance forall k (f :: k -> *) (a :: k). GHC.Classes.Eq (f a) => GHC.Classes.Eq (Data.HBifunctor.Tensor.WrapF f a)
instance forall k (f :: k -> *) (a :: k). GHC.Read.Read (f a) => GHC.Read.Read (Data.HBifunctor.Tensor.WrapF f a)
instance forall k (f :: k -> *) (a :: k). GHC.Show.Show (f a) => GHC.Show.Show (Data.HBifunctor.Tensor.WrapF f a)
instance GHC.Base.Functor (Data.HBifunctor.Tensor.Internal.ListBy t f) => GHC.Base.Functor (Data.HBifunctor.Tensor.WrapLB t f)
instance Data.Functor.Contravariant.Contravariant (Data.HBifunctor.Tensor.Internal.ListBy t f) => Data.Functor.Contravariant.Contravariant (Data.HBifunctor.Tensor.WrapLB t f)
instance Data.Functor.Invariant.Invariant (Data.HBifunctor.Tensor.Internal.ListBy t f) => Data.Functor.Invariant.Invariant (Data.HBifunctor.Tensor.WrapLB t f)
instance (Data.HBifunctor.Tensor.Internal.Tensor t i, Data.HBifunctor.Associative.FunctorBy t f, Data.HBifunctor.Associative.FunctorBy t (Data.HBifunctor.Tensor.WrapLB t f)) => Data.HBifunctor.Associative.SemigroupIn (Data.HBifunctor.Associative.WrapHBF t) (Data.HBifunctor.Tensor.WrapLB t f)
instance (Data.HBifunctor.Tensor.Internal.Tensor t i, Data.HBifunctor.Associative.FunctorBy t f, Data.HBifunctor.Associative.FunctorBy t (Data.HBifunctor.Tensor.WrapLB t f)) => Data.HBifunctor.Tensor.MonoidIn (Data.HBifunctor.Associative.WrapHBF t) (Data.HBifunctor.Tensor.WrapF i) (Data.HBifunctor.Tensor.WrapLB t f)
instance Data.Functor.Classes.Show1 f => Data.Functor.Classes.Show1 (Data.HBifunctor.Tensor.WrapF f)
instance Data.Functor.Classes.Eq1 f => Data.Functor.Classes.Eq1 (Data.HBifunctor.Tensor.WrapF f)
instance Data.Functor.Classes.Ord1 f => Data.Functor.Classes.Ord1 (Data.HBifunctor.Tensor.WrapF f)
instance Data.HBifunctor.Tensor.Internal.Tensor t i => Data.HBifunctor.Tensor.Internal.Tensor (Data.HBifunctor.Associative.WrapHBF t) (Data.HBifunctor.Tensor.WrapF i)
instance Data.HBifunctor.Tensor.Matchable Data.Functor.Invariant.Day.Day Data.Functor.Identity.Identity
instance Data.HBifunctor.Tensor.Matchable Data.Functor.Invariant.Night.Night Data.Functor.Contravariant.Night.Not
instance Data.HBifunctor.Tensor.Matchable (GHC.Generics.:*:) Data.Proxy.Proxy
instance Data.HBifunctor.Tensor.Matchable Data.Functor.Product.Product Data.Proxy.Proxy
instance Data.HBifunctor.Tensor.Matchable Data.Functor.Day.Day Data.Functor.Identity.Identity
instance Data.HBifunctor.Tensor.Matchable Data.Functor.Contravariant.Day.Day Data.Proxy.Proxy
instance Data.HBifunctor.Tensor.Matchable Data.Functor.Contravariant.Night.Night Data.Functor.Contravariant.Night.Not
instance Data.HBifunctor.Tensor.Matchable (GHC.Generics.:+:) GHC.Generics.V1
instance Data.HBifunctor.Tensor.Matchable Data.Functor.Sum.Sum GHC.Generics.V1
instance Data.Functor.Plus.Plus f => Data.HBifunctor.Tensor.MonoidIn (GHC.Generics.:*:) Data.Proxy.Proxy f
instance Data.Functor.Plus.Plus f => Data.HBifunctor.Tensor.MonoidIn Data.Functor.Product.Product Data.Proxy.Proxy f
instance (Data.Functor.Bind.Class.Apply f, GHC.Base.Applicative f) => Data.HBifunctor.Tensor.MonoidIn Data.Functor.Day.Day Data.Functor.Identity.Identity f
instance (Data.Functor.Contravariant.Divise.Divise f, Data.Functor.Contravariant.Divisible.Divisible f) => Data.HBifunctor.Tensor.MonoidIn Data.Functor.Contravariant.Day.Day Data.Proxy.Proxy f
instance Data.Functor.Invariant.Inplicative.Inplicative f => Data.HBifunctor.Tensor.MonoidIn Data.Functor.Invariant.Day.Day Data.Functor.Identity.Identity f
instance Data.Functor.Invariant.Internative.Inplus f => Data.HBifunctor.Tensor.MonoidIn Data.Functor.Invariant.Night.Night Data.Functor.Contravariant.Night.Not f
instance Data.Functor.Contravariant.Conclude.Conclude f => Data.HBifunctor.Tensor.MonoidIn Data.Functor.Contravariant.Night.Night Data.Functor.Contravariant.Night.Not f
instance Data.HBifunctor.Tensor.MonoidIn (GHC.Generics.:+:) GHC.Generics.V1 f
instance Data.HBifunctor.Tensor.MonoidIn Data.Functor.Sum.Sum GHC.Generics.V1 f
instance Data.Functor.Alt.Alt f => Data.HBifunctor.Tensor.MonoidIn Data.Functor.These.These1 GHC.Generics.V1 f
instance (Data.Functor.Bind.Class.Bind f, GHC.Base.Monad f) => Data.HBifunctor.Tensor.MonoidIn Control.Monad.Freer.Church.Comp Data.Functor.Identity.Identity f
instance Data.HBifunctor.Tensor.Internal.Tensor (GHC.Generics.:*:) Data.Proxy.Proxy
instance Data.HBifunctor.Tensor.Internal.Tensor Data.Functor.Product.Product Data.Proxy.Proxy
instance Data.HBifunctor.Tensor.Internal.Tensor Data.Functor.Day.Day Data.Functor.Identity.Identity
instance Data.HBifunctor.Tensor.Internal.Tensor Data.Functor.Contravariant.Day.Day Data.Proxy.Proxy
instance Data.HBifunctor.Tensor.Internal.Tensor Data.Functor.Invariant.Day.Day Data.Functor.Identity.Identity
instance Data.HBifunctor.Tensor.Internal.Tensor Data.Functor.Invariant.Night.Night Data.Functor.Contravariant.Night.Not
instance Data.HBifunctor.Tensor.Internal.Tensor Data.Functor.Contravariant.Night.Night Data.Functor.Contravariant.Night.Not
instance Data.HBifunctor.Tensor.Internal.Tensor (GHC.Generics.:+:) GHC.Generics.V1
instance Data.HBifunctor.Tensor.Internal.Tensor Data.Functor.Sum.Sum GHC.Generics.V1
instance Data.HBifunctor.Tensor.Internal.Tensor Data.Functor.These.These1 GHC.Generics.V1
instance Data.HBifunctor.Tensor.Internal.Tensor Control.Monad.Freer.Church.Comp Data.Functor.Identity.Identity


-- | This module provides an <a>Interpret</a>able data type of "linked list
--   of tensor applications".
--   
--   The type <tt><a>Chain</a> t</tt>, for any <tt><a>Tensor</a> t</tt>, is
--   meant to be the same as <tt><a>ListBy</a> t</tt> (the monoidal functor
--   combinator for <tt>t</tt>), and represents "zero or more" applications
--   of <tt>f</tt> to <tt>t</tt>.
--   
--   The type <tt><a>Chain1</a> t</tt>, for any <tt><a>Associative</a>
--   t</tt>, is meant to be the same as <tt><a>NonEmptyBy</a> t</tt> (the
--   semigroupoidal functor combinator for <tt>t</tt>) and represents "one
--   or more" applications of <tt>f</tt> to <tt>t</tt>.
--   
--   The advantage of using <a>Chain</a> and <a>Chain1</a> over
--   <a>ListBy</a> or <a>NonEmptyBy</a> is that they provide a universal
--   interface for pattern matching and constructing such values, which may
--   simplify working with new such functor combinators you might
--   encounter.
module Data.HFunctor.Chain

-- | A useful construction that works like a "linked list" of <tt>t f</tt>
--   applied to itself multiple times. That is, it contains <tt>t f f</tt>,
--   <tt>t f (t f f)</tt>, <tt>t f (t f (t f f))</tt>, etc, with <tt>f</tt>
--   occuring <i>zero or more</i> times. It is meant to be the same as
--   <tt><tt>ListBy</tt> t</tt>.
--   
--   If <tt>t</tt> is <tt>Tensor</tt>, then it means we can "collapse" this
--   linked list into some final type <tt><tt>ListBy</tt> t</tt>
--   (<tt>reroll</tt>), and also extract it back into a linked list
--   (<tt>unroll</tt>).
--   
--   So, a value of type <tt><a>Chain</a> t i f a</tt> is one of either:
--   
--   <ul>
--   <li><pre>i a</pre></li>
--   <li><pre>f a</pre></li>
--   <li><pre>t f f a</pre></li>
--   <li><pre>t f (t f f) a</pre></li>
--   <li><pre>t f (t f (t f f)) a</pre></li>
--   <li>.. etc.</li>
--   </ul>
--   
--   Note that this is <i>exactly</i> what an <tt><tt>ListBy</tt> t</tt> is
--   supposed to be. Using <a>Chain</a> allows us to work with all
--   <tt><tt>ListBy</tt> t</tt>s in a uniform way, with normal pattern
--   matching and normal constructors.
--   
--   You can fully "collapse" a <tt><a>Chain</a> t i f</tt> into an
--   <tt>f</tt> with <a>retract</a>, if you have <tt><tt>MonoidIn</tt> t i
--   f</tt>; this could be considered a fundamental property of
--   monoid-ness.
--   
--   Another way of thinking of this is that <tt><a>Chain</a> t i</tt> is
--   the "free <tt><tt>MonoidIn</tt> t i</tt>". Given any functor
--   <tt>f</tt>, <tt><a>Chain</a> t i f</tt> is a monoid in the monoidal
--   category of endofunctors enriched by <tt>t</tt>. So, <tt><a>Chain</a>
--   <a>Comp</a> <a>Identity</a></tt> is the "free <a>Monad</a>",
--   <tt><a>Chain</a> <a>Day</a> <a>Identity</a></tt> is the "free
--   <a>Applicative</a>", etc. You "lift" from <tt>f a</tt> to
--   <tt><a>Chain</a> t i f a</tt> using <a>inject</a>.
--   
--   Note: this instance doesn't exist directly because of restrictions in
--   typeclasses, but is implemented as
--   
--   <pre>
--   <tt>Tensor</tt> t i =&gt; <tt>MonoidIn</tt> (<tt>WrapHBF</tt> t) (<tt>WrapF</tt> i) (<a>Chain</a> t i f)
--   </pre>
--   
--   where <tt>pureT</tt> is <a>Done</a> and <tt>biretract</tt> is
--   <tt>appendChain</tt>.
--   
--   This construction is inspired by
--   <a>http://oleg.fi/gists/posts/2018-02-21-single-free.html</a>
data Chain t i f a
Done :: i a -> Chain t i f a
More :: t f (Chain t i f) a -> Chain t i f a

-- | Recursively fold down a <a>Chain</a>. Provide a function on how to
--   handle the "single <tt>f</tt> case" (<tt>nilLB</tt>), and how to
--   handle the "combined <tt>t f g</tt> case", and this will fold the
--   entire <tt><a>Chain</a> t i) f</tt> into a single <tt>g</tt>.
--   
--   This is a catamorphism.
foldChain :: forall t i f g. HBifunctor t => (i ~> g) -> (t f g ~> g) -> Chain t i f ~> g

-- | An "effectful" version of <a>foldChain</a>, weaving Applicative
--   effects.
foldChainA :: (HBifunctor t, Functor h) => (forall x. i x -> h (g x)) -> (forall x. t f (Comp h g) x -> h (g x)) -> Chain t i f a -> h (g a)

-- | Recursively build up a <a>Chain</a>. Provide a function that takes
--   some starting seed <tt>g</tt> and returns either "done" (<tt>i</tt>)
--   or "continue further" (<tt>t f g</tt>), and it will create a
--   <tt><a>Chain</a> t i f</tt> from a <tt>g</tt>.
--   
--   This is an anamorphism.
unfoldChain :: forall t f (g :: Type -> Type) i. HBifunctor t => (g ~> (i :+: t f g)) -> g ~> Chain t i f

-- | A type <tt><a>ListBy</a> t</tt> is supposed to represent the
--   successive application of <tt>t</tt>s to itself. <a>unroll</a> makes
--   that successive application explicit, buy converting it to a literal
--   <a>Chain</a> of applications of <tt>t</tt> to itself.
--   
--   <pre>
--   <a>unroll</a> = <a>unfoldChain</a> <a>unconsLB</a>
--   </pre>
unroll :: Tensor t i => ListBy t f ~> Chain t i f

-- | A type <tt><a>ListBy</a> t</tt> is supposed to represent the
--   successive application of <tt>t</tt>s to itself. <a>rerollNE</a> takes
--   an explicit <a>Chain</a> of applications of <tt>t</tt> to itself and
--   rolls it back up into an <tt><a>ListBy</a> t</tt>.
--   
--   <pre>
--   <a>reroll</a> = <a>foldChain</a> <a>nilLB</a> <a>consLB</a>
--   </pre>
--   
--   Because <tt>t</tt> cannot be inferred from the input or output, you
--   should call this with <i>-XTypeApplications</i>:
--   
--   <pre>
--   <a>reroll</a> @<a>Comp</a>
--       :: <a>Chain</a> Comp <a>Identity</a> f a -&gt; <a>Free</a> f a
--   </pre>
reroll :: forall t i f. Tensor t i => Chain t i f ~> ListBy t f

-- | A type <tt><a>ListBy</a> t</tt> is supposed to represent the
--   successive application of <tt>t</tt>s to itself. The type
--   <tt><a>Chain</a> t i f</tt> is an actual concrete ADT that contains
--   successive applications of <tt>t</tt> to itself, and you can pattern
--   match on each layer.
--   
--   <a>unrolling</a> states that the two types are isormorphic. Use
--   <a>unroll</a> and <a>reroll</a> to convert between the two.
unrolling :: Tensor t i => ListBy t f <~> Chain t i f

-- | <a>Chain</a> is a monoid with respect to <tt>t</tt>: we can "combine"
--   them in an associative way. The identity here is anything made with
--   the <a>Done</a> constructor.
--   
--   This is essentially <a>biretract</a>, but only requiring
--   <tt><a>Tensor</a> t i</tt>: it comes from the fact that
--   <tt><a>Chain1</a> t i</tt> is the "free <tt><tt>MonoidIn</tt> t
--   i</tt>". <tt>pureT</tt> is <a>Done</a>.
appendChain :: forall t i f. Tensor t i => t (Chain t i f) (Chain t i f) ~> Chain t i f

-- | For completeness, an isomorphism between <a>Chain</a> and its two
--   constructors, to match <tt>splittingLB</tt>.
splittingChain :: Chain t i f <~> (i :+: t f (Chain t i f))

-- | Convert a tensor value pairing two <tt>f</tt>s into a two-item
--   <a>Chain</a>. An analogue of <a>toListBy</a>.
toChain :: Tensor t i => t f f ~> Chain t i f

-- | Create a singleton chain.
injectChain :: Tensor t i => f ~> Chain t i f

-- | An analogue of <tt>unconsLB</tt>: match one of the two constructors of
--   a <a>Chain</a>.
unconsChain :: Chain t i f ~> (i :+: t f (Chain t i f))

-- | A useful construction that works like a "non-empty linked list" of
--   <tt>t f</tt> applied to itself multiple times. That is, it contains
--   <tt>t f f</tt>, <tt>t f (t f f)</tt>, <tt>t f (t f (t f f))</tt>, etc,
--   with <tt>f</tt> occuring <i>one or more</i> times. It is meant to be
--   the same as <tt><tt>NonEmptyBy</tt> t</tt>.
--   
--   A <tt><a>Chain1</a> t f a</tt> is explicitly one of:
--   
--   <ul>
--   <li><pre>f a</pre></li>
--   <li><pre>t f f a</pre></li>
--   <li><pre>t f (t f f) a</pre></li>
--   <li><pre>t f (t f (t f f)) a</pre></li>
--   <li>.. etc</li>
--   </ul>
--   
--   Note that this is exactly the description of <tt><tt>NonEmptyBy</tt>
--   t</tt>. And that's "the point": for all instances of
--   <tt>Associative</tt>, <tt><a>Chain1</a> t</tt> is isomorphic to
--   <tt><tt>NonEmptyBy</tt> t</tt> (witnessed by <tt>unrollingNE</tt>).
--   That's big picture of <tt>NonEmptyBy</tt>: it's supposed to be a type
--   that consists of all possible self-applications of <tt>f</tt> to
--   <tt>t</tt>.
--   
--   <a>Chain1</a> gives you a way to work with all <tt><tt>NonEmptyBy</tt>
--   t</tt> in a uniform way. Unlike for <tt><tt>NonEmptyBy</tt> t f</tt>
--   in general, you can always explicitly /pattern match/ on a
--   <a>Chain1</a> (with its two constructors) and do what you please with
--   it. You can also <i>construct</i> <a>Chain1</a> using normal
--   constructors and functions.
--   
--   You can convert in between <tt><tt>NonEmptyBy</tt> t f</tt> and
--   <tt><a>Chain1</a> t f</tt> with <tt>unrollNE</tt> and
--   <tt>rerollNE</tt>. You can fully "collapse" a <tt><a>Chain1</a> t
--   f</tt> into an <tt>f</tt> with <a>retract</a>, if you have
--   <tt><tt>SemigroupIn</tt> t f</tt>; this could be considered a
--   fundamental property of semigroup-ness.
--   
--   See <a>Chain</a> for a version that has an "empty" value.
--   
--   Another way of thinking of this is that <tt><a>Chain1</a> t</tt> is
--   the "free <tt><tt>SemigroupIn</tt> t</tt>". Given any functor
--   <tt>f</tt>, <tt><a>Chain1</a> t f</tt> is a semigroup in the
--   semigroupoidal category of endofunctors enriched by <tt>t</tt>. So,
--   <tt><a>Chain1</a> <a>Comp</a></tt> is the "free <a>Bind</a>",
--   <tt><a>Chain1</a> <tt>Day</tt></tt> is the "free <a>Apply</a>", etc.
--   You "lift" from <tt>f a</tt> to <tt><a>Chain1</a> t f a</tt> using
--   <a>inject</a>.
--   
--   Note: this instance doesn't exist directly because of restrictions in
--   typeclasses, but is implemented as
--   
--   <pre>
--   <tt>Associative</tt> t =&gt; <tt>SemigroupIn</tt> (<tt>WrapHBF</tt> t) (<a>Chain1</a> t f)
--   </pre>
--   
--   where <tt>biretract</tt> is <tt>appendChain1</tt>.
--   
--   You can fully "collapse" a <tt><a>Chain</a> t i f</tt> into an
--   <tt>f</tt> with <a>retract</a>, if you have <tt><tt>MonoidIn</tt> t i
--   f</tt>; this could be considered a fundamental property of
--   monoid-ness.
--   
--   This construction is inspired by iteratees and machines.
data Chain1 t f a
Done1 :: f a -> Chain1 t f a
More1 :: t f (Chain1 t f) a -> Chain1 t f a

-- | Recursively fold down a <a>Chain1</a>. Provide a function on how to
--   handle the "single <tt>f</tt> case" (<a>inject</a>), and how to handle
--   the "combined <tt>t f g</tt> case", and this will fold the entire
--   <tt><a>Chain1</a> t f</tt> into a single <tt>g</tt>.
--   
--   This is a catamorphism.
foldChain1 :: forall t f g. HBifunctor t => (f ~> g) -> (t f g ~> g) -> Chain1 t f ~> g

-- | An "effectful" version of <a>foldChain1</a>, weaving Applicative
--   effects.
foldChain1A :: (HBifunctor t, Functor h) => (forall x. f x -> h (g x)) -> (forall x. t f (Comp h g) x -> h (g x)) -> Chain1 t f a -> h (g a)

-- | Recursively build up a <a>Chain1</a>. Provide a function that takes
--   some starting seed <tt>g</tt> and returns either "done" (<tt>f</tt>)
--   or "continue further" (<tt>t f g</tt>), and it will create a
--   <tt><a>Chain1</a> t f</tt> from a <tt>g</tt>.
--   
--   This is an anamorphism.
unfoldChain1 :: forall t f (g :: Type -> Type). HBifunctor t => (g ~> (f :+: t f g)) -> g ~> Chain1 t f

-- | A type <tt><a>NonEmptyBy</a> t</tt> is supposed to represent the
--   successive application of <tt>t</tt>s to itself. The type
--   <tt><a>Chain1</a> t f</tt> is an actual concrete ADT that contains
--   successive applications of <tt>t</tt> to itself, and you can pattern
--   match on each layer.
--   
--   <a>unrollingNE</a> states that the two types are isormorphic. Use
--   <a>unrollNE</a> and <a>rerollNE</a> to convert between the two.
unrollingNE :: forall t f. (Associative t, FunctorBy t f) => NonEmptyBy t f <~> Chain1 t f

-- | A type <tt><a>NonEmptyBy</a> t</tt> is supposed to represent the
--   successive application of <tt>t</tt>s to itself. <a>unrollNE</a> makes
--   that successive application explicit, buy converting it to a literal
--   <a>Chain1</a> of applications of <tt>t</tt> to itself.
--   
--   <pre>
--   <a>unrollNE</a> = <a>unfoldChain1</a> <a>matchNE</a>
--   </pre>
unrollNE :: (Associative t, FunctorBy t f) => NonEmptyBy t f ~> Chain1 t f

-- | A type <tt><a>NonEmptyBy</a> t</tt> is supposed to represent the
--   successive application of <tt>t</tt>s to itself. <a>rerollNE</a> takes
--   an explicit <a>Chain1</a> of applications of <tt>t</tt> to itself and
--   rolls it back up into an <tt><a>NonEmptyBy</a> t</tt>.
--   
--   <pre>
--   <a>rerollNE</a> = <a>foldChain1</a> <a>inject</a> <a>consNE</a>
--   </pre>
rerollNE :: Associative t => Chain1 t f ~> NonEmptyBy t f

-- | <a>Chain1</a> is a semigroup with respect to <tt>t</tt>: we can
--   "combine" them in an associative way.
--   
--   This is essentially <a>biretract</a>, but only requiring
--   <tt><a>Associative</a> t</tt>: it comes from the fact that
--   <tt><a>Chain1</a> t</tt> is the "free <tt><a>SemigroupIn</a> t</tt>".
appendChain1 :: forall t f. (Associative t, FunctorBy t f) => t (Chain1 t f) (Chain1 t f) ~> Chain1 t f

-- | A <a>Chain1</a> is "one or more linked <tt>f</tt>s", and a
--   <a>Chain</a> is "zero or more linked <tt>f</tt>s". So, we can convert
--   from a <a>Chain1</a> to a <a>Chain</a> that always has at least one
--   <tt>f</tt>.
--   
--   The result of this function always is made with <a>More</a> at the top
--   level.
fromChain1 :: Tensor t i => Chain1 t f ~> Chain t i f

-- | For completeness, an isomorphism between <a>Chain1</a> and its two
--   constructors, to match <tt>matchNE</tt>.
matchChain1 :: Chain1 t f ~> (f :+: t f (Chain1 t f))

-- | Convert a tensor value pairing two <tt>f</tt>s into a two-item
--   <a>Chain1</a>. An analogue of <tt>toNonEmptyBy</tt>.
toChain1 :: HBifunctor t => t f f ~> Chain1 t f

-- | Create a singleton <a>Chain1</a>.
injectChain1 :: f ~> Chain1 t f

-- | A <tt><a>Chain1</a> t f</tt> is like a non-empty linked list of
--   <tt>f</tt>s, and a <tt><a>Chain</a> t i f</tt> is a possibly-empty
--   linked list of <tt>f</tt>s. This witnesses the fact that the former is
--   isomorphic to <tt>f</tt> consed to the latter.
splittingChain1 :: forall t i f. (Matchable t i, FunctorBy t f) => Chain1 t f <~> t f (Chain t i f)

-- | The "forward" function representing <tt>splittingChain1</tt>. Provided
--   here as a separate function because it does not require
--   <tt><a>Functor</a> f</tt>.
splitChain1 :: forall t i f. Tensor t i => Chain1 t f ~> t f (Chain t i f)

-- | A <tt><a>Chain</a> t i f</tt> is a linked list of <tt>f</tt>s, and a
--   <tt><a>Chain1</a> t f</tt> is a non-empty linked list of <tt>f</tt>s.
--   This witnesses the fact that a <tt><a>Chain</a> t i f</tt> is either
--   empty (<tt>i</tt>) or non-empty (<tt><a>Chain1</a> t f</tt>).
matchingChain :: forall t i f. (Tensor t i, Matchable t i, FunctorBy t f) => Chain t i f <~> (i :+: Chain1 t f)

-- | The "reverse" function representing <a>matchingChain</a>. Provided
--   here as a separate function because it does not require
--   <tt><a>Functor</a> f</tt>.
unmatchChain :: forall t i f. Tensor t i => (i :+: Chain1 t f) ~> Chain t i f
instance (Data.HFunctor.Internal.HBifunctor t, Data.HBifunctor.Associative.SemigroupIn t f) => Data.HFunctor.Interpret.Interpret (Data.HFunctor.Chain.Internal.Chain1 t) f
instance (Data.HBifunctor.Associative.Associative t, Data.HBifunctor.Associative.FunctorBy t f, Data.HBifunctor.Associative.FunctorBy t (Data.HFunctor.Chain.Internal.Chain1 t f)) => Data.HBifunctor.Associative.SemigroupIn (Data.HBifunctor.Associative.WrapHBF t) (Data.HFunctor.Chain.Internal.Chain1 t f)
instance GHC.Base.Functor f => Data.Functor.Bind.Class.Apply (Data.HFunctor.Chain.Internal.Chain1 Data.Functor.Day.Day f)
instance GHC.Base.Functor f => Data.Functor.Bind.Class.Apply (Data.HFunctor.Chain.Internal.Chain1 Control.Monad.Freer.Church.Comp f)
instance GHC.Base.Functor f => Data.Functor.Bind.Class.Bind (Data.HFunctor.Chain.Internal.Chain1 Control.Monad.Freer.Church.Comp f)
instance GHC.Base.Functor f => Data.Functor.Alt.Alt (Data.HFunctor.Chain.Internal.Chain1 (GHC.Generics.:*:) f)
instance GHC.Base.Functor f => Data.Functor.Alt.Alt (Data.HFunctor.Chain.Internal.Chain1 Data.Functor.Product.Product f)
instance Data.Functor.Contravariant.Contravariant f => Data.Functor.Contravariant.Divise.Divise (Data.HFunctor.Chain.Internal.Chain1 Data.Functor.Contravariant.Day.Day f)
instance Data.Functor.Contravariant.Contravariant f => Data.Functor.Contravariant.Decide.Decide (Data.HFunctor.Chain.Internal.Chain1 Data.Functor.Contravariant.Night.Night f)
instance Data.Functor.Invariant.Invariant f => Data.Functor.Invariant.Inplicative.Inply (Data.HFunctor.Chain.Internal.Chain1 Data.Functor.Invariant.Day.Day f)
instance Data.HBifunctor.Tensor.Internal.Tensor t i => Data.HFunctor.Inject (Data.HFunctor.Chain.Internal.Chain t i)
instance Data.Functor.Invariant.Invariant f => Data.Functor.Invariant.Internative.Inalt (Data.HFunctor.Chain.Internal.Chain1 Data.Functor.Invariant.Night.Night f)
instance Data.HBifunctor.Tensor.MonoidIn t i f => Data.HFunctor.Interpret.Interpret (Data.HFunctor.Chain.Internal.Chain t i) f
instance (Data.HBifunctor.Tensor.Internal.Tensor t i, Data.HBifunctor.Associative.FunctorBy t (Data.HFunctor.Chain.Internal.Chain t i f)) => Data.HBifunctor.Associative.SemigroupIn (Data.HBifunctor.Associative.WrapHBF t) (Data.HFunctor.Chain.Internal.Chain t i f)
instance (Data.HBifunctor.Tensor.Internal.Tensor t i, Data.HBifunctor.Associative.FunctorBy t (Data.HFunctor.Chain.Internal.Chain t i f)) => Data.HBifunctor.Tensor.MonoidIn (Data.HBifunctor.Associative.WrapHBF t) (Data.HBifunctor.Tensor.WrapF i) (Data.HFunctor.Chain.Internal.Chain t i f)
instance Data.Functor.Bind.Class.Apply (Data.HFunctor.Chain.Internal.Chain Data.Functor.Day.Day Data.Functor.Identity.Identity f)
instance GHC.Base.Applicative (Data.HFunctor.Chain.Internal.Chain Data.Functor.Day.Day Data.Functor.Identity.Identity f)
instance Data.Functor.Contravariant.Divise.Divise (Data.HFunctor.Chain.Internal.Chain Data.Functor.Contravariant.Day.Day Data.Proxy.Proxy f)
instance Data.Functor.Contravariant.Divisible.Divisible (Data.HFunctor.Chain.Internal.Chain Data.Functor.Contravariant.Day.Day Data.Proxy.Proxy f)
instance Data.Functor.Invariant.Inplicative.Inply (Data.HFunctor.Chain.Internal.Chain Data.Functor.Invariant.Day.Day Data.Functor.Identity.Identity f)
instance Data.Functor.Invariant.Inplicative.Inplicative (Data.HFunctor.Chain.Internal.Chain Data.Functor.Invariant.Day.Day Data.Functor.Identity.Identity f)
instance Data.Functor.Invariant.Internative.Inalt (Data.HFunctor.Chain.Internal.Chain Data.Functor.Invariant.Night.Night Data.Functor.Contravariant.Night.Not f)
instance Data.Functor.Invariant.Internative.Inplus (Data.HFunctor.Chain.Internal.Chain Data.Functor.Invariant.Night.Night Data.Functor.Contravariant.Night.Not f)
instance Data.Functor.Contravariant.Decide.Decide (Data.HFunctor.Chain.Internal.Chain Data.Functor.Contravariant.Night.Night Data.Functor.Contravariant.Night.Not f)
instance Data.Functor.Contravariant.Conclude.Conclude (Data.HFunctor.Chain.Internal.Chain Data.Functor.Contravariant.Night.Night Data.Functor.Contravariant.Night.Not f)
instance Data.Functor.Bind.Class.Apply (Data.HFunctor.Chain.Internal.Chain Control.Monad.Freer.Church.Comp Data.Functor.Identity.Identity f)
instance GHC.Base.Applicative (Data.HFunctor.Chain.Internal.Chain Control.Monad.Freer.Church.Comp Data.Functor.Identity.Identity f)
instance Data.Functor.Bind.Class.Bind (Data.HFunctor.Chain.Internal.Chain Control.Monad.Freer.Church.Comp Data.Functor.Identity.Identity f)
instance GHC.Base.Monad (Data.HFunctor.Chain.Internal.Chain Control.Monad.Freer.Church.Comp Data.Functor.Identity.Identity f)
instance GHC.Base.Functor f => Data.Functor.Alt.Alt (Data.HFunctor.Chain.Internal.Chain (GHC.Generics.:*:) Data.Proxy.Proxy f)
instance GHC.Base.Functor f => Data.Functor.Plus.Plus (Data.HFunctor.Chain.Internal.Chain (GHC.Generics.:*:) Data.Proxy.Proxy f)
instance GHC.Base.Functor f => Data.Functor.Alt.Alt (Data.HFunctor.Chain.Internal.Chain Data.Functor.Product.Product Data.Proxy.Proxy f)
instance GHC.Base.Functor f => Data.Functor.Plus.Plus (Data.HFunctor.Chain.Internal.Chain Data.Functor.Product.Product Data.Proxy.Proxy f)


-- | Provide an invariant functor combinator choice-collector, like a
--   combination of <a>ListF</a> and <a>Dec</a>.
--   
--   This module was named <a>DecAlt</a> before v0.4.0.0
module Data.Functor.Invariant.Internative.Free

-- | The invariant version of <tt>ListF</tt> and <tt>Dec</tt>: combines the
--   capabilities of both <tt>ListF</tt> and <tt>Dec</tt> together.
--   
--   Conceptually you can think of <tt><a>DecAlt</a> f a</tt> as a way of
--   consuming and producing <tt>a</tt>s that contains a collection of
--   <tt>f x</tt>s of different <tt>x</tt>s. When interpreting this, a
--   <i>specific</i> <tt>f</tt> is chosen to handle the interpreting; the
--   <tt>a</tt> is sent to that <tt>f</tt>, and the single result is
--   returned back out.
--   
--   To do this, the main tools to combine <a>DecAlt</a>s are its
--   <a>Inalt</a> instance, using <a>swerve</a> to combine two
--   <a>DecAlt</a>s in a choice-like manner (with the choosing and
--   re-injecting function), and its <a>Inplus</a> instance, using
--   <a>reject</a> to create an "empty" choice that is never taken.
--   
--   This does have an <a>Interpret</a> function, but the target typeclass
--   (<a>Inplus</a>) doesn't have too many useful instances. Instead, you
--   are probably going to run it into either <tt>Plus</tt> instance (to
--   "produce" an <tt>a</tt> from a <tt><a>DecAlt</a> f a</tt>) with
--   <tt>runCoDecAlt</tt>, or a <tt>Choose</tt> instance (to "consume" an
--   <tt>a</tt> from a <tt><a>DecAlt</a> f a</tt>) with
--   <tt>runContraDecAlt</tt>.
--   
--   If you think of this type as a combination of <tt>ListF</tt> and
--   <tt>Dec</tt>, then you can also extract the <tt>ListF</tt> part out
--   using <tt>decAltListF</tt>, and extract the <tt>Dec</tt> part out
--   using <tt>decAltDec</tt>.
--   
--   Note that this type's utility is similar to that of <tt><tt>PostT</tt>
--   <tt>Dec</tt></tt>, except <tt><tt>PostT</tt> <tt>Dec</tt></tt> lets
--   you use <tt>Conclude</tt> typeclass methods to assemble it.
newtype DecAlt f a
DecAlt :: Chain Night Not f a -> DecAlt f a
[unDecAlt] :: DecAlt f a -> Chain Night Not f a

-- | Match on a non-empty <a>DecAlt</a>; contains the splitting function,
--   the two rejoining functions, the first <tt>f</tt>, and the rest of the
--   chain. Analogous to the <a>Choose</a> constructor.
pattern Swerve :: (b -> a) -> (c -> a) -> (a -> Either b c) -> f b -> DecAlt f c -> DecAlt f a

-- | Match on an "empty" <a>DecAlt</a>; contains no <tt>f</tt>s, but only
--   the terminal value. Analogous to the <a>Lose</a> constructor.
pattern Reject :: (a -> Void) -> DecAlt f a

-- | In the covariant direction, we can interpret out of a <a>Chain</a> of
--   <a>Night</a> into any <a>Plus</a>.
runCoDecAlt :: forall f g. Plus g => (f ~> g) -> DecAlt f ~> g

-- | In the contravariant direction, we can interpret out of a <a>Chain</a>
--   of <a>Night</a> into any <a>Conclude</a>.
runContraDecAlt :: forall f g. Conclude g => (f ~> g) -> DecAlt f ~> g

-- | Extract the <a>ListF</a> part out of a <a>DecAlt</a>, shedding the
--   contravariant bits.
decAltListF :: Functor f => DecAlt f ~> ListF f

-- | Extract the <a>ListF</a> part out of a <a>DecAlt</a>, shedding the
--   contravariant bits.
--   
--   This version does not require a <a>Functor</a> constraint because it
--   converts to the coyoneda-wrapped product, which is more accurately the
--   true conversion to a covariant chain.
decAltListF_ :: DecAlt f ~> ComposeT ListF Coyoneda f

-- | Extract the <a>Dec</a> part out of a <a>DecAlt</a>, shedding the
--   covariant bits.
decAltDec :: DecAlt f ~> Dec f

-- | General-purpose folder of <a>DecAlt</a>. Provide a way to handle the
--   identity (<tt>empty</tt><i><a>conclude</a></i><a>Reject</a>) and a way
--   to handle a cons (<a>&lt;!&gt;</a><i><a>decide</a></i><a>swerve</a>).
foldDecAlt :: (forall x. (x -> Void) -> g x) -> (Night f g ~> g) -> DecAlt f ~> g

-- | Convenient wrapper to build up a <a>DecAlt</a> on by providing each
--   branch of it. This makes it much easier to build up longer chains
--   because you would only need to write the splitting/joining functions
--   in one place.
--   
--   For example, if you had a data type
--   
--   <pre>
--   data MyType = MTI Int | MTB Bool | MTS String
--   </pre>
--   
--   and an invariant functor <tt>Prim</tt> (representing, say, a
--   bidirectional parser, where <tt>Prim Int</tt> is a bidirectional
--   parser for an <a>Int</a><tt>), then you could assemble a bidirectional
--   parser for a </tt>MyType@ using:
--   
--   <pre>
--   invmap (case MTI x -&gt; Z (I x); MTB y -&gt; S (Z (I y)); MTS z -&gt; S (S (Z (I z))))
--          (case Z (I x) -&gt; MTI x; S (Z (I y)) -&gt; MTB y; S (S (Z (I z))) -&gt; MTS z) $
--     assembleDecAlt $ intPrim
--                       :* boolPrim
--                       :* stringPrim
--                       :* Nil
--   </pre>
--   
--   Some notes on usefulness depending on how many components you have:
--   
--   <ul>
--   <li>If you have 0 components, use <a>Reject</a> directly.</li>
--   <li>If you have 1 component, use <a>inject</a> or <a>injectChain</a>
--   directly.</li>
--   <li>If you have 2 components, use <a>toListBy</a> or
--   <a>toChain</a>.</li>
--   <li>If you have 3 or more components, these combinators may be useful;
--   otherwise you'd need to manually peel off eithers one-by-one.</li>
--   </ul>
--   
--   If each component is itself a <tt><a>DecAlt</a> f</tt> (instead of
--   <tt>f</tt>), you can use <a>concatInplus</a>.
assembleDecAlt :: NP f as -> DecAlt f (NS I as)

-- | The invariant version of <tt>NonEmptyF</tt> and <tt>Dec1</tt>:
--   combines the capabilities of both <tt>NonEmptyF</tt> and <tt>Dec1</tt>
--   together.
--   
--   Conceptually you can think of <tt><a>DecAlt1</a> f a</tt> as a way of
--   consuming and producing <tt>a</tt>s that contains a (non-empty)
--   collection of <tt>f x</tt>s of different <tt>x</tt>s. When
--   interpreting this, a <i>specific</i> <tt>f</tt> is chosen to handle
--   the interpreting; the <tt>a</tt> is sent to that <tt>f</tt>, and the
--   single result is returned back out.
--   
--   To do this, the main tools to combine <a>DecAlt1</a>s are its
--   <a>Inalt</a> instance, using <a>swerve</a> to combine two
--   <a>DecAlt1</a>s in a choice-like manner (with the choosing and
--   re-injecting function).
--   
--   This does have an <a>Interpret</a> function, but the target typeclass
--   (<a>Inalt</a>) doesn't have too many useful instances. Instead, you
--   are probably going to run it into either an <tt>Alt</tt> instance (to
--   "produce" an <tt>a</tt> from a <tt><a>DecAlt1</a> f a</tt>) with
--   <tt>runCoDecAlt1</tt>, or a <tt>Decide</tt> instance (to "consume" an
--   <tt>a</tt> from a <tt><a>DecAlt1</a> f a</tt>) with
--   <tt>runContraDecAlt1</tt>.
--   
--   If you think of this type as a combination of <tt>NonEmptyF</tt> and
--   <tt>Dec1</tt>, then you can also extract the <tt>NonEmptyF</tt> part
--   out using <tt>decAltNonEmptyF</tt>, and extract the <tt>Dec1</tt> part
--   out using <tt>decAltDec1</tt>.
--   
--   Note that this type's utility is similar to that of <tt><tt>PostT</tt>
--   <tt>Dec1</tt></tt>, except <tt><tt>PostT</tt> <tt>Dec1</tt></tt> lets
--   you use <tt>Decide</tt> typeclass methods to assemble it.
newtype DecAlt1 f a
DecAlt1_ :: Chain1 Night f a -> DecAlt1 f a
[unDecAlt1] :: DecAlt1 f a -> Chain1 Night f a

-- | Match on a <a>DecAlt1</a> to get the head and the rest of the items.
--   Analogous to the <a>Dec1</a> constructor.
pattern DecAlt1 :: Invariant f => (b -> a) -> (c -> a) -> (a -> Either b c) -> f b -> DecAlt f c -> DecAlt1 f a

-- | In the covariant direction, we can interpret out of a <a>Chain1</a> of
--   <a>Night</a> into any <a>Alt</a>.
runCoDecAlt1 :: forall f g. Alt g => (f ~> g) -> DecAlt1 f ~> g

-- | In the contravariant direction, we can interpret out of a
--   <a>Chain1</a> of <a>Night</a> into any <a>Decide</a>.
runContraDecAlt1 :: forall f g. Decide g => (f ~> g) -> DecAlt1 f ~> g

-- | Extract the <a>NonEmptyF</a> part out of a <a>DecAlt1</a>, shedding
--   the contravariant bits.
decAltNonEmptyF :: Functor f => DecAlt1 f ~> NonEmptyF f

-- | Extract the <a>NonEmptyF</a> part out of a <a>DecAlt1</a>, shedding
--   the contravariant bits.
--   
--   This version does not require a <a>Functor</a> constraint because it
--   converts to the coyoneda-wrapped product, which is more accurately the
--   true conversion to a covariant chain.
decAltNonEmptyF_ :: DecAlt1 f ~> ComposeT NonEmptyF Coyoneda f

-- | Extract the <a>Dec1</a> part out of a <a>DecAlt1</a>, shedding the
--   covariant bits.
decAltDec1 :: DecAlt1 f ~> Dec1 f

-- | General-purpose folder of <a>DecAlt1</a>. Provide a way to handle the
--   individual leaves and a way to handle a cons
--   (<a>&lt;!&gt;</a><i><a>decide</a></i><a>swerve</a>).
foldDecAlt1 :: (f ~> g) -> (Night f g ~> g) -> DecAlt1 f ~> g

-- | A version of <a>assembleDecAlt</a> but for <a>DecAlt1</a> instead. Can
--   be useful if you intend on interpreting it into something with only a
--   <a>Decide</a> or <a>Alt</a> instance, but no <a>Decidable</a> or
--   <a>Plus</a> or <a>Alternative</a>.
--   
--   If each component is itself a <tt><a>DecAlt1</a> f</tt> (instead of
--   <tt>f</tt>), you can use <a>concatInalt</a>.
assembleDecAlt1 :: Invariant f => NP f (a : as) -> DecAlt1 f (NS I (a : as))
instance Data.Functor.Invariant.Internative.Inalt (Data.HFunctor.Chain.Internal.DecAlt f)
instance Data.Functor.Invariant.Internative.Inplus (Data.HFunctor.Chain.Internal.DecAlt f)
instance Data.Functor.Invariant.Invariant f => Data.Functor.Invariant.Internative.Inalt (Data.HFunctor.Chain.Internal.DecAlt1 f)


-- | Provide an invariant functor combinator sequencer, like a combination
--   of <a>Ap</a> and <a>Div</a>.
--   
--   This module was named <a>DecAlt</a> before v0.4.0.0
module Data.Functor.Invariant.Inplicative.Free

-- | The invariant version of <tt>Ap</tt> and <tt>Div</tt>: combines the
--   capabilities of both <tt>Ap</tt> and <tt>Div</tt> together.
--   
--   Conceptually you can think of <tt><a>DivAp</a> f a</tt> as a way of
--   consuming and producing <tt>a</tt>s that contains a collection of
--   <tt>f x</tt>s of different <tt>x</tt>s. When interpreting this, each
--   <tt>a</tt> is distributed across all <tt>f x</tt>s to each interpret,
--   and then re-combined again to produce the resulting <tt>a</tt>.
--   
--   To do this, the main tools to combine <a>DivAp</a>s are its
--   <tt>Inply</tt> instance, using <tt>gather</tt> to combine two
--   <a>DivAp</a>s in a choice-like manner (with the splitting and
--   re-combining function), and its <tt>Inplicative</tt> instance, using
--   <tt>knot</tt> to create an "empty" branch that does not contribute to
--   the structure.
--   
--   This does have an <a>Interpret</a> function, but the target typeclass
--   (<tt>Inplicative</tt>) doesn't have too many useful instances.
--   Instead, you are probably going to run it into either
--   <a>Applicative</a> instance (to "produce" an <tt>a</tt> from a
--   <tt><a>DivAp</a> f a</tt>) with <tt>runCoDivAp</tt>, or a
--   <tt>Divisible</tt> instance (to "consume" an <tt>a</tt> from a
--   <tt><a>DivAp</a> f a</tt>) with <tt>runContraDivAp</tt>.
--   
--   If you think of this type as a combination of <tt>Ap</tt> and
--   <tt>Div</tt>, then you can also extract the <tt>Ap</tt> part out using
--   <tt>divApAp</tt>, and extract the <tt>Div</tt> part out using
--   <tt>divApDiv</tt>.
--   
--   Note that this type's utility is similar to that of <tt><tt>PreT</tt>
--   <tt>Ap</tt></tt>, except <tt><tt>PreT</tt> <tt>Ap</tt></tt> lets you
--   use <a>Applicative</a> typeclass methods to assemble it.
newtype DivAp f a
DivAp :: Chain Day Identity f a -> DivAp f a
[unDivAp] :: DivAp f a -> Chain Day Identity f a

-- | Match on a non-empty <a>DivAp</a>; contains no <tt>f</tt>s, but only
--   the terminal value. Analogous to the <a>Ap</a> constructor.
--   
--   Note that the order of the first two arguments has swapped as of
--   v0.4.0.0
pattern Gather :: (b -> c -> a) -> (a -> (b, c)) -> f b -> DivAp f c -> DivAp f a

-- | Match on an "empty" <a>DivAp</a>; contains no <tt>f</tt>s, but only
--   the terminal value. Analogous to <a>Pure</a>.
pattern Knot :: a -> DivAp f a

-- | In the covariant direction, we can interpret out of a <a>Chain</a> of
--   <a>Day</a> into any <a>Applicative</a>.
runCoDivAp :: forall f g. Applicative g => (f ~> g) -> DivAp f ~> g

-- | In the contravariant direction, we can interpret out of a <a>Chain</a>
--   of <a>Day</a> into any <a>Divisible</a>.
runContraDivAp :: forall f g. Divisible g => (f ~> g) -> DivAp f ~> g

-- | Extract the <a>Ap</a> part out of a <a>DivAp</a>, shedding the
--   contravariant bits.
divApAp :: DivAp f ~> Ap f

-- | Extract the <a>Div</a> part out of a <a>DivAp</a>, shedding the
--   covariant bits.
divApDiv :: DivAp f ~> Div f

-- | General-purpose folder of <a>DivAp</a>. Provide a way to handle the
--   identity (<a>pure</a><i><a>conquer</a></i><a>Knot</a>) and a way to
--   handle a cons (<a>liftA2</a><i><a>divide</a></i><a>Gather</a>).
foldDivAp :: (forall x. x -> g x) -> (Day f g ~> g) -> DivAp f ~> g

-- | Convenient wrapper to build up a <a>DivAp</a> by providing each
--   component of it. This makes it much easier to build up longer chains
--   because you would only need to write the splitting/joining functions
--   in one place.
--   
--   For example, if you had a data type
--   
--   <pre>
--   data MyType = MT Int Bool String
--   </pre>
--   
--   and an invariant functor <tt>Prim</tt> (representing, say, a
--   bidirectional parser, where <tt>Prim Int</tt> is a bidirectional
--   parser for an <a>Int</a><tt>), then you could assemble a bidirectional
--   parser for a </tt>MyType@ using:
--   
--   <pre>
--   invmap ((MyType x y z) -&gt; I x :* I y :* I z :* Nil)
--          ((I x :* I y :* I z :* Nil) -&gt; MyType x y z) $
--     assembleDivAp $ intPrim
--                     :* boolPrim
--                     :* stringPrim
--                     :* Nil
--   </pre>
--   
--   Some notes on usefulness depending on how many components you have:
--   
--   <ul>
--   <li>If you have 0 components, use <a>Knot</a> directly.</li>
--   <li>If you have 1 component, use <a>inject</a> or <a>injectChain</a>
--   directly.</li>
--   <li>If you have 2 components, use <a>toListBy</a> or
--   <a>toChain</a>.</li>
--   <li>If you have 3 or more components, these combinators may be useful;
--   otherwise you'd need to manually peel off tuples one-by-one.</li>
--   </ul>
--   
--   If each component is itself a <tt><a>DivAp</a> f</tt> (instead of
--   <tt>f</tt>), you can use <a>concatInplicative</a>.
assembleDivAp :: NP f as -> DivAp f (NP I as)

-- | A version of <a>assembleDivAp</a> using <a>XRec</a> from <i>vinyl</i>
--   instead of <a>NP</a> from <i>sop-core</i>. This can be more convenient
--   because it doesn't require manual unwrapping/wrapping of components.
--   
--   <pre>
--   data MyType = MT Int Bool String
--   
--   invmap ((MyType x y z) -&gt; x ::&amp; y ::&amp; z ::&amp; RNil)
--          ((x ::&amp; y ::&amp; z ::&amp; RNil) -&gt; MyType x y z) $
--     assembleDivApRec $ intPrim
--                        :&amp; boolPrim
--                        :&amp; stringPrim
--                        :&amp; Nil
--   </pre>
--   
--   If each component is itself a <tt><a>DivAp</a> f</tt> (instead of
--   <tt>f</tt>), you can use <tt>concatDivApRec</tt>.
assembleDivApRec :: Rec f as -> DivAp f (XRec Identity as)

-- | The invariant version of <tt>Ap1</tt> and <tt>Div1</tt>: combines the
--   capabilities of both <tt>Ap1</tt> and <tt>Div1</tt> together.
--   
--   Conceptually you can think of <tt><a>DivAp1</a> f a</tt> as a way of
--   consuming and producing <tt>a</tt>s that contains a (non-empty)
--   collection of <tt>f x</tt>s of different <tt>x</tt>s. When
--   interpreting this, each <tt>a</tt> is distributed across all <tt>f
--   x</tt>s to each interpret, and then re-combined again to produce the
--   resulting <tt>a</tt>.
--   
--   To do this, the main tools to combine <a>DivAp1</a>s are its
--   <tt>Inply</tt> instance, using <tt>gather</tt> to combine two
--   <a>DivAp1</a>s in a parallel-fork-like manner (with the splitting and
--   re-combining function).
--   
--   This does have an <a>Interpret</a> function, but the target typeclass
--   (<tt>Inply</tt>) doesn't have too many useful instances. Instead, you
--   are probably going to run it into either <a>Apply</a> instance (to
--   "produce" an <tt>a</tt> from a <tt><a>DivAp1</a> f a</tt>) with
--   <tt>runCoDivAp1</tt>, or a <tt>Divise</tt> instance (to "consume" an
--   <tt>a</tt> from a <tt><a>DivAp1</a> f a</tt>) with
--   <tt>runContraDivAp1</tt>.
--   
--   If you think of this type as a combination of <tt>Ap1</tt> and
--   <tt>Div1</tt>, then you can also extract the <tt>Ap1</tt> part out
--   using <tt>divApAp1</tt>, and extract the <tt>Div1</tt> part out using
--   <tt>divApDiv1</tt>.
--   
--   Note that this type's utility is similar to that of <tt><tt>PreT</tt>
--   <tt>Ap1</tt></tt>, except <tt><tt>PreT</tt> <tt>Ap1</tt></tt> lets you
--   use <a>Apply</a> typeclass methods to assemble it.
newtype DivAp1 f a
DivAp1_ :: Chain1 Day f a -> DivAp1 f a
[unDivAp1] :: DivAp1 f a -> Chain1 Day f a

-- | Match on a <a>DivAp1</a> to get the head and the rest of the items.
--   Analogous to the <a>Ap1</a> constructor.
--   
--   Note that the order of the first two arguments has swapped as of
--   v0.4.0.0
pattern DivAp1 :: Invariant f => (b -> c -> a) -> (a -> (b, c)) -> f b -> DivAp f c -> DivAp1 f a

-- | In the covariant direction, we can interpret out of a <a>Chain1</a> of
--   <a>Day</a> into any <a>Apply</a>.
runCoDivAp1 :: forall f g. Apply g => (f ~> g) -> DivAp1 f ~> g

-- | In the contravariant direction, we can interpret out of a
--   <a>Chain1</a> of <a>Day</a> into any <a>Divise</a>.
runContraDivAp1 :: forall f g. Divise g => (f ~> g) -> DivAp1 f ~> g

-- | Extract the <a>Ap1</a> part out of a <a>DivAp1</a>, shedding the
--   contravariant bits.
divApAp1 :: DivAp1 f ~> Ap1 f

-- | Extract the <a>Div1</a> part out of a <a>DivAp1</a>, shedding the
--   covariant bits.
divApDiv1 :: DivAp1 f ~> Div1 f

-- | General-purpose folder of <a>DivAp1</a>. Provide a way to handle the
--   individual leaves and a way to handle a cons
--   ('liftF2<i><a>divise</a></i><a>Gather</a>).
foldDivAp1 :: (f ~> g) -> (Day f g ~> g) -> DivAp1 f ~> g

-- | A version of <a>assembleDivAp</a> but for <a>DivAp1</a> instead. Can
--   be useful if you intend on interpreting it into something with only a
--   <a>Divise</a> or <a>Apply</a> instance, but no <a>Divisible</a> or
--   <a>Applicative</a>.
--   
--   If each component is itself a <tt><a>DivAp1</a> f</tt> (instead of
--   <tt>f</tt>), you can use <a>concatInply</a>.
assembleDivAp1 :: Invariant f => NP f (a : as) -> DivAp1 f (NP I (a : as))

-- | A version of <a>assembleDivAp1</a> using <a>XRec</a> from <i>vinyl</i>
--   instead of <a>NP</a> from <i>sop-core</i>. This can be more convenient
--   because it doesn't require manual unwrapping/wrapping of components.
--   
--   If each component is itself a <tt><a>DivAp1</a> f</tt> (instead of
--   <tt>f</tt>), you can use <tt>concatDivAp1Rec</tt>.
assembleDivAp1Rec :: Invariant f => Rec f (a : as) -> DivAp1 f (XRec Identity (a : as))

-- | Interpret the covariant part of a <a>Day</a> into a target context
--   <tt>h</tt>, as long as the context is an instance of <a>Apply</a>. The
--   <a>Apply</a> is used to combine results back together using
--   <a>&lt;*&gt;</a>.
runDayApply :: forall f g h. Apply h => (f ~> h) -> (g ~> h) -> Day f g ~> h

-- | Interpret the contravariant part of a <a>Day</a> into a target context
--   <tt>h</tt>, as long as the context is an instance of <a>Divise</a>.
--   The <a>Divise</a> is used to split up the input to pass to each of the
--   actions.
runDayDivise :: forall f g h. Divise h => (f ~> h) -> (g ~> h) -> Day f g ~> h
instance Data.Functor.Invariant.Inplicative.Inply (Data.HFunctor.Chain.Internal.DivAp f)
instance Data.Functor.Invariant.Inplicative.Inplicative (Data.HFunctor.Chain.Internal.DivAp f)
instance Data.Functor.Invariant.Invariant f => Data.Functor.Invariant.Inplicative.Inply (Data.HFunctor.Chain.Internal.DivAp1 f)
instance Data.Functor.Invariant.Inplicative.Inply f => Data.HFunctor.Interpret.Interpret Data.HFunctor.Chain.Internal.DivAp1 f
instance Data.Functor.Invariant.Inplicative.Inplicative f => Data.HFunctor.Interpret.Interpret Data.HFunctor.Chain.Internal.DivAp f


-- | Provides <a>Final</a>, which can be considered the "free
--   <a>Interpret</a> over a constraint": generate a handy <a>Interpret</a>
--   instance for any constraint <tt>c</tt>.
module Data.HFunctor.Final

-- | A simple way to inject/reject into any eventual typeclass.
--   
--   In a way, this is the "ultimate" multi-purpose <a>Interpret</a>
--   instance. You can use this to inject an <tt>f</tt> into a free
--   structure of any typeclass. If you want <tt>f</tt> to have a
--   <a>Monad</a> instance, for example, just use
--   
--   <pre>
--   <a>inject</a> :: f a -&gt; <a>Final</a> <a>Monad</a> f a
--   </pre>
--   
--   When you want to eventually interpret out the data, use:
--   
--   <pre>
--   <a>interpret</a> :: (f <a>~&gt;</a> g) -&gt; <a>Final</a> c f a -&gt; g a
--   </pre>
--   
--   Essentially, <tt><a>Final</a> c</tt> is the "free c". <tt><a>Final</a>
--   <a>Monad</a></tt> is the free <a>Monad</a>, etc.
--   
--   <a>Final</a> can theoretically replace <a>Ap</a>, <a>Ap1</a>,
--   <a>ListF</a>, <a>NonEmptyF</a>, <a>MaybeF</a>, <a>Free</a>,
--   <a>Identity</a>, <a>Coyoneda</a>, and other instances of
--   <a>FreeOf</a>, if you don't care about being able to pattern match on
--   explicit structure.
--   
--   However, it cannot replace <a>Interpret</a> instances that are not
--   free structures, like <a>Step</a>, <a>Steps</a>, <a>Backwards</a>,
--   etc.
--   
--   Note that this doesn't have instances for <i>all</i> the typeclasses
--   you could lift things into; you probably have to define your own if
--   you want to use <tt><a>Final</a> c</tt> as an <i>instance</i> of
--   <tt>c</tt> (using <a>liftFinal0</a>, <a>liftFinal1</a>,
--   <a>liftFinal2</a> for help).
newtype Final c f a
Final :: (forall g. c g => (forall x. f x -> g x) -> g a) -> Final c f a
[runFinal] :: Final c f a -> forall g. c g => (forall x. f x -> g x) -> g a

-- | <a>Concretize</a> a <a>Final</a>.
--   
--   <pre>
--   fromFinal :: <a>Final</a> <a>Functor</a> f <a>~&gt;</a> <a>Coyoneda</a> f
--   fromFinal :: <a>Final</a> <a>Applicative</a> f <a>~&gt;</a> <a>Ap</a> f
--   fromFinal :: <a>Final</a> <a>Alternative</a> f <a>~&gt;</a> <a>Alt</a> f
--   fromFinal :: <a>Final</a> <a>Monad</a> f <a>~&gt;</a> <a>Free</a> f
--   fromFinal :: <a>Final</a> <a>Pointed</a> f <a>~&gt;</a> <a>Lift</a> f
--   fromFinal :: <a>Final</a> <a>Plus</a> f <a>~&gt;</a> <a>ListF</a> f
--   </pre>
--   
--   This can be useful because <a>Final</a> doesn't have a concrete
--   structure that you can pattern match on and inspect, but <tt>t</tt>
--   might.
--   
--   In the case that this forms an isomorphism with <a>toFinal</a>, the
--   <tt>t</tt> will have an instance of <a>FreeOf</a>.
fromFinal :: (Inject t, c (t f)) => Final c f ~> t f

-- | <a>Finalize</a> an <a>Interpret</a> instance.
--   
--   <pre>
--   toFinal :: <a>Coyoneda</a> f <a>~&gt;</a> <a>Final</a> <a>Functor</a> f
--   toFinal :: <a>Ap</a> f <a>~&gt;</a> <a>Final</a> <a>Applicative</a> f
--   toFinal :: <a>Alt</a> f <a>~&gt;</a> <a>Final</a> <a>Alternative</a> f
--   toFinal :: <a>Free</a> f <a>~&gt;</a> <a>Final</a> <a>Monad</a> f
--   toFinal :: <a>Lift</a> f <a>~&gt;</a> <a>Final</a> <a>Pointed</a> f
--   toFinal :: <a>ListF</a> f <a>~&gt;</a> <a>Final</a> <a>Plus</a> f
--   </pre>
--   
--   Note that the instance of <tt>c</tt> for <tt><a>Final</a> c</tt> must
--   be defined.
--   
--   This operation can potentially <i>forget</i> structure in <tt>t</tt>.
--   For example, we have:
--   
--   <pre>
--   <a>toFinal</a> :: <a>Steps</a> f ~&gt; <a>Final</a> <a>Alt</a> f
--   </pre>
--   
--   In this process, we lose the "positional" structure of <a>Steps</a>.
--   
--   In the case where <a>toFinal</a> doesn't lose any information, this
--   will form an isomorphism with <a>fromFinal</a>, and <tt>t</tt> is
--   known as the "Free <tt>c</tt>". For such a situation, <tt>t</tt> will
--   have a <a>FreeOf</a> instance.
toFinal :: Interpret t (Final c f) => t f ~> Final c f

-- | A typeclass associating a free structure with the typeclass it is free
--   on.
--   
--   This essentially lists instances of <a>Interpret</a> where a "trip"
--   through <a>Final</a> will leave it unchanged.
--   
--   <pre>
--   <a>fromFree</a> . <a>toFree</a> == id
--   <a>toFree</a> . <a>fromFree</a> == id
--   </pre>
--   
--   This can be useful because <a>Final</a> doesn't have a concrete
--   structure that you can pattern match on and inspect, but <tt>t</tt>
--   might. This lets you work on a concrete structure if you desire.
class FreeOf c t | t -> c where {
    
    -- | What "type" of functor is expected: should be either
    --   <a>Unconstrained</a>, <a>Functor</a>, <a>Contravariant</a>, or
    --   <a>Invariant</a>.
    type family FreeFunctorBy t :: (Type -> Type) -> Constraint;
    type FreeFunctorBy t = Unconstrained;
}
fromFree :: FreeOf c t => t f ~> Final c f
toFree :: (FreeOf c t, FreeFunctorBy t f) => Final c f ~> t f
fromFree :: (FreeOf c t, Interpret t (Final c f)) => t f ~> Final c f
toFree :: (FreeOf c t, Inject t, c (t f)) => Final c f ~> t f

-- | The isomorphism between a free structure and its encoding as
--   <a>Final</a>.
finalizing :: (FreeOf c t, FreeFunctorBy t f) => t f <~> Final c f

-- | Re-interpret the context under a <a>Final</a>.
hoistFinalC :: (forall g x. (c g => g x) -> d g => g x) -> Final c f a -> Final d f a

-- | Lift an action into a <a>Final</a>.
liftFinal0 :: (forall g. c g => g a) -> Final c f a

-- | Map the action in a <a>Final</a>.
liftFinal1 :: (forall g. c g => g a -> g b) -> Final c f a -> Final c f b

-- | Merge two <a>Final</a> actions.
liftFinal2 :: (forall g. c g => g a -> g b -> g d) -> Final c f a -> Final c f b -> Final c f d
instance Data.HFunctor.Final.FreeOf GHC.Base.Functor Data.Functor.Coyoneda.Coyoneda
instance Data.HFunctor.Final.FreeOf Data.Functor.Contravariant.Contravariant Data.Functor.Contravariant.Coyoneda.Coyoneda
instance Data.HFunctor.Final.FreeOf GHC.Base.Applicative Control.Applicative.Free.Ap
instance Data.HFunctor.Final.FreeOf Data.Functor.Bind.Class.Apply Data.Functor.Apply.Free.Ap1
instance Data.HFunctor.Final.FreeOf GHC.Base.Applicative Control.Applicative.Free.Fast.Ap
instance Data.HFunctor.Final.FreeOf GHC.Base.Alternative Control.Alternative.Free.Alt
instance Data.HFunctor.Final.FreeOf GHC.Base.Monad Control.Monad.Freer.Church.Free
instance Data.HFunctor.Final.FreeOf Data.Functor.Bind.Class.Bind Control.Monad.Freer.Church.Free1
instance Data.HFunctor.Final.FreeOf Data.Pointed.Pointed Control.Applicative.Lift.Lift
instance Data.HFunctor.Final.FreeOf Data.Pointed.Pointed Data.Functor.Bind.Class.MaybeApply
instance Data.HFunctor.Final.FreeOf Data.Functor.Alt.Alt Control.Applicative.ListF.NonEmptyF
instance Data.HFunctor.Final.FreeOf Data.Functor.Plus.Plus Control.Applicative.ListF.ListF
instance Data.HFunctor.Final.FreeOf Data.Functor.Contravariant.Divise.Divise Data.Functor.Contravariant.Divisible.Free.Div1
instance Data.HFunctor.Final.FreeOf Data.Functor.Contravariant.Divisible.Divisible Data.Functor.Contravariant.Divisible.Free.Div
instance Data.HFunctor.Final.FreeOf Data.Functor.Contravariant.Decide.Decide Data.Functor.Contravariant.Divisible.Free.Dec1
instance Data.HFunctor.Final.FreeOf Data.Functor.Contravariant.Conclude.Conclude Data.Functor.Contravariant.Divisible.Free.Dec
instance Data.HFunctor.Final.FreeOf Data.Functor.Invariant.Inplicative.Inply Data.HFunctor.Chain.Internal.DivAp1
instance Data.HFunctor.Final.FreeOf Data.Functor.Invariant.Inplicative.Inplicative Data.HFunctor.Chain.Internal.DivAp
instance Data.HFunctor.Final.FreeOf Data.Functor.Invariant.Internative.Inalt Data.HFunctor.Chain.Internal.DecAlt1
instance Data.HFunctor.Final.FreeOf Data.Functor.Invariant.Internative.Inplus Data.HFunctor.Chain.Internal.DecAlt
instance Data.HFunctor.Final.FreeOf Data.Constraint.Trivial.Unconstrained Control.Monad.Trans.Identity.IdentityT
instance GHC.Base.Functor (Data.HFunctor.Final.Final GHC.Base.Functor f)
instance GHC.Base.Functor (Data.HFunctor.Final.Final Data.Functor.Bind.Class.Apply f)
instance Data.Functor.Bind.Class.Apply (Data.HFunctor.Final.Final Data.Functor.Bind.Class.Apply f)
instance GHC.Base.Functor (Data.HFunctor.Final.Final Data.Functor.Bind.Class.Bind f)
instance Data.Functor.Bind.Class.Apply (Data.HFunctor.Final.Final Data.Functor.Bind.Class.Bind f)
instance Data.Functor.Bind.Class.Bind (Data.HFunctor.Final.Final Data.Functor.Bind.Class.Bind f)
instance GHC.Base.Functor (Data.HFunctor.Final.Final GHC.Base.Applicative f)
instance Data.Functor.Bind.Class.Apply (Data.HFunctor.Final.Final GHC.Base.Applicative f)
instance GHC.Base.Applicative (Data.HFunctor.Final.Final GHC.Base.Applicative f)
instance GHC.Base.Functor (Data.HFunctor.Final.Final GHC.Base.Alternative f)
instance Data.Functor.Bind.Class.Apply (Data.HFunctor.Final.Final GHC.Base.Alternative f)
instance GHC.Base.Applicative (Data.HFunctor.Final.Final GHC.Base.Alternative f)
instance Data.Functor.Alt.Alt (Data.HFunctor.Final.Final GHC.Base.Alternative f)
instance Data.Functor.Plus.Plus (Data.HFunctor.Final.Final GHC.Base.Alternative f)
instance GHC.Base.Alternative (Data.HFunctor.Final.Final GHC.Base.Alternative f)
instance GHC.Base.Functor (Data.HFunctor.Final.Final GHC.Base.Monad f)
instance Data.Functor.Bind.Class.Apply (Data.HFunctor.Final.Final GHC.Base.Monad f)
instance GHC.Base.Applicative (Data.HFunctor.Final.Final GHC.Base.Monad f)
instance GHC.Base.Monad (Data.HFunctor.Final.Final GHC.Base.Monad f)
instance GHC.Base.Functor (Data.HFunctor.Final.Final GHC.Base.MonadPlus f)
instance GHC.Base.Applicative (Data.HFunctor.Final.Final GHC.Base.MonadPlus f)
instance GHC.Base.Monad (Data.HFunctor.Final.Final GHC.Base.MonadPlus f)
instance Data.Functor.Alt.Alt (Data.HFunctor.Final.Final GHC.Base.MonadPlus f)
instance Data.Functor.Plus.Plus (Data.HFunctor.Final.Final GHC.Base.MonadPlus f)
instance GHC.Base.Alternative (Data.HFunctor.Final.Final GHC.Base.MonadPlus f)
instance GHC.Base.MonadPlus (Data.HFunctor.Final.Final GHC.Base.MonadPlus f)
instance Data.Pointed.Pointed (Data.HFunctor.Final.Final Data.Pointed.Pointed f)
instance GHC.Base.Functor (Data.HFunctor.Final.Final (Control.Monad.Reader.Class.MonadReader r) f)
instance GHC.Base.Applicative (Data.HFunctor.Final.Final (Control.Monad.Reader.Class.MonadReader r) f)
instance Data.Functor.Bind.Class.Apply (Data.HFunctor.Final.Final (Control.Monad.Reader.Class.MonadReader r) f)
instance GHC.Base.Monad (Data.HFunctor.Final.Final (Control.Monad.Reader.Class.MonadReader r) f)
instance Control.Monad.Reader.Class.MonadReader r (Data.HFunctor.Final.Final (Control.Monad.Reader.Class.MonadReader r) f)
instance GHC.Base.Functor (Data.HFunctor.Final.Final Data.Functor.Alt.Alt f)
instance Data.Functor.Alt.Alt (Data.HFunctor.Final.Final Data.Functor.Alt.Alt f)
instance GHC.Base.Functor (Data.HFunctor.Final.Final Data.Functor.Plus.Plus f)
instance Data.Functor.Alt.Alt (Data.HFunctor.Final.Final Data.Functor.Plus.Plus f)
instance Data.Functor.Plus.Plus (Data.HFunctor.Final.Final Data.Functor.Plus.Plus f)
instance Data.Functor.Contravariant.Contravariant (Data.HFunctor.Final.Final Data.Functor.Contravariant.Contravariant f)
instance Data.Functor.Contravariant.Contravariant (Data.HFunctor.Final.Final Data.Functor.Contravariant.Divise.Divise f)
instance Data.Functor.Contravariant.Divise.Divise (Data.HFunctor.Final.Final Data.Functor.Contravariant.Divise.Divise f)
instance Data.Functor.Contravariant.Contravariant (Data.HFunctor.Final.Final Data.Functor.Contravariant.Divisible.Divisible f)
instance Data.Functor.Contravariant.Divise.Divise (Data.HFunctor.Final.Final Data.Functor.Contravariant.Divisible.Divisible f)
instance Data.Functor.Contravariant.Divisible.Divisible (Data.HFunctor.Final.Final Data.Functor.Contravariant.Divisible.Divisible f)
instance Data.Functor.Contravariant.Contravariant (Data.HFunctor.Final.Final Data.Functor.Contravariant.Decide.Decide f)
instance Data.Functor.Contravariant.Decide.Decide (Data.HFunctor.Final.Final Data.Functor.Contravariant.Decide.Decide f)
instance Data.Functor.Contravariant.Contravariant (Data.HFunctor.Final.Final Data.Functor.Contravariant.Conclude.Conclude f)
instance Data.Functor.Contravariant.Decide.Decide (Data.HFunctor.Final.Final Data.Functor.Contravariant.Conclude.Conclude f)
instance Data.Functor.Contravariant.Conclude.Conclude (Data.HFunctor.Final.Final Data.Functor.Contravariant.Conclude.Conclude f)
instance Data.Functor.Contravariant.Contravariant (Data.HFunctor.Final.Final Data.Functor.Contravariant.Divisible.Decidable f)
instance Data.Functor.Contravariant.Divisible.Divisible (Data.HFunctor.Final.Final Data.Functor.Contravariant.Divisible.Decidable f)
instance Data.Functor.Contravariant.Decide.Decide (Data.HFunctor.Final.Final Data.Functor.Contravariant.Divisible.Decidable f)
instance Data.Functor.Contravariant.Conclude.Conclude (Data.HFunctor.Final.Final Data.Functor.Contravariant.Divisible.Decidable f)
instance Data.Functor.Contravariant.Divisible.Decidable (Data.HFunctor.Final.Final Data.Functor.Contravariant.Divisible.Decidable f)
instance Data.Functor.Invariant.Invariant (Data.HFunctor.Final.Final Data.Functor.Invariant.Invariant f)
instance Data.Functor.Invariant.Invariant (Data.HFunctor.Final.Final Data.Functor.Invariant.Inplicative.Inply f)
instance Data.Functor.Invariant.Inplicative.Inply (Data.HFunctor.Final.Final Data.Functor.Invariant.Inplicative.Inply f)
instance Data.Functor.Invariant.Invariant (Data.HFunctor.Final.Final Data.Functor.Invariant.Inplicative.Inplicative f)
instance Data.Functor.Invariant.Inplicative.Inply (Data.HFunctor.Final.Final Data.Functor.Invariant.Inplicative.Inplicative f)
instance Data.Functor.Invariant.Inplicative.Inplicative (Data.HFunctor.Final.Final Data.Functor.Invariant.Inplicative.Inplicative f)
instance Data.Functor.Invariant.Invariant (Data.HFunctor.Final.Final Data.Functor.Invariant.Internative.Inalt f)
instance Data.Functor.Invariant.Internative.Inalt (Data.HFunctor.Final.Final Data.Functor.Invariant.Internative.Inalt f)
instance Data.Functor.Invariant.Invariant (Data.HFunctor.Final.Final Data.Functor.Invariant.Internative.Inplus f)
instance Data.Functor.Invariant.Internative.Inalt (Data.HFunctor.Final.Final Data.Functor.Invariant.Internative.Inplus f)
instance Data.Functor.Invariant.Internative.Inplus (Data.HFunctor.Final.Final Data.Functor.Invariant.Internative.Inplus f)
instance Data.Functor.Invariant.Invariant (Data.HFunctor.Final.Final Data.Functor.Invariant.Internative.Internative f)
instance Data.Functor.Invariant.Inplicative.Inply (Data.HFunctor.Final.Final Data.Functor.Invariant.Internative.Internative f)
instance Data.Functor.Invariant.Inplicative.Inplicative (Data.HFunctor.Final.Final Data.Functor.Invariant.Internative.Internative f)
instance Data.Functor.Invariant.Internative.Inalt (Data.HFunctor.Final.Final Data.Functor.Invariant.Internative.Internative f)
instance Data.Functor.Invariant.Internative.Inplus (Data.HFunctor.Final.Final Data.Functor.Invariant.Internative.Internative f)
instance forall k (c :: (k -> *) -> GHC.Types.Constraint). Data.HFunctor.Internal.HFunctor (Data.HFunctor.Final.Final c)
instance forall k (c :: (k -> *) -> GHC.Types.Constraint). Data.HFunctor.Inject (Data.HFunctor.Final.Final c)
instance forall k (c :: (k -> *) -> GHC.Types.Constraint) (f :: k -> *). c f => Data.HFunctor.Interpret.Interpret (Data.HFunctor.Final.Final c) f


-- | Functor combinators and tools (typeclasses and utiility functions) to
--   manipulate them. This is the main "entrypoint" of the library.
--   
--   Classes include:
--   
--   <ul>
--   <li><a>HFunctor</a> and <a>HBifunctor</a>, used to swap out the
--   functors that the combinators modify</li>
--   <li><a>Interpret</a>, <a>Associative</a>, <a>Tensor</a>, used to
--   inject and interpret functor values with respect to their
--   combinators.</li>
--   </ul>
--   
--   We have some helpful utility functions, as well, built on top of these
--   typeclasses.
--   
--   The second half of this module exports the various useful functor
--   combinators that can modify functors to add extra functionality, or
--   join two functors together and mix them in different ways. Use them to
--   build your final structure by combining simpler ones in composable
--   ways!
--   
--   See <a>https://blog.jle.im/entry/functor-combinatorpedia.html</a> and
--   the README for a tutorial and a rundown on each different functor
--   combinator.
module Data.Functor.Combinator
type (f :: k -> Type) ~> (g :: k -> Type) = forall (x :: k). () => f x -> g x

-- | The type of an isomorphism between two functors. <tt>f
--   <a>&lt;~&gt;</a> g</tt> means that <tt>f</tt> and <tt>g</tt> are
--   isomorphic to each other.
--   
--   We can effectively <i>use</i> an <tt>f &lt;~&gt; g</tt> with:
--   
--   <pre>
--   <a>viewF</a>   :: (f &lt;~&gt; g) -&gt; f a -&gt; g a
--   <a>reviewF</a> :: (f &lt;~&gt; g) -&gt; g a -&gt; a a
--   </pre>
--   
--   Use <a>viewF</a> to extract the "<tt>f</tt> to <tt>g</tt>" function,
--   and <a>reviewF</a> to extract the "<tt>g</tt> to <tt>f</tt>" function.
--   Reviewing and viewing the same value (or vice versa) leaves the value
--   unchanged.
--   
--   One nice thing is that we can compose isomorphisms using <a>.</a> from
--   <a>Prelude</a>:
--   
--   <pre>
--   (<a>.</a>) :: f &lt;~&gt; g
--       -&gt; g &lt;~&gt; h
--       -&gt; f &lt;~&gt; h
--   </pre>
--   
--   Another nice thing about this representation is that we have the
--   "identity" isomorphism by using <a>id</a> from <a>Prelude</a>.
--   
--   <pre>
--   <a>id</a> :: f <a>&lt;~&gt;</a> g
--   </pre>
--   
--   As a convention, most isomorphisms have form "X-ing", where the
--   forwards function is "ing". For example, we have:
--   
--   <pre>
--   <a>splittingSF</a> :: <a>Monoidal</a> t =&gt; <a>SF</a> t a <a>&lt;~&gt;</a> t f (<a>MF</a> t f)
--   <a>splitSF</a>     :: Monoidal t =&gt; SF t a  <a>~&gt;</a> t f (MF t f)
--   </pre>
type f <~> g = forall p a. Profunctor p => p (g a) (g a) -> p (f a) (f a)
infixr 0 <~>

-- | An <a>HFunctor</a> can be thought of a unary "functor transformer" ---
--   a basic functor combinator. It takes a functor as input and returns a
--   functor as output.
--   
--   It "enhances" a functor with extra structure (sort of like how a monad
--   transformer enhances a <a>Monad</a> with extra structure).
--   
--   As a uniform inteface, we can "swap the underlying functor" (also
--   sometimes called "hoisting"). This is what <a>hmap</a> does: it lets
--   us swap out the <tt>f</tt> in a <tt>t f</tt> for a <tt>t g</tt>.
--   
--   For example, the free monad <a>Free</a> takes a <a>Functor</a> and
--   returns a new <a>Functor</a>. In the process, it provides a monadic
--   structure over <tt>f</tt>. <a>hmap</a> lets us turn a <tt><a>Free</a>
--   f</tt> into a <tt><a>Free</a> g</tt>: a monad built over <tt>f</tt>
--   can be turned into a monad built over <tt>g</tt>.
--   
--   For the ability to move in and out of the enhanced functor, see
--   <a>Inject</a> and <a>Interpret</a>.
--   
--   This class is similar to <a>MFunctor</a> from
--   <a>Control.Monad.Morph</a>, but instances must work without a
--   <a>Monad</a> constraint.
--   
--   This class is also found in the <i>hschema</i> library with the same
--   name.
class HFunctor t

-- | If we can turn an <tt>f</tt> into a <tt>g</tt>, then we can turn a
--   <tt>t f</tt> into a <tt>t g</tt>.
--   
--   It must be the case that
--   
--   <pre>
--   <a>hmap</a> <a>id</a> == id
--   </pre>
--   
--   Essentially, <tt>t f</tt> adds some "extra structure" to <tt>f</tt>.
--   <a>hmap</a> must swap out the functor, <i>without affecting the added
--   structure</i>.
--   
--   For example, <tt><a>ListF</a> f a</tt> is essentially a list of <tt>f
--   a</tt>s. If we <a>hmap</a> to swap out the <tt>f a</tt>s for <tt>g
--   a</tt>s, then we must ensure that the "added structure" (here, the
--   number of items in the list, and the ordering of those items) remains
--   the same. So, <a>hmap</a> must preserve the number of items in the
--   list, and must maintain the ordering.
--   
--   The law <tt><a>hmap</a> <a>id</a> == id</tt> is a way of formalizing
--   this property.
hmap :: HFunctor t => (f ~> g) -> t f ~> t g

-- | A typeclass for <a>HFunctor</a>s where you can "inject" an <tt>f
--   a</tt> into a <tt>t f a</tt>:
--   
--   <pre>
--   <a>inject</a> :: f a -&gt; t f a
--   </pre>
--   
--   If you think of <tt>t f a</tt> as an "enhanced <tt>f</tt>", then
--   <a>inject</a> allows you to use an <tt>f</tt> as its enhanced form.
--   
--   With the exception of directly pattern matching on the result,
--   <a>inject</a> itself is not too useful in the general case without
--   <a>Interpret</a> to allow us to interpret or retrieve back the
--   <tt>f</tt>.
class HFunctor t => Inject t

-- | Lift from <tt>f</tt> into the enhanced <tt>t f</tt> structure.
--   Analogous to <a>lift</a> from <a>MonadTrans</a>.
--   
--   Note that this lets us "lift" a <tt>f a</tt>; if you want to lift an
--   <tt>a</tt> with <tt>a -&gt; t f a</tt>, check if <tt>t f</tt> is an
--   instance of <a>Applicative</a> or <a>Pointed</a>.
inject :: Inject t => f ~> t f

-- | An <a>Interpret</a> lets us move in and out of the "enhanced"
--   <a>Functor</a> (<tt>t f</tt>) and the functor it enhances
--   (<tt>f</tt>). An instance <tt><a>Interpret</a> t f</tt> means we have
--   <tt>t f a -&gt; f a</tt>.
--   
--   For example, <tt><a>Free</a> f</tt> is <tt>f</tt> enhanced with
--   monadic structure. We get:
--   
--   <pre>
--   <a>inject</a>    :: f a -&gt; <a>Free</a> f a
--   <a>interpret</a> :: <a>Monad</a> m =&gt; (forall x. f x -&gt; m x) -&gt; <a>Free</a> f a -&gt; m a
--   </pre>
--   
--   <a>inject</a> will let us use our <tt>f</tt> inside the enhanced
--   <tt><a>Free</a> f</tt>. <a>interpret</a> will let us "extract" the
--   <tt>f</tt> from a <tt><a>Free</a> f</tt> if we can give an
--   <i>interpreting function</i> that interprets <tt>f</tt> into some
--   target <a>Monad</a>.
--   
--   We enforce that:
--   
--   <pre>
--   <a>interpret</a> id . <a>inject</a> == id
--   -- or
--   <a>retract</a> . <a>inject</a> == id
--   </pre>
--   
--   That is, if we lift a value into our structure, then immediately
--   interpret it out as itself, it should lave the value unchanged.
--   
--   Note that instances of this class are <i>intended</i> to be written
--   with <tt>t</tt> as a fixed type constructor, and <tt>f</tt> to be
--   allowed to vary freely:
--   
--   <pre>
--   instance Monad f =&gt; Interpret Free f
--   </pre>
--   
--   Any other sort of instance and it's easy to run into problems with
--   type inference. If you want to write an instance that's "polymorphic"
--   on tensor choice, use the <a>WrapHF</a> newtype wrapper over a type
--   variable, where the second argument also uses a type constructor:
--   
--   <pre>
--   instance Interpret (WrapHF t) (MyFunctor t)
--   </pre>
--   
--   This will prevent problems with overloaded instances.
class Inject t => Interpret t f

-- | Remove the <tt>f</tt> out of the enhanced <tt>t f</tt> structure,
--   provided that <tt>f</tt> satisfies the necessary constraints. If it
--   doesn't, it needs to be properly <a>interpret</a>ed out.
retract :: Interpret t f => t f ~> f

-- | Given an "interpeting function" from <tt>f</tt> to <tt>g</tt>,
--   interpret the <tt>f</tt> out of the <tt>t f</tt> into a final context
--   <tt>g</tt>.
interpret :: Interpret t f => (g ~> f) -> t g ~> f

-- | A convenient flipped version of <a>interpret</a>.
forI :: Interpret t f => t g a -> (g ~> f) -> f a

-- | Useful wrapper over <a>interpret</a> to allow you to directly extract
--   a value <tt>b</tt> out of the <tt>t f a</tt>, if you can convert <tt>f
--   x</tt> into <tt>b</tt>.
--   
--   Note that depending on the constraints on <tt>f</tt> in
--   <tt><a>Interpret</a> t f</tt>, you may have extra constraints on
--   <tt>b</tt>.
--   
--   <ul>
--   <li>If <tt>f</tt> is unconstrained, there are no constraints on
--   <tt>b</tt></li>
--   <li>If <tt>f</tt> must be <a>Apply</a>, <a>Alt</a>, <a>Divise</a>, or
--   <a>Decide</a>, <tt>b</tt> needs to be an instance of
--   <a>Semigroup</a>.</li>
--   <li>If <tt>f</tt> is <a>Applicative</a>, <a>Plus</a>,
--   <a>Divisible</a>, or <a>Conclude</a>, <tt>b</tt> needs to be an
--   instance of <a>Monoid</a></li>
--   </ul>
--   
--   For some constraints (like <a>Monad</a>), this will not be usable.
--   
--   <pre>
--   -- get the length of the <tt>Map String</tt> in the <a>Step</a>.
--   <a>icollect</a> length
--        :: Step (Map String) Bool
--        -&gt; Int
--   </pre>
--   
--   Note that in many cases, you can also use <a>hfoldMap</a> and
--   <a>hfoldMap1</a>.
iget :: Interpret t (AltConst b) => (forall x. f x -> b) -> t f a -> b

-- | Useful wrapper over <a>iget</a> to allow you to collect a <tt>b</tt>
--   from all instances of <tt>f</tt> inside a <tt>t f a</tt>.
--   
--   Will work if there is an instance of <tt><a>Interpret</a> t
--   (<a>AltConst</a> m)</tt> if <tt><a>Monoid</a> m</tt>, which will be
--   the case if the constraint on the target functor is <a>Functor</a>,
--   <a>Apply</a>, <a>Applicative</a>, <a>Alt</a>, <a>Plus</a>,
--   <a>Decide</a>, <a>Divisible</a>, <a>Decide</a>, <a>Conclude</a>, or
--   unconstrained.
--   
--   <pre>
--   -- get the lengths of all <tt>Map String</tt>s in the <a>Ap</a>.
--   <a>icollect</a> length
--        :: Ap (Map String) Bool
--        -&gt; [Int]
--   </pre>
--   
--   Note that in many cases, you can also use <a>htoList</a>.
icollect :: (forall m. Monoid m => Interpret t (AltConst m)) => (forall x. f x -> b) -> t f a -> [b]

-- | Useful wrapper over <a>iget</a> to allow you to collect a <tt>b</tt>
--   from all instances of <tt>f</tt> inside a <tt>t f a</tt>, into a
--   non-empty collection of <tt>b</tt>s.
--   
--   Will work if there is an instance of <tt><a>Interpret</a> t
--   (<a>AltConst</a> m)</tt> if <tt><a>Semigroup</a> m</tt>, which will be
--   the case if the constraint on the target functor is <a>Functor</a>,
--   <a>Apply</a>, <a>Alt</a>, <a>Divise</a>, <a>Decide</a>, or
--   unconstrained.
--   
--   <pre>
--   -- get the lengths of all <tt>Map String</tt>s in the <a>Ap</a>.
--   <a>icollect1</a> length
--        :: Ap1 (Map String) Bool
--        -&gt; <a>NonEmpty</a> Int
--   </pre>
--   
--   Note that in many cases, you can also use <a>htoNonEmpty</a>.
icollect1 :: (forall m. Semigroup m => Interpret t (AltConst m)) => (forall x. f x -> b) -> t f a -> NonEmpty b

-- | Useful wrapper over <a>interpret</a> to allow you to directly consume
--   a value of type <tt>a</tt> with a <tt>t f a</tt> to create a
--   <tt>b</tt>. Do this by supplying the method by which each component
--   <tt>f x</tt> can consume an <tt>x</tt>. This works for contravariant
--   functor combinators, where <tt>t f a</tt> can be interpreted as a
--   consumer of <tt>a</tt>s.
--   
--   Note that depending on the constraints on <tt>f</tt> in
--   <tt><a>Interpret</a> t f</tt>, you may have extra constraints on
--   <tt>b</tt>.
--   
--   <ul>
--   <li>If <tt>f</tt> is unconstrained, <a>Decide</a>, or <a>Conclude</a>,
--   there are no constraints on <tt>b</tt>. This will be the case for
--   combinators like contravariant <a>Coyoneda</a>, <tt>Dec</tt>,
--   <tt>Dec1</tt>.</li>
--   <li>If <tt>f</tt> must be <a>Divise</a>, <tt>b</tt> needs to be an
--   instance of <a>Semigroup</a>. This will be the case for combinators
--   like <tt>Div1</tt>.</li>
--   <li>If <tt>f</tt> is <a>Divisible</a>, <tt>b</tt> needs to be an
--   instance of <a>Monoid</a>. This will be the case for combinators like
--   <tt>Div</tt>.</li>
--   </ul>
--   
--   For any <a>Functor</a> or <a>Invariant</a> constraint, this is not
--   usable.
iapply :: Interpret t (Op b) => (forall x. f x -> x -> b) -> t f a -> a -> b

-- | Useful wrapper over <a>interpret</a> to allow you to directly consume
--   a value of type <tt>a</tt> with a <tt>t f a</tt> to create a
--   <tt>b</tt>, and create a list of all the <tt>b</tt>s created by all
--   the <tt>f</tt>s. Do this by supplying the method by which each
--   component <tt>f x</tt> can consume an <tt>x</tt>. This works for
--   contravariant functor combinators, where <tt>t f a</tt> can be
--   interpreted as a consumer of <tt>a</tt>s.
--   
--   Will work if there is an instance of <tt><a>Interpret</a> t (<a>Op</a>
--   m)</tt> if <tt><a>Monoid</a> m</tt>, which will be the case if the
--   constraint on the target functor is <a>Contravariant</a>,
--   <a>Decide</a>, <a>Conclude</a>, <a>Divise</a>, <a>Divisible</a>, or
--   unconstrained.
--   
--   Note that this is really only useful outside of <a>iapply</a> for
--   <tt>Div</tt> and <tt>Div1</tt>, where a <tt><tt>Div</tt> f</tt> which
--   is a collection of many different <tt>f</tt>s consuming types of
--   different values. You can use this with <tt>Dec</tt> and <tt>Dec1</tt>
--   and the contravarient <a>Coyoneda</a> as well, but those would always
--   just give you a singleton list, so you might as well use
--   <a>iapply</a>. This is really only here for completion alongside
--   <a>icollect</a>, or if you define your own custom functor combinators.
ifanout :: (forall m. Monoid m => Interpret t (Op m)) => (forall x. f x -> x -> b) -> t f a -> a -> [b]

-- | Useful wrapper over <a>interpret</a> to allow you to directly consume
--   a value of type <tt>a</tt> with a <tt>t f a</tt> to create a
--   <tt>b</tt>, and create a list of all the <tt>b</tt>s created by all
--   the <tt>f</tt>s. Do this by supplying the method by which each
--   component <tt>f x</tt> can consume an <tt>x</tt>. This works for
--   contravariant functor combinators, where <tt>t f a</tt> can be
--   interpreted as a consumer of <tt>a</tt>s.
--   
--   Will work if there is an instance of <tt><a>Interpret</a> t (<a>Op</a>
--   m)</tt> if <tt><a>Monoid</a> m</tt>, which will be the case if the
--   constraint on the target functor is <a>Contravariant</a>,
--   <a>Decide</a>, <a>Divise</a>, or unconstrained.
--   
--   Note that this is really only useful outside of <a>iapply</a> and
--   <a>ifanout</a> for <tt>Div1</tt>, where a <tt><tt>Div1</tt> f</tt>
--   which is a collection of many different <tt>f</tt>s consuming types of
--   different values. You can use this with <tt>Dec</tt> and <tt>Dec1</tt>
--   and the contravarient <a>Coyoneda</a> as well, but those would always
--   just give you a singleton list, so you might as well use
--   <a>iapply</a>. This is really only here for completion alongside
--   <a>icollect1</a>, or if you define your own custom functor
--   combinators.
ifanout1 :: (forall m. Semigroup m => Interpret t (Op m)) => (forall x. f x -> x -> b) -> t f a -> a -> NonEmpty b

-- | (Deprecated) Old name for <a>getI</a>; will be removed in a future
--   version.

-- | <i>Deprecated: Use iget instead</i>
getI :: Interpret t (AltConst b) => (forall x. f x -> b) -> t f a -> b

-- | (Deprecated) Old name for <a>icollect</a>; will be removed in a future
--   version.

-- | <i>Deprecated: Use icollect instead</i>
collectI :: (forall m. Monoid m => Interpret t (AltConst m)) => (forall x. f x -> b) -> t f a -> [b]

-- | A useful wrapper over the common pattern of
--   fmap-before-inject/inject-and-fmap.
injectMap :: (Inject t, Functor f) => (a -> b) -> f a -> t f b

-- | A useful wrapper over the common pattern of
--   contramap-before-inject/inject-and-contramap.
injectContramap :: (Inject t, Contravariant f) => (a -> b) -> f b -> t f a

-- | A version of <a>Const</a> that supports <a>Alt</a>, <a>Plus</a>,
--   <a>Decide</a>, and <a>Conclude</a> instances. It does this by avoiding
--   having an <a>Alternative</a> or <a>Decidable</a> instance, which
--   causes all sorts of problems with the interactions between
--   <a>Alternative</a>/<a>Applicative</a> and
--   <a>Decidable</a>/<a>Divisible</a>.
newtype AltConst w a
AltConst :: w -> AltConst w a
[getAltConst] :: AltConst w a -> w

-- | A higher-kinded version of <a>Traversable</a>, in the same way that
--   <a>HFunctor</a> is the higher-kinded version of <a>Functor</a>. Gives
--   you an "effectful" <a>hmap</a>, in the same way that <a>traverse</a>
--   gives you an effectful <a>fmap</a>.
--   
--   The typical analogues of <a>Traversable</a> laws apply.
class HFunctor t => HTraversable t

-- | An "effectful" <a>hmap</a>, in the same way that <a>traverse</a> is an
--   effectful <a>fmap</a>.
htraverse :: (HTraversable t, Applicative h) => (forall x. f x -> h (g x)) -> t f a -> h (t g a)

-- | A wrapper over a common pattern of "inverting" layers of a functor
--   combinator.
hsequence :: (HTraversable t, Applicative h) => t (h :.: f) a -> h (t f a)

-- | Collect all the <tt>f x</tt>s inside a <tt>t f a</tt> into a monoidal
--   result using a projecting function.
--   
--   See <a>iget</a>.
hfoldMap :: (HTraversable t, Monoid m) => (forall x. f x -> m) -> t f a -> m

-- | Collect all the <tt>f x</tt>s inside a <tt>t f a</tt> into a list,
--   using a projecting function.
--   
--   See <a>icollect</a>.
htoList :: HTraversable t => (forall x. f x -> b) -> t f a -> [b]

-- | A higher-kinded version of <a>Traversable1</a>, in the same way that
--   <a>HFunctor</a> is the higher-kinded version of <a>Functor</a>. Gives
--   you an "effectful" <a>hmap</a>, in the same way that <a>traverse1</a>
--   gives you an effectful <a>fmap</a>, guaranteeing at least one item.
--   
--   The typical analogues of <a>Traversable1</a> laws apply.
class HTraversable t => HTraversable1 t

-- | An "effectful" <a>hmap</a>, in the same way that <a>traverse1</a> is
--   an effectful <a>fmap</a>, guaranteeing at least one item.
htraverse1 :: (HTraversable1 t, Apply h) => (forall x. f x -> h (g x)) -> t f a -> h (t g a)

-- | A wrapper over a common pattern of "inverting" layers of a functor
--   combinator that always contains at least one <tt>f</tt> item.
hsequence1 :: (HTraversable1 t, Apply h) => t (h :.: f) a -> h (t f a)

-- | Collect all the <tt>f x</tt>s inside a <tt>t f a</tt> into a
--   semigroupoidal result using a projecting function.
--   
--   See <a>iget</a>.
hfoldMap1 :: (HTraversable1 t, Semigroup m) => (forall x. f x -> m) -> t f a -> m

-- | Collect all the <tt>f x</tt>s inside a <tt>t f a</tt> into a non-empty
--   list, using a projecting function.
--   
--   See <a>icollect1</a>.
htoNonEmpty :: HTraversable1 t => (forall x. f x -> b) -> t f a -> NonEmpty b

-- | A <a>HBifunctor</a> is like an <a>HFunctor</a>, but it enhances
--   <i>two</i> different functors instead of just one.
--   
--   Usually, it enhaces them "together" in some sort of combining way.
--   
--   This typeclass provides a uniform instance for "swapping out" or
--   "hoisting" the enhanced functors. We can hoist the first one with
--   <a>hleft</a>, the second one with <a>hright</a>, or both at the same
--   time with <a>hbimap</a>.
--   
--   For example, the <tt>f :*: g</tt> type gives us "both <tt>f</tt> and
--   <tt>g</tt>":
--   
--   <pre>
--   data (f <a>:*:</a> g) a = f a :*: g a
--   </pre>
--   
--   It combines both <tt>f</tt> and <tt>g</tt> into a unified structure
--   --- here, it does it by providing both <tt>f</tt> and <tt>g</tt>.
--   
--   The single law is:
--   
--   <pre>
--   <a>hbimap</a> <a>id</a> id == id
--   </pre>
--   
--   This ensures that <a>hleft</a>, <a>hright</a>, and <a>hbimap</a> do
--   not affect the structure that <tt>t</tt> adds on top of the underlying
--   functors.
class HBifunctor (t :: (k -> Type) -> (k -> Type) -> k -> Type)

-- | Swap out the first transformed functor.
hleft :: HBifunctor t => (f ~> j) -> t f g ~> t j g

-- | Swap out the second transformed functor.
hright :: HBifunctor t => (g ~> l) -> t f g ~> t f l

-- | Swap out both transformed functors at the same time.
hbimap :: HBifunctor t => (f ~> j) -> (g ~> l) -> t f g ~> t j l

-- | An <a>HBifunctor</a> where it doesn't matter which binds first is
--   <a>Associative</a>. Knowing this gives us a lot of power to rearrange
--   the internals of our <a>HFunctor</a> at will.
--   
--   For example, for the functor product:
--   
--   <pre>
--   data (f <a>:*:</a> g) a = f a :*: g a
--   </pre>
--   
--   We know that <tt>f :*: (g :*: h)</tt> is the same as <tt>(f :*: g) :*:
--   h</tt>.
--   
--   Formally, we can say that <tt>t</tt> enriches a the category of
--   endofunctors with semigroup strcture: it turns our endofunctor
--   category into a "semigroupoidal category".
--   
--   Different instances of <tt>t</tt> each enrich the endofunctor category
--   in different ways, giving a different semigroupoidal category.
class (HBifunctor t, Inject (NonEmptyBy t)) => Associative t where {
    
    -- | The "semigroup functor combinator" generated by <tt>t</tt>.
    --   
    --   A value of type <tt>NonEmptyBy t f a</tt> is <i>equivalent</i> to one
    --   of:
    --   
    --   <ul>
    --   <li><pre>f a</pre></li>
    --   <li><pre>t f f a</pre></li>
    --   <li><pre>t f (t f f) a</pre></li>
    --   <li><pre>t f (t f (t f f)) a</pre></li>
    --   <li><pre>t f (t f (t f (t f f))) a</pre></li>
    --   <li>.. etc</li>
    --   </ul>
    --   
    --   For example, for <a>:*:</a>, we have <a>NonEmptyF</a>. This is
    --   because:
    --   
    --   <pre>
    --   x             ~ <a>NonEmptyF</a> (x <a>:|</a> [])      ~ <a>inject</a> x
    --   x <a>:*:</a> y       ~ NonEmptyF (x :| [y])     ~ <a>toNonEmptyBy</a> (x :*: y)
    --   x :*: y :*: z ~ NonEmptyF (x :| [y,z])
    --   -- etc.
    --   </pre>
    --   
    --   You can create an "singleton" one with <a>inject</a>, or else one from
    --   a single <tt>t f f</tt> with <a>toNonEmptyBy</a>.
    --   
    --   See <a>ListBy</a> for a "possibly empty" version of this type.
    type family NonEmptyBy t :: (Type -> Type) -> Type -> Type;
    
    -- | A description of "what type of Functor" this tensor is expected to be
    --   applied to. This should typically always be either <a>Functor</a>,
    --   <a>Contravariant</a>, or <a>Invariant</a>.
    type family FunctorBy t :: (Type -> Type) -> Constraint;
    type FunctorBy t = Unconstrained;
}

-- | The isomorphism between <tt>t f (t g h) a</tt> and <tt>t (t f g) h
--   a</tt>. To use this isomorphism, see <a>assoc</a> and <a>disassoc</a>.
associating :: (Associative t, FunctorBy t f, FunctorBy t g, FunctorBy t h) => t f (t g h) <~> t (t f g) h

-- | If a <tt><a>NonEmptyBy</a> t f</tt> represents multiple applications
--   of <tt>t f</tt> to itself, then we can also "append" two
--   <tt><a>NonEmptyBy</a> t f</tt>s applied to themselves into one giant
--   <tt><a>NonEmptyBy</a> t f</tt> containing all of the <tt>t f</tt>s.
--   
--   Note that this essentially gives an instance for
--   <tt><a>SemigroupIn</a> t (NonEmptyBy t f)</tt>, for any functor
--   <tt>f</tt>.
appendNE :: Associative t => t (NonEmptyBy t f) (NonEmptyBy t f) ~> NonEmptyBy t f

-- | If a <tt><a>NonEmptyBy</a> t f</tt> represents multiple applications
--   of <tt>t f</tt> to itself, then we can split it based on whether or
--   not it is just a single <tt>f</tt> or at least one top-level
--   application of <tt>t f</tt>.
--   
--   Note that you can recursively "unroll" a <a>NonEmptyBy</a> completely
--   into a <a>Chain1</a> by using <a>unrollNE</a>.
matchNE :: (Associative t, FunctorBy t f) => NonEmptyBy t f ~> (f :+: t f (NonEmptyBy t f))

-- | Prepend an application of <tt>t f</tt> to the front of a
--   <tt><a>NonEmptyBy</a> t f</tt>.
consNE :: Associative t => t f (NonEmptyBy t f) ~> NonEmptyBy t f

-- | Embed a direct application of <tt>f</tt> to itself into a
--   <tt><a>NonEmptyBy</a> t f</tt>.
toNonEmptyBy :: Associative t => t f f ~> NonEmptyBy t f

-- | For different <tt><a>Associative</a> t</tt>, we have functors
--   <tt>f</tt> that we can "squash", using <a>biretract</a>:
--   
--   <pre>
--   t f f ~&gt; f
--   </pre>
--   
--   This gives us the ability to squash applications of <tt>t</tt>.
--   
--   Formally, if we have <tt><a>Associative</a> t</tt>, we are enriching
--   the category of endofunctors with semigroup structure, turning it into
--   a semigroupoidal category. Different choices of <tt>t</tt> give
--   different semigroupoidal categories.
--   
--   A functor <tt>f</tt> is known as a "semigroup in the (semigroupoidal)
--   category of endofunctors on <tt>t</tt>" if we can <a>biretract</a>:
--   
--   <pre>
--   t f f ~&gt; f
--   </pre>
--   
--   This gives us a few interesting results in category theory, which you
--   can stil reading about if you don't care:
--   
--   <ul>
--   <li><i>All</i> functors are semigroups in the semigroupoidal category
--   on <a>:+:</a></li>
--   <li>The class of functors that are semigroups in the semigroupoidal
--   category on <a>:*:</a> is exactly the functors that are instances of
--   <a>Alt</a>.</li>
--   <li>The class of functors that are semigroups in the semigroupoidal
--   category on <a>Day</a> is exactly the functors that are instances of
--   <a>Apply</a>.</li>
--   <li>The class of functors that are semigroups in the semigroupoidal
--   category on <a>Comp</a> is exactly the functors that are instances of
--   <a>Bind</a>.</li>
--   </ul>
--   
--   Note that instances of this class are <i>intended</i> to be written
--   with <tt>t</tt> as a fixed type constructor, and <tt>f</tt> to be
--   allowed to vary freely:
--   
--   <pre>
--   instance Bind f =&gt; SemigroupIn Comp f
--   </pre>
--   
--   Any other sort of instance and it's easy to run into problems with
--   type inference. If you want to write an instance that's "polymorphic"
--   on tensor choice, use the <a>WrapHBF</a> newtype wrapper over a type
--   variable, where the second argument also uses a type constructor:
--   
--   <pre>
--   instance SemigroupIn (WrapHBF t) (MyFunctor t i)
--   </pre>
--   
--   This will prevent problems with overloaded instances.
class (Associative t, FunctorBy t f) => SemigroupIn t f

-- | The <a>HBifunctor</a> analogy of <a>retract</a>. It retracts
--   <i>both</i> <tt>f</tt>s into a single <tt>f</tt>, effectively fully
--   mixing them together.
--   
--   This function makes <tt>f</tt> a semigroup in the category of
--   endofunctors with respect to tensor <tt>t</tt>.
biretract :: SemigroupIn t f => t f f ~> f

-- | The <a>HBifunctor</a> analogy of <a>retract</a>. It retracts
--   <i>both</i> <tt>f</tt>s into a single <tt>f</tt>, effectively fully
--   mixing them together.
--   
--   This function makes <tt>f</tt> a semigroup in the category of
--   endofunctors with respect to tensor <tt>t</tt>.
biretract :: (SemigroupIn t f, Interpret (NonEmptyBy t) f) => t f f ~> f

-- | The <a>HBifunctor</a> analogy of <a>interpret</a>. It takes two
--   interpreting functions, and mixes them together into a target functor
--   <tt>h</tt>.
--   
--   Note that this is useful in the poly-kinded case, but it is not
--   possible to define generically for all <a>SemigroupIn</a> because it
--   only is defined for <tt>Type -&gt; Type</tt> inputes. See <a>!+!</a>
--   for a version that is poly-kinded for <a>:+:</a> in specific.
binterpret :: SemigroupIn t f => (g ~> f) -> (h ~> f) -> t g h ~> f

-- | The <a>HBifunctor</a> analogy of <a>interpret</a>. It takes two
--   interpreting functions, and mixes them together into a target functor
--   <tt>h</tt>.
--   
--   Note that this is useful in the poly-kinded case, but it is not
--   possible to define generically for all <a>SemigroupIn</a> because it
--   only is defined for <tt>Type -&gt; Type</tt> inputes. See <a>!+!</a>
--   for a version that is poly-kinded for <a>:+:</a> in specific.
binterpret :: (SemigroupIn t f, Interpret (NonEmptyBy t) f) => (g ~> f) -> (h ~> f) -> t g h ~> f

-- | Useful wrapper over <a>binterpret</a> to allow you to directly extract
--   a value <tt>b</tt> out of the <tt>t f g a</tt>, if you can convert an
--   <tt>f x</tt> and <tt>g x</tt> into <tt>b</tt>.
--   
--   Note that depending on the constraints on <tt>h</tt> in
--   <tt><a>SemigroupIn</a> t h</tt>, you may have extra constraints on
--   <tt>b</tt>.
--   
--   <ul>
--   <li>If <tt>h</tt> is unconstrained, there are no constraints on
--   <tt>b</tt></li>
--   <li>If <tt>h</tt> must be <a>Apply</a>, <a>Alt</a>, <a>Divise</a>, or
--   <a>Decide</a>, <tt>b</tt> needs to be an instance of
--   <a>Semigroup</a></li>
--   <li>If <tt>h</tt> is <a>Applicative</a>, <a>Plus</a>,
--   <a>Divisible</a>, or <a>Conclude</a>, <tt>b</tt> needs to be an
--   instance of <a>Monoid</a></li>
--   </ul>
--   
--   For some constraints (like <a>Monad</a>), this will not be usable.
--   
--   <pre>
--   -- Return the length of either the list, or the Map, depending on which
--   --   one s in the <a>+</a>
--   <a>biget</a> <a>length</a> length
--       :: ([] :+: <a>Map</a> <a>Int</a>) <a>Char</a>
--       -&gt; Int
--   
--   -- Return the length of both the list and the map, added together
--   <a>biget</a> (<a>Sum</a> . length) (Sum . length)
--       :: <a>Day</a> [] (Map Int) Char
--       -&gt; Sum Int
--   </pre>
biget :: SemigroupIn t (AltConst b) => (forall x. f x -> b) -> (forall x. g x -> b) -> t f g a -> b

-- | Useful wrapper over <a>binterpret</a> to allow you to directly extract
--   a value <tt>b</tt> out of the <tt>t f g a</tt>, if you can convert an
--   <tt>f x</tt> and <tt>g x</tt> into <tt>b</tt>, given an <tt>x</tt>
--   input.
--   
--   Note that depending on the constraints on <tt>h</tt> in
--   <tt><a>SemigroupIn</a> t h</tt>, you may have extra constraints on
--   <tt>b</tt>.
--   
--   <ul>
--   <li>If <tt>h</tt> is unconstrained, there are no constraints on
--   <tt>b</tt></li>
--   <li>If <tt>h</tt> must be <a>Divise</a>, or <tt>Divisible</tt>,
--   <tt>b</tt> needs to be an instance of <a>Semigroup</a></li>
--   <li>If <tt>h</tt> must be <tt>Divisible</tt>, then <tt>b</tt> needs to
--   be an instance of <a>Monoid</a>.</li>
--   </ul>
--   
--   For some constraints (like <a>Monad</a>), this will not be usable.
biapply :: SemigroupIn t (Op b) => (forall x. f x -> x -> b) -> (forall x. g x -> x -> b) -> t f g a -> a -> b

-- | Infix alias for <a>binterpret</a>
--   
--   Note that this is useful in the poly-kinded case, but it is not
--   possible to define generically for all <a>SemigroupIn</a> because it
--   only is defined for <tt>Type -&gt; Type</tt> inputes. See <a>!+!</a>
--   for a version that is poly-kinded for <a>:+:</a> in specific.
(!*!) :: SemigroupIn t h => (f ~> h) -> (g ~> h) -> t f g ~> h
infixr 5 !*!

-- | A version of <a>!*!</a> specifically for <a>:+:</a> that is
--   poly-kinded
(!+!) :: (f ~> h) -> (g ~> h) -> (f :+: g) ~> h
infixr 5 !+!

-- | Infix alias for <a>biget</a>
--   
--   <pre>
--   -- Return the length of either the list, or the Map, depending on which
--   --   one s in the <a>+</a>
--   <a>length</a> <a>!$!</a> length
--       :: ([] :+: <a>Map</a> <a>Int</a>) <a>Char</a>
--       -&gt; Int
--   
--   -- Return the length of both the list and the map, added together
--   <a>Sum</a> . length !$! Sum . length
--       :: <a>Day</a> [] (Map Int) Char
--       -&gt; Sum Int
--   </pre>
(!$!) :: SemigroupIn t (AltConst b) => (forall x. f x -> b) -> (forall x. g x -> b) -> t f g a -> b
infixr 5 !$!

-- | An <a>Associative</a> <a>HBifunctor</a> can be a <a>Tensor</a> if
--   there is some identity <tt>i</tt> where <tt>t i f</tt> and <tt>t f
--   i</tt> are equivalent to just <tt>f</tt>.
--   
--   That is, "enhancing" <tt>f</tt> with <tt>t i</tt> does nothing.
--   
--   The methods in this class provide us useful ways of navigating a
--   <tt><a>Tensor</a> t</tt> with respect to this property.
--   
--   The <a>Tensor</a> is essentially the <a>HBifunctor</a> equivalent of
--   <a>Inject</a>, with <a>intro1</a> and <a>intro2</a> taking the place
--   of <a>inject</a>.
--   
--   Formally, we can say that <tt>t</tt> enriches a the category of
--   endofunctors with monoid strcture: it turns our endofunctor category
--   into a "monoidal category".
--   
--   Different instances of <tt>t</tt> each enrich the endofunctor category
--   in different ways, giving a different monoidal category.
class (Associative t, Inject (ListBy t)) => Tensor t i | t -> i where {
    
    -- | The "monoidal functor combinator" induced by <tt>t</tt>.
    --   
    --   A value of type <tt>ListBy t f a</tt> is <i>equivalent</i> to one of:
    --   
    --   <ul>
    --   <li><tt>I a</tt> -- zero fs</li>
    --   <li><tt>f a</tt> -- one f</li>
    --   <li><tt>t f f a</tt> -- two fs</li>
    --   <li><tt>t f (t f f) a</tt> -- three fs</li>
    --   <li><pre>t f (t f (t f f)) a</pre></li>
    --   <li><pre>t f (t f (t f (t f f))) a</pre></li>
    --   <li>.. etc</li>
    --   </ul>
    --   
    --   For example, for <a>:*:</a>, we have <tt>ListF</tt>. This is because:
    --   
    --   <pre>
    --   <tt>Proxy</tt>         ~ <tt>ListF</tt> []         ~ <a>nilLB</a> @(<a>:*:</a>)
    --   x             ~ ListF [x]        ~ <a>inject</a> x
    --   x :*: y       ~ ListF [x,y]      ~ <a>toListBy</a> (x :*: y)
    --   x :*: y :*: z ~ ListF [x,y,z]
    --   -- etc.
    --   </pre>
    --   
    --   You can create an "empty" one with <a>nilLB</a>, a "singleton" one
    --   with <a>inject</a>, or else one from a single <tt>t f f</tt> with
    --   <a>toListBy</a>.
    --   
    --   See <a>NonEmptyBy</a> for a "non-empty" version of this type.
    type family ListBy t :: (Type -> Type) -> Type -> Type;
}

-- | Because <tt>t f (I t)</tt> is equivalent to <tt>f</tt>, we can always
--   "insert" <tt>f</tt> into <tt>t f (I t)</tt>.
--   
--   This is analogous to <a>inject</a> from <a>Inject</a>, but for
--   <a>HBifunctor</a>s.
intro1 :: Tensor t i => f ~> t f i

-- | Because <tt>t (I t) g</tt> is equivalent to <tt>f</tt>, we can always
--   "insert" <tt>g</tt> into <tt>t (I t) g</tt>.
--   
--   This is analogous to <a>inject</a> from <a>Inject</a>, but for
--   <a>HBifunctor</a>s.
intro2 :: Tensor t i => g ~> t i g

-- | Witnesses the property that <tt>i</tt> is the identity of <tt>t</tt>:
--   <tt>t f i</tt> always leaves <tt>f</tt> unchanged, so we can always
--   just drop the <tt>i</tt>.
elim1 :: (Tensor t i, FunctorBy t f) => t f i ~> f

-- | Witnesses the property that <tt>i</tt> is the identity of <tt>t</tt>:
--   <tt>t i g</tt> always leaves <tt>g</tt> unchanged, so we can always
--   just drop the <tt>i t</tt>.
elim2 :: (Tensor t i, FunctorBy t g) => t i g ~> g

-- | If a <tt><a>ListBy</a> t f</tt> represents multiple applications of
--   <tt>t f</tt> to itself, then we can also "append" two
--   <tt><a>ListBy</a> t f</tt>s applied to themselves into one giant
--   <tt><a>ListBy</a> t f</tt> containing all of the <tt>t f</tt>s.
--   
--   Note that this essentially gives an instance for
--   <tt><a>SemigroupIn</a> t (ListBy t f)</tt>, for any functor
--   <tt>f</tt>; this is witnessed by <tt>WrapLB</tt>.
appendLB :: Tensor t i => t (ListBy t f) (ListBy t f) ~> ListBy t f

-- | Lets you convert an <tt><a>NonEmptyBy</a> t f</tt> into a single
--   application of <tt>f</tt> to <tt><a>ListBy</a> t f</tt>.
--   
--   Analogous to a function <tt><a>NonEmpty</a> a -&gt; (a, [a])</tt>
--   
--   Note that this is not reversible in general unless we have
--   <tt><tt>Matchable</tt> t</tt>.
splitNE :: Tensor t i => NonEmptyBy t f ~> t f (ListBy t f)

-- | An <tt><a>ListBy</a> t f</tt> is either empty, or a single application
--   of <tt>t</tt> to <tt>f</tt> and <tt>ListBy t f</tt> (the "head" and
--   "tail"). This witnesses that isomorphism.
--   
--   To <i>use</i> this property, see <a>nilLB</a>, <a>consLB</a>, and
--   <a>unconsLB</a>.
splittingLB :: Tensor t i => ListBy t f <~> (i :+: t f (ListBy t f))

-- | Embed a direct application of <tt>f</tt> to itself into a
--   <tt><a>ListBy</a> t f</tt>.
toListBy :: Tensor t i => t f f ~> ListBy t f

-- | <tt><a>NonEmptyBy</a> t f</tt> is "one or more <tt>f</tt>s", and
--   <tt>'ListBy t f</tt> is "zero or more <tt>f</tt>s". This function lets
--   us convert from one to the other.
--   
--   This is analogous to a function <tt><a>NonEmpty</a> a -&gt; [a]</tt>.
--   
--   Note that because <tt>t</tt> is not inferrable from the input or
--   output type, you should call this using <i>-XTypeApplications</i>:
--   
--   <pre>
--   <a>fromNE</a> @(<a>:*:</a>) :: <tt>NonEmptyF</tt> f a -&gt; <tt>ListF</tt> f a
--   fromNE @<tt>Comp</tt>  :: <tt>Free1</tt> f a -&gt; <tt>Free</tt> f a
--   </pre>
fromNE :: Tensor t i => NonEmptyBy t f ~> ListBy t f

-- | This class effectively gives us a way to generate a value of <tt>f
--   a</tt> based on an <tt>i a</tt>, for <tt><a>Tensor</a> t i</tt>.
--   Having this ability makes a lot of interesting functions possible when
--   used with <a>biretract</a> from <a>SemigroupIn</a> that weren't
--   possible without it: it gives us a "base case" for recursion in a lot
--   of cases.
--   
--   Essentially, we get an <tt>i ~&gt; f</tt>, <a>pureT</a>, where we can
--   introduce an <tt>f a</tt> as long as we have an <tt>i a</tt>.
--   
--   Formally, if we have <tt><a>Tensor</a> t i</tt>, we are enriching the
--   category of endofunctors with monoid structure, turning it into a
--   monoidal category. Different choices of <tt>t</tt> give different
--   monoidal categories.
--   
--   A functor <tt>f</tt> is known as a "monoid in the (monoidal) category
--   of endofunctors on <tt>t</tt>" if we can <a>biretract</a>:
--   
--   <pre>
--   t f f ~&gt; f
--   </pre>
--   
--   and also <a>pureT</a>:
--   
--   <pre>
--   i ~&gt; f
--   </pre>
--   
--   This gives us a few interesting results in category theory, which you
--   can stil reading about if you don't care:
--   
--   <ul>
--   <li><i>All</i> functors are monoids in the monoidal category on
--   <a>:+:</a></li>
--   <li>The class of functors that are monoids in the monoidal category on
--   <a>:*:</a> is exactly the functors that are instances of
--   <a>Plus</a>.</li>
--   <li>The class of functors that are monoids in the monoidal category on
--   <a>Day</a> is exactly the functors that are instances of
--   <a>Applicative</a>.</li>
--   <li>The class of functors that are monoids in the monoidal category on
--   <a>Comp</a> is exactly the functors that are instances of
--   <a>Monad</a>.</li>
--   </ul>
--   
--   This is the meaning behind the common adage, "monads are just monoids
--   in the category of endofunctors". It means that if you enrich the
--   category of endofunctors to be monoidal with <a>Comp</a>, then the
--   class of functors that are monoids in that monoidal category are
--   exactly what monads are. However, the adage is a little misleading:
--   there are many other ways to enrich the category of endofunctors to be
--   monoidal, and <a>Comp</a> is just one of them. Similarly, the class of
--   functors that are monoids in the category of endofunctors enriched by
--   <a>Day</a> are <a>Applicative</a>.
--   
--   Note that instances of this class are <i>intended</i> to be written
--   with <tt>t</tt> and <tt>i</tt> to be fixed type constructors, and
--   <tt>f</tt> to be allowed to vary freely:
--   
--   <pre>
--   instance Monad f =&gt; MonoidIn Comp Identity f
--   </pre>
--   
--   Any other sort of instance and it's easy to run into problems with
--   type inference. If you want to write an instance that's "polymorphic"
--   on tensor choice, use the <a>WrapHBF</a> and <a>WrapF</a> newtype
--   wrappers over type variables, where the third argument also uses a
--   type constructor:
--   
--   <pre>
--   instance MonoidIn (WrapHBF t) (WrapF i) (MyFunctor t i)
--   </pre>
--   
--   This will prevent problems with overloaded instances.
class (Tensor t i, SemigroupIn t f) => MonoidIn t i f

-- | If we have an <tt>i</tt>, we can generate an <tt>f</tt> based on how
--   it interacts with <tt>t</tt>.
--   
--   Specialized (and simplified), this type is:
--   
--   <pre>
--   <a>pureT</a> @<a>Day</a>   :: <a>Applicative</a> f =&gt; <a>Identity</a> a -&gt; f a  -- <a>pure</a>
--   pureT @<a>Comp</a>  :: <a>Monad</a> f =&gt; Identity a -&gt; f a        -- <a>return</a>
--   pureT @(<a>:*:</a>) :: <a>Plus</a> f =&gt; <a>Proxy</a> a -&gt; f a            -- <a>zero</a>
--   </pre>
--   
--   Note that because <tt>t</tt> appears nowhere in the input or output
--   types, you must always use this with explicit type application syntax
--   (like <tt>pureT @Day</tt>)
--   
--   Along with <a>biretract</a>, this function makes <tt>f</tt> a monoid
--   in the category of endofunctors with respect to tensor <tt>t</tt>.
pureT :: MonoidIn t i f => i ~> f

-- | If we have an <tt>i</tt>, we can generate an <tt>f</tt> based on how
--   it interacts with <tt>t</tt>.
--   
--   Specialized (and simplified), this type is:
--   
--   <pre>
--   <a>pureT</a> @<a>Day</a>   :: <a>Applicative</a> f =&gt; <a>Identity</a> a -&gt; f a  -- <a>pure</a>
--   pureT @<a>Comp</a>  :: <a>Monad</a> f =&gt; Identity a -&gt; f a        -- <a>return</a>
--   pureT @(<a>:*:</a>) :: <a>Plus</a> f =&gt; <a>Proxy</a> a -&gt; f a            -- <a>zero</a>
--   </pre>
--   
--   Note that because <tt>t</tt> appears nowhere in the input or output
--   types, you must always use this with explicit type application syntax
--   (like <tt>pureT @Day</tt>)
--   
--   Along with <a>biretract</a>, this function makes <tt>f</tt> a monoid
--   in the category of endofunctors with respect to tensor <tt>t</tt>.
pureT :: (MonoidIn t i f, Interpret (ListBy t) f) => i ~> f

-- | Create the "empty <a>ListBy</a>".
--   
--   If <tt><a>ListBy</a> t f</tt> represents multiple applications of
--   <tt>t f</tt> with itself, then <tt>nilLB</tt> gives us "zero
--   applications of <tt>f</tt>".
--   
--   Note that <tt>t</tt> cannot be inferred from the input or output type
--   of <a>nilLB</a>, so this function must always be called with
--   -XTypeApplications:
--   
--   <pre>
--   <a>nilLB</a> @<tt>Day</tt> :: <tt>Identity</tt> <a>~&gt;</a> <tt>Ap</tt> f
--   nilLB @<tt>Comp</tt> :: Identity ~&gt; <tt>Free</tt> f
--   nilLB @(<a>:*:</a>) :: <tt>Proxy</tt> ~&gt; <tt>ListF</tt> f
--   </pre>
--   
--   Note that this essentially gives an instance for <tt><tt>MonoidIn</tt>
--   t i (ListBy t f)</tt>, for any functor <tt>f</tt>; this is witnessed
--   by <tt>WrapLB</tt>.
nilLB :: forall t i f. Tensor t i => i ~> ListBy t f

-- | Lets us "cons" an application of <tt>f</tt> to the front of an
--   <tt><a>ListBy</a> t f</tt>.
consLB :: Tensor t i => t f (ListBy t f) ~> ListBy t f

-- | Convenient wrapper over <a>intro1</a> that lets us introduce an
--   arbitrary functor <tt>g</tt> to the right of an <tt>f</tt>.
--   
--   You can think of this as an <a>HBifunctor</a> analogue of
--   <a>inject</a>.
inL :: forall t i f g. MonoidIn t i g => f ~> t f g

-- | Convenient wrapper over <a>intro2</a> that lets us introduce an
--   arbitrary functor <tt>f</tt> to the right of a <tt>g</tt>.
--   
--   You can think of this as an <a>HBifunctor</a> analogue of
--   <a>inject</a>.
inR :: forall t i f g. MonoidIn t i f => g ~> t f g

-- | Convenient wrapper over <a>elim1</a> that lets us drop one of the
--   arguments of a <a>Tensor</a> for free, without requiring any extra
--   constraints (like for <a>binterpret</a>).
--   
--   See <a>prodOutL</a> for a version that does not require
--   <tt><a>Functor</a> f</tt>, specifically for <a>:*:</a>.
outL :: (Tensor t Proxy, FunctorBy t f) => t f g ~> f

-- | Convenient wrapper over <a>elim2</a> that lets us drop one of the
--   arguments of a <a>Tensor</a> for free, without requiring any
--   constraints (like for <a>binterpret</a>).
--   
--   See <a>prodOutR</a> for a version that does not require
--   <tt><a>Functor</a> g</tt>, specifically for <a>:*:</a>.
outR :: (Tensor t Proxy, FunctorBy t g) => t f g ~> g
data Coyoneda (f :: Type -> Type) a
[Coyoneda] :: forall b a (f :: Type -> Type). (b -> a) -> f b -> Coyoneda f a

-- | A list of <tt>f a</tt>s. Can be used to describe a product of many
--   different values of type <tt>f a</tt>.
--   
--   This is the Free <a>Plus</a>.
--   
--   Incidentally, if used with a <a>Contravariant</a> <tt>f</tt>, this is
--   instead the free <a>Divisible</a>.
newtype ListF f a
ListF :: [f a] -> ListF f a
[runListF] :: ListF f a -> [f a]

-- | A non-empty list of <tt>f a</tt>s. Can be used to describe a product
--   between many different possible values of type <tt>f a</tt>.
--   
--   Essentially:
--   
--   <pre>
--   <a>NonEmptyF</a> f
--       ~ f                          -- one f
--     <a>:+:</a> (f <a>:*:</a> f)              -- two f's
--     :+: (f :*: f :*: f)            -- three f's
--     :+: (f :*: f :*: f :*: f)      -- four f's
--     :+: ...                        -- etc.
--   </pre>
--   
--   This is the Free <a>Plus</a> on any <a>Functor</a> <tt>f</tt>.
--   
--   Incidentally, if used with a <a>Contravariant</a> <tt>f</tt>, this is
--   instead the free <a>Divise</a>.
newtype NonEmptyF f a
NonEmptyF :: NonEmpty (f a) -> NonEmptyF f a
[runNonEmptyF] :: NonEmptyF f a -> NonEmpty (f a)

-- | Treat a <tt><a>NonEmptyF</a> f</tt> as a product between an <tt>f</tt>
--   and a <tt><a>ListF</a> f</tt>.
--   
--   <a>nonEmptyProd</a> is the record accessor.
pattern ProdNonEmpty :: (f :*: ListF f) a -> NonEmptyF f a

-- | A maybe <tt>f a</tt>.
--   
--   Can be useful for describing a "an <tt>f a</tt> that may or may not be
--   there".
--   
--   This is the free structure for a "fail"-like typeclass that would only
--   have <tt>zero :: f a</tt>.
newtype MaybeF f a
MaybeF :: Maybe (f a) -> MaybeF f a
[runMaybeF] :: MaybeF f a -> Maybe (f a)

-- | A map of <tt>f a</tt>s, indexed by keys of type <tt>k</tt>. It can be
--   useful for represeting a product of many different values of type
--   <tt>f a</tt>, each "at" a different <tt>k</tt> location.
--   
--   Can be considered a combination of <a>EnvT</a> and <a>ListF</a>, in a
--   way --- a <tt><a>MapF</a> k f a</tt> is like a <tt><a>ListF</a>
--   (<a>EnvT</a> k f) a</tt> with unique (and ordered) keys.
--   
--   One use case might be to extend a schema with many "options", indexed
--   by some string.
--   
--   For example, if you had a command line argument parser for a single
--   command
--   
--   <pre>
--   data Command a
--   </pre>
--   
--   Then you can represent a command line argument parser for
--   <i>multiple</i> named commands with
--   
--   <pre>
--   type Commands = <a>MapF</a> <a>String</a> Command
--   </pre>
--   
--   See <a>NEMapF</a> for a non-empty variant, if you want to enforce that
--   your bag has at least one <tt>f a</tt>.
newtype MapF k f a
MapF :: Map k (f a) -> MapF k f a
[runMapF] :: MapF k f a -> Map k (f a)

-- | A non-empty map of <tt>f a</tt>s, indexed by keys of type <tt>k</tt>.
--   It can be useful for represeting a product of many different values of
--   type <tt>f a</tt>, each "at" a different <tt>k</tt> location, where
--   you need to have at least one <tt>f a</tt> at all times.
--   
--   Can be considered a combination of <a>EnvT</a> and <a>NonEmptyF</a>,
--   in a way --- an <tt><a>NEMapF</a> k f a</tt> is like a
--   <tt><a>NonEmptyF</a> (<a>EnvT</a> k f) a</tt> with unique (and
--   ordered) keys.
--   
--   See <a>MapF</a> for some use cases.
newtype NEMapF k f a
NEMapF :: NEMap k (f a) -> NEMapF k f a
[runNEMapF] :: NEMapF k f a -> NEMap k (f a)
data Ap (f :: Type -> Type) a

-- | One or more <tt>f</tt>s convolved with itself.
--   
--   Essentially:
--   
--   <pre>
--   <a>Ap1</a> f
--       ~ f                            -- one f
--     <a>:+:</a> (f `<a>Day</a>` f)          -- two f's
--     :+: (f `Day` f `Day` f)           -- three f's
--     :+: (f `Day` f `Day` f `Day` f)  -- four f's
--     :+: ...                          -- etc.
--   </pre>
--   
--   Useful if you want to promote an <tt>f</tt> to a situation with "at
--   least one <tt>f</tt> sequenced with itself".
--   
--   Mostly useful for its <a>HFunctor</a> and <a>Interpret</a> instance,
--   along with its relationship with <a>Ap</a> and <a>Day</a>.
--   
--   This is the free <a>Apply</a> --- Basically a "non-empty" <a>Ap</a>.
--   
--   The construction here is based on <a>Ap</a>, similar to now
--   <a>NonEmpty</a> is built on list.
data Ap1 :: (Type -> Type) -> Type -> Type
[Ap1] :: f a -> Ap f (a -> b) -> Ap1 f b

-- | An <tt><a>Ap1</a> f</tt> is just a <tt><a>Day</a> f (<a>Ap</a>
--   f)</tt>. This bidirectional pattern synonym lets you treat it as such.
pattern DayAp1 :: Day f (Ap f) a -> Ap1 f a
data Alt (f :: Type -> Type) a

-- | A <tt><a>Free</a> f</tt> is <tt>f</tt> enhanced with "sequential
--   binding" capabilities. It allows you to sequence multiple <tt>f</tt>s
--   one after the other, and also to determine "what <tt>f</tt> to
--   sequence" based on the result of the computation so far.
--   
--   Essentially, you can think of this as "giving <tt>f</tt> a
--   <a>Monad</a> instance", with all that that entails (<a>return</a>,
--   <a>&gt;&gt;=</a>, etc.).
--   
--   Lift <tt>f</tt> into it with <tt><a>inject</a> :: f a -&gt; Free f
--   a</tt>. When you finally want to "use" it, you can interpret it into
--   any monadic context:
--   
--   <pre>
--   <a>interpret</a>
--       :: <a>Monad</a> g
--       =&gt; (forall x. f x -&gt; g x)
--       -&gt; <a>Free</a> f a
--       -&gt; g a
--   </pre>
--   
--   Structurally, this is equivalent to many "nested" f's. A value of type
--   <tt><a>Free</a> f a</tt> is either:
--   
--   <ul>
--   <li><pre>a</pre></li>
--   <li><pre>f a</pre></li>
--   <li><pre>f (f a)</pre></li>
--   <li><pre>f (f (f a))</pre></li>
--   <li>.. etc.</li>
--   </ul>
--   
--   Under the hood, this is the Church-encoded Freer monad. It's
--   <a>Free</a>, or <a>F</a>, but in a way that is compatible with
--   <a>HFunctor</a> and <a>Interpret</a>.
data Free f a

-- | The Free <a>Bind</a>. Imbues any functor <tt>f</tt> with a <a>Bind</a>
--   instance.
--   
--   Conceptually, this is "<a>Free</a> without pure". That is, while
--   normally <tt><a>Free</a> f a</tt> is an <tt>a</tt>, a <tt>f a</tt>, a
--   <tt>f (f a)</tt>, etc., a <tt><a>Free1</a> f a</tt> is an <tt>f
--   a</tt>, <tt>f (f a)</tt>, <tt>f (f (f a))</tt>, etc. It's a
--   <a>Free</a> with "at least one layer of <tt>f</tt>", excluding the
--   <tt>a</tt> case.
--   
--   It can be useful as the semigroup formed by <a>:.:</a> (functor
--   composition): Sometimes we want an <tt>f :.: f</tt>, or an <tt>f :.: f
--   :.: f</tt>, or an <tt>f :.: f :.: f :.: f</tt>...just as long as we
--   have at least one <tt>f</tt>.
data Free1 f a

-- | Applicative functor formed by adding pure computations to a given
--   applicative functor.
data Lift (f :: Type -> Type) a

-- | An <tt>f a</tt>, along with a <a>Natural</a> index.
--   
--   <pre>
--   <a>Step</a> f a ~ (<a>Natural</a>, f a)
--   Step f   ~ ((,) Natural) <a>:.:</a> f       -- functor composition
--   </pre>
--   
--   It is the fixed point of infinite applications of <a>:+:</a> (functor
--   sums).
--   
--   Intuitively, in an infinite <tt>f :+: f :+: f :+: f ...</tt>, you have
--   exactly one <tt>f</tt> <i>somewhere</i>. A <tt><a>Step</a> f a</tt>
--   has that <tt>f</tt>, with a <a>Natural</a> giving you "where" the
--   <tt>f</tt> is in the long chain.
--   
--   Can be useful for using with the <a>Monoidal</a> instance of
--   <a>:+:</a>.
--   
--   <a>interpret</a>ing it requires no constraint on the target context.
--   
--   Note that this type and its instances equivalent to <tt><a>EnvT</a>
--   (<a>Sum</a> <a>Natural</a>)</tt>.
data Step f a
Step :: Natural -> f a -> Step f a
[stepPos] :: Step f a -> Natural
[stepVal] :: Step f a -> f a

-- | A non-empty map of <a>Natural</a> to <tt>f a</tt>. Basically, contains
--   multiple <tt>f a</tt>s, each at a given <a>Natural</a> index.
--   
--   <pre>
--   Steps f a ~ <a>Map</a> <a>Natural</a> (f a)
--   Steps f   ~ <a>Map</a> <a>Natural</a> <a>:.:</a> f       -- functor composition
--   </pre>
--   
--   It is the fixed point of applications of <a>TheseT</a>.
--   
--   You can think of this as an infinite sparse array of <tt>f a</tt>s.
--   
--   Intuitively, in an infinite <tt>f `TheseT` f `TheseT` f `TheseT` f
--   ...</tt>, each of those infinite positions may have an <tt>f</tt> in
--   them. However, because of the at-least-one nature of <a>TheseT</a>, we
--   know we have at least one f at one position <i>somewhere</i>.
--   
--   A <tt><a>Steps</a> f a</tt> has potentially many <tt>f</tt>s, each
--   stored at a different <a>Natural</a> position, with the guaruntee that
--   at least one <tt>f</tt> exists.
--   
--   Can be useful for using with the <a>Monoidal</a> instance of
--   <a>TheseT</a>.
--   
--   <a>interpret</a>ing it requires at least an <a>Alt</a> instance in the
--   target context, since we have to handle potentially more than one
--   <tt>f</tt>.
--   
--   This type is essentailly the same as <tt><a>NEMapF</a> (<a>Sum</a>
--   <a>Natural</a>)</tt> (except with a different <a>Semigroup</a>
--   instance).
newtype Steps f a
Steps :: NEMap Natural (f a) -> Steps f a
[getSteps] :: Steps f a -> NEMap Natural (f a)

-- | The functor combinator that forgets all structure in the input.
--   Ignores the input structure and stores no information.
--   
--   Acts like the "zero" with respect to functor combinator composition.
--   
--   <pre>
--   <a>ComposeT</a> ProxyF f      ~ ProxyF
--   <a>ComposeT</a> f      ProxyF ~ ProxyF
--   </pre>
--   
--   It can be <a>inject</a>ed into (losing all information), but it is
--   impossible to ever <a>retract</a> or <a>interpret</a> it.
--   
--   This is essentially <tt><a>ConstF</a> ()</tt>.
data ProxyF f a
ProxyF :: ProxyF f a

-- | Functor combinator that forgets all structure on the input, and
--   instead stores a value of type <tt>e</tt>.
--   
--   Like <a>ProxyF</a>, acts like a "zero" with functor combinator
--   composition.
--   
--   It can be <a>inject</a>ed into (losing all information), but it is
--   impossible to ever <a>retract</a> or <a>interpret</a> it.
data ConstF e f a
ConstF :: e -> ConstF e f a
[getConstF] :: ConstF e f a -> e
data EnvT e (w :: Type -> Type) a
EnvT :: e -> w a -> EnvT e (w :: Type -> Type) a

-- | The reader monad transformer, which adds a read-only environment to
--   the given monad.
--   
--   The <a>return</a> function ignores the environment, while
--   <tt>&gt;&gt;=</tt> passes the inherited environment to both
--   subcomputations.
newtype ReaderT r (m :: Type -> Type) a
ReaderT :: (r -> m a) -> ReaderT r (m :: Type -> Type) a
[runReaderT] :: ReaderT r (m :: Type -> Type) a -> r -> m a

-- | An <tt>f a</tt>, along with a <a>Bool</a> flag
--   
--   <pre>
--   <a>Flagged</a> f a ~ (<a>Bool</a>, f a)
--   Flagged f   ~ ((,) Bool) <a>:.:</a> f       -- functor composition
--   </pre>
--   
--   Creation with <a>inject</a> or <a>pure</a> uses <a>False</a> as the
--   boolean.
--   
--   You can think of it as an <tt>f a</tt> that is "flagged" with a
--   boolean value, and that value can indicuate whether or not it is
--   "pure" (made with <a>inject</a> or <a>pure</a>) as <a>False</a>, or
--   "impure" (made from some other source) as <a>True</a>. However,
--   <a>False</a> may be always created directly, of course, using the
--   constructor.
--   
--   You can think of it like a <a>Step</a> that is either 0 or 1, as well.
--   
--   <a>interpret</a>ing it requires no constraint on the target context.
--   
--   This type is equivalent (along with its instances) to:
--   
--   <ul>
--   <li><pre><a>HLift</a> <a>IdentityT</a></pre></li>
--   <li><pre><a>EnvT</a> <a>Any</a></pre></li>
--   </ul>
data Flagged f a
Flagged :: Bool -> f a -> Flagged f a
[flaggedFlag] :: Flagged f a -> Bool
[flaggedVal] :: Flagged f a -> f a

-- | The trivial monad transformer, which maps a monad to an equivalent
--   monad.
newtype IdentityT (f :: k -> Type) (a :: k)
IdentityT :: f a -> IdentityT (f :: k -> Type) (a :: k)
[runIdentityT] :: IdentityT (f :: k -> Type) (a :: k) -> f a

-- | <tt><a>Void2</a> a b</tt> is uninhabited for all <tt>a</tt> and
--   <tt>b</tt>.
data Void2 a b

-- | A simple way to inject/reject into any eventual typeclass.
--   
--   In a way, this is the "ultimate" multi-purpose <a>Interpret</a>
--   instance. You can use this to inject an <tt>f</tt> into a free
--   structure of any typeclass. If you want <tt>f</tt> to have a
--   <a>Monad</a> instance, for example, just use
--   
--   <pre>
--   <a>inject</a> :: f a -&gt; <a>Final</a> <a>Monad</a> f a
--   </pre>
--   
--   When you want to eventually interpret out the data, use:
--   
--   <pre>
--   <a>interpret</a> :: (f <a>~&gt;</a> g) -&gt; <a>Final</a> c f a -&gt; g a
--   </pre>
--   
--   Essentially, <tt><a>Final</a> c</tt> is the "free c". <tt><a>Final</a>
--   <a>Monad</a></tt> is the free <a>Monad</a>, etc.
--   
--   <a>Final</a> can theoretically replace <a>Ap</a>, <a>Ap1</a>,
--   <a>ListF</a>, <a>NonEmptyF</a>, <a>MaybeF</a>, <a>Free</a>,
--   <a>Identity</a>, <a>Coyoneda</a>, and other instances of
--   <a>FreeOf</a>, if you don't care about being able to pattern match on
--   explicit structure.
--   
--   However, it cannot replace <a>Interpret</a> instances that are not
--   free structures, like <a>Step</a>, <a>Steps</a>, <a>Backwards</a>,
--   etc.
--   
--   Note that this doesn't have instances for <i>all</i> the typeclasses
--   you could lift things into; you probably have to define your own if
--   you want to use <tt><a>Final</a> c</tt> as an <i>instance</i> of
--   <tt>c</tt> (using <a>liftFinal0</a>, <a>liftFinal1</a>,
--   <a>liftFinal2</a> for help).
newtype Final c f a
Final :: (forall g. c g => (forall x. f x -> g x) -> g a) -> Final c f a
[runFinal] :: Final c f a -> forall g. c g => (forall x. f x -> g x) -> g a

-- | A typeclass associating a free structure with the typeclass it is free
--   on.
--   
--   This essentially lists instances of <a>Interpret</a> where a "trip"
--   through <a>Final</a> will leave it unchanged.
--   
--   <pre>
--   <a>fromFree</a> . <a>toFree</a> == id
--   <a>toFree</a> . <a>fromFree</a> == id
--   </pre>
--   
--   This can be useful because <a>Final</a> doesn't have a concrete
--   structure that you can pattern match on and inspect, but <tt>t</tt>
--   might. This lets you work on a concrete structure if you desire.
class FreeOf c t | t -> c where {
    
    -- | What "type" of functor is expected: should be either
    --   <a>Unconstrained</a>, <a>Functor</a>, <a>Contravariant</a>, or
    --   <a>Invariant</a>.
    type family FreeFunctorBy t :: (Type -> Type) -> Constraint;
    type FreeFunctorBy t = Unconstrained;
}
fromFree :: FreeOf c t => t f ~> Final c f
toFree :: (FreeOf c t, FreeFunctorBy t f) => Final c f ~> t f
fromFree :: (FreeOf c t, Interpret t (Final c f)) => t f ~> Final c f
toFree :: (FreeOf c t, Inject t, c (t f)) => Final c f ~> t f
newtype ComposeT (f :: Type -> Type -> Type -> Type) (g :: Type -> Type -> Type -> Type) (m :: Type -> Type) a
ComposeT :: f (g m) a -> ComposeT (f :: (Type -> Type) -> Type -> Type) (g :: (Type -> Type) -> Type -> Type) (m :: Type -> Type) a
[getComposeT] :: ComposeT (f :: (Type -> Type) -> Type -> Type) (g :: (Type -> Type) -> Type -> Type) (m :: Type -> Type) a -> f (g m) a
data Day (f :: Type -> Type) (g :: Type -> Type) a
Day :: f b -> g c -> (b -> c -> a) -> Day (f :: Type -> Type) (g :: Type -> Type) a

-- | Products: encode multiple arguments to constructors
data ( (f :: k -> Type) :*: (g :: k -> Type) ) (p :: k)
(:*:) :: f p -> g p -> (:*:) (f :: k -> Type) (g :: k -> Type) (p :: k)
infixr 6 :*:
infixr 6 :*:

-- | A poly-kinded version of <a>outL</a> for <a>:*:</a>.
prodOutL :: (f :*: g) ~> f

-- | A poly-kinded version of <a>outR</a> for <a>:*:</a>.
prodOutR :: (f :*: g) ~> g

-- | Sums: encode choice between constructors
data ( (f :: k -> Type) :+: (g :: k -> Type) ) (p :: k)
L1 :: f p -> (:+:) (f :: k -> Type) (g :: k -> Type) (p :: k)
R1 :: g p -> (:+:) (f :: k -> Type) (g :: k -> Type) (p :: k)
infixr 5 :+:

-- | Void: used for datatypes without constructors
data V1 (p :: k)
data These1 (f :: Type -> Type) (g :: Type -> Type) a
This1 :: f a -> These1 (f :: Type -> Type) (g :: Type -> Type) a
That1 :: g a -> These1 (f :: Type -> Type) (g :: Type -> Type) a
These1 :: f a -> g a -> These1 (f :: Type -> Type) (g :: Type -> Type) a

-- | A pairing of invariant functors to create a new invariant functor that
--   represents the "choice" between the two.
--   
--   A <tt><a>Night</a> f g a</tt> is a invariant "consumer" and "producer"
--   of <tt>a</tt>, and it does this by either feeding the <tt>a</tt> to
--   <tt>f</tt>, or feeding the <tt>a</tt> to <tt>g</tt>, and then
--   collecting the result from whichever one it was fed to. Which decision
--   of which path to takes happens at runtime depending <i>what</i>
--   <tt>a</tt> is actually given.
--   
--   For example, if we have <tt>x :: f a</tt> and <tt>y :: g b</tt>, then
--   <tt><a>night</a> x y :: <a>Night</a> f g (<a>Either</a> a b)</tt>.
--   This is a consumer/producer of <tt><a>Either</a> a b</tt>s, and it
--   consumes <a>Left</a> branches by feeding it to <tt>x</tt>, and
--   <a>Right</a> branches by feeding it to <tt>y</tt>. It then passes back
--   the single result from the one of the two that was chosen.
--   
--   Mathematically, this is a invariant day convolution, except with a
--   different choice of bifunctor (<a>Either</a>) than the typical one we
--   talk about in Haskell (which uses <tt>(,)</tt>). Therefore, it is an
--   alternative to the typical <a>Day</a> convolution --- hence, the name
--   <a>Night</a>.
data Night :: (Type -> Type) -> (Type -> Type) -> (Type -> Type)
[Night] :: f b -> g c -> (b -> a) -> (c -> a) -> (a -> Either b c) -> Night f g a

-- | A value of type <tt><a>Not</a> a</tt> is "proof" that <tt>a</tt> is
--   uninhabited.
newtype Not a
Not :: (a -> Void) -> Not a
[refute] :: Not a -> a -> Void

-- | A useful shortcut for a common usage: <a>Void</a> is always not so.
refuted :: Not Void

-- | Functor composition. <tt><a>Comp</a> f g a</tt> is equivalent to <tt>f
--   (g a)</tt>, and the <a>Comp</a> pattern synonym is a way of getting
--   the <tt>f (g a)</tt> in a <tt><a>Comp</a> f g a</tt>.
--   
--   For example, <tt><a>Maybe</a> (<a>IO</a> <a>Bool</a>)</tt> is
--   <tt><a>Comp</a> <a>Maybe</a> <a>IO</a> <a>Bool</a></tt>.
--   
--   This is mostly useful for its typeclass instances: in particular,
--   <a>Functor</a>, <a>Applicative</a>, <a>HBifunctor</a>, and
--   <a>Monoidal</a>.
--   
--   This is essentially a version of <a>:.:</a> and <a>Compose</a> that
--   allows for an <a>HBifunctor</a> instance.
--   
--   It is slightly less performant. Using <tt><a>comp</a> .
--   <a>unComp</a></tt> every once in a while will concretize a <a>Comp</a>
--   value (if you have <tt><a>Functor</a> f</tt>) and remove some
--   indirection if you have a lot of chained operations.
--   
--   The "free monoid" over <a>Comp</a> is <a>Free</a>, and the "free
--   semigroup" over <a>Comp</a> is <a>Free1</a>.
data Comp f g a

-- | Pattern match on and construct a <tt><a>Comp</a> f g a</tt> as if it
--   were <tt>f (g a)</tt>.
pattern Comp :: Functor f => f (g a) -> Comp f g a

-- | An <a>HBifunctor</a> that ignores its second input. Like a <a>:+:</a>
--   with no <a>R1</a>/right branch.
--   
--   This is <a>Joker</a> from <a>Data.Bifunctors.Joker</a>, but given a
--   more sensible name for its purpose.
newtype LeftF f g a
LeftF :: f a -> LeftF f g a
[runLeftF] :: LeftF f g a -> f a

-- | An <a>HBifunctor</a> that ignores its first input. Like a <a>:+:</a>
--   with no <a>L1</a>/left branch.
--   
--   In its polykinded form (on <tt>f</tt>), it is essentially a
--   higher-order version of <a>Tagged</a>.
newtype RightF f g a
RightF :: g a -> RightF f g a
[runRightF] :: RightF f g a -> g a

-- | An "<a>HFunctor</a> combinator" that enhances an <a>HFunctor</a> with
--   the ability to hold a single <tt>f a</tt>. This is the higher-order
--   analogue of <a>Lift</a>.
--   
--   You can think of it as a free <a>Inject</a> for any <tt>f</tt>.
--   
--   Note that <tt><a>HLift</a> <a>IdentityT</a></tt> is equivalent to
--   <tt><a>EnvT</a> <a>Any</a></tt>.
data HLift t f a
HPure :: f a -> HLift t f a
HOther :: t f a -> HLift t f a

-- | An "<a>HFunctor</a> combinator" that turns an <a>HFunctor</a> into
--   potentially infinite nestings of that <a>HFunctor</a>.
--   
--   An <tt><a>HFree</a> t f a</tt> is either <tt>f a</tt>, <tt>t f a</tt>,
--   <tt>t (t f) a</tt>, <tt>t (t (t f)) a</tt>, etc.
--   
--   This effectively turns <tt>t</tt> into a tree with <tt>t</tt>
--   branches.
--   
--   One particularly useful usage is with <a>MapF</a>. For example if you
--   had a data type representing a command line command parser:
--   
--   <pre>
--   data Command a
--   </pre>
--   
--   You could represent "many possible named commands" using
--   
--   <pre>
--   type Commands = <a>MapF</a> <a>String</a> Command
--   </pre>
--   
--   And you can represent multiple <i>nested</i> named commands using:
--   
--   <pre>
--   type NestedCommands = <a>HFree</a> (<a>MapF</a> <a>String</a>)
--   </pre>
--   
--   This has an <a>Interpret</a> instance, but it can be more useful to
--   use via direct pattern matching, or through
--   
--   <pre>
--   <a>foldHFree</a>
--       :: <a>HBifunctor</a> t
--       =&gt; f <a>~&gt;</a> g
--       -&gt; t g ~&gt; g
--       -&gt; HFree t f ~&gt; g
--   </pre>
--   
--   which requires no extra constriant on <tt>g</tt>, and lets you
--   consider each branch separately.
--   
--   This can be considered the higher-oder analogue of <a>Free</a>; it is
--   the free <a>HBind</a> for any <tt><a>HFunctor</a> t</tt>.
--   
--   Note that <tt><a>HFree</a> <a>IdentityT</a></tt> is equivalent to
--   <a>Step</a>.
data HFree t f a
HReturn :: f a -> HFree t f a
HJoin :: t (HFree t f) a -> HFree t f a

-- | Turn <a>Identity</a> into any <tt><a>Applicative</a> f</tt>. Can be
--   useful as an argument to <a>hmap</a>, <a>hbimap</a>, or
--   <a>interpret</a>.
--   
--   It is a more general form of <a>generalize</a> from <i>mmorph</i>.
generalize :: Applicative f => Identity ~> f

-- | Natural transformation from any functor <tt>f</tt> into <a>Proxy</a>.
--   Can be useful for "zeroing out" a functor with <a>hmap</a> or
--   <a>hbimap</a> or <a>interpret</a>.
absorb :: f ~> Proxy

-- | Convenient helper function to build up a <a>Divisible</a> by splitting
--   input across many different <tt>f a</tt>s. Most useful when used
--   alongside <a>contramap</a>:
--   
--   <pre>
--   dsum [
--       contramap get1 x
--     , contramap get2 y
--     , contramap get3 z
--     ]
--   </pre>
dsum :: (Foldable t, Divisible f) => t (f a) -> f a

-- | Convenient helper function to build up a <a>Divise</a> by splitting
--   input across many different <tt>f a</tt>s. Most useful when used
--   alongside <a>contramap</a>:
--   
--   <pre>
--   dsum1 $ contramap get1 x
--      :| [ contramap get2 y
--         , contramap get3 z
--         ]
--   </pre>
dsum1 :: (Foldable1 t, Divise f) => t (f a) -> f a

-- | Convenient helper function to build up a <a>Conclude</a> by providing
--   each component of it. This makes it much easier to build up longer
--   chains as opposed to nested calls to <a>decide</a> and manually
--   peeling off eithers one-by-one.
--   
--   For example, if you had a data type
--   
--   <pre>
--   data MyType = MTI Int | MTB Bool | MTS String
--   </pre>
--   
--   and a contravariant consumer <tt>Builder</tt> (representing, say, a
--   way to serialize an item, where <tt>intBuilder :: Builder Int</tt> is
--   a serializer of <a>Int</a>s), then you could assemble a serializer a
--   <tt>MyType</tt> using:
--   
--   <pre>
--   contramap (case MTI x -&gt; Z (I x); MTB y -&gt; S (Z (I y)); MTS z -&gt; S (S (Z (I z)))) $
--     concludeN $ intBuilder
--              :* boolBuilder
--              :* stringBuilder
--              :* Nil
--   </pre>
--   
--   Some notes on usefulness depending on how many components you have:
--   
--   <ul>
--   <li>If you have 0 components, use <a>conclude</a>.</li>
--   <li>If you have 1 component, use <a>inject</a> directly.</li>
--   <li>If you have 2 components, use <a>decide</a> directly.</li>
--   <li>If you have 3 or more components, these combinators may be useful;
--   otherwise you'd need to manually peel off eithers one-by-one.</li>
--   </ul>
concludeN :: Conclude f => NP f as -> f (NS I as)

-- | A version of <a>concludeN</a> that works for non-empty
--   <a>NP</a>/<a>NS</a>, and so only requires a <a>Decide</a> constraint.
decideN :: Decide f => NP f (a : as) -> f (NS I (a : as))


-- | This module contains the useful combinators <a>Pre</a> and
--   <a>Post</a>, which enhances a functor with a "route" to and from the
--   outside world; even if the functor itself is existentially closed in a
--   functor combinator, the route will provide line to the outside world
--   for extraction or injection.
--   
--   See <a>Pre</a> and <a>Post</a> for more information.
module Data.HFunctor.Route

-- | A useful helper type to use with a covariant functor combinator that
--   allows you to tag along contravariant access to all <tt>f</tt>s inside
--   the combinator.
--   
--   Maybe most usefully, it can be used with <tt>Ap</tt>. Remember that
--   <tt><tt>Ap</tt> f a</tt> is a collection of <tt>f x</tt>s, with each x
--   existentially wrapped. Now, for a <tt><tt>Ap</tt> (Pre a f) a</tt>, it
--   will be a collection of <tt>f x</tt> and <tt>a -&gt; x</tt>s: not only
--   each individual part, but a way to "select" that individual part from
--   the overal <tt>a</tt>.
--   
--   So, you can imagine <tt><tt>Ap</tt> (<a>Pre</a> a f) b</tt> as a
--   collection of <tt>f x</tt> that consumes <tt>a</tt> and produces
--   <tt>b</tt>.
--   
--   When <tt>a</tt> and <tt>b</tt> are the same, <tt><tt>Ap</tt>
--   (<a>Pre</a> a f) a</tt> is like the free invariant sequencer. That is,
--   in a sense, <tt><tt>Ap</tt> (<a>Pre</a> a f) a</tt> contains both
--   contravariant and covariant sequences side-by-side, <i>consuming</i>
--   <tt>a</tt>s and also <i>producing</i> <tt>a</tt>s.
--   
--   You can build up these values with <a>injectPre</a>, and then use
--   whatever typeclasses your <tt>t</tt> normally supports to build it up,
--   like <a>Applicative</a> (for <tt>Ap</tt>). You can then interpret it
--   into both its contravariant and covariant contexts:
--   
--   <pre>
--   -- interpret the covariant part
--   runCovariant :: <a>Applicative</a> g =&gt; (f ~&gt; g) -&gt; Ap (Pre a f) a -&gt; g a
--   runCovariant f = interpret (f . getPre)
--   
--   -- interpret the contravariant part
--   runContravariant :: <a>Divisible</a> g =&gt; (f ~&gt; g) -&gt; Ap (Pre a f) a -&gt; g a
--   runContravariant = preDivisible
--   </pre>
--   
--   The <a>PreT</a> type wraps up <tt><tt>Ap</tt> (<a>Pre</a> a f) a</tt>
--   into a type <tt><a>PreT</a> <tt>Ap</tt> f a</tt>, with nice
--   instances/helpers.
--   
--   An example of a usage of this in the real world is the <i>unjson</i>
--   library's record type constructor, to implement bidrectional
--   serializers for product types.
data Pre a f b
(:>$<:) :: (a -> b) -> f b -> Pre a f b
infixl 4 :>$<:

-- | Interpret a <a>Pre</a> into a contravariant context, applying the
--   pre-routing function.
interpretPre :: Contravariant g => (f ~> g) -> Pre a f b -> g a

-- | Drop the pre-routing function and just give the original wrapped
--   value.
getPre :: Pre a f b -> f b

-- | Contravariantly retract the <tt>f</tt> out of a <a>Pre</a>, applying
--   the pre-routing function. Not usually that useful because <a>Pre</a>
--   is meant to be used with covariant <a>Functor</a>s.
retractPre :: Contravariant f => Pre a f b -> f a

-- | Like <a>inject</a>, but allowing you to provide a pre-routing
--   function.
injectPre :: Inject t => (a -> b) -> f b -> t (Pre a f) b

-- | Pre-compose on the pre-routing function.
mapPre :: (c -> a) -> Pre a f b -> Pre c f b

-- | Run a "pre-routed" <tt>t</tt> into a contravariant <a>Divisible</a>
--   context. To run it in <tt>t</tt>s normal covariant context, use
--   <a>interpret</a> with <a>getPre</a>.
--   
--   This will work for types where there are a possibly-empty collection
--   of <tt>f</tt>s, like:
--   
--   <pre>
--   preDivisible :: Divisible g =&gt; (f ~&gt; g) -&gt; <tt>Ap</tt>    (<a>Pre</a> a f) b -&gt; g a
--   preDivisible :: Divisible g =&gt; (f ~&gt; g) -&gt; <tt>ListF</tt> (<a>Pre</a> a f) b -&gt; g a
--   </pre>
preDivisible :: (forall m. Monoid m => Interpret t (AltConst m), Divisible g) => (f ~> g) -> t (Pre a f) b -> g a

-- | Run a "pre-routed" <tt>t</tt> into a contravariant <a>Divise</a>
--   context. To run it in <tt>t</tt>s normal covariant context, use
--   <a>interpret</a> with <a>getPre</a>.
--   
--   This will work for types where there are is a non-empty collection of
--   <tt>f</tt>s, like:
--   
--   <pre>
--   preDivise :: Divise g =&gt; (f ~&gt; g) -&gt; <tt>Ap1</tt>       (<a>Pre</a> a f) b -&gt; g a
--   preDivise :: Divise g =&gt; (f ~&gt; g) -&gt; <tt>NonEmptyF</tt> (<a>Pre</a> a f) b -&gt; g a
--   </pre>
preDivise :: (forall m. Semigroup m => Interpret t (AltConst m), Divise g) => (f ~> g) -> t (Pre a f) b -> g a

-- | Run a "pre-routed" <tt>t</tt> into a <a>Contravariant</a>. To run it
--   in <tt>t</tt>s normal covariant context, use <a>interpret</a> with
--   <a>getPre</a>.
--   
--   This will work for types where there is exactly one <tt>f</tt> inside:
--   
--   <pre>
--   preContravariant :: Contravariant g =&gt; (f ~&gt; g) -&gt; <tt>Step</tt>     (<a>Pre</a> a f) b -&gt; g a
--   preContravariant :: Contravariant g =&gt; (f ~&gt; g) -&gt; <tt>Coyoneda</tt> (<a>Pre</a> a f) b -&gt; g a
--   </pre>
preContravariant :: (forall m. Interpret t (AltConst m), Contravariant g) => (f ~> g) -> t (Pre a f) b -> g a

-- | A useful helper type to use with a contravariant functor combinator
--   that allows you to tag along covariant access to all <tt>f</tt>s
--   inside the combinator.
--   
--   Maybe most usefully, it can be used with <tt>Dec</tt>. Remember that
--   <tt><tt>Dec</tt> f a</tt> is a collection of <tt>f x</tt>s, with each
--   x existentially wrapped. Now, for a <tt><tt>Dec</tt> (Post a f)
--   a</tt>, it will be a collection of <tt>f x</tt> and <tt>x -&gt;
--   a</tt>s: not only each individual part, but a way to "re-embed" that
--   individual part into overal <tt>a</tt>.
--   
--   So, you can imagine <tt><tt>Dec</tt> (<a>Post</a> a f) b</tt> as a
--   collection of <tt>f x</tt> that consumes <tt>b</tt> and produces
--   <tt>a</tt>.
--   
--   When <tt>a</tt> and <tt>b</tt> are the same, <tt><tt>Dec</tt>
--   (<a>Post</a> a f) a</tt> is like the free invariant sequencer. That
--   is, in a sense, <tt><tt>Dec</tt> (<a>Post</a> a f) a</tt> contains
--   both contravariant and covariant sequences side-by-side,
--   <i>consuming</i> <tt>a</tt>s and also <i>producing</i> <tt>a</tt>s.
--   
--   You can build up these values with <a>injectPre</a>, and then use
--   whatever typeclasses your <tt>t</tt> normally supports to build it up,
--   like <a>Conclude</a> (for <tt>Div</tt>). You can then interpret it
--   into both its contravariant and covariant contexts:
--   
--   <pre>
--   -- interpret the covariant part
--   runCovariant :: <a>Plus</a> g =&gt; (f ~&gt; g) -&gt; Div (Post a f) a -&gt; g a
--   runCovariant f = interpret (f . getPost)
--   
--   -- interpret the contravariant part
--   runContravariant :: <a>Conclude</a> g =&gt; (f ~&gt; g) -&gt; Div (Post a f) a -&gt; g a
--   runContravariant = preDivisible
--   </pre>
--   
--   The <a>PostT</a> type wraps up <tt><tt>Dec</tt> (<a>Post</a> a f)
--   a</tt> into a type <tt><a>PostT</a> <tt>Dec</tt> f a</tt>, with nice
--   instances/helpers.
--   
--   An example of a usage of this in the real world is a possible
--   implementation of the <i>unjson</i> library's sum type constructor, to
--   implement bidrectional serializers for sum types.
data Post a f b
(:<$>:) :: (b -> a) -> f b -> Post a f b
infixl 4 :<$>:

-- | Interpret a <a>Post</a> into a covariant context, applying the
--   post-routing function.
interpretPost :: Functor g => (f ~> g) -> Post a f b -> g a

-- | Drop the post-routing function and just give the original wrapped
--   value.
getPost :: Post a f b -> f b

-- | Covariantly retract the <tt>f</tt> out of a <a>Post</a>, applying the
--   post-routing function. Not usually that useful because <a>Post</a> is
--   meant to be used with contravariant <a>Functor</a>s.
retractPost :: Functor f => Post a f b -> f a

-- | Like <a>inject</a>, but allowing you to provide a post-routing
--   function.
injectPost :: Inject t => (b -> a) -> f b -> t (Post a f) b

-- | Post-compose on the post-routing function.
mapPost :: (a -> c) -> Post a f b -> Post c f b

-- | Run a "post-routed" <tt>t</tt> into a covariant <a>Plus</a> context.
--   To run it in <tt>t</tt>s normal contravariant context, use
--   <a>interpret</a>.
--   
--   This will work for types where there are a possibly-empty collection
--   of <tt>f</tt>s, like:
--   
--   <pre>
--   postPlus :: Plus g =&gt; (f ~&gt; g) -&gt; <tt>Dec</tt> (Post a f) b -&gt; g a
--   postPlus :: Plus g =&gt; (f ~&gt; g) -&gt; <tt>Div</tt> (Post a f) b -&gt; g a
--   </pre>
postPlus :: (forall m. Monoid m => Interpret t (AltConst m), Plus g) => (f ~> g) -> t (Post a f) b -> g a

-- | Run a "post-routed" <tt>t</tt> into a covariant <a>Alt</a> context. To
--   run it in <tt>t</tt>s normal contravariant context, use
--   <a>interpret</a>.
--   
--   This will work for types where there are is a non-empty collection of
--   <tt>f</tt>s, like:
--   
--   <pre>
--   postAlt :: Alt g =&gt; (f ~&gt; g) -&gt; <tt>Dec1</tt> (Post a f) b -&gt; g a
--   postAlt :: Alt g =&gt; (f ~&gt; g) -&gt; <tt>Div1</tt> (Post a f) b -&gt; g a
--   </pre>
postAlt :: (forall m. Semigroup m => Interpret t (AltConst m), Alt g) => (f ~> g) -> t (Post a f) b -> g a

-- | Run a "post-routed" <tt>t</tt> into a covariant <a>Functor</a>
--   context. To run it in <tt>t</tt>s normal contravariant context, use
--   <a>interpret</a>.
--   
--   This will work for types where there is exactly one <tt>f</tt> inside:
--   
--   <pre>
--   postFunctor :: Functor g =&gt; (f ~&gt; g) -&gt; <tt>Step</tt>         (Post a f) b -&gt; g a
--   postFunctor :: Functor g =&gt; (f ~&gt; g) -&gt; <a>Coyoneda</a> (Post a f) b -&gt; g a
--   </pre>
postFunctor :: (forall m. Interpret t (AltConst m), Functor g) => (f ~> g) -> t (Post a f) b -> g a

-- | Turn the covariant functor combinator <tt>t</tt> into an
--   <a>Invariant</a> functor combinator; if <tt>t f a</tt> "produces"
--   <tt>a</tt>s, then <tt><a>PreT</a> t f a</tt> will both consume and
--   produce <tt>a</tt>s.
--   
--   You can run this normally as if it were a <tt>t f a</tt> by using
--   <a>interpret</a>; however, you can also interpret into covariant
--   contexts with <a>preDivisibleT</a>, <a>preDiviseT</a>, and
--   <a>preContravariantT</a>.
--   
--   A useful way to use this type is to use normal methods of the
--   underlying <tt>t</tt> to assemble a final <tt>t</tt>, then using the
--   <a>PreT</a> constructor to wrap it all up.
--   
--   <pre>
--   data MyType = MyType
--        { mtInt    :: Int
--        , mtBool   :: Bool
--        , mtString :: String
--        }
--   
--   myThing :: PreT Ap MyFunctor MyType
--   myThing = PreT $ MyType
--       <a>$</a> injectPre mtInt    (mfInt    :: MyFunctor Int   )
--       <a>*</a> injectPre mtBool   (mfBool   :: MyFunctor Bool  )
--       <a>*</a> injectPre mtString (mfString :: MyFunctor STring)
--   </pre>
--   
--   See <a>Pre</a> for more information.
newtype PreT t f a
PreT :: t (Pre a f) a -> PreT t f a
[unPreT] :: PreT t f a -> t (Pre a f) a

-- | Run a <tt><a>PreT</a> t</tt> into a contravariant <a>Divisible</a>
--   context. To run it in <tt>t</tt>s normal covariant context, use
--   <a>interpret</a>.
--   
--   This will work for types where there are a possibly-empty collection
--   of <tt>f</tt>s, like:
--   
--   <pre>
--   preDivisibleT :: Divisible g =&gt; (f ~&gt; g) -&gt; PreT <tt>Ap</tt>    f ~&gt; g
--   preDivisibleT :: Divisible g =&gt; (f ~&gt; g) -&gt; PreT <tt>ListF</tt> f ~&gt; g
--   </pre>
preDivisibleT :: (forall m. Monoid m => Interpret t (AltConst m), Divisible g) => (f ~> g) -> PreT t f ~> g

-- | Run a <tt><a>PreT</a> t</tt> into a contravariant <a>Divise</a>
--   context. To run it in <tt>t</tt>s normal covariant context, use
--   <a>interpret</a>.
--   
--   This will work for types where there is a non-empty collection of
--   <tt>f</tt>s, like:
--   
--   <pre>
--   preDiviseT :: Divise g =&gt; (f ~&gt; g) -&gt; PreT <tt>Ap1</tt>       f ~&gt; g
--   preDiviseT :: Divise g =&gt; (f ~&gt; g) -&gt; PreT <tt>NonEmptyF</tt> f ~&gt; g
--   </pre>
preDiviseT :: (forall m. Semigroup m => Interpret t (AltConst m), Divise g) => (f ~> g) -> PreT t f ~> g

-- | Run a <tt><a>PreT</a> t</tt> into a <a>Contravariant</a>. To run it in
--   <tt>t</tt>s normal covariant context, use <a>interpret</a>.
--   
--   This will work for types where there is exactly one <tt>f</tt> inside:
--   
--   <pre>
--   preContravariantT :: Contravariant g =&gt; (f ~&gt; g) -&gt; PreT <tt>Step</tt>     f ~&gt; g
--   preContravariantT :: Contravariant g =&gt; (f ~&gt; g) -&gt; PreT <tt>Coyoneda</tt> f ~&gt; g
--   </pre>
preContravariantT :: (forall m. Interpret t (AltConst m), Contravariant g) => (f ~> g) -> PreT t f ~> g

-- | Turn the contravariant functor combinator <tt>t</tt> into an
--   <a>Invariant</a> functor combinator; if <tt>t f a</tt> "consumes"
--   <tt>a</tt>s, then <tt><a>PostT</a> t f a</tt> will both consume and
--   produce <tt>a</tt>s.
--   
--   You can run this normally as if it were a <tt>t f a</tt> by using
--   <a>interpret</a>; however, you can also interpret into covariant
--   contexts with <a>postPlusT</a>, <a>postAltT</a>, and
--   <a>postFunctorT</a>.
--   
--   A useful way to use this type is to use normal methods of the
--   underlying <tt>t</tt> to assemble a final <tt>t</tt>, then using the
--   <a>PreT</a> constructor to wrap it all up.
--   
--   <pre>
--   myThing :: PostT Dec MyFunctor (Either Int Bool)
--   myThing = PostT $ decided $
--       (injectPost Left  (mfInt  :: MyFunctor Int ))
--       (injectPost Right (mfBool :: MyFunctor Bool))
--   </pre>
--   
--   See <a>Post</a> for more information.
newtype PostT t f a
PostT :: t (Post a f) a -> PostT t f a
[unPostT] :: PostT t f a -> t (Post a f) a

-- | Run a <tt><a>PostT</a> t</tt> into a covariant <a>Plus</a> context. To
--   run it in <tt>t</tt>s normal contravariant context, use
--   <a>interpret</a>.
--   
--   This will work for types where there are a possibly-empty collection
--   of <tt>f</tt>s, like:
--   
--   <pre>
--   postPlusT :: Plus g =&gt; (f ~&gt; g) -&gt; PreT <tt>Dec</tt> f ~&gt; g
--   postPlusT :: Plus g =&gt; (f ~&gt; g) -&gt; PreT <tt>Div</tt> f ~&gt; g
--   </pre>
postPlusT :: (forall m. Monoid m => Interpret t (AltConst m), Plus g) => (f ~> g) -> PostT t f ~> g

-- | Run a <tt><a>PostT</a> t</tt> into a covariant <a>Alt</a> context. To
--   run it in <tt>t</tt>s normal contravariant context, use
--   <a>interpret</a>.
--   
--   This will work for types where there is a non-empty collection of
--   <tt>f</tt>s, like:
--   
--   <pre>
--   postAltT :: Alt g =&gt; (f ~&gt; g) -&gt; PreT <tt>Dec1</tt> f ~&gt; g
--   postAltT :: Alt g =&gt; (f ~&gt; g) -&gt; PreT <tt>Div1</tt> f ~&gt; g
--   </pre>
postAltT :: (forall m. Semigroup m => Interpret t (AltConst m), Alt g) => (f ~> g) -> PostT t f ~> g

-- | Run a <tt><a>PostT</a> t</tt> into a covariant <a>Functor</a> context.
--   To run it in <tt>t</tt>s normal contravariant context, use
--   <a>interpret</a>.
--   
--   This will work for types where there is exactly one <tt>f</tt> inside:
--   
--   <pre>
--   postFunctorT :: Functor g =&gt; (f ~&gt; g) -&gt; PreT <tt>Step</tt> f ~&gt; g
--   postFunctorT :: Functor g =&gt; (f ~&gt; g) -&gt; PreT <a>Coyoneda</a> f ~&gt; g
--   </pre>
postFunctorT :: (forall m. Interpret t (AltConst m), Functor g) => (f ~> g) -> PostT t f ~> g
instance GHC.Base.Functor f => GHC.Base.Functor (Data.HFunctor.Route.Pre a f)
instance GHC.Base.Functor (t (Data.HFunctor.Route.Pre a f)) => GHC.Base.Functor (Data.HFunctor.Route.ProPre t f a)
instance Data.Functor.Bind.Class.Apply (t (Data.HFunctor.Route.Pre a f)) => Data.Functor.Bind.Class.Apply (Data.HFunctor.Route.ProPre t f a)
instance GHC.Base.Applicative (t (Data.HFunctor.Route.Pre a f)) => GHC.Base.Applicative (Data.HFunctor.Route.ProPre t f a)
instance GHC.Base.Monad (t (Data.HFunctor.Route.Pre a f)) => GHC.Base.Monad (Data.HFunctor.Route.ProPre t f a)
instance Data.Functor.Contravariant.Contravariant (t (Data.HFunctor.Route.Pre a f)) => Data.Functor.Contravariant.Contravariant (Data.HFunctor.Route.ProPre t f a)
instance Data.Functor.Contravariant.Divisible.Divisible (t (Data.HFunctor.Route.Pre a f)) => Data.Functor.Contravariant.Divisible.Divisible (Data.HFunctor.Route.ProPre t f a)
instance Data.Functor.Contravariant.Divise.Divise (t (Data.HFunctor.Route.Pre a f)) => Data.Functor.Contravariant.Divise.Divise (Data.HFunctor.Route.ProPre t f a)
instance Data.Functor.Contravariant.Decide.Decide (t (Data.HFunctor.Route.Pre a f)) => Data.Functor.Contravariant.Decide.Decide (Data.HFunctor.Route.ProPre t f a)
instance Data.Functor.Contravariant.Conclude.Conclude (t (Data.HFunctor.Route.Pre a f)) => Data.Functor.Contravariant.Conclude.Conclude (Data.HFunctor.Route.ProPre t f a)
instance Data.Functor.Contravariant.Divisible.Decidable (t (Data.HFunctor.Route.Pre a f)) => Data.Functor.Contravariant.Divisible.Decidable (Data.HFunctor.Route.ProPre t f a)
instance Data.Functor.Plus.Plus (t (Data.HFunctor.Route.Pre a f)) => Data.Functor.Plus.Plus (Data.HFunctor.Route.ProPre t f a)
instance Data.Functor.Invariant.Invariant (t (Data.HFunctor.Route.Pre a f)) => Data.Functor.Invariant.Invariant (Data.HFunctor.Route.ProPre t f a)
instance Data.Functor.Invariant.Inplicative.Inply (t (Data.HFunctor.Route.Pre a f)) => Data.Functor.Invariant.Inplicative.Inply (Data.HFunctor.Route.ProPre t f a)
instance Data.Functor.Invariant.Inplicative.Inplicative (t (Data.HFunctor.Route.Pre a f)) => Data.Functor.Invariant.Inplicative.Inplicative (Data.HFunctor.Route.ProPre t f a)
instance Data.Functor.Invariant.Internative.Inalt (t (Data.HFunctor.Route.Pre a f)) => Data.Functor.Invariant.Internative.Inalt (Data.HFunctor.Route.ProPre t f a)
instance Data.Functor.Invariant.Internative.Inplus (t (Data.HFunctor.Route.Pre a f)) => Data.Functor.Invariant.Internative.Inplus (Data.HFunctor.Route.ProPre t f a)
instance Data.Functor.Invariant.Internative.Internative (t (Data.HFunctor.Route.Pre a f)) => Data.Functor.Invariant.Internative.Internative (Data.HFunctor.Route.ProPre t f a)
instance forall k (t :: (* -> *) -> k -> *) a (f :: * -> *) (b :: k). GHC.Base.Semigroup (t (Data.HFunctor.Route.Pre a f) b) => GHC.Base.Semigroup (Data.HFunctor.Route.ProPre t f a b)
instance forall k (t :: (* -> *) -> k -> *) a (f :: * -> *) (b :: k). GHC.Base.Monoid (t (Data.HFunctor.Route.Pre a f) b) => GHC.Base.Monoid (Data.HFunctor.Route.ProPre t f a b)
instance forall k (t :: (* -> *) -> k -> *) a (f :: * -> *) (b :: k). GHC.Show.Show (t (Data.HFunctor.Route.Pre a f) b) => GHC.Show.Show (Data.HFunctor.Route.ProPre t f a b)
instance forall k (t :: (* -> *) -> k -> *) a (f :: * -> *) (b :: k). GHC.Classes.Eq (t (Data.HFunctor.Route.Pre a f) b) => GHC.Classes.Eq (Data.HFunctor.Route.ProPre t f a b)
instance forall k (t :: (* -> *) -> k -> *) a (f :: * -> *) (b :: k). GHC.Classes.Ord (t (Data.HFunctor.Route.Pre a f) b) => GHC.Classes.Ord (Data.HFunctor.Route.ProPre t f a b)
instance (Data.HFunctor.Internal.HFunctor t, forall x. Data.Functor.Contravariant.Contravariant (t (Data.HFunctor.Route.Post x f))) => Data.Profunctor.Unsafe.Profunctor (Data.HFunctor.Route.ProPost t f)
instance (Data.HFunctor.Internal.HFunctor t, Data.Functor.Contravariant.Contravariant (t (Data.HFunctor.Route.Post a f))) => GHC.Base.Functor (Data.HFunctor.Route.ProPost t f a)
instance (Data.HFunctor.Internal.HFunctor t, Data.Functor.Contravariant.Contravariant (t (Data.HFunctor.Route.Post a f))) => Data.Functor.Invariant.Invariant (Data.HFunctor.Route.ProPost t f a)
instance (Data.HFunctor.Internal.HFunctor t, forall x. GHC.Base.Functor (t (Data.HFunctor.Route.Pre x f))) => Data.Profunctor.Unsafe.Profunctor (Data.HFunctor.Route.ProPre t f)
instance Data.Functor.Bind.Class.Bind (t (Data.HFunctor.Route.Pre a f)) => Data.Functor.Bind.Class.Bind (Data.HFunctor.Route.ProPre t f a)
instance Data.Functor.Alt.Alt (t (Data.HFunctor.Route.Pre a f)) => Data.Functor.Alt.Alt (Data.HFunctor.Route.ProPre t f a)
instance (Data.HFunctor.Internal.HFunctor t, forall x. Data.Functor.Contravariant.Contravariant (t (Data.HFunctor.Route.Post x f))) => Data.Functor.Invariant.Invariant (Data.HFunctor.Route.PostT t f)
instance Data.HFunctor.Internal.HFunctor t => Data.HFunctor.Internal.HFunctor (Data.HFunctor.Route.PostT t)
instance Data.HFunctor.Inject t => Data.HFunctor.Inject (Data.HFunctor.Route.PostT t)
instance Data.HFunctor.HTraversable.HTraversable t => Data.HFunctor.HTraversable.HTraversable (Data.HFunctor.Route.PostT t)
instance Data.HFunctor.Interpret.Interpret t f => Data.HFunctor.Interpret.Interpret (Data.HFunctor.Route.PostT t) f
instance (Data.HFunctor.Internal.HFunctor t, forall x. GHC.Base.Functor (t (Data.HFunctor.Route.Pre x f))) => Data.Functor.Invariant.Invariant (Data.HFunctor.Route.PreT t f)
instance Data.HFunctor.Internal.HFunctor t => Data.HFunctor.Internal.HFunctor (Data.HFunctor.Route.PreT t)
instance Data.HFunctor.Inject t => Data.HFunctor.Inject (Data.HFunctor.Route.PreT t)
instance Data.HFunctor.HTraversable.HTraversable t => Data.HFunctor.HTraversable.HTraversable (Data.HFunctor.Route.PreT t)
instance Data.HFunctor.Interpret.Interpret t f => Data.HFunctor.Interpret.Interpret (Data.HFunctor.Route.PreT t) f
instance Data.Functor.Contravariant.Contravariant f => Data.Functor.Contravariant.Contravariant (Data.HFunctor.Route.Post a f)
instance GHC.Base.Functor f => Data.Functor.Invariant.Invariant (Data.HFunctor.Route.Post a f)
instance Data.HFunctor.Internal.HFunctor (Data.HFunctor.Route.Post a)
instance Data.HFunctor.HTraversable.HTraversable (Data.HFunctor.Route.Post a)
instance GHC.Base.Monoid a => Data.HFunctor.Inject (Data.HFunctor.Route.Post a)
instance GHC.Base.Monoid a => Data.HFunctor.HBind (Data.HFunctor.Route.Post a)
instance GHC.Base.Monoid a => Data.HFunctor.Interpret.Interpret (Data.HFunctor.Route.Post a) f
instance Data.Functor.Contravariant.Contravariant f => Data.Functor.Invariant.Invariant (Data.HFunctor.Route.Pre a f)
instance Data.HFunctor.Internal.HFunctor (Data.HFunctor.Route.Pre a)
instance Data.HFunctor.HTraversable.HTraversable (Data.HFunctor.Route.Pre a)
instance (a GHC.Types.~ Data.Void.Void) => Data.HFunctor.Inject (Data.HFunctor.Route.Pre a)
instance (a GHC.Types.~ Data.Void.Void) => Data.HFunctor.HBind (Data.HFunctor.Route.Pre a)
instance (a GHC.Types.~ Data.Void.Void) => Data.HFunctor.Interpret.Interpret (Data.HFunctor.Route.Pre a) f