Copyright | (c) Justin Le 2019 |
---|---|
License | BSD3 |
Maintainer | justin@jle.im |
Stability | experimental |
Portability | non-portable |
Safe Haskell | None |
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 Request
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
RunClient m => HasCLI m Raw ctx Source # | Asks for method as a command line argument. If any |
Defined in Servant.CLI.HasCLI | |
HasCLI m EmptyAPI ctx Source # |
The branch ending in One can use |
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 | |
(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) :: Type Source # type CLIHandler m (BasicAuth realm usr :> api) r :: Type 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 # | |
(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) :: Type Source # type CLIHandler m (AuthProtect tag :> api) r :: Type 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 # | |
(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) :: Type Source # type CLIHandler m (WithNamedContext name subctx subapi) r :: Type 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 # | |
HasCLI m api ctx => HasCLI m (IsSecure :> api) ctx Source # | |
HasCLI m api ctx => HasCLI m (RemoteHost :> api) ctx Source # | |
Defined in Servant.CLI.HasCLI type CLIResult m (RemoteHost :> api) :: Type Source # type CLIHandler m (RemoteHost :> api) r :: Type 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 # | |
HasCLI m api ctx => HasCLI m (Vault :> api) ctx Source # | |
Defined in Servant.CLI.HasCLI | |
(KnownSymbol desc, HasCLI m api ctx) => HasCLI m (Description desc :> api) ctx Source # |
|
Defined in Servant.CLI.HasCLI type CLIResult m (Description desc :> api) :: Type Source # type CLIHandler m (Description desc :> api) r :: Type 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 => HasCLI m (HttpVersion :> api) ctx Source # | Using |
Defined in Servant.CLI.HasCLI type CLIResult m (HttpVersion :> api) :: Type Source # type CLIHandler m (HttpVersion :> api) r :: Type 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 # | |
(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) :: Type Source # type CLIHandler m (Header' mods sym a :> api) r :: Type 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 # | |
(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) :: Type Source # type CLIHandler m (StreamBody' mods framing ctype a :> api) r :: Type 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 # | |
(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) :: Type Source # type CLIHandler m (ReqBody' mods (ct ': cts) a :> api) r :: Type 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 # | |
(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) :: Type Source # type CLIHandler m (QueryParam' mods sym a :> api) r :: Type 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 # | |
(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) :: Type Source # type CLIHandler m (CaptureAll sym a :> api) r :: Type 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 # | |
(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) :: Type Source # type CLIHandler m (Capture' mods sym a :> api) r :: Type 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 # | |
(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 | |
(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) :: Type Source # type CLIHandler m (Verb method status cts' a) r :: Type 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) :: Type Source # type CLIHandler m (Stream method status framing ct a) r :: Type 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
data ContextFor m (BasicAuth realm usr) Source # | |
Defined in Servant.CLI.HasCLI | |
data ContextFor m (AuthProtect tag) Source # | |
Defined in Servant.CLI.HasCLI data ContextFor m (AuthProtect tag) = GenAuthReq {
| |
data ContextFor m (NamedContext m name subContext) Source # | |
Defined in Servant.CLI.HasCLI | |
data 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
data 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.