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


-- | Error handling using extensible exceptions outside the IO monad.
--   
--   Defines a data type, Attempt, which has a Success and Failure
--   constructor. Failure contains an extensible exception.
@package attempt
@version 0.0.1


-- | A universal data type for computations which may fail. Errors are
--   reported using extensible exceptions. These exceptions are not
--   explicitly stated; if you want this kind of functionality, something
--   like control-monad-exception might be a more appropriate fit.
module Data.Attempt

-- | Contains either a <a>Success</a> value or a <a>Failure</a> exception.
data Attempt v
Success :: v -> Attempt v
Failure :: SomeException -> Attempt v

-- | Any type which can be converted from an <a>Attempt</a>. The included
--   instances are your "usual suspects" for dealing with error handling.
--   They include:
--   
--   <a>IO</a>: For the IO instance, any exceptions in the <a>Attempt</a>
--   are thrown as runtime exceptions.
--   
--   <a>Maybe</a>: Returns <a>Nothing</a> on <a>Failure</a>, or <a>Just</a>
--   on <a>Success</a>.
--   
--   List: Returns the empty list on <a>Failure</a>, or a singleton list on
--   <a>Success</a>.
--   
--   <a>Either</a> <a>String</a>: Returns <a>Left</a> (<a>show</a>
--   exception) on <a>Failure</a>, or <a>Right</a> on <a>Success</a>.
--   
--   <a>Either</a> <a>Exception</a>: Returns <a>Left</a> exception on
--   <a>Failure</a>, or <a>Right</a> on <a>Success</a>.
class FromAttempt a
fromAttempt :: (FromAttempt a) => Attempt v -> a v

-- | A shortcut for <a>fromAttempt</a>.
fa :: (FromAttempt a) => Attempt v -> a v

-- | This is not a simple translation of the Control.Monad.join function.
--   Instead, for <a>Monad</a>s which are instances of <a>FromAttempt</a>,
--   it removes the inner <a>Attempt</a> type, reporting errors as defined
--   in the <a>FromAttempt</a> instance.
--   
--   For example, join (Just (failureString "foo")) == Nothing.
joinAttempt :: (FromAttempt m, Monad m) => m (Attempt v) -> m v

-- | Process either the exception or value in an <a>Attempt</a> to produce
--   a result.
--   
--   This function is modeled after <a>maybe</a> and <a>either</a>. The
--   first argument must accept any instances of <a>Exception</a>. If you
--   want to handle multiple types of exceptions, see <a>makeHandler</a>.
--   The second argument converts the success value.
attempt :: (forall e. (Exception e) => e -> b) -> (a -> b) -> Attempt a -> b

-- | Convert multiple <a>AttemptHandler</a>s and a default value into an
--   exception handler.
--   
--   This is a convenience function when you want to have special handling
--   for a few types of <a>Exception</a>s and provide another value for
--   anything else.
makeHandler :: [AttemptHandler v] -> v -> (forall e. (Exception e) => e -> v)

-- | A simple wrapper value necesary due to the Haskell type system. Wraps
--   a function from a *specific* <a>Exception</a> type to some value.
data AttemptHandler v
AttemptHandler :: (e -> v) -> AttemptHandler v

-- | Tests for a <a>Failure</a> value.
isFailure :: Attempt v -> Bool

-- | Tests for a <a>Success</a> value.
isSuccess :: Attempt v -> Bool

-- | This is an unsafe, partial function which should only be used if you
--   either know that a function will succeed or don't mind the occassional
--   runtime exception.
fromSuccess :: Attempt v -> v

-- | Returns only the <a>Success</a> values.
successes :: [Attempt v] -> [v]

-- | Returns only the <a>Failure</a> values, each wrapped in a
--   SomeException.
failures :: [Attempt v] -> [SomeException]

-- | Return all of the <a>Failure</a>s and <a>Success</a>es separately in a
--   tuple.
partitionAttempts :: [Attempt v] -> ([SomeException], [v])
instance Typeable1 Attempt
instance (Show v) => Show (Attempt v)
instance FromAttempt (Either SomeException)
instance FromAttempt (Either String)
instance FromAttempt []
instance FromAttempt Maybe
instance FromAttempt IO
instance (Exception e) => WrapFailure e Attempt
instance (Exception e) => MonadFailure e Attempt
instance Monad Attempt
instance Applicative Attempt
instance Functor Attempt


-- | Provide a monad transformer for the attempt monad, which allows the
--   reporting of errors using extensible exceptions.
module Control.Monad.Attempt
newtype AttemptT m v
AttemptT :: m (Attempt v) -> AttemptT m v
runAttemptT :: AttemptT m v -> m (Attempt v)

-- | Instances of <a>FromAttempt</a> specify a manner for embedding
--   <a>Attempt</a> failures directly into the target data type. For
--   example, the <a>IO</a> instance simply throws a runtime error. This is
--   a convenience wrapper when you simply want to use that default action.
--   
--   So given a type <a>AttemptT</a> <a>IO</a> <a>Int</a>, this function
--   will convert it to <a>IO</a> <a>Int</a>, throwing any exceptions in
--   the original value.
evalAttemptT :: (Monad m, FromAttempt m) => AttemptT m v -> m v
instance (Monad m) => FromAttempt (AttemptT m)
instance (MonadIO m) => MonadIO (AttemptT m)
instance MonadTrans AttemptT
instance (Monad m, Exception e) => WrapFailure e (AttemptT m)
instance (Exception e, Monad m) => MonadFailure e (AttemptT m)
instance (Monad m) => Monad (AttemptT m)
instance (Monad m) => Applicative (AttemptT m)
instance (Monad m) => Functor (AttemptT m)