-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Exceptions which are explicit in the type signature. -- -- Synchronous and Asynchronous exceptions which are explicit in the type -- signature. The first ones are very similar to Either and -- Control.Monad.Error.ErrorT. The second ones are used for -- System.IO.readFile and System.IO.hGetContents. This -- package is a proposal for improved exception handling in Haskell. It -- strictly separates between handling of exceptional situations (file -- not found, invalid user input, see -- http://www.haskell.org/haskellwiki/Exception) and (programming) -- errors (division by zero, index out of range, see -- http://www.haskell.org/haskellwiki/Error). Handling of the -- first one is called "exception handling", whereas handling of errors -- is better known as "debugging". -- -- For an application see the midi package. -- -- Although I'm not happy with the identifier style of the Monad Template -- Library (partially intended for unqualified use) I have tried to adopt -- it for this library, in order to let Haskell programmers get -- accustomed easily to it. -- -- To do: Because many people requested it, we will provide a -- bracket function that frees a resource both when an exception -- and an error occurs, that is, it combines exception handling and -- debugging. However note that freeing resources in case of an error is -- dangerous and may cause further damage. @package explicit-exception @version 0.0.1 -- | Synchronous exceptions immediately abort a series of computations. We -- provide monads for describing this behaviour. module Control.Monad.Exception.Synchronous -- | Like Either, but explicitly intended for handling of -- exceptional results. In contrast to Either we do not support -- fail. Calling fail in the Exceptional monad is an -- error. data Exceptional e a Success :: a -> Exceptional e a Exception :: e -> Exceptional e a fromMaybe :: e -> Maybe a -> Exceptional e a fromEither :: Either e a -> Exceptional e a toEither :: Exceptional e a -> Either e a -- | If you are sure that the value is always a Success you can tell -- that the run-time system thus making your program lazy. However, try -- to avoid this function by using catch and friends, since this -- function is partial. force :: Exceptional e a -> Exceptional e a mapException :: (e0 -> e1) -> Exceptional e0 a -> Exceptional e1 a mapExceptional :: (e0 -> e1) -> (a -> b) -> Exceptional e0 a -> Exceptional e1 b throw :: e -> Exceptional e a catch :: Exceptional e0 a -> (e0 -> Exceptional e1 a) -> Exceptional e1 a resolve :: (e -> a) -> Exceptional e a -> a -- | like ErrorT, but ExceptionalT is the better name in order to -- distinguish from real (programming) errors newtype ExceptionalT e m a ExceptionalT :: m (Exceptional e a) -> ExceptionalT e m a runExceptionalT :: ExceptionalT e m a -> m (Exceptional e a) fromErrorT :: (Monad m) => ErrorT e m a -> ExceptionalT e m a toErrorT :: (Monad m) => ExceptionalT e m a -> ErrorT e m a -- | see force forceT :: (Monad m) => ExceptionalT e m a -> ExceptionalT e m a mapExceptionT :: (Monad m) => (e0 -> e1) -> ExceptionalT e0 m a -> ExceptionalT e1 m a mapExceptionalT :: (m (Exceptional e0 a) -> n (Exceptional e1 b)) -> ExceptionalT e0 m a -> ExceptionalT e1 n b throwT :: (Monad m) => e -> ExceptionalT e m a catchT :: (Monad m) => ExceptionalT e0 m a -> (e0 -> ExceptionalT e1 m a) -> ExceptionalT e1 m a -- | If the enclosed monad has custom exception facilities, they could skip -- the cleanup code. Make sure, that this cannot happen by choosing an -- appropriate monad. bracketT :: (Monad m) => ExceptionalT e m h -> (h -> ExceptionalT e m ()) -> (h -> ExceptionalT e m a) -> ExceptionalT e m a resolveT :: (Monad m) => (e -> m a) -> ExceptionalT e m a -> m a tryT :: (Monad m) => ExceptionalT e m a -> m (Exceptional e a) -- | Repeat an action until an exception occurs. Initialize the result with -- empty and add new elements using cons (e.g. -- [] and (:)). The exception handler decides whether -- the terminating exception is re-raised (Just) or catched -- (Nothing). manyT :: (Monad m) => (e0 -> Maybe e1) -> (a -> b -> b) -> b -> ExceptionalT e0 m a -> ExceptionalT e1 m b instance (Show e, Show a) => Show (Exceptional e a) instance (Eq e, Eq a) => Eq (Exceptional e a) instance MonadTrans (ExceptionalT e) instance (MonadFix m) => MonadFix (ExceptionalT e m) instance (Monad m) => Monad (ExceptionalT e m) instance (Applicative m) => Applicative (ExceptionalT e m) instance (Functor m) => Functor (ExceptionalT e m) instance MonadFix (Exceptional e) instance Monad (Exceptional e) instance Applicative (Exceptional e) instance Functor (Exceptional e) -- | Asynchronous exceptions can occur during the construction of a lazy -- data structure. They are represent by a lazy data structure itself. -- -- TODO: -- -- module Control.Monad.Exception.Asynchronous -- | Contains a value and a reason why the computation of the value of type -- a was terminated. Imagine a as a list type, and an -- according operation like the readFile operation. If the -- exception part is Nothing then the value could be constructed -- regularly. If the exception part is Just then the value could -- not be constructed completely. However you can read the result of type -- a lazily, even if an exception occurs while it is evaluated. -- If you evaluate the exception part, then the result value is certainly -- computed completely. -- -- However, we cannot provide functions that combine several -- Exceptional values, due to the very different ways of combining -- the results of type a. It is recommended to process the -- result value in an application specific way, and after consumption of -- the result, throw a synchronous exception using toSynchronous. data Exceptional e a Exceptional :: Maybe e -> a -> Exceptional e a exception :: Exceptional e a -> Maybe e result :: Exceptional e a -> a -- | Create an exceptional value without exception. pure :: a -> Exceptional e a -- | Create an exceptional value with exception. broken :: e -> a -> Exceptional e a fromSynchronous :: a -> Exceptional e a -> Exceptional e a fromSynchronousNull :: Exceptional e () -> Exceptional e () toSynchronous :: Exceptional e a -> Exceptional e a throw :: e -> Exceptional e () -- | Repeat an action with synchronous exceptions until an exception -- occurs. Combine all atomic results using the bind function. -- It may be cons = (:) and empty = [] for b -- being a list type. The defer function may be id or -- unsafeInterleaveIO for lazy read operations. The exception is -- returned as asynchronous exception. manySynchronousT :: (Monad m) => (m (Exceptional e b) -> m (Exceptional e b)) -> (a -> b -> b) -> b -> ExceptionalT e m a -> m (Exceptional e b) -- | Scan x using the decons function and run an action -- with synchronous exceptions for each element fetched from x. -- Each invocation of an element action may stop this function due to an -- exception. If all element action can be performed successfully and if -- there is an asynchronous exception then at the end this exception is -- raised as synchronous exception. decons function might be -- viewL. processToSynchronousT_ :: (Monad m) => (b -> Maybe (a, b)) -> (a -> ExceptionalT e m ()) -> Exceptional e b -> ExceptionalT e m () -- | This is an example for application specific handling of result values. -- Assume you obtain two lazy lists say from readFile and you want -- to zip their contents. If one of the stream readers emits an -- exception, we quit with that exception. If both streams have throw an -- exception at the same file position, the exception of the first stream -- is propagated. zipWith :: (a -> b -> c) -> Exceptional e [a] -> Exceptional e [b] -> Exceptional e [c] -- | construct Exceptional constructor lazily force :: Exceptional e a -> Exceptional e a traverse :: (Applicative f) => (a -> f b) -> Exceptional e a -> f (Exceptional e b) sequenceA :: (Applicative f) => Exceptional e (f a) -> f (Exceptional e a) mapM :: (Monad m) => (a -> m b) -> Exceptional e a -> m (Exceptional e b) sequence :: (Monad m) => Exceptional e (m a) -> m (Exceptional e a) instance (Show e, Show a) => Show (Exceptional e a) instance Functor (Exceptional e)