-- 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.3.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 <a>Success</a> value or a <a>Failure</a> exception.
data Attempt v
Success :: v -> Attempt v
Failure :: e -> 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.
--   
--   Note that this function does not expose all the data available in an
--   <a>Attempt</a> value. Notably, the monadic stack trace is not passed
--   on to the error handler. If desired, use the
--   <tt>monadicStackTrace</tt> function to extract it.
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
--   <tt>SomeException</tt>.
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])

-- | Catches runtime (ie, IO) exceptions and inserts them into an
--   <a>Attempt</a>.
--   
--   Like <tt>handle</tt>, 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 => WrapFailure e Attempt
instance Exception e => Failure e Attempt
instance Monad Attempt
instance Applicative Attempt
instance Functor Attempt
instance Show v => Show (Attempt v)