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


-- | This module provides <a>throwEither</a> and <a>catchEither</a> for
--   <a>Either</a>. These two functions reside here because
--   <a>throwEither</a> and <a>catchEither</a> correspond to <a>return</a>
--   and (<a>&gt;&gt;=</a>) for the flipped <a>Either</a> monad:
--   <a>EitherR</a>. Additionally, this module defines <a>handleE</a> as
--   the flipped version of <a>catchE</a> for <a>ExceptT</a>.
--   
--   <a>throwEither</a> and <a>catchEither</a> improve upon
--   <tt>MonadError</tt> because:
--   
--   <ul>
--   <li><a>catchEither</a> is more general than <tt>catch</tt> and allows
--   you to change the left value's type</li>
--   <li>Both are Haskell98</li>
--   </ul>
--   
--   More advanced users can use <a>EitherR</a> and <a>ExceptRT</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>
--   runExceptRT $ 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>flipEither</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>throwEither</a>.</li>
--   <li>(<a>&gt;&gt;=</a>) is <a>catchEither</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>throwEither</a> in the error monad corresponds to <a>return</a> in
--   the success monad
throwEither :: e -> Either e r

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

-- | <a>catchEither</a> with the arguments flipped
handleEither :: (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>
flipEither :: Either a b -> Either b a

-- | <a>EitherR</a> converted into a monad transformer
newtype ExceptRT r m e
ExceptRT :: ExceptT e m r -> ExceptRT r m e
[runExceptRT] :: ExceptRT r m e -> ExceptT e m r

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

-- | <tt>catchT</tt> with the arguments flipped
handleE :: (Monad m) => (a -> ExceptT b m r) -> ExceptT a m r -> ExceptT b m r

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

-- | Flip the type variables of an <a>ExceptT</a>
flipET :: (Monad m) => ExceptT a m b -> ExceptT b m a
instance GHC.Base.Functor (Data.EitherR.EitherR r)
instance GHC.Base.Applicative (Data.EitherR.EitherR r)
instance GHC.Base.Monad (Data.EitherR.EitherR r)
instance GHC.Base.Monoid r => GHC.Base.Alternative (Data.EitherR.EitherR r)
instance GHC.Base.Monoid r => GHC.Base.MonadPlus (Data.EitherR.EitherR r)
instance GHC.Base.Monad m => GHC.Base.Functor (Data.EitherR.ExceptRT r m)
instance GHC.Base.Monad m => GHC.Base.Applicative (Data.EitherR.ExceptRT r m)
instance GHC.Base.Monad m => GHC.Base.Monad (Data.EitherR.ExceptRT r m)
instance (GHC.Base.Monad m, GHC.Base.Monoid r) => GHC.Base.Alternative (Data.EitherR.ExceptRT r m)
instance (GHC.Base.Monad m, GHC.Base.Monoid r) => GHC.Base.MonadPlus (Data.EitherR.ExceptRT r m)
instance Control.Monad.Trans.Class.MonadTrans (Data.EitherR.ExceptRT r)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Data.EitherR.ExceptRT r m)


-- | 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>ExceptT</a>
hushT :: (Monad m) => ExceptT 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 -> ExceptT a m b

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

-- | Upgrade an <a>Either</a> to an <a>ExceptT</a>
hoistEither :: Monad m => Either e a -> ExceptT e m a

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

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

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

-- | Convert an applicative <a>Maybe</a> value into the <a>ExceptT</a>
--   monad
--   
--   Named version of (<a>!?</a>) with arguments flipped
failWithM :: Applicative m => e -> m (Maybe a) -> ExceptT 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>ExceptT</a>
isLeftT :: (Monad m) => ExceptT a m b -> m Bool

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

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

-- | Fold an <a>ExceptT</a> by providing one continuation for each
--   constructor
exceptT :: Monad m => (a -> m c) -> (b -> m c) -> ExceptT a m b -> m c

-- | Transform the left and right value
bimapExceptT :: Functor m => (e -> f) -> (a -> b) -> ExceptT e m a -> ExceptT f 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>ExceptT</a> monad
tryIO :: MonadIO m => IO a -> ExceptT IOException m a

-- | Catch all exceptions, except for asynchronous exceptions found in
--   <tt>base</tt> and convert them to the <a>ExceptT</a> monad
syncIO :: Unexceptional m => IO a -> ExceptT SomeException m a
instance (GHC.Base.Monoid e, GHC.Base.Monoid r) => GHC.Base.Monoid (Control.Error.Util.AllE e r)
instance (GHC.Base.Monoid e, GHC.Base.Monoid r) => GHC.Base.Monoid (Control.Error.Util.AnyE e r)


-- | Use this module if you like to write simple scripts with
--   <a>String</a>-based errors, but you prefer to use <a>ExceptT</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 = ExceptT 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 -> ExceptT String m a


-- | This module extends the <tt>safe</tt> library's functions with
--   corresponding versions compatible with <a>Either</a> and
--   <a>ExceptT</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>ExceptT</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>ExceptT</a> (if the left value is a <a>Monoid</a>)</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>ExceptT</a> monad
tryTail :: (Monad m) => e -> [a] -> ExceptT e m [a]

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

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

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

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

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

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

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

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

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

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

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

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

-- | A <tt>fromRight</tt> that fails in the <a>ExceptT</a> monad
tryRight :: (Monad m) => Either e a -> ExceptT 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>, <tt>EitherT</tt>, 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.Except</tt>: The <a>ExceptT</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
