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


-- | Haskell98 partial maps and filters over MonadPlus.
--   
--   Filtering and folding over arbitrary <a>MonadPlus</a> instances. This
--   package generalizes many common stream operations such as
--   <a>filter</a>, <a>catMaybes</a> etc.
@package monadplus
@version 1.4.2


-- | Partial maps and filters over <a>Alternative</a> instances.
--   
--   This is considerably weaker than <tt>MonadPlus</tt>, as we have no
--   possibility of removing intermediate structure, as in
--   <tt>mcatMaybes</tt>.
module Control.Applicative.Alternative

-- | The sum of a collection of actions, generalizing <a>concat</a>.
--   
--   asum [Just <a>Hello</a>, Nothing, Just <a>World</a>] Just <a>Hello</a>
asum :: (Foldable t, Alternative f) => t f a -> f a

-- | Fold a value into an arbitrary <tt>MonadPlus</tt> type.
--   
--   This function generalizes the <a>toList</a> function.
afold :: (Alternative f, Foldable t) => t a -> f a

-- | This function generalizes the <tt>listToMaybe</tt> function.
afromList :: Alternative f => [a] -> f a

-- | Translate maybe to an arbitrary <a>Alternative</a> type.
--   
--   This function generalizes the <tt>maybeToList</tt> function.
afromMaybe :: Alternative f => Maybe a -> f a


-- | Partial maps and filters over <a>MonadPlus</a> instances. The basic
--   idea here is that the monad interface together with the monoidal
--   structure of <a>MonadPlus</a> is enough to implement partial maps and
--   filters (i.e. <a>mmapMaybe</a> and <a>mfilter</a>).
--   
--   This is especially useful for sequential structures such as event
--   lists, tracks etc.
--   
--   Inspired by the following blog post:
--   
--   <ul>
--   <li><a>http://conal.net/blog/posts/a-handy-generalized-filter</a></li>
--   </ul>
module Control.Monad.Plus

-- | Conditional failure of <a>Alternative</a> computations. Defined by
--   
--   <pre>
--   guard True  = <a>pure</a> ()
--   guard False = <a>empty</a>
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   Common uses of <a>guard</a> include conditionally signaling an error
--   in an error monad and conditionally rejecting the current choice in an
--   <a>Alternative</a>-based parser.
--   
--   As an example of signaling an error in the error monad <a>Maybe</a>,
--   consider a safe division function <tt>safeDiv x y</tt> that returns
--   <a>Nothing</a> when the denominator <tt>y</tt> is zero and
--   <tt><a>Just</a> (x `div` y)</tt> otherwise. For example:
--   
--   <pre>
--   &gt;&gt;&gt; safeDiv 4 0
--   Nothing
--   &gt;&gt;&gt; safeDiv 4 2
--   Just 2
--   </pre>
--   
--   A definition of <tt>safeDiv</tt> using guards, but not <a>guard</a>:
--   
--   <pre>
--   safeDiv :: Int -&gt; Int -&gt; Maybe Int
--   safeDiv x y | y /= 0    = Just (x `div` y)
--               | otherwise = Nothing
--   </pre>
--   
--   A definition of <tt>safeDiv</tt> using <a>guard</a> and <a>Monad</a>
--   <tt>do</tt>-notation:
--   
--   <pre>
--   safeDiv :: Int -&gt; Int -&gt; Maybe Int
--   safeDiv x y = do
--     guard (y /= 0)
--     return (x `div` y)
--   </pre>
guard :: Alternative f => Bool -> f ()

-- | The <a>join</a> function is the conventional monad join operator. It
--   is used to remove one level of monadic structure, projecting its bound
--   argument into the outer level.
join :: Monad m => m m a -> m a

