-- 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.3


-- | 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

-- | 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
instance GHC.Base.Functor f => GHC.Base.Functor (Control.Selective.ComposeEither f e)
instance (GHC.Show.Show e, GHC.Show.Show a) => GHC.Show.Show (Control.Selective.Validation e a)
instance GHC.Base.Functor (Control.Selective.Validation e)
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 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.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.Applicative f => GHC.Base.Applicative (Control.Selective.SelectA f)
instance GHC.Base.Functor f => GHC.Base.Functor (Control.Selective.SelectA f)
instance GHC.Base.Applicative 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 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 => GHC.Base.Applicative (Control.Selective.Under m)
instance GHC.Base.Monoid m => Control.Selective.Selective (Control.Selective.Under m)
instance GHC.Base.Monoid m => GHC.Base.Applicative (Control.Selective.Over 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 (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.Except.ExceptT e m)
instance GHC.Base.Monad m => Control.Selective.Selective (Control.Monad.Trans.Identity.IdentityT m)
instance GHC.Base.Monad m => Control.Selective.Selective (Control.Monad.Trans.Maybe.MaybeT m)
instance GHC.Base.Monad m => Control.Selective.Selective (Control.Monad.Trans.Reader.ReaderT r 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 (GHC.Base.Monoid w, GHC.Base.Monad m) => Control.Selective.Selective (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (GHC.Base.Monoid w, GHC.Base.Monad m) => Control.Selective.Selective (Control.Monad.Trans.Writer.Strict.WriterT w 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>free rigid selective functors</i>. Rigid
--   selective functors are those that satisfy the property <tt>&lt;*&gt; =
--   apS</tt>.
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)


-- | 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)
