Copyright | (c) Justin Le 2019 |
---|---|
License | BSD3 |
Maintainer | justin@jle.im |
Stability | experimental |
Portability | non-portable |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
Main module providing underlying functionality for the command line interface parser for servant API clients.
For the most part, you can ignore this module unless you're adding new API combinators.
Synopsis
- class HasCLI m api ctx where
- type CLIResult (m :: Type -> Type) (api :: Type) :: Type
- type CLIHandler (m :: Type -> Type) (api :: Type) (r :: Type) :: Type
- cliPStructWithContext_ :: Proxy m -> Proxy api -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m api))
- cliHandler :: Proxy m -> Proxy api -> Proxy ctx -> CLIHandler m api r -> CLIResult m api -> r
- data family ContextFor (m :: Type -> Type) :: Type -> Type
- newtype NamedContext m (name :: Symbol) (subContext :: [Type]) = NamedContext (Rec (ContextFor m) subContext)
- descendIntoNamedContext :: forall (name :: Symbol) context subContext m. NamedContext m name subContext ∈ context => Proxy name -> Rec (ContextFor m) context -> Rec (ContextFor m) subContext
Class
class HasCLI m api ctx where Source #
Typeclass defining how each API combinator influences how a server can be interacted with using command line options.
Note that query parameters and captures all require servant-docs annotation instances, to allow for proper help messages.
Unless you are adding new combinators to be used with APIs, you can ignore this class.
type CLIResult (m :: Type -> Type) (api :: Type) :: Type Source #
The parsed type of the client request response. Usually this will
be a bunch of nested Either
s for every API endpoint, nested
according to the :<|>
s in the API.
type CLIHandler (m :: Type -> Type) (api :: Type) (r :: Type) :: Type Source #
The type of a data structure to conveniently handle the results of
all pontential endpoints. This is useful because it is often
tedious to handle the bunch of nested Either
s that CLIResult
has.
It essentially lets you specify how to sort each potential endpoint's response into a single output value.
Usually this will be a bunch of nested :<|>
s which handle each
endpoint, according to the :<|>
s in the API. It mirrors the
structure of Client
and ServerT
.
Used with functions like parseHandleClient
.
cliPStructWithContext_ :: Proxy m -> Proxy api -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m api)) Source #
Create a structure for a command line parser, which parses how to
modify a RequestF
and perform an action, given an API and
underlying monad. Only meant for internal use; should be used
through cliPStructWithContext
instead.
Takes a Rec
of actions to generate required items that cannot be
passed via the command line (like authentication). Pass in RNil
if no parameters are expected. The actions will only be run if they
are needed.
cliHandler :: Proxy m -> Proxy api -> Proxy ctx -> CLIHandler m api r -> CLIResult m api -> r Source #
Handle all the possibilities in a CLIResult
, by giving the
appropriate CLIHandler
.
Instances
HasCLI m EmptyAPI ctx Source # |
The branch ending in One can use |
Defined in Servant.CLI.HasCLI | |
RunClient m => HasCLI m Raw ctx Source # | Asks for method as a command line argument. If any |
Defined in Servant.CLI.HasCLI | |
(HasCLI m a ctx, HasCLI m b ctx, Functor m) => HasCLI m (a :<|> b) ctx Source # | Using alternation with |
Defined in Servant.CLI.HasCLI | |
(RunClient m, ReflectMethod method) => HasCLI m (NoContentVerb method) ctx Source # | Final actions are the result of specifying all necessary command line positional arguments. All command line options are associated with the final action at the end of their endpoint/path. They cannot be entered in "before" you arrive at your final endpoint. If more than one action (under a different method) exists
under the same endpoint/path, the method ( |
Defined in Servant.CLI.HasCLI type CLIResult m (NoContentVerb method) Source # type CLIHandler m (NoContentVerb method) r Source # cliPStructWithContext_ :: Proxy m -> Proxy (NoContentVerb method) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (NoContentVerb method))) Source # cliHandler :: Proxy m -> Proxy (NoContentVerb method) -> Proxy ctx -> CLIHandler m (NoContentVerb method) r -> CLIResult m (NoContentVerb method) -> r Source # | |
(KnownSymbol path, HasCLI m api ctx) => HasCLI m (path :> api) ctx Source # | A path component is interpreted as a "subcommand". |
Defined in Servant.CLI.HasCLI | |
HasCLI m api ctx => HasCLI m (HttpVersion :> api) ctx Source # | Using |
Defined in Servant.CLI.HasCLI type CLIResult m (HttpVersion :> api) Source # type CLIHandler m (HttpVersion :> api) r Source # cliPStructWithContext_ :: Proxy m -> Proxy (HttpVersion :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (HttpVersion :> api))) Source # cliHandler :: Proxy m -> Proxy (HttpVersion :> api) -> Proxy ctx -> CLIHandler m (HttpVersion :> api) r -> CLIResult m (HttpVersion :> api) -> r Source # | |
(ToAuthInfo (BasicAuth realm usr), HasCLI m api ctx, BasicAuth realm usr ∈ ctx, Monad m) => HasCLI m (BasicAuth realm usr :> api) ctx Source # | Add Please use a secure connection! |
Defined in Servant.CLI.HasCLI type CLIResult m (BasicAuth realm usr :> api) Source # type CLIHandler m (BasicAuth realm usr :> api) r Source # cliPStructWithContext_ :: Proxy m -> Proxy (BasicAuth realm usr :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (BasicAuth realm usr :> api))) Source # cliHandler :: Proxy m -> Proxy (BasicAuth realm usr :> api) -> Proxy ctx -> CLIHandler m (BasicAuth realm usr :> api) r -> CLIResult m (BasicAuth realm usr :> api) -> r Source # | |
(FromHttpApiData a, ToHttpApiData a, Typeable a, ToCapture (Capture sym a), HasCLI m api ctx) => HasCLI m (Capture' mods sym a :> api) ctx Source # | A Note that these require |
Defined in Servant.CLI.HasCLI type CLIResult m (Capture' mods sym a :> api) Source # type CLIHandler m (Capture' mods sym a :> api) r Source # cliPStructWithContext_ :: Proxy m -> Proxy (Capture' mods sym a :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (Capture' mods sym a :> api))) Source # cliHandler :: Proxy m -> Proxy (Capture' mods sym a :> api) -> Proxy ctx -> CLIHandler m (Capture' mods sym a :> api) r -> CLIResult m (Capture' mods sym a :> api) -> r Source # | |
(FromHttpApiData a, ToHttpApiData a, Typeable a, ToCapture (CaptureAll sym a), HasCLI m api ctx) => HasCLI m (CaptureAll sym a :> api) ctx Source # | A |
Defined in Servant.CLI.HasCLI type CLIResult m (CaptureAll sym a :> api) Source # type CLIHandler m (CaptureAll sym a :> api) r Source # cliPStructWithContext_ :: Proxy m -> Proxy (CaptureAll sym a :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (CaptureAll sym a :> api))) Source # cliHandler :: Proxy m -> Proxy (CaptureAll sym a :> api) -> Proxy ctx -> CLIHandler m (CaptureAll sym a :> api) r -> CLIResult m (CaptureAll sym a :> api) -> r Source # | |
(KnownSymbol desc, HasCLI m api ctx) => HasCLI m (Description desc :> api) ctx Source # |
|
Defined in Servant.CLI.HasCLI type CLIResult m (Description desc :> api) Source # type CLIHandler m (Description desc :> api) r Source # cliPStructWithContext_ :: Proxy m -> Proxy (Description desc :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (Description desc :> api))) Source # cliHandler :: Proxy m -> Proxy (Description desc :> api) -> Proxy ctx -> CLIHandler m (Description desc :> api) r -> CLIResult m (Description desc :> api) -> r Source # | |
(KnownSymbol desc, HasCLI m api ctx) => HasCLI m (Summary desc :> api) ctx Source # |
|
Defined in Servant.CLI.HasCLI cliPStructWithContext_ :: Proxy m -> Proxy (Summary desc :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (Summary desc :> api))) Source # cliHandler :: Proxy m -> Proxy (Summary desc :> api) -> Proxy ctx -> CLIHandler m (Summary desc :> api) r -> CLIResult m (Summary desc :> api) -> r Source # | |
(HasCLI m api ctx, AuthProtect tag ∈ ctx, Monad m) => HasCLI m (AuthProtect tag :> api) ctx Source # | Add Please use a secure connection! |
Defined in Servant.CLI.HasCLI type CLIResult m (AuthProtect tag :> api) Source # type CLIHandler m (AuthProtect tag :> api) r Source # cliPStructWithContext_ :: Proxy m -> Proxy (AuthProtect tag :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (AuthProtect tag :> api))) Source # cliHandler :: Proxy m -> Proxy (AuthProtect tag :> api) -> Proxy ctx -> CLIHandler m (AuthProtect tag :> api) r -> CLIResult m (AuthProtect tag :> api) -> r Source # | |
(KnownSymbol sym, FromHttpApiData a, ToHttpApiData a, SBoolI (FoldRequired' 'False mods), Typeable a, HasCLI m api ctx) => HasCLI m (Header' mods sym a :> api) ctx Source # | A Like for |
Defined in Servant.CLI.HasCLI type CLIResult m (Header' mods sym a :> api) Source # type CLIHandler m (Header' mods sym a :> api) r Source # cliPStructWithContext_ :: Proxy m -> Proxy (Header' mods sym a :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (Header' mods sym a :> api))) Source # cliHandler :: Proxy m -> Proxy (Header' mods sym a :> api) -> Proxy ctx -> CLIHandler m (Header' mods sym a :> api) r -> CLIResult m (Header' mods sym a :> api) -> r Source # | |
HasCLI m api ctx => HasCLI m (IsSecure :> api) ctx Source # | |
Defined in Servant.CLI.HasCLI | |
(KnownSymbol sym, ToParam (QueryFlag sym), HasCLI m api ctx) => HasCLI m (QueryFlag sym :> api) ctx Source # | Query flags are interpreted as command line flags/switches.
Note that these require |
Defined in Servant.CLI.HasCLI cliPStructWithContext_ :: Proxy m -> Proxy (QueryFlag sym :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (QueryFlag sym :> api))) Source # cliHandler :: Proxy m -> Proxy (QueryFlag sym :> api) -> Proxy ctx -> CLIHandler m (QueryFlag sym :> api) r -> CLIResult m (QueryFlag sym :> api) -> r Source # | |
(KnownSymbol sym, FromHttpApiData a, ToHttpApiData a, SBoolI (FoldRequired' 'False mods), Typeable a, ToParam (QueryParam' mods sym a), HasCLI m api ctx) => HasCLI m (QueryParam' mods sym a :> api) ctx Source # | Query parameters are interpreted as command line options.
Note that these require |
Defined in Servant.CLI.HasCLI type CLIResult m (QueryParam' mods sym a :> api) Source # type CLIHandler m (QueryParam' mods sym a :> api) r Source # cliPStructWithContext_ :: Proxy m -> Proxy (QueryParam' mods sym a :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (QueryParam' mods sym a :> api))) Source # cliHandler :: Proxy m -> Proxy (QueryParam' mods sym a :> api) -> Proxy ctx -> CLIHandler m (QueryParam' mods sym a :> api) r -> CLIResult m (QueryParam' mods sym a :> api) -> r Source # | |
(ToHttpApiData a, ToParam (QueryParams sym a), KnownSymbol sym, Typeable a, FromHttpApiData a, HasCLI m api ctx) => HasCLI m (QueryParams sym a :> api) ctx Source # | Query parameters are interpreted as command line options, and so repeated query parameters are repeated command line options.
Note that these require |
Defined in Servant.CLI.HasCLI type CLIResult m (QueryParams sym a :> api) Source # type CLIHandler m (QueryParams sym a :> api) r Source # cliPStructWithContext_ :: Proxy m -> Proxy (QueryParams sym a :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (QueryParams sym a :> api))) Source # cliHandler :: Proxy m -> Proxy (QueryParams sym a :> api) -> Proxy ctx -> CLIHandler m (QueryParams sym a :> api) r -> CLIResult m (QueryParams sym a :> api) -> r Source # | |
HasCLI m api ctx => HasCLI m (RemoteHost :> api) ctx Source # | |
Defined in Servant.CLI.HasCLI type CLIResult m (RemoteHost :> api) Source # type CLIHandler m (RemoteHost :> api) r Source # cliPStructWithContext_ :: Proxy m -> Proxy (RemoteHost :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (RemoteHost :> api))) Source # cliHandler :: Proxy m -> Proxy (RemoteHost :> api) -> Proxy ctx -> CLIHandler m (RemoteHost :> api) r -> CLIResult m (RemoteHost :> api) -> r Source # | |
(MimeRender ct a, ParseBody a, HasCLI m api ctx) => HasCLI m (ReqBody' mods (ct ': cts) a :> api) ctx Source # | Request body requirements are interpreted using Note if more than one |
Defined in Servant.CLI.HasCLI type CLIResult m (ReqBody' mods (ct ': cts) a :> api) Source # type CLIHandler m (ReqBody' mods (ct ': cts) a :> api) r Source # cliPStructWithContext_ :: Proxy m -> Proxy (ReqBody' mods (ct ': cts) a :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (ReqBody' mods (ct ': cts) a :> api))) Source # cliHandler :: Proxy m -> Proxy (ReqBody' mods (ct ': cts) a :> api) -> Proxy ctx -> CLIHandler m (ReqBody' mods (ct ': cts) a :> api) r -> CLIResult m (ReqBody' mods (ct ': cts) a :> api) -> r Source # | |
(ToSourceIO chunk a, MimeRender ctype chunk, FramingRender framing, StreamBody' mods framing ctype a ∈ ctx, HasCLI m api ctx, Monad m) => HasCLI m (StreamBody' mods framing ctype a :> api) ctx Source # | As a part of |
Defined in Servant.CLI.HasCLI type CLIResult m (StreamBody' mods framing ctype a :> api) Source # type CLIHandler m (StreamBody' mods framing ctype a :> api) r Source # cliPStructWithContext_ :: Proxy m -> Proxy (StreamBody' mods framing ctype a :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (StreamBody' mods framing ctype a :> api))) Source # cliHandler :: Proxy m -> Proxy (StreamBody' mods framing ctype a :> api) -> Proxy ctx -> CLIHandler m (StreamBody' mods framing ctype a :> api) r -> CLIResult m (StreamBody' mods framing ctype a :> api) -> r Source # | |
HasCLI m api ctx => HasCLI m (Vault :> api) ctx Source # | |
Defined in Servant.CLI.HasCLI | |
(NamedContext m name subctx ∈ ctx, HasCLI m subapi subctx) => HasCLI m (WithNamedContext name subctx subapi) ctx Source # | Descend down a subcontext indexed by a given name. Must be provided when parsing within the context. Useful for when you have multiple items with the same name within a context; this essentially creates a namespace for context items. |
Defined in Servant.CLI.HasCLI type CLIResult m (WithNamedContext name subctx subapi) Source # type CLIHandler m (WithNamedContext name subctx subapi) r Source # cliPStructWithContext_ :: Proxy m -> Proxy (WithNamedContext name subctx subapi) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (WithNamedContext name subctx subapi))) Source # cliHandler :: Proxy m -> Proxy (WithNamedContext name subctx subapi) -> Proxy ctx -> CLIHandler m (WithNamedContext name subctx subapi) r -> CLIResult m (WithNamedContext name subctx subapi) -> r Source # | |
(HasClient m (Verb method status cts' a), ReflectMethod method) => HasCLI m (Verb method status cts' a) ctx Source # | Final actions are the result of specifying all necessary command line positional arguments. All command line options are associated with the final action at the end of their endpoint/path. They cannot be entered in "before" you arrive at your final endpoint. If more than one action (under a different method) exists
under the same endpoint/path, the method ( |
Defined in Servant.CLI.HasCLI type CLIResult m (Verb method status cts' a) Source # type CLIHandler m (Verb method status cts' a) r Source # cliPStructWithContext_ :: Proxy m -> Proxy (Verb method status cts' a) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (Verb method status cts' a))) Source # cliHandler :: Proxy m -> Proxy (Verb method status cts' a) -> Proxy ctx -> CLIHandler m (Verb method status cts' a) r -> CLIResult m (Verb method status cts' a) -> r Source # | |
(RunStreamingClient m, MimeUnrender ct chunk, ReflectMethod method, FramingUnrender framing, FromSourceIO chunk a) => HasCLI m (Stream method status framing ct a) ctx Source # | Same semantics in parsing command line options as |
Defined in Servant.CLI.HasCLI type CLIResult m (Stream method status framing ct a) Source # type CLIHandler m (Stream method status framing ct a) r Source # cliPStructWithContext_ :: Proxy m -> Proxy (Stream method status framing ct a) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (Stream method status framing ct a))) Source # cliHandler :: Proxy m -> Proxy (Stream method status framing ct a) -> Proxy ctx -> CLIHandler m (Stream method status framing ct a) r -> CLIResult m (Stream method status framing ct a) -> r Source # |
Context
data family ContextFor (m :: Type -> Type) :: Type -> Type Source #
Data family associating API combinators with contexts required to run
them. These typically will be actions in m
that fetch/generate the
required data, and will only be "run" if the user selects an endpoint
that requires it through the command line interface.
Instances
newtype ContextFor m (BasicAuth realm usr) Source # | |
Defined in Servant.CLI.HasCLI | |
newtype ContextFor m (AuthProtect tag) Source # | |
Defined in Servant.CLI.HasCLI newtype ContextFor m (AuthProtect tag) = GenAuthReq {
| |
newtype ContextFor m (NamedContext m name subContext) Source # | |
Defined in Servant.CLI.HasCLI | |
newtype ContextFor m (StreamBody' mods framing ctype a) Source # | |
Defined in Servant.CLI.HasCLI |
newtype NamedContext m (name :: Symbol) (subContext :: [Type]) Source #
Contains a subcontext that can be descended down into using
NamedContext
. Mirrors NamedContext
.
Useful for when you have multiple items with the same name within a context; this essentially creates a namespace for context items.
NamedContext (Rec (ContextFor m) subContext) |
Instances
newtype ContextFor m (NamedContext m name subContext) Source # | |
Defined in Servant.CLI.HasCLI |
descendIntoNamedContext :: forall (name :: Symbol) context subContext m. NamedContext m name subContext ∈ context => Proxy name -> Rec (ContextFor m) context -> Rec (ContextFor m) subContext Source #
Allows you to access NamedContext
s inside a context.