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


-- | Canonical fromMaybeM and fromEitherM functions.
--   
--   Please see README.md
@package from-sum
@version 0.2.1.0


-- | This Haskell module exports various "from" functions for <a>Either</a>
--   and <a>Maybe</a>.
module Control.FromSum

-- | A monadic version of <a>fromEither</a>.
--   
--   <pre>
--   <a>fromEitherM</a> leftAction === <a>either</a> leftAction <a>pure</a>
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromEitherM (\s -&gt; [length s]) $ Right 5
--   [5]
--   
--   &gt;&gt;&gt; fromEitherM (\s -&gt; [length s]) $ Left ("foo" :: String)
--   [3]
--   </pre>
fromEitherM :: Applicative m => (e -> m a) -> Either e a -> m a

-- | A <a>flip</a>ed version of <a>fromEitherM</a>.
--   
--   <pre>
--   &gt;&gt;&gt; fromEitherOrM (Right 5) $ \s -&gt; [length s]
--   [5]
--   </pre>
--   
--   This can be nice to use as an error handler.
--   
--   <pre>
--   &gt;&gt;&gt; fromEitherOrM (Right 5) $ \s -&gt; putStrLn ("error: " ++ s) &gt;&gt; undefined
--   5
--   
--   &gt;&gt;&gt; fromEitherOrM (Left "foo") $ \s -&gt; putStrLn ("error: " ++ s) &gt;&gt; undefined
--   error: foo
--   ...
--   </pre>
fromEitherOrM :: Applicative m => Either e a -> (e -> m a) -> m a

-- | Similar to <a>fromEitherM</a>, but only run the monadic
--   <tt>leftAction</tt> if the <a>Either</a> argument is <a>Left</a>.
--   Otherwise, return <a>pure</a> <a>mempty</a>.
--   
--   <pre>
--   <a>fromEitherM_</a> leftAction === <a>either</a> leftAction (<a>const</a> <a>$</a> <a>pure</a> <a>mempty</a>)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromEitherM_ (\err -&gt; putStrLn err &gt;&gt; pure "bye") $ Right 5
--   ""
--   
--   &gt;&gt;&gt; fromEitherM_ (\err -&gt; putStrLn err &gt;&gt; pure "bye") $ Left "there was an error"
--   there was an error
--   "bye"
--   </pre>
--   
--   This can be convenient when you want to run some sort of logging
--   function whenever an <a>Either</a> is <a>Left</a>. If you imagine the
--   logging function is <tt>b -&gt; <a>IO</a> '()'</tt>, then the
--   effective type of <a>fromEitherM_</a> becomes <tt><a>fromEitherM_</a>
--   :: (e -&gt; <a>IO</a> '()') -&gt; <a>Either</a> e a -&gt; <a>IO</a>
--   '()'</tt>, because '()' has a <a>Monoid</a> instance, and <a>IO</a>,
--   has an <a>Applicative</a> instance.
--   
--   <pre>
--   &gt;&gt;&gt; fromEitherM_ putStrLn $ Left "there was an error"
--   there was an error
--   </pre>
fromEitherM_ :: (Applicative m, Monoid b) => (e -> m b) -> Either e a -> m b

-- | A <a>flip</a>ed version of <a>fromEitherM_</a>.
fromEitherOrM_ :: (Applicative m, Monoid b) => Either e a -> (e -> m b) -> m b

-- | A monadic version of <a>fromMaybe</a>.
--   
--   <pre>
--   <a>fromMaybeM</a> nothingAction === <a>maybe</a> nothingAction <a>pure</a>
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromMaybeM [] $ Just 5
--   [5]
--   
--   &gt;&gt;&gt; fromMaybeM [] Nothing
--   []
--   </pre>
fromMaybeM :: Applicative m => m a -> Maybe a -> m a

-- | A <a>flip</a>ed version of <a>fromMaybeM</a>.
--   
--   <pre>
--   &gt;&gt;&gt; fromMaybeOrM (Just 5) []
--   [5]
--   </pre>
--   
--   This can be nice to use as an error handler.
--   
--   <pre>
--   &gt;&gt;&gt; fromMaybeOrM (Just 5) $ putStrLn "some error occurred" &gt;&gt; undefined
--   5
--   
--   &gt;&gt;&gt; fromMaybeOrM (Nothing) $ putStrLn "some error occurred" &gt;&gt; undefined
--   some error occurred
--   ...
--   </pre>
fromMaybeOrM :: Applicative m => Maybe a -> m a -> m a

