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


-- | Selective applicative functors
--   
--   Selective applicative functors: declare your effects statically,
--   select which to execute dynamically.
--   
--   This is a library for <i>selective applicative functors</i>, or just
--   <i>selective functors</i> for short, an abstraction between
--   applicative functors and monads, introduced in <a>this paper</a>.
@package selective
@version 0.7


-- | This is a library for <i>selective applicative functors</i>, or just
--   <i>selective functors</i> for short, an abstraction between
--   applicative functors and monads, introduced in this paper:
--   <a>https://www.staff.ncl.ac.uk/andrey.mokhov/selective-functors.pdf</a>.
module Control.Selective

-- | Selective applicative functors. You can think of <a>select</a> as a
--   selective function application: when given a value of type <a>Left</a>
--   <tt>a</tt>, you <b>must apply</b> the given function, but when given a
--   <a>Right</a> <tt>b</tt>, you <b>may skip</b> the function and
--   associated effects, and simply return the <tt>b</tt>.
--   
--   Note that it is not a requirement for selective functors to skip
--   unnecessary effects. It may be counterintuitive, but this makes them
--   more useful. Why? Typically, when executing a selective computation,
--   you would want to skip the effects (saving work); but on the other
--   hand, if your goal is to statically analyse a given selective
--   computation and extract the set of all possible effects (without
--   actually executing them), then you do not want to skip any effects,
--   because that defeats the purpose of static analysis.
--   
--   The type signature of <a>select</a> is reminiscent of both
--   <a>&lt;*&gt;</a> and <a>&gt;&gt;=</a>, and indeed a selective functor
--   is in some sense a composition of an applicative functor and the
--   <a>Either</a> monad.
--   
--   Laws:
--   
--   <ul>
--   <li>Identity:</li>
--   </ul>
--   
--   <pre>
--   x &lt;*? pure id = either id id &lt;$&gt; x
--   </pre>
--   
--   <ul>
--   <li>Distributivity; note that <tt>y</tt> and <tt>z</tt> have the same
--   type <tt>f (a -&gt; b)</tt>:</li>
--   </ul>
--   
--   <pre>
--   pure x &lt;*? (y *&gt; z) = (pure x &lt;*? y) *&gt; (pure x &lt;*? z)
--   </pre>
--   
--   <ul>
--   <li>Associativity:</li>
--   </ul>
--   
--   <pre>
--   x &lt;*? (y &lt;*? z) = (f &lt;$&gt; x) &lt;*? (g &lt;$&gt; y) &lt;*? (h &lt;$&gt; z)
--     where
--       f x = Right &lt;$&gt; x
--       g y = a -&gt; bimap (,a) ($a) y
--       h z = uncurry z
--   </pre>
--   
--   <ul>
--   <li>Monadic <a>select</a> (for selective functors that are also
--   monads):</li>
--   </ul>
--   
--   <pre>
--   select = selectM
--   </pre>
--   
--   There are also a few useful theorems:
--   
--   <ul>
--   <li>Apply a pure function to the result:</li>
--   </ul>
--   
--   <pre>
--   f &lt;$&gt; select x y = select (fmap f &lt;$&gt; x) (fmap f &lt;$&gt; y)
--   </pre>
--   
--   <ul>
--   <li>Apply a pure function to the <tt>Left</tt> case of the first
--   argument:</li>
--   </ul>
--   
--   <pre>
--   select (first f &lt;$&gt; x) y = select x ((. f) &lt;$&gt; y)
--   </pre>
--   
--   <ul>
--   <li>Apply a pure function to the second argument:</li>
--   </ul>
--   
--   <pre>
--   select x (f &lt;$&gt; y) = select (first (flip f) &lt;$&gt; x) ((&amp;) &lt;$&gt; y)
--   </pre>
--   
--   <ul>
--   <li>Generalised identity:</li>
--   </ul>
--   
--   <pre>
--   x &lt;*? pure y = either y id &lt;$&gt; x
--   </pre>
--   
--   <ul>
--   <li>A selective functor is <i>rigid</i> if it satisfies
--   <a>&lt;*&gt;</a> <tt>=</tt> <a>apS</a>. The following
--   <i>interchange</i> law holds for rigid selective functors:</li>
--   </ul>
--   
--   <pre>
--   x *&gt; (y &lt;*? z) = (x *&gt; y) &lt;*? z
--   </pre>
--   
--   If f is also a <a>Monad</a>, we require that <a>select</a> =
--   <a>selectM</a>, from which one can prove <a>&lt;*&gt;</a> <tt>=</tt>
--   <a>apS</a>.
class Applicative f => Selective f
select :: Selective f => f (Either a b) -> f (a -> b) -> f b

-- | An operator alias for <a>select</a>, which is sometimes convenient. It
--   tries to follow the notational convention for <a>Applicative</a>
--   operators. The angle bracket pointing to the left means we always use
--   the corresponding value. The value on the right, however, may be
--   skipped, hence the question mark.
(<*?) :: Selective f => f (Either a b) -> f (a -> b) -> f b
infixl 4 <*?

