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


-- | Extensible exceptions for servant API servers
--   
--   `servant-exceptions-server` provides the `servant-server` related
--   parts for `servant-exceptions`. Namely it catches declared exceptions
--   and renders responses using the handler content-type.
@package servant-exceptions-server
@version 0.2.1


-- | <a>HasServer</a> instances for the <a>Throws</a> api combinator.
module Servant.Exception.Server

-- | Declare that an API might throw errors of given type <tt>e</tt>.
data Throws e

-- | Type class to convert an <tt>e</tt> to servant's error types, e.g.
--   <tt>ServerError</tt> on the server side. Thus, servers use methods of
--   this class, along with <a>Typeable</a> and <a>Show</a> allow
--   convenient definition of how error responses should look like.
class (Typeable e, Show e) => ToServantErr e

-- | HTTP status code to return
status :: ToServantErr e => e -> Status

-- | A human-readable message to include. Default implementation uses
--   <a>Show</a>.
message :: ToServantErr e => e -> Text

-- | Additional headers to include in the response. Content-type headers
--   are created by default.
headers :: ToServantErr e => e -> [Header]

-- | A root exception type (see <a>Exception</a>) to provide a common
--   rendering format via <a>MimeRender</a> for builtin content types
--   <a>JSON</a> and <a>PlainText</a>.
data ServantException
toServantException :: (Exception e, ToJSON e, ToServantErr e) => e -> SomeException
fromServantException :: Exception e => SomeException -> Maybe e

-- | Any type that you wish to throw or catch as an exception must be an
--   instance of the <tt>Exception</tt> class. The simplest case is a new
--   exception type directly below the root:
--   
--   <pre>
--   data MyException = ThisException | ThatException
--       deriving Show
--   
--   instance Exception MyException
--   </pre>
--   
--   The default method definitions in the <tt>Exception</tt> class do what
--   we need in this case. You can now throw and catch
--   <tt>ThisException</tt> and <tt>ThatException</tt> as exceptions:
--   
--   <pre>
--   *Main&gt; throw ThisException `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: MyException))
--   Caught ThisException
--   </pre>
--   
--   In more complicated examples, you may wish to define a whole hierarchy
--   of exceptions:
--   
--   <pre>
--   ---------------------------------------------------------------------
--   -- Make the root exception type for all the exceptions in a compiler
--   
--   data SomeCompilerException = forall e . Exception e =&gt; SomeCompilerException e
--   
--   instance Show SomeCompilerException where
--       show (SomeCompilerException e) = show e
--   
--   instance Exception SomeCompilerException
--   
--   compilerExceptionToException :: Exception e =&gt; e -&gt; SomeException
--   compilerExceptionToException = toException . SomeCompilerException
--   
--   compilerExceptionFromException :: Exception e =&gt; SomeException -&gt; Maybe e
--   compilerExceptionFromException x = do
--       SomeCompilerException a &lt;- fromException x
--       cast a
--   
--   ---------------------------------------------------------------------
--   -- Make a subhierarchy for exceptions in the frontend of the compiler
--   
--   data SomeFrontendException = forall e . Exception e =&gt; SomeFrontendException e
--   
--   instance Show SomeFrontendException where
--       show (SomeFrontendException e) = show e
--   
--   instance Exception SomeFrontendException where
--       toException = compilerExceptionToException
--       fromException = compilerExceptionFromException
--   
--   frontendExceptionToException :: Exception e =&gt; e -&gt; SomeException
--   frontendExceptionToException = toException . SomeFrontendException
--   
--   frontendExceptionFromException :: Exception e =&gt; SomeException -&gt; Maybe e
--   frontendExceptionFromException x = do
--       SomeFrontendException a &lt;- fromException x
--       cast a
--   
--   ---------------------------------------------------------------------
--   -- Make an exception type for a particular frontend compiler exception
--   
--   data MismatchedParentheses = MismatchedParentheses
--       deriving Show
--   
--   instance Exception MismatchedParentheses where
--       toException   = frontendExceptionToException
--       fromException = frontendExceptionFromException
--   </pre>
--   
--   We can now catch a <tt>MismatchedParentheses</tt> exception as
--   <tt>MismatchedParentheses</tt>, <tt>SomeFrontendException</tt> or
--   <tt>SomeCompilerException</tt>, but not other types, e.g.
--   <tt>IOException</tt>:
--   
--   <pre>
--   *Main&gt; throw MismatchedParentheses `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: MismatchedParentheses))
--   Caught MismatchedParentheses
--   *Main&gt; throw MismatchedParentheses `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: SomeFrontendException))
--   Caught MismatchedParentheses
--   *Main&gt; throw MismatchedParentheses `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: SomeCompilerException))
--   Caught MismatchedParentheses
--   *Main&gt; throw MismatchedParentheses `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: IOException))
--   *** Exception: MismatchedParentheses
--   </pre>
class (Typeable e, Show e) => Exception e
toException :: Exception e => e -> SomeException
fromException :: Exception e => SomeException -> Maybe e

-- | Render this exception value in a human-friendly manner.
--   
--   Default implementation: <tt><a>show</a></tt>.
displayException :: Exception e => e -> String

-- | Catch and rethrow using mapping function <tt>f</tt>.
mapException :: (Exception e1, Exception e2, MonadCatch m) => (e1 -> e2) -> m a -> m a
instance forall e (ct :: [*]) k (mt :: k) (st :: GHC.Types.Nat) a (context :: [*]). (GHC.Exception.Type.Exception e, Servant.Exception.ToServantErr e, Servant.API.ContentTypes.AllMimeRender ct e, Servant.Server.Internal.HasServer (Servant.API.Verbs.Verb mt st ct a) context) => Servant.Server.Internal.HasServer (Servant.Exception.Throws e Servant.API.Sub.:> Servant.API.Verbs.Verb mt st ct a) context
instance forall k (api :: k) e upstream (context :: [*]). Servant.Server.Internal.HasServer (api Servant.API.Sub.:> (Servant.Exception.Throws e Servant.API.Sub.:> upstream)) context => Servant.Server.Internal.HasServer (Servant.Exception.Throws e Servant.API.Sub.:> (api Servant.API.Sub.:> upstream)) context
instance Servant.Server.Internal.HasServer ((Servant.Exception.Throws e Servant.API.Sub.:> api1) Servant.API.Alternative.:<|> (Servant.Exception.Throws e Servant.API.Sub.:> api2)) context => Servant.Server.Internal.HasServer (Servant.Exception.Throws e Servant.API.Sub.:> (api1 Servant.API.Alternative.:<|> api2)) context