-- | The <a>Monad</a> class defines the basic operations over a
--   <i>monad</i>, a concept from a branch of mathematics known as
--   <i>category theory</i>. From the perspective of a Haskell programmer,
--   however, it is best to think of a monad as an <i>abstract datatype</i>
--   of actions. Haskell's <tt>do</tt> expressions provide a convenient
--   syntax for writing monadic expressions.
--   
--   Instances of <a>Monad</a> should satisfy the following laws:
--   
--   <ul>
--   <li><pre><a>return</a> a <a>&gt;&gt;=</a> k = k a</pre></li>
--   <li><pre>m <a>&gt;&gt;=</a> <a>return</a> = m</pre></li>
--   <li><pre>m <a>&gt;&gt;=</a> (\x -&gt; k x <a>&gt;&gt;=</a> h) = (m
--   <a>&gt;&gt;=</a> k) <a>&gt;&gt;=</a> h</pre></li>
--   </ul>
--   
--   Furthermore, the <a>Monad</a> and <a>Applicative</a> operations should
--   relate as follows:
--   
--   <ul>
--   <li><pre><a>pure</a> = <a>return</a></pre></li>
--   <li><pre>(<a>&lt;*&gt;</a>) = <a>ap</a></pre></li>
--   </ul>
--   
--   The above laws imply:
--   
--   <ul>
--   <li><pre><a>fmap</a> f xs = xs <a>&gt;&gt;=</a> <a>return</a> .
--   f</pre></li>
--   <li><pre>(<a>&gt;&gt;</a>) = (<a>*&gt;</a>)</pre></li>
--   </ul>
--   
--   and that <a>pure</a> and (<a>&lt;*&gt;</a>) satisfy the applicative
--   functor laws.
--   
--   The instances of <a>Monad</a> for lists, <a>Maybe</a> and <a>IO</a>
--   defined in the <a>Prelude</a> satisfy these laws.
class Applicative m => Monad (m :: * -> *)

-- | Sequentially compose two actions, passing any value produced by the
--   first as an argument to the second.
(>>=) :: Monad m => m a -> a -> m b -> m b

-- | Sequentially compose two actions, discarding any value produced by the
--   first, like sequencing operators (such as the semicolon) in imperative
--   languages.
(>>) :: Monad m => m a -> m b -> m b

-- | Inject a value into the monadic type.
return :: Monad m => a -> m a

-- | Fail with a message. This operation is not part of the mathematical
--   definition of a monad, but is invoked on pattern-match failure in a
--   <tt>do</tt> expression.
--   
--   As part of the MonadFail proposal (MFP), this function is moved to its
--   own class <tt>MonadFail</tt> (see <a>Control.Monad.Fail</a> for more
--   details). The definition here will be removed in a future release.
fail :: Monad m => String -> m a

-- | The <a>Functor</a> class is used for types that can be mapped over.
--   Instances of <a>Functor</a> should satisfy the following laws:
--   
--   <pre>
--   fmap id  ==  id
--   fmap (f . g)  ==  fmap f . fmap g
--   </pre>
--   
--   The instances of <a>Functor</a> for lists, <a>Maybe</a> and <a>IO</a>
--   satisfy these laws.
class Functor (f :: * -> *)
fmap :: Functor f => a -> b -> f a -> f b

-- | Map each element of a structure to a monadic action, evaluate these
--   actions from left to right, and collect the results. For a version
--   that ignores the results see <a>mapM_</a>.
mapM :: (Traversable t, Monad m) => a -> m b -> t a -> m t b

-- | Evaluate each monadic action in the structure from left to right, and
--   collect the results. For a version that ignores the results see
--   <a>sequence_</a>.
sequence :: (Traversable t, Monad m) => t m a -> m t a

