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


-- | Simplified error-handling
--   
--   The one-stop shop for all your error-handling needs! Just import
--   <a>Control.Error</a>.
--   
--   This library encourages an error-handling style that directly uses the
--   type system, rather than out-of-band exceptions.
@package errors
@version 1.4.7


-- | This module provides <a>throwE</a> and <a>catchE</a> for
--   <a>Either</a>. These two functions reside here because <a>throwE</a>
--   and <a>catchE</a> correspond to <a>return</a> and (<a>&gt;&gt;=</a>)
--   for the flipped <a>Either</a> monad: <a>EitherR</a>. Similarly, this
--   module defines <a>throwT</a> and <a>catchT</a> for <a>EitherT</a>,
--   which correspond to the <a>Monad</a> operations for <a>EitherRT</a>.
--   
--   These throw and catch functions improve upon <tt>MonadError</tt>
--   because:
--   
--   <ul>
--   <li><tt>catch</tt> is more general and allows you to change the left
--   value's type</li>
--   <li>They are Haskell98</li>
--   </ul>
--   
--   More advanced users can use <a>EitherR</a> and <a>EitherRT</a> to
--   program in an entirely symmetric "success monad" where exceptional
--   results are the norm and successful results terminate the computation.
--   This allows you to chain error-handlers using <tt>do</tt> notation and
--   pass around exceptional values of varying types until you can finally
--   recover from the error:
--   
--   <pre>
--   runEitherRT $ do
--       e2   &lt;- ioExceptionHandler e1
--       bool &lt;- arithmeticExceptionhandler e2
--       when bool $ lift $ putStrLn "DEBUG: Arithmetic handler did something"
--   </pre>
--   
--   If any of the above error handlers <a>succeed</a>, no other handlers
--   are tried.
--   
--   If you choose not to typefully distinguish between the error and
--   sucess monad, then use <a>flipE</a> and <a>flipET</a>, which swap the
--   type variables without changing the type.
module Data.EitherR

-- | If "<tt>Either e r</tt>" is the error monad, then "<tt>EitherR r
--   e</tt>" is the corresponding success monad, where:
--   
--   <ul>
--   <li><a>return</a> is <a>throwE</a>.</li>
--   <li>(<a>&gt;&gt;=</a>) is <a>catchE</a>.</li>
--   <li>Successful results abort the computation</li>
--   </ul>
newtype EitherR r e
EitherR :: Either e r -> EitherR r e
runEitherR :: EitherR r e -> Either e r

-- | Complete error handling, returning a result
succeed :: r -> EitherR r e

-- | <a>throwE</a> in the error monad corresponds to <a>return</a> in the
--   success monad
throwE :: e -> Either e r

-- | <a>catchE</a> in the error monad corresponds to (<a>&gt;&gt;=</a>) in
--   the success monad
catchE :: Either a r -> (a -> Either b r) -> Either b r

-- | <a>catchE</a> with the arguments flipped
handleE :: (a -> Either b r) -> Either a r -> Either b r

-- | Map a function over the <a>Left</a> value of an <a>Either</a>
fmapL :: (a -> b) -> Either a r -> Either b r

-- | Flip the type variables of <a>Either</a>
flipE :: Either a b -> Either b a

-- | <a>EitherR</a> converted into a monad transformer
newtype EitherRT r m e
EitherRT :: EitherT e m r -> EitherRT r m e
runEitherRT :: EitherRT r m e -> EitherT e m r

-- | Complete error handling, returning a result
succeedT :: Monad m => r -> EitherRT r m e

-- | <a>throwT</a> in the error monad corresponds to <a>return</a> in the
--   success monad
throwT :: Monad m => e -> EitherT e m r

-- | <a>catchT</a> in the error monad corresponds to (<a>&gt;&gt;=</a>) in
--   the success monad
catchT :: Monad m => EitherT a m r -> (a -> EitherT b m r) -> EitherT b m r

-- | <a>catchT</a> with the arguments flipped
handleT :: Monad m => (a -> EitherT b m r) -> EitherT a m r -> EitherT b m r

-- | Map a function over the <a>Left</a> value of an <a>EitherT</a>
fmapLT :: Monad m => (a -> b) -> EitherT a m r -> EitherT b m r

-- | Flip the type variables of an <a>EitherT</a>
flipET :: Monad m => EitherT a m b -> EitherT b m a
instance MonadIO m => MonadIO (EitherRT r m)
instance MonadTrans (EitherRT r)
instance (Monad m, Monoid r) => MonadPlus (EitherRT r m)
instance (Monad m, Monoid r) => Alternative (EitherRT r m)
instance Monad m => Monad (EitherRT r m)
instance Monad m => Applicative (EitherRT r m)
instance Monad m => Functor (EitherRT r m)
instance Monoid r => MonadPlus (EitherR r)
instance Monoid r => Alternative (EitherR r)
instance Monad (EitherR r)
instance Applicative (EitherR r)
instance Functor (EitherR r)