-- | The <a>branch</a> function is a natural generalisation of
--   <a>select</a>: instead of skipping an unnecessary effect, it chooses
--   which of the two given effectful functions to apply to a given
--   argument; the other effect is unnecessary. It is possible to implement
--   <a>branch</a> in terms of <a>select</a>, which is a good puzzle (give
--   it a try!).
--   
--   We can also implement <a>select</a> via <a>branch</a>:
--   
--   <pre>
--   selectB :: Selective f =&gt; f (Either a b) -&gt; f (a -&gt; b) -&gt; f b
--   selectB x y = branch x y (pure id)
--   </pre>
branch :: Selective f => f (Either a b) -> f (a -> c) -> f (b -> c) -> f c

-- | We can write a function with the type signature of <a>select</a> using
--   the <a>Applicative</a> type class, but it will always execute the
--   effects associated with the second argument, hence being potentially
--   less efficient.
selectA :: Applicative f => f (Either a b) -> f (a -> b) -> f b

-- | For traversable functors, we can implement <a>select</a> in another
--   interesting way: the effects associated with the second argument can
--   be skipped as long as the first argument contains only <a>Right</a>
--   values.
selectT :: Traversable f => f (Either a b) -> f (a -> b) -> f b

-- | Recover the application operator <a>&lt;*&gt;</a> from <a>select</a>.
--   <i>Rigid</i> selective functors satisfy the law <a>&lt;*&gt;</a>
--   <tt>=</tt> <a>apS</a> and furthermore, the resulting applicative
--   functor satisfies all laws of <a>Applicative</a>:
--   
--   <ul>
--   <li>Identity:<pre>pure id &lt;*&gt; v = v</pre></li>
--   <li>Homomorphism:<pre>pure f &lt;*&gt; pure x = pure (f x)</pre></li>
--   <li>Interchange:<pre>u &lt;*&gt; pure y = pure ($y) &lt;*&gt;
--   u</pre></li>
--   <li>Composition:<pre>(.) &lt;$&gt; u &lt;*&gt; v &lt;*&gt; w = u
--   &lt;*&gt; (v &lt;*&gt; w)</pre></li>
--   </ul>
apS :: Selective f => f (a -> b) -> f a -> f b

-- | One can easily implement a monadic <a>selectM</a> that satisfies the
--   laws, hence any <a>Monad</a> is <a>Selective</a>.
selectM :: Monad f => f (Either a b) -> f (a -> b) -> f b

-- | Branch on a Boolean value, skipping unnecessary effects.
ifS :: Selective f => f Bool -> f a -> f a -> f a

-- | Conditionally perform an effect.
whenS :: Selective f => f Bool -> f () -> f ()

-- | A lifted version of <a>fromMaybe</a>.
fromMaybeS :: Selective f => f a -> f (Maybe a) -> f a

-- | Return the first <tt>Right</tt> value. If both are <tt>Left</tt>'s,
--   accumulate errors.
orElse :: (Selective f, Semigroup e) => f (Either e a) -> f (Either e a) -> f (Either e a)

-- | Accumulate the <tt>Right</tt> values, or return the first
--   <tt>Left</tt>.
andAlso :: (Selective f, Semigroup a) => f (Either e a) -> f (Either e a) -> f (Either e a)

-- | Keep running an effectful computation until it returns a
--   <tt>Right</tt> value, collecting the <tt>Left</tt>'s using a supplied
--   <tt>Monoid</tt> instance.
untilRight :: (Monoid a, Selective f) => f (Either a b) -> f (a, b)

-- | Keep checking an effectful condition while it holds.
whileS :: Selective f => f Bool -> f ()

-- | A lifted version of lazy Boolean OR.
(<||>) :: Selective f => f Bool -> f Bool -> f Bool

-- | A lifted version of lazy Boolean AND.
(<&&>) :: Selective f => f Bool -> f Bool -> f Bool

-- | Generalised folding with the short-circuiting behaviour.
foldS :: (Selective f, Foldable t, Monoid a) => t (f (Either e a)) -> f (Either e a)

-- | A lifted version of <a>any</a>. Retains the short-circuiting
--   behaviour.
anyS :: Selective f => (a -> f Bool) -> [a] -> f Bool

-- | A lifted version of <a>all</a>. Retains the short-circuiting
--   behaviour.
allS :: Selective f => (a -> f Bool) -> [a] -> f Bool

-- | A restricted version of monadic bind. Fails with an error if the
--   <a>Bounded</a> and <a>Enum</a> instances for <tt>a</tt> do not cover
--   all values of <tt>a</tt>.
bindS :: (Bounded a, Enum a, Eq a, Selective f) => f a -> (a -> f b) -> f b

-- | A list of values, equipped with a fast membership test.
data Cases a

-- | The list of all possible values of an enumerable data type.
casesEnum :: (Bounded a, Enum a) => Cases a

-- | Embed a list of values into <a>Cases</a> using the trivial but slow
--   membership test based on <a>elem</a>.
cases :: Eq a => [a] -> Cases a

-- | Eliminate all specified values <tt>a</tt> from <tt>f (Either a b)</tt>
--   by replacing each of them with a given <tt>f a</tt>.
matchS :: (Eq a, Selective f) => Cases a -> f a -> (a -> f b) -> f (Either a b)

