Servant.Checked.Exceptions.Internal.Servant.API

This module defines the Throws and Throwing types.

Documentation

data Throws (e :: *)

Throws is used in Servant API definitions and signifies that an API will throw the given error.

Here is an example of how to create an API that potentially returns a String as an error, or an Int on success:

>>> import Servant.API (Get, JSON, (:>))
>>> type API = Throws String :> Get '[JSON] Int

Instances

HasDocs (Throwing (Snoc es e) :> api) => HasDocs (Throwing es :> (Throws e :> api) :: Type)

When a Throws e comes immediately after a Throwing es, Snoc the e onto the es.

Defined in Servant.Checked.Exceptions.Internal.Servant.Docs

Methods

docsFor :: Proxy (Throwing es :> (Throws e :> api)) -> (Endpoint, Action) -> DocOptions -> API

HasDocs (Throwing '[e] :> api) => HasDocs (Throws e :> api :: Type)

Change a Throws into Throwing.

Defined in Servant.Checked.Exceptions.Internal.Servant.Docs

Methods

docsFor :: Proxy (Throws e :> api) -> (Endpoint, Action) -> DocOptions -> API

data NoThrow

NoThrow is used to indicate that an API will not throw an error, but that it will still return a response wrapped in a Envelope.

Examples

Create an API using NoThrow:

>>> import Servant.API (Get, JSON, (:>))
>>> type API = NoThrow :> Get '[JSON] Int

A servant-server handler for this type would look like the following:

  apiHandler :: Handler (Envelope '[] Int)
  apiHandler = pureSuccEnvelope 3

Instances

HasDocs (Verb method status ctypes (Envelope ('[] :: [Type]) a)) => HasDocs (NoThrow :> Verb method status ctypes a :: Type)

When NoThrow comes before a Verb, generate the documentation for the same Verb, but returning an Envelope '[].

Defined in Servant.Checked.Exceptions.Internal.Servant.Docs

Methods

docsFor :: Proxy (NoThrow :> Verb method status ctypes a) -> (Endpoint, Action) -> DocOptions -> API

data Throwing (e :: [*])

This is used internally and should not be used by end-users.

Instances

HasDocs (Throwing (Snoc es e) :> api) => HasDocs (Throwing es :> (Throws e :> api) :: Type)

When a Throws e comes immediately after a Throwing es, Snoc the e onto the es.

Defined in Servant.Checked.Exceptions.Internal.Servant.Docs

Methods

docsFor :: Proxy (Throwing es :> (Throws e :> api)) -> (Endpoint, Action) -> DocOptions -> API

(CreateRespBodiesFor es ctypes, HasDocs (Verb method status ctypes (Envelope es a))) => HasDocs (Throwing es :> Verb method status ctypes a :: Type)

When Throwing es comes before a Verb, generate the documentation for the same Verb, but returning an Envelope es. Also add documentation for the potential es.

Defined in Servant.Checked.Exceptions.Internal.Servant.Docs

Methods

docsFor :: Proxy (Throwing es :> Verb method status ctypes a) -> (Endpoint, Action) -> DocOptions -> API

type family ThrowingNonterminal api where ...

Used by the HasServer and HasClient instances for Throwing es :> api :> apis to detect Throwing es followed immediately by Throws e.

Equations

ThrowingNonterminal (Throwing es :> (Throws e :> api)) = Throwing (Snoc es e) :> api

ThrowingNonterminal (Throwing es :> (c :> api)) = c :> (Throwing es :> api)

class ErrStatus e where

Note that clients generated by servant-client currently don't handle status codes outside the 2XX range correctly. Take a look at the README for more details.

Methods

toErrStatus :: e -> Status

type family AllErrStatus (es :: [k]) :: Constraint where ...

Equations

AllErrStatus '[] = ()

AllErrStatus (a ': as) = (ErrStatus a, AllErrStatus as)

>>> :set -XDataKinds
>>> :set -XTypeOperators