-- 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 Maybe and
--   Either, including canonical fromMaybeM and
--   fromEitherM functions. Please see README.md.
@package from-sum
@version 0.2.3.0

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

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

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

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

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

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

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

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

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

-- | Similar to fromEitherM but the Either argument is also a
--   monadic value.
--   
--   
--   >>> fromEitherMM (\s -> [length s]) [Right 5, Right 10]
--   [5,10]
--   
--   >>> fromEitherMM (\s -> [length s]) [Left ("foo" :: String), Right 100]
--   [3,100]
--   
--   
--   NOTE: 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 fliped version of fromEitherMM.
fromEitherOrMM :: Monad m => m (Either e a) -> (e -> m a) -> m a

-- | Similar to fromMaybeM but the Maybe argument is also a
--   monadic value.
--   
--   
--   >>> fromMaybeMM [] [Just 6, Just 5]
--   [6,5]
--   
--   >>> fromMaybeMM [] [Just 6, Nothing, Just 7]
--   [6,7]
--   
--   
--   NOTE: 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 fliped version of fromMaybeMM.
fromMaybeOrMM :: Monad m => m (Maybe a) -> m a -> m a

-- | Similar to fromMaybe.
--   
--   
--   >>> fromEither show $ Left 5
--   "5"
--   
--   >>> fromEither show $ Right "hello"
--   "hello"
--   
fromEither :: (e -> a) -> Either e a -> a

-- | A fliped version of fromEither.
fromEitherOr :: Either e a -> (e -> a) -> a

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

-- | A fliped version of fromMaybe.
fromMaybeOr :: Maybe a -> a -> a

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

-- | A fliped version of maybeToEither.
--   
--   
--   >>> maybeToEitherOr (Just "hello") 3
--   Right "hello"
--   
--   
--   
--   >>> maybeToEitherOr Nothing 3
--   Left 3
--   
maybeToEitherOr :: Maybe a -> e -> Either e a

-- | Convert an Either to a Maybe.
--   
--   A Right value becomes Just.
--   
--   
--   >>> eitherToMaybe $ Right 3
--   Just 3
--   
--   
--   A Left value becomes Nothing.
--   
--   
--   >>> eitherToMaybe $ Left "bye"
--   Nothing
--   
eitherToMaybe :: Either e a -> Maybe a

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

-- | Similar to collapseEither, but for ExceptT.
--   
--   
--   >>> collapseExceptT (ExceptT $ pure (Right 3))
--   3
--   
--   >>> collapseExceptT (ExceptT $ pure (Left "hello"))
--   "hello"
--   
collapseExceptT :: Monad m => ExceptT a m a -> m a

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

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

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

-- | Just like fromEitherExceptT, 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 fromEitherExceptT but the Either value is
--   lifted in a Monad.
--   
--   
--   >>> let identityLeft = Identity (Left "hello") :: Identity (Either String ())
--   
--   >>> fromEitherMExceptT (\str -> length str) identityLeft :: ExceptT Int Identity ()
--   ExceptT (Identity (Left 5))
--   
--   
--   This is similar to withExceptT, but the second argument is the
--   unwrapped ExceptT computation.
fromEitherMExceptT :: Monad m => (e -> x) -> m (Either e a) -> ExceptT x m a

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

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

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

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

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

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

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