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


-- | Essentially the Maybe type with error messages.
--   
@package exceptional
@version 0.2.0.0

module Control.Exceptional

-- | This is basically specialized 'Either String', or <a>Maybe</a> with
--   error messages.
data Exceptional x
Failure :: String -> Exceptional x
Success :: x -> Exceptional x

-- | This is <a>fail</a>-safe, so to speak. That is,
--   
--   <pre>
--   fail = Failure
--   </pre>

-- | Convert <a>Exceptional</a> into another <a>Monad</a>. If you don't
--   have proper exception handling in your monad, this can throw errors.
--   
--   <pre>
--   runExceptional (Failure s) = fail s
--   runExceptional (Success s) = pure s
--   </pre>
runExceptional :: Monad m => Exceptional x -> m x

-- | Convert a <a>Maybe</a> to an <a>Exceptional</a>
--   
--   <pre>
--   fromMaybe s Nothing = fail s
--   fromMaybe s (Just x) = pure x
--   </pre>
fromMaybe :: String -> Maybe a -> Exceptional a

-- | Convert an <a>Exceptional</a> into a <a>Maybe</a>. This function
--   disregards the error message.
--   
--   <pre>
--   toMaybe (Success x) = Just x
--   toMaybe (Failure _) = Nothing
--   </pre>
toMaybe :: Exceptional a -> Maybe a

-- | Convert an <a>Either</a> <a>String</a> to an <a>Exceptional</a>
--   
--   <pre>
--   fromEither (Left s) = fail s
--   fromEither (Right x) = pure x
--   </pre>
fromEither :: Either String a -> Exceptional a

-- | Convert an <a>Exceptional</a> to an <a>Either</a> <a>String</a>
--   
--   <pre>
--   toEither (Failure s) = Left s
--   toEither (Success x) = Right x
--   </pre>
toEither :: Exceptional a -> Either String a

-- | A wrapper around <a>tryIOError</a>. Encapsulates I/O exceptions in the
--   <a>Exceptional</a> monad.
exceptIO :: IO a -> IO (Exceptional a)

-- | Run an exception-prone action in another monad, catch the errors in
--   <a>Exceptional</a>.
exceptional :: MonadCatch m => m a -> m (Exceptional a)

-- | Get all of the <a>Failure</a>s from a bunch of <a>Exceptional</a>s
failures :: Foldable t => t (Exceptional x) -> [String]

-- | Get all of the <a>Success</a>es from a bunch of <a>Exceptional</a>s
successes :: Foldable t => t (Exceptional x) -> [x]

-- | Given a number of <a>Exceptional</a> values:
--   
--   <ul>
--   <li>If all are <a>Success</a>ful, then return <a>Right</a> with the
--   sucesses * If there is at least one <a>Failure</a>, then return
--   <a>Left</a> the list of error messages</li>
--   </ul>
foldExceptional :: Foldable t => t (Exceptional x) -> Either [String] [x]
instance Eq x => Eq (Exceptional x)
instance Show x => Show (Exceptional x)
instance Read x => Read (Exceptional x)
instance Monad Exceptional
instance Alternative Exceptional
instance Applicative Exceptional
instance Functor Exceptional