-- | This module exports miscellaneous error-handling functions.
module Control.Error.Util

-- | Suppress the <a>Left</a> value of an <a>Either</a>
hush :: Either a b -> Maybe b

-- | Suppress the <a>Left</a> value of an <a>EitherT</a>
hushT :: Monad m => EitherT a m b -> MaybeT m b

-- | Tag the <a>Nothing</a> value of a <a>Maybe</a>
note :: a -> Maybe b -> Either a b

-- | Tag the <a>Nothing</a> value of a <a>MaybeT</a>
noteT :: Monad m => a -> MaybeT m b -> EitherT a m b

-- | Lift a <a>Maybe</a> to the <a>MaybeT</a> monad
hoistMaybe :: Monad m => Maybe b -> MaybeT m b

-- | Convert a <a>Maybe</a> value into the <a>EitherT</a> monad
(??) :: Applicative m => Maybe a -> e -> EitherT e m a

-- | Convert an applicative <a>Maybe</a> value into the <a>EitherT</a>
--   monad
(!?) :: Applicative m => m (Maybe a) -> e -> EitherT e m a

-- | Convert a <a>Maybe</a> value into the <a>EitherT</a> monad
--   
--   Named version of (<a>??</a>) with arguments flipped
failWith :: Applicative m => e -> Maybe a -> EitherT e m a

-- | Convert an applicative <a>Maybe</a> value into the <a>EitherT</a>
--   monad
--   
--   Named version of (<a>!?</a>) with arguments flipped
failWithM :: Applicative m => e -> m (Maybe a) -> EitherT e m a

-- | Case analysis for the <a>Bool</a> type.
--   
--   <pre>
--   bool a b c == if c then b else a
--   </pre>
bool :: a -> a -> Bool -> a

-- | An infix form of <a>fromMaybe</a> with arguments flipped.
(?:) :: Maybe a -> a -> a

-- | Case analysis for <a>MaybeT</a>
--   
--   Use the first argument if the <a>MaybeT</a> computation fails,
--   otherwise apply the function to the successful result.
maybeT :: Monad m => m b -> (a -> m b) -> MaybeT m a -> m b

-- | Analogous to <a>Just</a> and equivalent to <a>return</a>
just :: Monad m => a -> MaybeT m a

-- | Analogous to <a>Nothing</a> and equivalent to <tt>mzero</tt>
nothing :: Monad m => MaybeT m a

-- | Analogous to <a>isJust</a>, but for <a>MaybeT</a>
isJustT :: Monad m => MaybeT m a -> m Bool

-- | Analogous to <a>isNothing</a>, but for <a>MaybeT</a>
isNothingT :: Monad m => MaybeT m a -> m Bool

-- | Returns whether argument is a <a>Left</a>
isLeft :: Either a b -> Bool

-- | Returns whether argument is a <a>Right</a>
isRight :: Either a b -> Bool

-- | <a>fmap</a> specialized to <a>Either</a>, given a name symmetric to
--   <a>fmapL</a>
fmapR :: (a -> b) -> Either l a -> Either l b

-- | Run multiple <a>Either</a> computations and succeed if all of them
--   succeed
--   
--   <a>mappend</a>s all successes or failures
newtype AllE e r
AllE :: Either e r -> AllE e r
runAllE :: AllE e r -> Either e r

-- | Run multiple <a>Either</a> computations and succeed if any of them
--   succeed
--   
--   <a>mappend</a>s all successes or failures
newtype AnyE e r
AnyE :: Either e r -> AnyE e r
runAnyE :: AnyE e r -> Either e r

-- | Analogous to <a>isLeft</a>, but for <a>EitherT</a>
isLeftT :: Monad m => EitherT a m b -> m Bool

-- | Analogous to <a>isRight</a>, but for <a>EitherT</a>
isRightT :: Monad m => EitherT a m b -> m Bool

-- | <a>fmap</a> specialized to <a>EitherT</a>, given a name symmetric to
--   <a>fmapLT</a>
fmapRT :: Monad m => (a -> b) -> EitherT l m a -> EitherT l m b

-- | Write a string to standard error
err :: String -> IO ()

-- | Write a string with a newline to standard error
errLn :: String -> IO ()

-- | Catch <a>IOException</a>s and convert them to the <a>EitherT</a> monad
tryIO :: MonadIO m => IO a -> EitherT IOException m a

-- | Catch all exceptions, except for asynchronous exceptions found in
--   <tt>base</tt> and convert them to the <a>EitherT</a> monad
syncIO :: MonadIO m => IO a -> EitherT SomeException m a
instance (Monoid e, Monoid r) => Monoid (AnyE e r)
instance (Monoid e, Monoid r) => Monoid (AllE e r)