-- | Similar to <a>fromMaybeM</a>, but only run the monadic
--   <tt>nothingAction</tt> if the <a>Maybe</a> argument is <a>Nothing</a>.
--   Otherwise, return <a>pure</a> <a>mempty</a>.
--   
--   <pre>
--   <a>fromMaybeM_</a> nothingAction === <a>maybe</a> nothingAction (<a>const</a> <a>$</a> <a>pure</a> <a>mempty</a>)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromMaybeM_ (putStrLn "hello" &gt;&gt; pure "bye") $ Just 5
--   ""
--   
--   &gt;&gt;&gt; fromMaybeM_ (putStrLn "hello" &gt;&gt; pure "bye") Nothing
--   hello
--   "bye"
--   </pre>
--   
--   This can be convenient when you want to run some sort of logging
--   function whenever a <a>Maybe</a> is <a>Nothing</a>. If you imagine the
--   logging function is <tt><a>IO</a> '()'</tt>, then the effective type
--   of <a>fromMaybeM_</a> becomes <tt><a>fromMaybeM_</a> :: <a>IO</a> '()'
--   -&gt; <a>Maybe</a> a -&gt; <a>IO</a> '()'</tt>, because '()' has a
--   <a>Monoid</a> instance, and <a>IO</a>, has an <a>Applicative</a>
--   instance.
--   
--   <pre>
--   &gt;&gt;&gt; fromMaybeM_ (putStrLn "hello") Nothing
--   hello
--   </pre>
fromMaybeM_ :: (Applicative m, Monoid b) => m b -> Maybe a -> m b

-- | A <a>flip</a>ed version of <a>fromMaybeM</a>.
fromMaybeOrM_ :: (Applicative m, Monoid b) => Maybe a -> m b -> m b

-- | Similar to <a>fromEitherM</a> but the <a>Either</a> argument is also a
--   monadic value.
--   
--   <pre>
--   &gt;&gt;&gt; fromEitherMM (\s -&gt; [length s]) [Right 5, Right 10]
--   [5,10]
--   
--   &gt;&gt;&gt; fromEitherMM (\s -&gt; [length s]) [Left ("foo" :: String), Right 100]
--   [3,100]
--   </pre>
--   
--   <b>NOTE</b>: I don't particularly like the name of this function. If
--   you have a suggestion for a better name, please submit a PR or issue.
fromEitherMM :: Monad m => (e -> m a) -> m (Either e a) -> m a

-- | A <a>flip</a>ed version of <a>fromEitherMM</a>.
fromEitherOrMM :: Monad m => m (Either e a) -> (e -> m a) -> m a

-- | Similar to <a>fromMaybeM</a> but the <a>Maybe</a> argument is also a
--   monadic value.
--   
--   <pre>
--   &gt;&gt;&gt; fromMaybeMM [] [Just 6, Just 5]
--   [6,5]
--   
--   &gt;&gt;&gt; fromMaybeMM [] [Just 6, Nothing, Just 7]
--   [6,7]
--   </pre>
--   
--   <b>NOTE</b>: I don't particularly like the name of this function. If
--   you have a suggestion for a better name, please submit a PR or issue.
fromMaybeMM :: Monad m => m a -> m (Maybe a) -> m a

-- | A <a>flip</a>ed version of <a>fromMaybeMM</a>.
fromMaybeOrMM :: Monad m => m (Maybe a) -> m a -> m a

-- | Similar to <a>fromMaybe</a>.
--   
--   <pre>
--   &gt;&gt;&gt; fromEither show $ Left 5
--   "5"
--   
--   &gt;&gt;&gt; fromEither show $ Right "hello"
--   "hello"
--   </pre>
fromEither :: (e -> a) -> Either e a -> a

-- | A <a>flip</a>ed version of <a>fromEither</a>.
fromEitherOr :: Either e a -> (e -> a) -> a

-- | The <a>fromMaybe</a> function takes a default value and and
--   <a>Maybe</a> value. If the <a>Maybe</a> is <a>Nothing</a>, it returns
--   the default values; otherwise, it returns the value contained in the
--   <a>Maybe</a>.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; fromMaybe "" (Just "Hello, World!")
--   "Hello, World!"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromMaybe "" Nothing
--   ""
--   </pre>
--   
--   Read an integer from a string using <tt>readMaybe</tt>. If we fail to
--   parse an integer, we want to return <tt>0</tt> by default:
--   
--   <pre>
--   &gt;&gt;&gt; import Text.Read ( readMaybe )
--   
--   &gt;&gt;&gt; fromMaybe 0 (readMaybe "5")
--   5
--   
--   &gt;&gt;&gt; fromMaybe 0 (readMaybe "")
--   0
--   </pre>
fromMaybe :: () => a -> Maybe a -> a

-- | A <a>flip</a>ed version of <a>fromMaybe</a>.
fromMaybeOr :: Maybe a -> a -> a

-- | Collapse an <tt><a>Either</a> a a</tt> to an <tt>a</tt>. Defined as
--   <tt><a>fromEither</a> <a>id</a></tt>.
--   
--   Note: Other libraries export this function as <tt>fromEither</tt>, but
--   our <a>fromEither</a> function is slightly more general.
--   
--   <pre>
--   &gt;&gt;&gt; collapseEither (Right 3)
--   3
--   
--   &gt;&gt;&gt; collapseEither (Left "hello")
--   "hello"
--   </pre>
collapseEither :: Either a a -> a

-- | Similar to <a>collapseEither</a>, but for <a>ExceptT</a>.
--   
--   <pre>
--   &gt;&gt;&gt; import Control.Monad.Except (ExceptT(ExceptT))
--   
--   &gt;&gt;&gt; collapseExceptT (ExceptT $ pure (Right 3))
--   3
--   
--   &gt;&gt;&gt; collapseExceptT (ExceptT $ pure (Left "hello"))
--   "hello"
--   </pre>
collapseExceptT :: Monad m => ExceptT a m a -> m a