-- | Direct <a>MonadPlus</a> equivalent of <tt>filter</tt>
--   <tt><tt>filter</tt></tt> = <tt>(mfilter:: (a -&gt; Bool) -&gt; [a]
--   -&gt; [a]</tt> applicable to any <a>MonadPlus</a>, for example
--   <tt>mfilter odd (Just 1) == Just 1</tt> <tt>mfilter odd (Just 2) ==
--   Nothing</tt>
mfilter :: MonadPlus m => a -> Bool -> m a -> m a

-- | Strict version of <a>&lt;$&gt;</a>.
(<$!>) :: Monad m => a -> b -> m a -> m b
infixl 4 <$!>

-- | The reverse of <a>when</a>.
unless :: Applicative f => Bool -> f () -> f ()

-- | Like <a>replicateM</a>, but discards the result.
replicateM_ :: Applicative m => Int -> m a -> m ()

-- | <tt><a>replicateM</a> n act</tt> performs the action <tt>n</tt> times,
--   gathering the results.
replicateM :: Applicative m => Int -> m a -> m [a]

-- | Like <a>foldM</a>, but discards the result.
foldM_ :: (Foldable t, Monad m) => b -> a -> m b -> b -> t a -> m ()

-- | The <a>foldM</a> function is analogous to <tt>foldl</tt>, except that
--   its result is encapsulated in a monad. Note that <a>foldM</a> works
--   from left-to-right over the list arguments. This could be an issue
--   where <tt>(<a>&gt;&gt;</a>)</tt> and the `folded function' are not
--   commutative.
--   
--   <pre>
--   foldM f a1 [x1, x2, ..., xm]
--   
--   ==
--   
--   do
--     a2 &lt;- f a1 x1
--     a3 &lt;- f a2 x2
--     ...
--     f am xm
--   </pre>
--   
--   If right-to-left evaluation is required, the input list should be
--   reversed.
--   
--   Note: <a>foldM</a> is the same as <a>foldlM</a>
foldM :: (Foldable t, Monad m) => b -> a -> m b -> b -> t a -> m b

-- | <a>zipWithM_</a> is the extension of <a>zipWithM</a> which ignores the
--   final result.
zipWithM_ :: Applicative m => a -> b -> m c -> [a] -> [b] -> m ()

-- | The <a>zipWithM</a> function generalizes <a>zipWith</a> to arbitrary
--   applicative functors.
zipWithM :: Applicative m => a -> b -> m c -> [a] -> [b] -> m [c]

-- | The <a>mapAndUnzipM</a> function maps its first argument over a list,
--   returning the result as a pair of lists. This function is mainly used
--   with complicated data structures or a state-transforming monad.
mapAndUnzipM :: Applicative m => a -> m (b, c) -> [a] -> m ([b], [c])

-- | <tt><a>forever</a> act</tt> repeats the action infinitely.
forever :: Applicative f => f a -> f b

-- | Right-to-left Kleisli composition of monads.
--   <tt>(<a>&gt;=&gt;</a>)</tt>, with the arguments flipped.
--   
--   Note how this operator resembles function composition
--   <tt>(<a>.</a>)</tt>:
--   
--   <pre>
--   (.)   ::            (b -&gt;   c) -&gt; (a -&gt;   b) -&gt; a -&gt;   c
--   (&lt;=&lt;) :: Monad m =&gt; (b -&gt; m c) -&gt; (a -&gt; m b) -&gt; a -&gt; m c
--   </pre>
(<=<) :: Monad m => b -> m c -> a -> m b -> a -> m c
infixr 1 <=<

-- | Left-to-right Kleisli composition of monads.
(>=>) :: Monad m => a -> m b -> b -> m c -> a -> m c
infixr 1 >=>

-- | This generalizes the list-based <tt>filter</tt> function.
filterM :: Applicative m => a -> m Bool -> [a] -> m [a]

-- | <a>forM</a> is <a>mapM</a> with its arguments flipped. For a version
--   that ignores the results see <a>forM_</a>.
forM :: (Traversable t, Monad m) => t a -> a -> m b -> m t b

-- | Evaluate each monadic action in the structure from left to right, and
--   ignore the results. For a version that doesn't ignore the results see
--   <a>sequence</a>.
--   
--   As of base 4.8.0.0, <a>sequence_</a> is just <a>sequenceA_</a>,
--   specialized to <a>Monad</a>.
sequence_ :: (Foldable t, Monad m) => t m a -> m ()

-- | <a>forM_</a> is <a>mapM_</a> with its arguments flipped. For a version
--   that doesn't ignore the results see <a>forM</a>.
--   
--   As of base 4.8.0.0, <a>forM_</a> is just <a>for_</a>, specialized to
--   <a>Monad</a>.
forM_ :: (Foldable t, Monad m) => t a -> a -> m b -> m ()

-- | Map each element of a structure to a monadic action, evaluate these
--   actions from left to right, and ignore the results. For a version that
--   doesn't ignore the results see <a>mapM</a>.
--   
--   As of base 4.8.0.0, <a>mapM_</a> is just <a>traverse_</a>, specialized
--   to <a>Monad</a>.
mapM_ :: (Foldable t, Monad m) => a -> m b -> t a -> m ()

-- | <tt><a>void</a> value</tt> discards or ignores the result of
--   evaluation, such as the return value of an <a>IO</a> action.
--   
--   <h4><b>Examples</b></h4>
--   
--   Replace the contents of a <tt><tt>Maybe</tt> <tt>Int</tt></tt> with
--   unit:
--   
--   <pre>
--   &gt;&gt;&gt; void Nothing
--   Nothing
--   
--   &gt;&gt;&gt; void (Just 3)
--   Just ()
--   </pre>
--   
--   Replace the contents of an <tt><tt>Either</tt> <tt>Int</tt>
--   <tt>Int</tt></tt> with unit, resulting in an <tt><tt>Either</tt>
--   <tt>Int</tt> '()'</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; void (Left 8675309)
--   Left 8675309
--   
--   &gt;&gt;&gt; void (Right 8675309)
--   Right ()
--   </pre>
--   
--   Replace every element of a list with unit:
--   
--   <pre>
--   &gt;&gt;&gt; void [1,2,3]
--   [(),(),()]
--   </pre>
--   
--   Replace the second element of a pair with unit:
--   
--   <pre>
--   &gt;&gt;&gt; void (1,2)
--   (1,())
--   </pre>
--   
--   Discard the result of an <a>IO</a> action:
--   
--   <pre>
--   &gt;&gt;&gt; mapM print [1,2]
--   1
--   2
--   [(),()]
--   
--   &gt;&gt;&gt; void $ mapM print [1,2]
--   1
--   2
--   </pre>
void :: Functor f => f a -> f ()

-- | In many situations, the <a>liftM</a> operations can be replaced by
--   uses of <a>ap</a>, which promotes function application.
--   
--   <pre>
--   return f `ap` x1 `ap` ... `ap` xn
--   </pre>
--   
--   is equivalent to
--   
--   <pre>
--   liftMn f x1 x2 ... xn
--   </pre>
ap :: Monad m => m a -> b -> m a -> m b

-- | Promote a function to a monad, scanning the monadic arguments from
--   left to right (cf. <a>liftM2</a>).
liftM5 :: Monad m => a1 -> a2 -> a3 -> a4 -> a5 -> r -> m a1 -> m a2 -> m a3 -> m a4 -> m a5 -> m r

-- | Promote a function to a monad, scanning the monadic arguments from
--   left to right (cf. <a>liftM2</a>).
liftM4 :: Monad m => a1 -> a2 -> a3 -> a4 -> r -> m a1 -> m a2 -> m a3 -> m a4 -> m r

-- | Promote a function to a monad, scanning the monadic arguments from
--   left to right (cf. <a>liftM2</a>).
liftM3 :: Monad m => a1 -> a2 -> a3 -> r -> m a1 -> m a2 -> m a3 -> m r

-- | Promote a function to a monad, scanning the monadic arguments from
--   left to right. For example,
--   
--   <pre>
--   liftM2 (+) [0,1] [0,2] = [0,2,1,3]
--   liftM2 (+) (Just 1) Nothing = Nothing
--   </pre>
liftM2 :: Monad m => a1 -> a2 -> r -> m a1 -> m a2 -> m r

-- | Promote a function to a monad.
liftM :: Monad m => a1 -> r -> m a1 -> m r

-- | Conditional execution of <a>Applicative</a> expressions. For example,
--   
--   <pre>
--   when debug (putStrLn "Debugging")
--   </pre>
--   
--   will output the string <tt>Debugging</tt> if the Boolean value
--   <tt>debug</tt> is <a>True</a>, and otherwise do nothing.
when :: Applicative f => Bool -> f () -> f ()

-- | Same as <a>&gt;&gt;=</a>, but with the arguments interchanged.
(=<<) :: Monad m => a -> m b -> m a -> m b
infixr 1 =<<

-- | Monads that also support choice and failure.
class (Alternative m, Monad m) => MonadPlus (m :: * -> *)

-- | The identity of <a>mplus</a>. It should also satisfy the equations
--   
--   <pre>
--   mzero &gt;&gt;= f  =  mzero
--   v &gt;&gt; mzero   =  mzero
--   </pre>
--   
--   The default definition is
--   
--   <pre>
--   mzero = <a>empty</a>
--   </pre>
mzero :: MonadPlus m => m a

-- | An associative operation. The default definition is
--   
--   <pre>
--   mplus = (<a>&lt;|&gt;</a>)
--   </pre>
mplus :: MonadPlus m => m a -> m a -> m a

-- | The sum of a collection of actions, generalizing <a>concat</a>. As of
--   base 4.8.0.0, <a>msum</a> is just <a>asum</a>, specialized to
--   <a>MonadPlus</a>.
msum :: (Foldable t, MonadPlus m) => t m a -> m a

-- | This generalizes the list-based <a>concat</a> function.
msum' :: (MonadPlus m, Foldable t) => t (m a) -> m a

-- | Fold a value into an arbitrary <a>MonadPlus</a> type.
--   
--   This function generalizes the <a>toList</a> function.
mfold :: (MonadPlus m, Foldable t) => t a -> m a

-- | Translate a list to an arbitrary <a>MonadPlus</a> type.
--   
--   This function generalizes the <a>listToMaybe</a> function.
mfromList :: MonadPlus m => [a] -> m a

-- | Translate maybe to an arbitrary <a>MonadPlus</a> type.
--   
--   This function generalizes the <a>maybeToList</a> function.
mfromMaybe :: MonadPlus m => Maybe a -> m a

-- | Convert a partial function to a function returning an arbitrary
--   <a>MonadPlus</a> type.
mreturn :: MonadPlus m => (a -> Maybe b) -> a -> m b

-- | The <a>partition</a> function takes a predicate a list and returns the
--   pair of lists of elements which do and do not satisfy the predicate,
--   respectively; i.e.,
--   
--   <pre>
--   partition p xs == (filter p xs, filter (not . p) xs)
--   </pre>
--   
--   This function generalizes the <a>partition</a> function.
mpartition :: MonadPlus m => (a -> Bool) -> m a -> (m a, m a)

-- | Join list elements together.
--   
--   This function generalizes the <a>catMaybes</a> function.
mscatter :: MonadPlus m => m [b] -> m b

-- | Join foldable elements together.
--   
--   This function generalizes the <a>catMaybes</a> function.
mscatter' :: (MonadPlus m, Foldable t) => m (t b) -> m b

-- | Pass through <tt>Just</tt> elements.
--   
--   This function generalizes the <a>catMaybes</a> function.
mcatMaybes :: MonadPlus m => m (Maybe a) -> m a

-- | Pass through <tt>Left</tt> elements.
--   
--   This function generalizes the <a>lefts</a> function.
mlefts :: MonadPlus m => m (Either a b) -> m a

-- | Pass through <tt>Right</tt> elements.
--   
--   This function generalizes the <a>rights</a> function.
mrights :: MonadPlus m => m (Either a b) -> m b

-- | Separate <tt>Left</tt> and <tt>Right</tt> elements.
--   
--   This function generalizes the <a>partitionEithers</a> function.
mpartitionEithers :: MonadPlus m => m (Either a b) -> (m a, m b)

-- | Modify or discard a value.
--   
--   This function generalizes the <a>mapMaybe</a> function.
mmapMaybe :: MonadPlus m => (a -> Maybe b) -> m a -> m b

-- | Modify, discard or spawn values.
--   
--   This function generalizes the <a>concatMap</a> function.
mconcatMap :: MonadPlus m => (a -> [b]) -> m a -> m b

-- | Modify, discard or spawn values.
--   
--   This function generalizes the <a>concatMap</a> function.
mconcatMap' :: (MonadPlus m, Foldable t) => (a -> t b) -> m a -> m b

-- | Wrapper for partial functions with <a>MonadPlus</a> instance.
newtype Partial a b
Partial :: a -> Maybe b -> Partial a b
[getPartial] :: Partial a b -> a -> Maybe b

-- | Convert a predicate to a partial function.
partial :: (a -> Bool) -> a -> Maybe a

-- | Convert a partial function to a predicate.
predicate :: (a -> Maybe a) -> a -> Bool

-- | Convert a total function to a partial function.
always :: (a -> b) -> a -> Maybe b

-- | Make a partial function that always rejects its input.
never :: a -> Maybe c
instance GHC.Base.Functor (Control.Monad.Plus.Partial r)
instance GHC.Base.Monad (Control.Monad.Plus.Partial r)
instance GHC.Base.MonadPlus (Control.Monad.Plus.Partial r)
instance GHC.Base.Applicative (Control.Monad.Plus.Partial r)
instance GHC.Base.Alternative (Control.Monad.Plus.Partial r)
instance GHC.Base.Semigroup (Control.Monad.Plus.Partial a b)
instance GHC.Base.Monoid (Control.Monad.Plus.Partial a b)