-- | Use this module if you like to write simple scripts with
--   <a>String</a>-based errors, but you prefer to use <a>EitherT</a> to
--   handle errors rather than <tt>Control.Exception</tt>.
--   
--   <pre>
--   import Control.Error
--   
--   main = runScript $ do
--       str &lt;- scriptIO getLine
--       n   &lt;- tryRead "Read failed" str
--       scriptIO $ print (n + 1)
--   </pre>
module Control.Error.Script

-- | An <a>IO</a> action that can fail with a <a>String</a> error message
type Script = EitherT String IO

-- | Runs the <a>Script</a> monad
--   
--   Prints the first error to <a>stderr</a> and exits with
--   <a>exitFailure</a>
runScript :: Script a -> IO a

-- | <a>scriptIO</a> resembles <a>lift</a>, except it catches all
--   exceptions and converts them to <a>String</a>s.
--   
--   Note that <a>scriptIO</a> is compatible with the <a>Script</a> monad.
scriptIO :: MonadIO m => IO a -> EitherT String m a


-- | This module extends the <tt>safe</tt> library's functions with
--   corresponding versions compatible with <a>Either</a> and
--   <a>EitherT</a>, and also provides a few <a>Maybe</a>-compatible
--   functions missing from <tt>safe</tt>.
--   
--   I suffix the <a>Either</a>-compatible functions with <tt>Err</tt> and
--   prefix the <a>EitherT</a>-compatible functions with <tt>try</tt>.
--   
--   Note that this library re-exports the <a>Maybe</a> compatible
--   functions from <tt>safe</tt> in the <a>Control.Error</a> module, so
--   they are not provided here.
--   
--   The '<tt>Z</tt>'-suffixed functions generalize the <a>Maybe</a>
--   functions to also work with anything that implements <a>MonadPlus</a>,
--   including:
--   
--   <ul>
--   <li>Lists</li>
--   <li>Most parsers</li>
--   <li><a>EitherT</a> (if the left value is a <tt>Monoid</tt>)</li>
--   </ul>
module Control.Error.Safe

-- | An assertion that fails in the <a>Maybe</a> monad
assertMay :: Bool -> Maybe ()

-- | A <tt>fromRight</tt> that fails in the <a>Maybe</a> monad
rightMay :: Either e a -> Maybe a

-- | A <a>tail</a> that fails in the <a>Either</a> monad
tailErr :: e -> [a] -> Either e [a]

-- | An <a>init</a> that fails in the <a>Either</a> monad
initErr :: e -> [a] -> Either e [a]

-- | A <a>head</a> that fails in the <a>Either</a> monad
headErr :: e -> [a] -> Either e a

-- | A <a>last</a> that fails in the <a>Either</a> monad
lastErr :: e -> [a] -> Either e a

-- | A <a>minimum</a> that fails in the <a>Either</a> monad
minimumErr :: Ord a => e -> [a] -> Either e a

-- | A <a>maximum</a> that fails in the <a>Either</a> monad
maximumErr :: Ord a => e -> [a] -> Either e a

-- | A <a>foldr1</a> that fails in the <a>Either</a> monad
foldr1Err :: e -> (a -> a -> a) -> [a] -> Either e a

-- | A <a>foldl1</a> that fails in the <a>Either</a> monad
foldl1Err :: e -> (a -> a -> a) -> [a] -> Either e a

-- | A <tt>foldl1'</tt> that fails in the <a>Either</a> monad
foldl1Err' :: e -> (a -> a -> a) -> [a] -> Either e a

-- | A (<a>!!</a>) that fails in the <a>Either</a> monad
atErr :: e -> [a] -> Int -> Either e a

-- | A <a>read</a> that fails in the <a>Either</a> monad
readErr :: Read a => e -> String -> Either e a

-- | An assertion that fails in the <a>Either</a> monad
assertErr :: e -> Bool -> Either e ()

-- | A <tt>fromJust</tt> that fails in the <a>Either</a> monad
justErr :: e -> Maybe a -> Either e a

-- | A <a>tail</a> that fails in the <a>EitherT</a> monad
tryTail :: Monad m => e -> [a] -> EitherT e m [a]

-- | An <a>init</a> that fails in the <a>EitherT</a> monad
tryInit :: Monad m => e -> [a] -> EitherT e m [a]

-- | A <a>head</a> that fails in the <a>EitherT</a> monad
tryHead :: Monad m => e -> [a] -> EitherT e m a

-- | A <a>last</a> that fails in the <a>EitherT</a> monad
tryLast :: Monad m => e -> [a] -> EitherT e m a

-- | A <a>minimum</a> that fails in the <a>EitherT</a> monad
tryMinimum :: (Monad m, Ord a) => e -> [a] -> EitherT e m a

