-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Canonical fromMaybeM and fromEitherM functions. -- -- Provides many functions for working with Maybe and -- Either. Please see README.md. @package from-sum @version 0.2.2.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 and -- Maybe value. If the Maybe is Nothing, it returns -- the default values; 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 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. -- --

--   >>> import Control.Monad.Trans.Except (ExceptT(ExceptT))
--   
--   >>> collapseExceptT (ExceptT $ pure (Right 3))
--   3
--   
--   >>> collapseExceptT (ExceptT $ pure (Left "hello"))
--   "hello"
--

collapseExceptT :: Monad m => ExceptT a m a -> m a