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


-- | Essentially the Maybe type with error messages.
--   
--   This is a very simple type:
--   
--   <pre>
--   data Exceptional x
--     = Failure String
--     | Success x
--   </pre>
--   
--   It's much like <tt>Maybe</tt>, except instead of <tt>Nothing</tt>, we
--   have <tt>Failure String</tt>.
--   
--   A comparison could also be made to <tt>Either String</tt>. I made this
--   library because I was dissatisfied with the <tt>Monad</tt> instance
--   for <tt>Either</tt>. In this type, <tt>fail = Failure</tt>. It's
--   rather simple.
@package exceptional
@version 0.1.4.2

module Control.Exceptional

-- | This is basically specialized 'Either String', or <a>Maybe</a> with
--   error messages.
data Exceptional x
[Failure] :: String -> Exceptional x
[Success] :: x -> Exceptional x

-- | This is <a>fail</a>-safe, so to speak. That is,
--   
--   <pre>
--   fail = Failure
--   </pre>

-- | Convert <a>Exceptional</a> into another <a>Monad</a>. If you don't
--   have proper exception handling in your monad, this can throw errors.
--   
--   <pre>
--   runExceptional (Failure s) = fail s
--   runExceptional (Success s) = pure s
--   </pre>
runExceptional :: Monad m => Exceptional x -> m x

-- | Convert a <a>Maybe</a> to an <a>Exceptional</a>
--   
--   <pre>
--   fromMaybe s Nothing = fail s
--   fromMaybe s (Just x) = pure x
--   </pre>
fromMaybe :: String -> Maybe a -> Exceptional a

-- | Convert an <a>Exceptional</a> into a <a>Maybe</a>. This function
--   disregards the error message.
--   
--   <pre>
--   toMaybe (Success x) = Just x
--   toMaybe (Failure _) = Nothing
--   </pre>
toMaybe :: Exceptional a -> Maybe a

-- | Convert an <a>Either</a> <a>String</a> to an <a>Exceptional</a>
--   
--   <pre>
--   fromEither (Left s) = fail s
--   fromEither (Right x) = pure x
--   </pre>
fromEither :: Either String a -> Exceptional a

-- | Convert an <a>Exceptional</a> to an <a>Either</a> <a>String</a>
--   
--   <pre>
--   toEither (Failure s) = Left s
--   toEither (Success x) = Right x
--   </pre>
toEither :: Exceptional a -> Either String a
instance Read x => Read (Exceptional x)
instance Show x => Show (Exceptional x)
instance Eq x => Eq (Exceptional x)
instance Functor Exceptional
instance Applicative Exceptional
instance Alternative Exceptional
instance Monad Exceptional