-- 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.0


-- | Defines a type class for any monads which may report failure using
--   extensible exceptions.
module Control.Monad.Attempt.Class

-- | Any <a>Monad</a> which may report failure using extensible exceptions.
--   This most obviously applies to the Attempt data type, but you should
--   just as well use this for arbitrary <a>Monad</a>s.
--   
--   Usage should be straight forward: <a>return</a> successes and
--   <a>failure</a> errors. If you simply want to send a string error
--   message, use <a>failureString</a>. Although tempting to do so,
--   <a>fail</a> is *not* used as a synonym for <a>failureString</a>;
--   <a>fail</a> should not be used at all.
--   
--   Minimal complete definition: <a>failure</a> and <a>wrapFailure</a>.
class (Monad m) => MonadAttempt m
failure :: (MonadAttempt m, Exception e) => e -> m v
failureString :: (MonadAttempt m) => String -> m v
wrapFailure :: (MonadAttempt m, Exception eOut) => (forall eIn. (Exception eIn) => eIn -> eOut) -> m v -> m v

-- | A simple exception which simply contains a string. Note that the
--   <a>Show</a> instance simply returns the contained string.
newtype StringException
StringException :: String -> StringException
instance Typeable StringException
instance Exception StringException
instance Show StringException


-- | 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

-- | 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
instance Typeable1 Attempt
instance FromAttempt (Either SomeException)
instance FromAttempt (Either String)
instance FromAttempt []
instance FromAttempt Maybe
instance FromAttempt IO
instance MonadAttempt Attempt
instance Monad Attempt
instance Applicative Attempt
instance Functor Attempt
instance (Show v) => Show (Attempt v)


-- | 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) => MonadAttempt (AttemptT m)
instance (Monad m) => Monad (AttemptT m)
instance (Monad m) => Applicative (AttemptT m)
instance (Monad m) => Functor (AttemptT m)


-- | Replacements for standard functions to represent failure with a
--   <a>MonadAttempt</a>. Lots of inspiration taken from the <a>safe</a>
--   package.
module Data.Attempt.Helper

-- | 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.
join :: (FromAttempt m, Monad m) => m (Attempt v) -> m v

-- | Exception type for the <a>lookup</a> function.
data KeyNotFound k v
KeyNotFound :: k -> [(k, v)] -> KeyNotFound k v

-- | Exception type for functions which expect non-empty lists.
data EmptyList
EmptyList :: EmptyList

-- | Report errors from the <a>read</a> function.
newtype CouldNotRead
CouldNotRead :: String -> CouldNotRead

-- | For functions which expect index values &gt;= 0.
data NegativeIndex
NegativeIndex :: NegativeIndex
lookup :: (Typeable k, Typeable v, Show k, Eq k, MonadAttempt m) => k -> [(k, v)] -> m v
tail :: (MonadAttempt m) => [a] -> m [a]
init :: (MonadAttempt m) => [a] -> m [a]
head :: (MonadAttempt m) => [a] -> m a
last :: (MonadAttempt m) => [a] -> m a
read :: (MonadAttempt m, Read a) => String -> m a

-- | Same as Prelude.!!. Name stolen from safe library.
at :: (MonadAttempt m) => [a] -> Int -> m a

-- | Assert a value to be true. If true, returns the first value as a
--   succss. Otherwise, returns the second value as a failure.
assert :: (MonadAttempt m, Exception e) => Bool -> v -> e -> m v

-- | The standard readFile function with any <a>IOException</a>s returned
--   as a failure instead of a runtime exception.
readFile :: (MonadAttempt m, MonadIO m) => FilePath -> m String
instance Typeable OutOfBoundsIndex
instance Typeable NegativeIndex
instance Typeable CouldNotRead
instance Typeable EmptyList
instance Typeable2 KeyNotFound
instance Show OutOfBoundsIndex
instance Show NegativeIndex
instance Show CouldNotRead
instance Show EmptyList
instance Exception OutOfBoundsIndex
instance Exception NegativeIndex
instance Exception CouldNotRead
instance Exception EmptyList
instance (Typeable k, Typeable v, Show k) => Exception (KeyNotFound k v)
instance (Show k) => Show (KeyNotFound k v)