-- | Eliminate all specified values <tt>a</tt> from <tt>f (Either a b)</tt>
--   by replacing each of them with a given <tt>f a</tt>.
matchM :: Monad m => Cases a -> m a -> (a -> m b) -> m (Either a b)

-- | Any applicative functor can be given a <a>Selective</a> instance by
--   defining <a>select</a> <tt>=</tt> <a>selectA</a>. This data type
--   captures this pattern, so you can use it in combination with the
--   <tt>DerivingVia</tt> extension as follows:
--   
--   <pre>
--   newtype Over m a = Over m
--       deriving (Functor, Applicative, Selective) via SelectA (Const m)
--   </pre>
newtype SelectA f a
SelectA :: f a -> SelectA f a
[getSelectA] :: SelectA f a -> f a

-- | Any monad can be given a <a>Selective</a> instance by defining
--   <a>select</a> <tt>=</tt> <a>selectM</a>. This data type captures this
--   pattern, so you can use it in combination with the
--   <tt>DerivingVia</tt> extension as follows:
--   
--   <pre>
--   newtype V1 a = V1 a
--       deriving (Functor, Applicative, Selective, Monad) via SelectM Identity
--   </pre>
newtype SelectM f a
SelectM :: f a -> SelectM f a
[getSelectM] :: SelectM f a -> f a

-- | Static analysis of selective functors with over-approximation.
newtype Over m a
Over :: m -> Over m a
[getOver] :: Over m a -> m

-- | Static analysis of selective functors with under-approximation.
newtype Under m a
Under :: m -> Under m a
[getUnder] :: Under m a -> m

-- | Selective instance for the standard applicative functor Validation.
--   This is a good example of a non-trivial selective functor which is not
--   a monad.
data Validation e a
Failure :: e -> Validation e a
Success :: a -> Validation e a

-- | Swap <tt>Left</tt> and <tt>Right</tt>.
swapEither :: Either a b -> Either b a

-- | Composition of a selective functor <tt>f</tt> with the <a>Either</a>
--   monad.
newtype ComposeEither f e a
ComposeEither :: f (Either e a) -> ComposeEither f e a

