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


-- | Combinators for working with Maybe and Either
--   
--   Provides many functions for working with <a>Maybe</a> and
--   <a>Either</a>, including canonical <a>fromMaybeM</a> and
--   <a>fromEitherM</a> functions. Please see <tt>README.md</tt>.
@package from-sum
@version 0.2.3.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>()</tt></tt>, then the
--   effective type of <a>fromEitherM_</a> becomes <tt><a>fromEitherM_</a>
--   :: (e -&gt; <a>IO</a> <tt>()</tt>) -&gt; <a>Either</a> e a -&gt;
--   <a>IO</a> <tt>()</tt></tt>, because <tt>()</tt> 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>()</tt></tt>, then the effective
--   type of <a>fromMaybeM_</a> becomes <tt><a>fromMaybeM_</a> :: <a>IO</a>
--   <tt>()</tt> -&gt; <a>Maybe</a> a -&gt; <a>IO</a> <tt>()</tt></tt>,
--   because <tt>()</tt> 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 a <a>Maybe</a>
--   value. If the <a>Maybe</a> is <a>Nothing</a>, it returns the default
--   value; 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 <a>readMaybe</a>. If we fail to
--   parse an integer, we want to return <tt>0</tt> by default:
--   
--   <pre>
--   &gt;&gt;&gt; import GHC.Internal.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

-- | Convert a <a>Maybe</a> to an <a>Either</a>.
--   
--   If the <a>Maybe</a> is <a>Just</a>, then return the value in
--   <a>Right</a>.
--   
--   <pre>
--   &gt;&gt;&gt; maybeToEither 3 $ Just "hello"
--   Right "hello"
--   </pre>
--   
--   If the <a>Maybe</a> is <a>Nothing</a>, then use the given <tt>e</tt>
--   as <a>Left</a>.
--   
--   <pre>
--   &gt;&gt;&gt; maybeToEither 3 Nothing
--   Left 3
--   </pre>
maybeToEither :: e -> Maybe a -> Either e a

-- | A <a>flip</a>ed version of <a>maybeToEither</a>.
--   
--   <pre>
--   &gt;&gt;&gt; maybeToEitherOr (Just "hello") 3
--   Right "hello"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; maybeToEitherOr Nothing 3
--   Left 3
--   </pre>
maybeToEitherOr :: Maybe a -> e -> Either e a

-- | Convert an <a>Either</a> to a <a>Maybe</a>.
--   
--   A <a>Right</a> value becomes <a>Just</a>.
--   
--   <pre>
--   &gt;&gt;&gt; eitherToMaybe $ Right 3
--   Just 3
--   </pre>
--   
--   A <a>Left</a> value becomes <a>Nothing</a>.
--   
--   <pre>
--   &gt;&gt;&gt; eitherToMaybe $ Left "bye"
--   Nothing
--   </pre>
eitherToMaybe :: Either e a -> Maybe 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; 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

-- | Collapse an <a>ExceptT</a> where the error returns the same type as
--   the whole computation.
--   
--   <pre>
--   &gt;&gt;&gt; let exceptTOne = pure 3 :: ExceptT (IO Int) IO Int
--   
--   &gt;&gt;&gt; collapseErrExceptT exceptTOne :: IO Int
--   3
--   </pre>
--   
--   This is helpful when writing short-circuiting computations where you
--   throw errors that match the type of the underlying computation.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   let go :: Int -&gt; ExceptT (IO ()) IO ()
--       go x = do
--         bar &lt;-
--           if x &lt; 10
--           then
--             pure "hello"
--           else
--             throwE (putStrLn "Error occurred, x too big!")
--         lift $ putStrLn $ bar ++ " world"
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; collapseErrExceptT (go 100) :: IO ()
--   Error occurred, x too big!
--   
--   &gt;&gt;&gt; collapseErrExceptT (go 3) :: IO ()
--   hello world
--   </pre>
--   
--   In this example, the error type in the <a>ExceptT</a> is <tt><a>IO</a>
--   ()</tt>. This allows us to easily short-circuit the remaining
--   computations. In this example, the remaining computation is just
--   printing <tt>bar <a>++</a> " world"</tt>.
collapseErrExceptT :: Monad m => ExceptT (m a) m a -> m a

-- | Lift an <a>Either</a> into an <a>ExceptT</a>.
--   
--   This is the same as <a>liftEither</a>, but the return type is
--   specialized for <a>ExceptT</a>.
--   
--   <pre>
--   &gt;&gt;&gt; liftEitherExceptT (Right 3) :: ExceptT String Identity Int
--   ExceptT (Identity (Right 3))
--   </pre>
--   
--   Note that if you want to lift <tt>m (<a>Either</a> e a)</tt> to
--   <tt><a>ExceptT</a> e m a</tt>, just use <a>ExceptT</a>:
--   
--   <pre>
--   &gt;&gt;&gt; action = Identity (Left "error") :: Identity (Either String Int)
--   
--   &gt;&gt;&gt; ExceptT action :: ExceptT String Identity Int
--   ExceptT (Identity (Left "error"))
--   </pre>
liftEitherExceptT :: forall (m :: Type -> Type) e a. Applicative m => Either e a -> ExceptT e m a

