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


-- | The canonical error type
--   
--   A canonical <a>Error</a> type, which provides a way to turn an error
--   string into an <a>Error</a>, add context to an <a>Error</a>, and
--   pretty print the <a>Error</a> for displaying it to users.
@package error
@version 0.1.0.0

module Data.Error

-- | The canonical <tt>Error</tt> type.
--   
--   It can be
--   
--   <ul>
--   <li>created from a human-readable error message (<a>newError</a>)</li>
--   <li>more semantic context can be added to an existing <tt>Error</tt>
--   (<a>addContext</a>)</li>
--   <li>pretty-printed (<a>prettyError</a>)</li>
--   </ul>
data Error

-- | Create an ad-hoc <a>Error</a> from an error message.
newError :: Text -> Error

-- | Add a higher-level context to an <a>Error</a>.
--   
--   For example, your code hits a “file not found” I/O exception. Instead
--   of propagating it unseen, you catch it and annotate it with
--   <a>addContext</a>, and describe why you wanted to open the file in the
--   first place:
--   
--   <pre>
--   addContext "Trying to open config file"
--     $ newError "file not found: ./foo"
--   </pre>
--   
--   This way, when a user see the error, they will understand better what
--   happened:
--   
--   <pre>
--   "Trying to open config file: file not found: ./foo"
--   </pre>
--   
--   See <a>prettyError</a>.
addContext :: Text -> Error -> Error

-- | Pretty print the error.
--   
--   It will print all context messages, starting with the outermost.
--   
--   Example:
--   
--   <pre>
--   prettyError $ newError "file not found: ./foo"
--   
--   ==&gt; "file not found: ./foo"
--   
--   prettyError
--     $ addContext "Trying to open config file"
--       $ newError "file not found: ./foo"
--   
--   ==&gt; "Trying to open config file: file not found: ./foo"
--   </pre>
prettyError :: Error -> Text

-- | Return the value from a potentially failing computation.
--   
--   Abort with the <a>Error</a>s message if it was a <a>Left</a>.
--   
--   Panic: if Error
--   
--   Example:
--   
--   <pre>
--   unwrapError $ Left (newError "oh no!")
--   
--   ==&gt; *** Exception: oh no!
--   
--   unwrapError $ Right 42
--   
--   ==&gt; 42
--   </pre>
unwrapError :: Either Error p -> p

-- | Return the value from a potentially failing computation.
--   
--   Abort with the error message if it was an error.
--   
--   The text message is added to the <a>Error</a> as additional context
--   before aborting.
--   
--   Panic: if Error
--   
--   Example:
--   
--   <pre>
--   exceptError "something bad happened" $ Left (newError "oh no!")
--   
--   ==&gt; *** Exception: something bad happened: oh no!
--   
--   exceptError $ Right 42
--   
--   ==&gt; 42
--   </pre>
expectError :: Text -> Either Error p -> p