-- | A <a>maximum</a> that fails in the <a>EitherT</a> monad
tryMaximum :: (Monad m, Ord a) => e -> [a] -> EitherT e m a

-- | A <a>foldr1</a> that fails in the <a>EitherT</a> monad
tryFoldr1 :: Monad m => e -> (a -> a -> a) -> [a] -> EitherT e m a

-- | A <a>foldl1</a> that fails in the <a>EitherT</a> monad
tryFoldl1 :: Monad m => e -> (a -> a -> a) -> [a] -> EitherT e m a

-- | A <tt>foldl1'</tt> that fails in the <a>EitherT</a> monad
tryFoldl1' :: Monad m => e -> (a -> a -> a) -> [a] -> EitherT e m a

-- | A (<a>!!</a>) that fails in the <a>EitherT</a> monad
tryAt :: Monad m => e -> [a] -> Int -> EitherT e m a

-- | A <a>read</a> that fails in the <a>EitherT</a> monad
tryRead :: (Monad m, Read a) => e -> String -> EitherT e m a

-- | An assertion that fails in the <a>EitherT</a> monad
tryAssert :: Monad m => e -> Bool -> EitherT e m ()

-- | A <tt>fromJust</tt> that fails in the <a>EitherT</a> monad
tryJust :: Monad m => e -> Maybe a -> EitherT e m a

-- | A <tt>fromRight</tt> that fails in the <a>EitherT</a> monad
tryRight :: Monad m => Either e a -> EitherT e m a

-- | A <a>tail</a> that fails using <a>mzero</a>
tailZ :: MonadPlus m => [a] -> m [a]

-- | An <a>init</a> that fails using <a>mzero</a>
initZ :: MonadPlus m => [a] -> m [a]

-- | A <a>head</a> that fails using <a>mzero</a>
headZ :: MonadPlus m => [a] -> m a

-- | A <a>last</a> that fails using <a>mzero</a>
lastZ :: MonadPlus m => [a] -> m a

-- | A <a>minimum</a> that fails using <a>mzero</a>
minimumZ :: MonadPlus m => Ord a => [a] -> m a

-- | A <a>maximum</a> that fails using <a>mzero</a>
maximumZ :: MonadPlus m => Ord a => [a] -> m a

-- | A <a>foldr1</a> that fails using <a>mzero</a>
foldr1Z :: MonadPlus m => (a -> a -> a) -> [a] -> m a

-- | A <a>foldl1</a> that fails using <a>mzero</a>
foldl1Z :: MonadPlus m => (a -> a -> a) -> [a] -> m a

-- | A <tt>foldl1'</tt> that fails using <a>mzero</a>
foldl1Z' :: MonadPlus m => (a -> a -> a) -> [a] -> m a

-- | A (<a>!!</a>) that fails using <a>mzero</a>
atZ :: MonadPlus m => [a] -> Int -> m a

-- | A <a>read</a> that fails using <a>mzero</a>
readZ :: MonadPlus m => Read a => String -> m a

-- | An assertion that fails using <a>mzero</a>
assertZ :: MonadPlus m => Bool -> m ()

-- | A <tt>fromJust</tt> that fails using <a>mzero</a>
justZ :: MonadPlus m => Maybe a -> m a

-- | A <tt>fromRight</tt> that fails using <a>mzero</a>
rightZ :: MonadPlus m => Either e a -> m a


-- | Import this module in your code to access the entire library's
--   functionality:
--   
--   <pre>
--   import Control.Error
--   </pre>
--   
--   This module exports the entire library as well as useful exports from
--   other standard error-handling libraries:
--   
--   <ul>
--   <li><a>Control.Error.Safe</a>: Generalizes the <tt>safe</tt> library,
--   including <a>Either</a>, <a>EitherT</a>, and <tt>MonadPlus</tt>
--   variations on total functions</li>
--   <li><a>Control.Error.Script</a>: Support for simple scripts that catch
--   all errors and transform them to <a>String</a>s</li>
--   <li><a>Control.Error.Util</a>: Utility functions and conversions
--   between common error-handling types</li>
--   <li><tt>Control.Monad.Trans.Either</tt>: The <a>EitherT</a> monad
--   transformer</li>
--   <li><tt>Control.Monad.Trans.Maybe</tt>: The <a>MaybeT</a> monad
--   transformer</li>
--   <li><tt>Data.Either</tt>: <a>Either</a> utility functions</li>
--   <li><a>Data.EitherR</a>: throw and catch functions, and their
--   corresponding "success" monads</li>
--   <li><tt>Data.Maybe</tt>: <a>Maybe</a> utility functions</li>
--   <li><tt>Safe</tt>: Total versions of partial Prelude functions</li>
--   </ul>
--   
--   This module does not re-export partial functions from other libraries.
module Control.Error