-- | Lift an <a>Either</a> to an <a>ExceptT</a> with a handler for
--   transforming the error value.
--   
--   If the input <a>Either</a> is <a>Right</a>, then just return it like
--   normal:
--   
--   <pre>
--   &gt;&gt;&gt; let rightEither = Right () :: Either String ()
--   
--   &gt;&gt;&gt; fromEitherExceptT (\str -&gt; length str) rightEither :: ExceptT Int Identity ()
--   ExceptT (Identity (Right ()))
--   </pre>
--   
--   If the input <a>Either</a> is <a>Left</a>, then pass the value to the
--   handler:
--   
--   <pre>
--   &gt;&gt;&gt; let leftEither = Left "hello" :: Either String ()
--   
--   &gt;&gt;&gt; fromEitherExceptT (\str -&gt; length str) leftEither :: ExceptT Int Identity ()
--   ExceptT (Identity (Left 5))
--   </pre>
fromEitherExceptT :: forall (m :: Type -> Type) e x a. Monad m => (e -> x) -> Either e a -> ExceptT x m a

-- | Just like <a>fromEitherExceptT</a>, but the arguments are flipped.
fromEitherOrExceptT :: forall (m :: Type -> Type) e a x. Monad m => Either e a -> (e -> x) -> ExceptT x m a

-- | Similar to <a>fromEitherExceptT</a> but the <a>Either</a> value is
--   lifted in a <a>Monad</a>.
--   
--   <pre>
--   &gt;&gt;&gt; let identityLeft = Identity (Left "hello") :: Identity (Either String ())
--   
--   &gt;&gt;&gt; fromEitherMExceptT (\str -&gt; length str) identityLeft :: ExceptT Int Identity ()
--   ExceptT (Identity (Left 5))
--   </pre>
--   
--   This is similar to <a>withExceptT</a>, but the second argument is the
--   unwrapped <a>ExceptT</a> computation.
fromEitherMExceptT :: Monad m => (e -> x) -> m (Either e a) -> ExceptT x m a

-- | Just like <a>fromEitherOrMExceptT</a>, but the arguments are flipped.
fromEitherOrMExceptT :: Monad m => m (Either e a) -> (e -> x) -> ExceptT x m a

-- | Lift a <a>Maybe</a> to an <a>ExceptT</a> with a default value for the
--   case when the <a>Maybe</a> is <a>Nothing</a>.
--   
--   If the <a>Maybe</a> is <a>Just</a>, then just return the value like
--   normal:
--   
--   <pre>
--   &gt;&gt;&gt; let justVal = Just True :: Maybe Bool
--   
--   &gt;&gt;&gt; fromMaybeExceptT 5 justVal :: ExceptT Int Identity Bool
--   ExceptT (Identity (Right True))
--   </pre>
--   
--   If the <a>Maybe</a> is <a>Nothing</a>, then use the default value as
--   the error value:
--   
--   <pre>
--   &gt;&gt;&gt; let nothingVal = Nothing :: Maybe Bool
--   
--   &gt;&gt;&gt; fromMaybeExceptT 5 nothingVal :: ExceptT Int Identity Bool
--   ExceptT (Identity (Left 5))
--   </pre>
fromMaybeExceptT :: forall (m :: Type -> Type) x a. Monad m => x -> Maybe a -> ExceptT x m a

-- | Just like <a>fromMaybeExceptT</a> but with the arguments flipped.
fromMaybeOrExceptT :: forall (m :: Type -> Type) a x. Monad m => Maybe a -> x -> ExceptT x m a

-- | Similar to <a>fromMaybeExceptT</a> except the <a>Maybe</a> value is
--   lifted in a <a>Monad</a>.
--   
--   <pre>
--   &gt;&gt;&gt; let identityNothing = Identity Nothing :: Identity (Maybe Bool)
--   
--   &gt;&gt;&gt; fromMaybeMExceptT 5 identityNothing :: ExceptT Int Identity Bool
--   ExceptT (Identity (Left 5))
--   </pre>
fromMaybeMExceptT :: Monad m => x -> m (Maybe a) -> ExceptT x m a

-- | Just like <a>fromMaybeMExceptT</a> but with the arguments flipped.
fromMaybeOrMExceptT :: Monad m => m (Maybe a) -> x -> ExceptT x m a

-- | Similar to <tt>guard</tt>, but for <a>ExceptT</a>.
--   
--   If the <a>Bool</a> is <a>True</a>, then do nothing.
--   
--   <pre>
--   &gt;&gt;&gt; guardExceptT True "error occurred" :: ExceptT String Identity ()
--   ExceptT (Identity (Right ()))
--   </pre>
--   
--   If the <a>Bool</a> is <a>False</a>, then return the error case:
--   
--   <pre>
--   &gt;&gt;&gt; guardExceptT False "error occurred" :: ExceptT String Identity ()
--   ExceptT (Identity (Left "error occurred"))
--   </pre>
guardExceptT :: forall (m :: Type -> Type) x. Monad m => Bool -> x -> ExceptT x m ()

-- | Just like <a>guardExceptT</a> (and similar to <tt>guardM</tt>), except
--   the boolean is lifted in a <a>Monad</a>.
--   
--   <pre>
--   &gt;&gt;&gt; guardMExceptT (Identity False) "error occurred" :: ExceptT String Identity ()
--   ExceptT (Identity (Left "error occurred"))
--   </pre>
guardMExceptT :: Monad m => m Bool -> x -> ExceptT x m ()
