-- 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.
--   
--   Changes
--   
--   <ul>
--   <li><i>0.3.0.0</i> Fix erroneous behavior in <tt>foldExceptional</tt>
--   function added in version 0.2. This release actually does break (or
--   rather fix) the <tt>foldExceptional</tt> function, so be careful.</li>
--   <li><i>0.2.0.0</i> Add <tt>exceptional</tt> function to encapsulate
--   ordinary exceptions in the <tt>Exceptional</tt> monad. Add folding
--   functions.</li>
--   </ul>
--   
--   This release does not actually break the API, however I was rather
--   tired when I chose the version number. This should be 0.1.6.
--   
--   <ul>
--   <li><i>0.1.5.0</i> Add <tt>exceptIO</tt> function to encapsulate IO
--   errors in the <tt>Exceptional</tt> monad.</li>
--   <li><i>0.1.4.3</i> Fix bug where <tt>exceptional</tt> won't compile on
--   <tt>base &lt; 4.8</tt>. Also move the changelog back to the
--   description so it's more visible.</li>
--   <li><i>0.1.4.2</i> Moved change log to a separate file so Hackage
--   displays it correctly.</li>
--   <li><i>0.1.4.1</i> Documentation enhancements/fixes.</li>
--   <li><i>0.1.4.0</i> Added <tt>fromMaybe</tt> and <tt>toMaybe</tt>
--   functions, and a link to the bug tracker.</li>
--   <li><i>0.1.3.0</i> Fixed a typo. 0.1.2.0 won't build. Also added
--   definition of <tt>empty</tt> for <tt>Alternative</tt>.</li>
--   <li><i>0.1.2.0</i> Added <tt>fromEither</tt> and <tt>toEither</tt>
--   functions.</li>
--   <li><i>0.1.1.3</i> Hackage is terrible. Yet another formatting
--   fix.</li>
--   <li><i>0.1.1.2</i> Yet another formatting fix.</li>
--   <li><i>0.1.1.1</i> Formatting fix to the haddock documentation.</li>
--   <li><i>0.1.1.0</i> Add <tt>runExceptional</tt> function.</li>
--   <li><i>0.1.0.1</i> Minor documentation changes. No changes to the
--   API.</li>
--   <li><i>0.1.0.0</i> Initial version</li>
--   </ul>
@package exceptional
@version 0.3.0.0

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

-- | A wrapper around <a>tryIOError</a>. Encapsulates I/O exceptions in the
--   <a>Exceptional</a> monad.
exceptIO :: IO a -> IO (Exceptional a)

-- | Run an exception-prone action in another monad, catch the errors in
--   <a>Exceptional</a>.
exceptional :: MonadCatch m => m a -> m (Exceptional a)

-- | Get all of the <a>Failure</a>s from a bunch of <a>Exceptional</a>s
failures :: Foldable t => t (Exceptional x) -> [String]

-- | Get all of the <a>Success</a>es from a bunch of <a>Exceptional</a>s
successes :: Foldable t => t (Exceptional x) -> [x]

-- | Given a number of <a>Exceptional</a> values:
--   
--   <ul>
--   <li>If all are <a>Success</a>ful, then return <a>Right</a> with the
--   sucesses * If there is at least one <a>Failure</a>, then return
--   <a>Left</a> the list of error messages</li>
--   </ul>
foldExceptional :: (Foldable t) => t (Exceptional x) -> Either [String] [x]
instance GHC.Read.Read x => GHC.Read.Read (Control.Exceptional.Exceptional x)
instance GHC.Show.Show x => GHC.Show.Show (Control.Exceptional.Exceptional x)
instance GHC.Classes.Eq x => GHC.Classes.Eq (Control.Exceptional.Exceptional x)
instance GHC.Base.Functor Control.Exceptional.Exceptional
instance GHC.Base.Applicative Control.Exceptional.Exceptional
instance GHC.Base.Alternative Control.Exceptional.Exceptional
instance GHC.Base.Monad Control.Exceptional.Exceptional
