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

-- | Concrete data type for handling extensible exceptions as failures.
--   
--   Defines a data type, Attempt, which has a Success and Failure
--   constructor. Failure contains an extensible exception.
@package attempt
@version 0.4.0

-- | 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 Success value or a Failure exception.
data Attempt v
Success :: v -> Attempt v
Failure :: e -> Attempt v

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

-- | A shortcut for fromAttempt.
fa :: FromAttempt a => Attempt v -> a v

-- | This is not a simple translation of the Control.Monad.join function.
--   Instead, for Monads which are instances of FromAttempt,
--   it removes the inner Attempt type, reporting errors as defined
--   in the FromAttempt 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 Attempt to produce
--   a result.
--   
--   This function is modeled after maybe and either. The
--   first argument must accept any instances of Exception. If you
--   want to handle multiple types of exceptions, see makeHandler.
--   The second argument converts the success value.
--   
--   Note that this function does not expose all the data available in an
--   Attempt value. Notably, the monadic stack trace is not passed
--   on to the error handler. If desired, use the
--   monadicStackTrace function to extract it.
attempt :: (forall e. Exception e => e -> b) -> (a -> b) -> Attempt a -> b

-- | Convert multiple AttemptHandlers 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 Exceptions 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* Exception type to some value.
data AttemptHandler v
AttemptHandler :: (e -> v) -> AttemptHandler v

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

-- | Tests for a Success 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 Success values.
successes :: [Attempt v] -> [v]

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

-- | Return all of the Failures and Successes separately in a
--   tuple.
partitionAttempts :: [Attempt v] -> ([SomeException], [v])

-- | Catches runtime (ie, IO) exceptions and inserts them into an
--   Attempt.
--   
--   Like handle, the first argument to this function must
--   explicitly state the type of its input.
attemptIO :: (Exception eIn, Exception eOut) => (eIn -> eOut) -> IO v -> IO (Attempt v)
instance Typeable1 Attempt
instance FromAttempt (Either SomeException)
instance FromAttempt (Either String)
instance FromAttempt []
instance FromAttempt Maybe
instance FromAttempt IO
instance Exception e => Failure e Attempt
instance Monad Attempt
instance Applicative Attempt
instance Functor Attempt
instance Show v => Show (Attempt v)