-- | Composition of a selective functor <tt>f</tt> and an applicative
--   traversable functor <tt>g</tt>.
newtype ComposeTraversable f g a
ComposeTraversable :: f (g a) -> ComposeTraversable f g a
instance GHC.Base.Applicative f => GHC.Base.Applicative (Control.Selective.SelectA f)
instance GHC.Base.Functor f => GHC.Base.Functor (Control.Selective.SelectA f)
instance GHC.Base.Monad f => GHC.Base.Monad (Control.Selective.SelectM f)
instance GHC.Base.Applicative f => GHC.Base.Applicative (Control.Selective.SelectM f)
instance GHC.Base.Functor f => GHC.Base.Functor (Control.Selective.SelectM f)
instance GHC.Base.Monoid m => GHC.Base.Applicative (Control.Selective.Over m)
instance GHC.Show.Show m => GHC.Show.Show (Control.Selective.Over m a)
instance GHC.Classes.Ord m => GHC.Classes.Ord (Control.Selective.Over m a)
instance GHC.Base.Functor (Control.Selective.Over m)
instance GHC.Classes.Eq m => GHC.Classes.Eq (Control.Selective.Over m a)
instance GHC.Base.Monoid m => GHC.Base.Applicative (Control.Selective.Under m)
instance Data.Traversable.Traversable (Control.Selective.Under m)
instance Data.Foldable.Foldable (Control.Selective.Under m)
instance GHC.Show.Show m => GHC.Show.Show (Control.Selective.Under m a)
instance GHC.Classes.Ord m => GHC.Classes.Ord (Control.Selective.Under m a)
instance GHC.Base.Functor (Control.Selective.Under m)
instance GHC.Classes.Eq m => GHC.Classes.Eq (Control.Selective.Under m a)
instance (GHC.Show.Show e, GHC.Show.Show a) => GHC.Show.Show (Control.Selective.Validation e a)
instance (GHC.Classes.Ord e, GHC.Classes.Ord a) => GHC.Classes.Ord (Control.Selective.Validation e a)
instance GHC.Base.Functor (Control.Selective.Validation e)
instance (GHC.Classes.Eq e, GHC.Classes.Eq a) => GHC.Classes.Eq (Control.Selective.Validation e a)
instance (GHC.Base.Applicative f, GHC.Base.Applicative g) => GHC.Base.Applicative (Control.Selective.ComposeTraversable f g)
instance (GHC.Base.Functor f, GHC.Base.Functor g) => GHC.Base.Functor (Control.Selective.ComposeTraversable f g)
instance Control.Selective.Selective f => Control.Selective.Selective (Control.Selective.ComposeEither f e)
instance GHC.Base.Functor f => GHC.Base.Functor (Control.Selective.ComposeEither f e)
instance Control.Selective.Selective f => GHC.Base.Applicative (Control.Selective.ComposeEither f e)
instance (Control.Selective.Selective f, GHC.Base.Monoid e) => GHC.Base.Alternative (Control.Selective.ComposeEither f e)
instance (Control.Selective.Selective f, GHC.Base.Applicative g, Data.Traversable.Traversable g) => Control.Selective.Selective (Control.Selective.ComposeTraversable f g)
instance GHC.Base.Semigroup e => GHC.Base.Applicative (Control.Selective.Validation e)
instance GHC.Base.Semigroup e => Control.Selective.Selective (Control.Selective.Validation e)
instance GHC.Base.Monoid m => Control.Selective.Selective (Control.Selective.Under m)
instance GHC.Base.Monoid m => Control.Selective.Selective (Control.Selective.Over m)
instance GHC.Base.Monad f => Control.Selective.Selective (Control.Selective.SelectM f)
instance GHC.Base.Applicative f => Control.Selective.Selective (Control.Selective.SelectA f)
instance Control.Selective.Selective f => Control.Selective.Selective (Control.Applicative.Lift.Lift f)
instance Control.Selective.Selective Control.Applicative.ZipList
instance (Control.Selective.Selective f, Control.Selective.Selective g) => Control.Selective.Selective (Data.Functor.Product.Product f g)
instance Control.Selective.Selective f => Control.Selective.Selective (Control.Monad.Trans.Identity.IdentityT f)
instance Control.Selective.Selective f => Control.Selective.Selective (Control.Monad.Trans.Reader.ReaderT env f)
instance (GHC.Base.Monoid w, Control.Selective.Selective f) => Control.Selective.Selective (Control.Monad.Trans.Writer.Lazy.WriterT w f)
instance (GHC.Base.Monoid w, Control.Selective.Selective f) => Control.Selective.Selective (Control.Monad.Trans.Writer.Strict.WriterT w f)
instance (GHC.Base.Applicative f, Control.Selective.Selective g) => Control.Selective.Selective (Data.Functor.Compose.Compose f g)
instance Control.Selective.Selective GHC.Types.IO
instance Control.Selective.Selective []
instance GHC.Base.Monoid a => Control.Selective.Selective ((,) a)
instance Control.Selective.Selective ((->) a)
instance Control.Selective.Selective (Data.Either.Either e)
instance Control.Selective.Selective Data.Functor.Identity.Identity
instance Control.Selective.Selective GHC.Maybe.Maybe
instance Control.Selective.Selective GHC.Base.NonEmpty
instance Control.Selective.Selective Data.Proxy.Proxy
instance Control.Selective.Selective (GHC.ST.ST s)
instance Control.Selective.Selective GHC.Conc.Sync.STM
instance Control.Selective.Selective (Control.Monad.Trans.Cont.ContT r m)
instance GHC.Base.Monad m => Control.Selective.Selective (Control.Monad.Trans.Maybe.MaybeT m)
instance (GHC.Base.Monoid w, GHC.Base.Monad m) => Control.Selective.Selective (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance (GHC.Base.Monoid w, GHC.Base.Monad m) => Control.Selective.Selective (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance GHC.Base.Monad m => Control.Selective.Selective (Control.Monad.Trans.State.Lazy.StateT s m)
instance GHC.Base.Monad m => Control.Selective.Selective (Control.Monad.Trans.State.Strict.StateT s m)
instance Control.Arrow.ArrowChoice a => Control.Selective.Selective (Control.Arrow.ArrowMonad a)


-- | This is a library for <i>selective applicative functors</i>, or just
--   <i>selective functors</i> for short, an abstraction between
--   applicative functors and monads, introduced in this paper:
--   <a>https://www.staff.ncl.ac.uk/andrey.mokhov/selective-functors.pdf</a>.
--   
--   This module defines <i>free selective functors</i> using the ideas
--   from the Sjoerd Visscher's package 'free-functors':
--   <a>https://hackage.haskell.org/package/free-functors-1.0.1/docs/Data-Functor-HFree.html</a>.
module Control.Selective.Free

-- | Free selective functors.
newtype Select f a
Select :: (forall g. Selective g => (forall x. f x -> g x) -> g a) -> Select f a

-- | Lift a functor into a free selective computation.
liftSelect :: f a -> Select f a

-- | Extract the resulting value if there are no necessary effects.
getPure :: Select f a -> Maybe a

-- | Collect <i>all possible effects</i> in the order they appear in a free
--   selective computation.
getEffects :: Functor f => Select f a -> [f ()]

-- | Extract <i>all necessary effects</i> in the order they appear in a
--   free selective computation.
getNecessaryEffects :: Functor f => Select f a -> [f ()]

-- | Given a natural transformation from <tt>f</tt> to <tt>g</tt>, this
--   gives a canonical natural transformation from <tt>Select f</tt> to
--   <tt>g</tt>. Note that here we rely on the fact that <tt>g</tt> is a
--   lawful selective functor.
runSelect :: Selective g => (forall x. f x -> g x) -> Select f a -> g a

-- | Concatenate all effects of a free selective computation.
foldSelect :: Monoid m => (forall x. f x -> m) -> Select f a -> m
instance GHC.Base.Functor (Control.Selective.Free.Select f)
instance GHC.Base.Applicative (Control.Selective.Free.Select f)
instance Control.Selective.Selective (Control.Selective.Free.Select f)


-- | This is a library for <i>selective applicative functors</i>, or just
--   <i>selective functors</i> for short, an abstraction between
--   applicative functors and monads, introduced in this paper:
--   <a>https://www.staff.ncl.ac.uk/andrey.mokhov/selective-functors.pdf</a>.
--   
--   This module defines <i>multi-way selective functors</i>, which are
--   more efficient when selecting from a large number of options. They
--   also fully subsume the <a>Applicative</a> type class because they
--   allow to express the notion of independet effects.
--   
--   This definition is inspired by the following construction by Daniel
--   Peebles, with the main difference being the added <tt>Enumerable</tt>
--   constraint:
--   <a>https://gist.github.com/copumpkin/d5bdbc7afda54ff04049b6bdbcffb67e</a>
module Control.Selective.Multi

-- | A generalised sum type where <tt>t</tt> stands for the type of
--   constructor "tags". Each tag has a type parameter <tt>x</tt> which
--   determines the type of the payload. A <a>Sigma</a> <tt>t</tt> value
--   therefore contains a payload whose type is not visible externally but
--   is revealed when pattern-matching on the tag.
--   
--   See <a>Two</a>, <a>eitherToSigma</a> and <a>sigmaToEither</a> for an
--   example.
data Sigma t
[Sigma] :: t x -> x -> Sigma t

-- | An injection into a generalised sum. An alias for <a>Sigma</a>.
inject :: t x -> x -> Sigma t

-- | A data type defining no tags. Similar to <a>Void</a> but
--   parameterised.
data Zero a

-- | A data type with a single tag. This data type is commonly known as
--   <tt>Refl</tt>, see <a>Data.Type.Equality</a>.
data One a b
[One] :: One a a

-- | A data type with two tags <a>A</a> and <a>B</a> that allows us to
--   encode the good old <a>Either</a> as <a>Sigma</a> <a>Two</a>, where
--   the tags <a>A</a> and <a>B</a> correspond to <a>Left</a> and
--   <a>Right</a>, respectively. See <a>eitherToSigma</a> and
--   <a>sigmaToEither</a> that witness the isomorphism between
--   <a>Either</a> <tt>a b</tt> and <a>Sigma</a> <tt>(</tt><a>Two</a><tt> a
--   b)</tt>.
data Two a b c
[A] :: Two a b a
[B] :: Two a b b

-- | A potentially uncountable collection of tags for the same unit
--   <tt>()</tt> payload.
data Many a b
[Many] :: a -> Many a ()
many :: a -> Sigma (Many a)

-- | Generalised pattern matching on a Sigma type using a Pi type to
--   describe how to handle each case.
--   
--   This is a specialisation of <a>matchCases</a> for <tt>f =
--   Identity</tt>. We could also have also given it the following type:
--   
--   <pre>
--   matchPure :: Sigma t -&gt; (t ~&gt; Case Identity a) -&gt; a
--   </pre>
--   
--   We chose to simplify it by inlining <a>~&gt;</a>, <a>Case</a> and
--   <a>Identity</a>.
matchPure :: Sigma t -> (forall x. t x -> x -> a) -> a

-- | Encode <a>Either</a> into a generalised sum type.
eitherToSigma :: Either a b -> Sigma (Two a b)

-- | Decode <a>Either</a> from a generalised sum type.
sigmaToEither :: Sigma (Two a b) -> Either a b

-- | Hide the type of the payload a tag.
--   
--   There is a whole library dedicated to this nice little GADT:
--   <a>http://hackage.haskell.org/package/some</a>.
data Some t
[Some] :: t a -> Some t

-- | A class of tags that can be enumerated.
--   
--   A valid instance must list every tag in the resulting list exactly
--   once.
class Enumerable t
enumerate :: Enumerable t => [Some t]

-- | Multi-way selective functors. Given a computation that produces a
--   value of a sum type, we can <a>match</a> it to the corresponding
--   computation in a given product type.
--   
--   For greater similarity with <a>matchCases</a>, we could have given the
--   following type to <a>match</a>:
--   
--   <pre>
--   match :: f (Sigma t) -&gt; (t ~&gt; Case f a) -&gt; f a
--   </pre>
--   
--   We chose to simplify it by inlining <a>~&gt;</a> and <a>Case</a>.
class Applicative f => Selective f
match :: (Selective f, Enumerable t) => f (Sigma t) -> (forall x. t x -> f (x -> a)) -> f a

-- | Static analysis of selective functors with over-approximation.
newtype Over m a
Over :: m -> Over m a
[getOver] :: Over m a -> m

-- | Static analysis of selective functors with under-approximation.
newtype Under m a
Under :: m -> Under m a
[getUnder] :: Under m a -> m

-- | The basic "if-then" selection primitive from <a>Control.Selective</a>.
select :: Selective f => f (Either a b) -> f (a -> b) -> f b

-- | Choose a matching effect with <a>Either</a>.
branch :: Selective f => f (Either a b) -> f (a -> c) -> f (b -> c) -> f c

-- | Recover the application operator <a>&lt;*&gt;</a> from <a>match</a>.
apS :: Selective f => f a -> f (a -> b) -> f b

-- | A restricted version of monadic bind.
bindS :: (Enum a, Selective f) => f a -> (a -> f b) -> f b

-- | An alternative definition of applicative functors, as witnessed by
--   <a>ap</a> and <a>matchOne</a>. This class is almost like
--   <a>Selective</a> but has a strict constraint on <tt>t</tt>.
class Functor f => ApplicativeS f
pureA :: ApplicativeS f => a -> f a
matchOne :: (ApplicativeS f, t ~ One x) => f (Sigma t) -> (forall x. t x -> f (x -> a)) -> f a

-- | Recover the application operator <a>&lt;*&gt;</a> from
--   <a>matchOne</a>.
ap :: ApplicativeS f => f a -> f (a -> b) -> f b

-- | Every <a>Applicative</a> is also an <a>ApplicativeS</a>.
matchA :: (Applicative f, t ~ One x) => f (Sigma t) -> (forall x. t x -> f (x -> a)) -> f a

-- | An alternative definition of monads, as witnessed by <a>bind</a> and
--   <a>matchM</a>. This class is almost like <a>Selective</a> but has no
--   the constraint on <tt>t</tt>.
class Applicative f => MonadS f
matchUnconstrained :: MonadS f => f (Sigma t) -> (forall x. t x -> f (x -> a)) -> f a

-- | Monadic bind.
bind :: MonadS f => f a -> (a -> f b) -> f b

-- | Every monad is a multi-way selective functor.
matchM :: Monad f => f (Sigma t) -> (forall x. t x -> f (x -> a)) -> f a

-- | A generalised product type (Pi), which holds an appropriately tagged
--   payload <tt>u x</tt> for every possible tag <tt>t x</tt>.
--   
--   Note that this looks different than the standard formulation of Pi
--   types. Maybe it's just all wrong!
--   
--   See <a>Two</a>, <a>pairToPi</a> and <a>piToPair</a> for an example.
type (~>) t u = forall x. t x -> u x
infixl 4 ~>

-- | A product type where the payload has the type specified with the tag.
type Pi t = t ~> Identity

-- | A projection from a generalised product.
project :: t a -> Pi t -> a

-- | A trivial product type that stores nothing and simply returns the
--   given tag as the result.
identity :: t ~> t

-- | As it turns out, one can compose such generalised products. Why not:
--   given a tag, get the payload of the first product and then pass it as
--   input to the second. This feels too trivial to be useful but is still
--   somewhat cute.
compose :: (u ~> v) -> (t ~> u) -> t ~> v

-- | Update a generalised sum given a generalised product that takes care
--   of all possible cases.
apply :: (t ~> u) -> Sigma t -> Sigma u

-- | Encode a value into a generalised sum type that has a single tag
--   <a>One</a>.
toSigma :: a -> Sigma (One a)

-- | Decode a value from a generalised sum type that has a single tag
--   <a>One</a>.
fromSigma :: Sigma (One a) -> a

-- | Encode a value into a generalised product type that has a single tag
--   <a>One</a>.
toPi :: a -> Pi (One a)

-- | Decode a value from a generalised product type that has a single tag
--   <a>One</a>.
fromPi :: Pi (One a) -> a

-- | Encode <tt>(a, b)</tt> into a generalised product type.
pairToPi :: (a, b) -> Pi (Two a b)

-- | Decode <tt>(a, b)</tt> from a generalised product type.
piToPair :: Pi (Two a b) -> (a, b)

-- | Handler of a single case in a generalised pattern matching
--   <a>matchCases</a>.
newtype Case f a x
Case :: f (x -> a) -> Case f a x
[handleCase] :: Case f a x -> f (x -> a)

-- | Generalised pattern matching on a Sigma type using a Pi type to
--   describe how to handle each case.
matchCases :: Functor f => Sigma t -> (t ~> Case f a) -> f a
instance GHC.Show.Show m => GHC.Show.Show (Control.Selective.Multi.Over m a)
instance GHC.Classes.Ord m => GHC.Classes.Ord (Control.Selective.Multi.Over m a)
instance GHC.Base.Functor (Control.Selective.Multi.Over m)
instance GHC.Classes.Eq m => GHC.Classes.Eq (Control.Selective.Multi.Over m a)
instance GHC.Show.Show m => GHC.Show.Show (Control.Selective.Multi.Under m a)
instance GHC.Classes.Ord m => GHC.Classes.Ord (Control.Selective.Multi.Under m a)
instance GHC.Base.Functor (Control.Selective.Multi.Under m)
instance GHC.Classes.Eq m => GHC.Classes.Eq (Control.Selective.Multi.Under m a)
instance GHC.Base.Monoid m => GHC.Base.Applicative (Control.Selective.Multi.Under m)
instance GHC.Base.Monoid m => Control.Selective.Multi.Selective (Control.Selective.Multi.Under m)
instance GHC.Base.Monoid m => GHC.Base.Applicative (Control.Selective.Multi.Over m)
instance GHC.Base.Monoid m => Control.Selective.Multi.Selective (Control.Selective.Multi.Over m)
instance Control.Selective.Multi.Enumerable Control.Selective.Multi.Zero
instance Control.Selective.Multi.Enumerable (Control.Selective.Multi.One a)
instance Control.Selective.Multi.Enumerable (Control.Selective.Multi.Two a b)
instance GHC.Enum.Enum a => Control.Selective.Multi.Enumerable (Control.Selective.Multi.Many a)


-- | This is a library for <i>selective applicative functors</i>, or just
--   <i>selective functors</i> for short, an abstraction between
--   applicative functors and monads, introduced in this paper:
--   <a>https://www.staff.ncl.ac.uk/andrey.mokhov/selective-functors.pdf</a>.
--   
--   This module defines a newtype around <a>ExceptT</a> from
--   <tt>transformers</tt> with less restrictive <a>Applicative</a>,
--   <a>Selective</a>, and <a>Alternative</a> implementations. It supplies
--   an <tt>instance <a>Selective</a> f =&gt; <a>Selective</a>
--   (<a>ExceptT</a> e f)</tt>, which makes <a>ExceptT</a> a bona-fide
--   <a>Selective</a> transformer.
--   
--   The API follows the API from the <tt>transformers</tt> package, so it
--   can be used as a drop-in replacement. The documentation can be found
--   in the <a><tt>transformers</tt></a> package.
module Control.Selective.Trans.Except

-- | A newtype wrapper around <a>ExceptT</a> from <tt>transformers</tt>
--   that provides less restrictive <a>Applicative</a>, <a>Selective</a>
--   and <a>Alternative</a> instances.
newtype ExceptT e f a
ExceptT :: ExceptT e f a -> ExceptT e f a
[unwrap] :: ExceptT e f a -> ExceptT e f a

-- | Inject an <a>ExceptT</a> value into the newtype wrapper.
wrap :: ExceptT e m a -> ExceptT e m a
type Except e = ExceptT e Identity
except :: Monad m => Either e a -> ExceptT e m a
runExcept :: Except e a -> Either e a
mapExcept :: (Either e a -> Either e' b) -> Except e a -> Except e' b
withExcept :: (e -> e') -> Except e a -> Except e' a
runExceptT :: ExceptT e m a -> m (Either e a)
mapExceptT :: (m (Either e a) -> n (Either e' b)) -> ExceptT e m a -> ExceptT e' n b
withExceptT :: Functor m => (e -> e') -> ExceptT e m a -> ExceptT e' m a
throwE :: Monad m => e -> ExceptT e m a
catchE :: Monad m => ExceptT e m a -> (e -> ExceptT e' m a) -> ExceptT e' m a
liftCallCC :: CallCC m (Either e a) (Either e b) -> CallCC (ExceptT e m) a b
liftListen :: Monad m => Listen w m (Either e a) -> Listen w (ExceptT e m) a
liftPass :: Monad m => Pass w m (Either e a) -> Pass w (ExceptT e m) a
instance (Control.Selective.Selective f, GHC.Base.Monoid e) => GHC.Base.Alternative (Control.Selective.Trans.Except.ExceptT e f)
instance Control.Selective.Selective f => Control.Selective.Selective (Control.Selective.Trans.Except.ExceptT e f)
instance Control.Selective.Selective f => GHC.Base.Applicative (Control.Selective.Trans.Except.ExceptT e f)
instance (GHC.Show.Show e, Data.Functor.Classes.Show1 f) => Data.Functor.Classes.Show1 (Control.Selective.Trans.Except.ExceptT e f)
instance (GHC.Read.Read e, Data.Functor.Classes.Read1 f) => Data.Functor.Classes.Read1 (Control.Selective.Trans.Except.ExceptT e f)
instance (GHC.Classes.Ord e, Data.Functor.Classes.Ord1 f) => Data.Functor.Classes.Ord1 (Control.Selective.Trans.Except.ExceptT e f)
instance (GHC.Classes.Eq e, Data.Functor.Classes.Eq1 f) => Data.Functor.Classes.Eq1 (Control.Selective.Trans.Except.ExceptT e f)
instance (Control.Selective.Selective f, GHC.Base.Monoid e, GHC.Base.Monad f) => GHC.Base.MonadPlus (Control.Selective.Trans.Except.ExceptT e f)
instance (Control.Selective.Selective f, Control.Monad.IO.Class.MonadIO f) => Control.Monad.IO.Class.MonadIO (Control.Selective.Trans.Except.ExceptT e f)
instance (Control.Selective.Selective f, Control.Monad.Zip.MonadZip f) => Control.Monad.Zip.MonadZip (Control.Selective.Trans.Except.ExceptT e f)
instance (Control.Selective.Selective f, Control.Monad.Fail.MonadFail f) => Control.Monad.Fail.MonadFail (Control.Selective.Trans.Except.ExceptT e f)
instance (Control.Selective.Selective f, Control.Monad.Fix.MonadFix f) => Control.Monad.Fix.MonadFix (Control.Selective.Trans.Except.ExceptT e f)
instance (Data.Functor.Classes.Show1 f, GHC.Show.Show e, GHC.Show.Show a) => GHC.Show.Show (Control.Selective.Trans.Except.ExceptT e f a)
instance (Data.Functor.Classes.Read1 f, GHC.Read.Read e, GHC.Read.Read a) => GHC.Read.Read (Control.Selective.Trans.Except.ExceptT e f a)
instance (Data.Functor.Classes.Ord1 f, GHC.Classes.Ord e, GHC.Classes.Ord a) => GHC.Classes.Ord (Control.Selective.Trans.Except.ExceptT e f a)
instance (Data.Functor.Classes.Eq1 f, GHC.Classes.Eq e, GHC.Classes.Eq a) => GHC.Classes.Eq (Control.Selective.Trans.Except.ExceptT e f a)
instance Data.Functor.Contravariant.Contravariant f => Data.Functor.Contravariant.Contravariant (Control.Selective.Trans.Except.ExceptT e f)
instance (Control.Selective.Selective f, GHC.Base.Monad f) => GHC.Base.Monad (Control.Selective.Trans.Except.ExceptT e f)
instance Data.Traversable.Traversable f => Data.Traversable.Traversable (Control.Selective.Trans.Except.ExceptT e f)
instance Data.Foldable.Foldable f => Data.Foldable.Foldable (Control.Selective.Trans.Except.ExceptT e f)
instance GHC.Base.Functor f => GHC.Base.Functor (Control.Selective.Trans.Except.ExceptT e f)


-- | This is a library for <i>selective applicative functors</i>, or just
--   <i>selective functors</i> for short, an abstraction between
--   applicative functors and monads, introduced in this paper:
--   <a>https://www.staff.ncl.ac.uk/andrey.mokhov/selective-functors.pdf</a>.
--   
--   This module defines <i>freer rigid selective functors</i>. Rigid
--   selective functors are those that satisfy the property <tt>&lt;*&gt; =
--   apS</tt>. Compared to the "free" construction from
--   <a>Control.Selective.Rigid.Free</a>, this "freer" construction does
--   not require the underlying base data type to be a functor.
module Control.Selective.Rigid.Freer

-- | Free rigid selective functors.
data Select f a
[Pure] :: a -> Select f a
[Select] :: Select f (Either (x -> a) a) -> f x -> Select f a

-- | Lift a functor into a free selective computation.
liftSelect :: f a -> Select f a

-- | Extract the resulting value if there are no necessary effects.
getPure :: Select f a -> Maybe a

-- | Collect all possible effects in the order they appear in a free
--   selective computation.
getEffects :: Functor f => Select f a -> [f ()]

-- | Extract the necessary effect from a free selective computation. Note:
--   there can be at most one effect that is statically guaranteed to be
--   necessary.
getNecessaryEffect :: Functor f => Select f a -> Maybe (f ())

-- | Given a natural transformation from <tt>f</tt> to <tt>g</tt>, this
--   gives a canonical natural transformation from <tt>Select f</tt> to
--   <tt>g</tt>.
runSelect :: Selective g => (forall x. f x -> g x) -> Select f a -> g a

-- | Concatenate all effects of a free selective computation.
foldSelect :: Monoid m => (forall x. f x -> m) -> Select f a -> m
instance GHC.Base.Functor (Control.Selective.Rigid.Freer.Select f)
instance GHC.Base.Applicative (Control.Selective.Rigid.Freer.Select f)
instance Control.Selective.Selective (Control.Selective.Rigid.Freer.Select f)


-- | This is a library for <i>selective applicative functors</i>, or just
--   <i>selective functors</i> for short, an abstraction between
--   applicative functors and monads, introduced in this paper:
--   <a>https://www.staff.ncl.ac.uk/andrey.mokhov/selective-functors.pdf</a>.
--   
--   This module defines <i>free rigid selective functors</i>. Rigid
--   selective functors are those that satisfy the property <tt>&lt;*&gt; =
--   apS</tt>.
--   
--   Intuitively, a selective functor <tt>f</tt> is "rigid" if any
--   expression <tt>f a</tt> is equivalent to a list of effects chained
--   with <tt>select</tt> operators (the normal form given by the free
--   construction). In contrast, "non-rigid" selective functors can have
--   non-linear, tree-like shapes, because <tt><a>*</a></tt> nodes can't be
--   straightened using the <tt>&lt;*&gt; = apS</tt> equation.
module Control.Selective.Rigid.Free

-- | Free rigid selective functors.
data Select f a
[Pure] :: a -> Select f a
[Select] :: Select f (Either a b) -> f (a -> b) -> Select f b

-- | Lift a functor into a free selective computation.
liftSelect :: Functor f => f a -> Select f a

-- | Extract the resulting value if there are no necessary effects.
getPure :: Select f a -> Maybe a

-- | Collect all possible effects in the order they appear in a free
--   selective computation.
getEffects :: Functor f => Select f a -> [f ()]

-- | Extract the necessary effect from a free selective computation. Note:
--   there can be at most one effect that is statically guaranteed to be
--   necessary.
getNecessaryEffect :: Functor f => Select f a -> Maybe (f ())

-- | Given a natural transformation from <tt>f</tt> to <tt>g</tt>, this
--   gives a canonical natural transformation from <tt>Select f</tt> to
--   <tt>g</tt>.
runSelect :: Selective g => (forall x. f x -> g x) -> Select f a -> g a

-- | Concatenate all effects of a free selective computation.
foldSelect :: Monoid m => (forall x. f x -> m) -> Select f a -> m
instance GHC.Base.Functor f => GHC.Base.Functor (Control.Selective.Rigid.Free.Select f)
instance GHC.Base.Functor f => GHC.Base.Applicative (Control.Selective.Rigid.Free.Select f)
instance GHC.Base.Functor f => Control.Selective.Selective (Control.Selective.Rigid.Free.Select f)