-- 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.1.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

-- | Create an error from a <a>Show</a> type.
--   
--   If your type implements <a>Exception</a>, it is usually better to use
--   <a>exceptionToError</a> instead. Strings produced by <a>show</a> are
--   usually not very user-friendly.
--   
--   Note: goes via <a>String</a>, so not efficient.
showToError :: Show a => a -> Error

-- | Create an error from an <a>Exception</a> type.
--   
--   The default implementation of <a>displayException</a> is <a>show</a>,
--   so the same user-friendliness problems of <a>showToError</a> apply.
--   
--   Note: goes via <a>String</a>, so not efficient.
exceptionToError :: Exception exc => exc -> 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>
--   &gt;&gt;&gt; prettyError $ newError "file not found: ./foo"
--   "file not found: ./foo"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--     prettyError
--       $ addContext "Trying to open config file"
--         $ newError "file not found: ./foo"
--   :}
--   "Trying to open config file: file not found: ./foo"
--   </pre>
prettyError :: Error -> Text

-- | 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.
--   
--   <b>Panics</b>: if Error
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; expectError "something bad happened" $ Left (newError "oh no!")
--   *** Exception: something bad happened: oh no!
--   ...
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; expectError "something bad happened" $ Right 42
--   42
--   </pre>
expectError :: HasCallStack => Text -> Either Error p -> p

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