Servant.CLI.HasCLI

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.

Class

class HasCLI m api ctx where

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.

Associated Types

type CLIResult (m :: Type -> Type) (api :: Type) :: Type

The parsed type of the client request response. Usually this will be a bunch of nested Eithers for every API endpoint, nested according to the :<|>s in the API.

type CLIHandler (m :: Type -> Type) (api :: Type) (r :: Type) :: Type

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

Methods

cliPStructWithContext_ :: Proxy m -> Proxy api -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m api))

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

Handle all the possibilities in a CLIResult, by giving the appropriate CLIHandler.

Instances

RunClient m => HasCLI m Raw ctx

Asks for method as a command line argument. If any Verb exists at the same endpoint, it can only be accessed as an extra RAW subcommand (as if it had an extra path component labeled RAW).

Defined in Servant.CLI.HasCLI

Associated Types

type CLIResult m Raw :: Type

type CLIHandler m Raw r :: Type

Methods

cliPStructWithContext_ :: Proxy m -> Proxy Raw -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m Raw))

cliHandler :: Proxy m -> Proxy Raw -> Proxy ctx -> CLIHandler m Raw r -> CLIResult m Raw -> r

HasCLI m EmptyAPI ctx

EmptyAPI will always fail to parse.

The branch ending in EmptyAPI will never be return, so if this is combined using :<|>, the branch will never end up on the side of EmptyAPI.

One can use absurd to handle this branch as a part of CLIHandler.

Defined in Servant.CLI.HasCLI

Associated Types

type CLIResult m EmptyAPI :: Type

type CLIHandler m EmptyAPI r :: Type

Methods

cliPStructWithContext_ :: Proxy m -> Proxy EmptyAPI -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m EmptyAPI))

cliHandler :: Proxy m -> Proxy EmptyAPI -> Proxy ctx -> CLIHandler m EmptyAPI r -> CLIResult m EmptyAPI -> r

(HasCLI m a ctx, HasCLI m b ctx, Functor m) => HasCLI m (a :<|> b) ctx

Using alternation with :<|> provides an Either between the two results.

Defined in Servant.CLI.HasCLI

Associated Types

type CLIResult m (a :<|> b) :: Type

type CLIHandler m (a :<|> b) r :: Type

Methods

cliPStructWithContext_ :: Proxy m -> Proxy (a :<|> b) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (a :<|> b)))

cliHandler :: Proxy m -> Proxy (a :<|> b) -> Proxy ctx -> CLIHandler m (a :<|> b) r -> CLIResult m (a :<|> b) -> r

(ToAuthInfo (BasicAuth realm usr), HasCLI m api ctx, BasicAuth realm usr ∈ ctx, Monad m) => HasCLI m (BasicAuth realm usr :> api) ctx

Add GenBasicAuthData to the required context, meaning it must be provided to allow the client to generate authentication data. The action will only be run if the user selects this endpoint via command line arguments.

Please use a secure connection!

Defined in Servant.CLI.HasCLI

Associated Types

type CLIResult m (BasicAuth realm usr :> api) :: Type

type CLIHandler m (BasicAuth realm usr :> api) r :: Type

Methods

cliPStructWithContext_ :: Proxy m -> Proxy (BasicAuth realm usr :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (BasicAuth realm usr :> api)))

cliHandler :: Proxy m -> Proxy (BasicAuth realm usr :> api) -> Proxy ctx -> CLIHandler m (BasicAuth realm usr :> api) r -> CLIResult m (BasicAuth realm usr :> api) -> r

(HasCLI m api ctx, AuthProtect tag ∈ ctx, Monad m) => HasCLI m (AuthProtect tag :> api) ctx

Add GenAuthReq to the required context, meaning it must be provided to allow the client to generate authentication data. The action will only be run if the user selects this endpoint via command line arguments.

Please use a secure connection!

Defined in Servant.CLI.HasCLI

Associated Types

type CLIResult m (AuthProtect tag :> api) :: Type

type CLIHandler m (AuthProtect tag :> api) r :: Type

Methods

cliPStructWithContext_ :: Proxy m -> Proxy (AuthProtect tag :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (AuthProtect tag :> api)))

cliHandler :: Proxy m -> Proxy (AuthProtect tag :> api) -> Proxy ctx -> CLIHandler m (AuthProtect tag :> api) r -> CLIResult m (AuthProtect tag :> api) -> r

(NamedContext m name subctx ∈ ctx, HasCLI m subapi subctx) => HasCLI m (WithNamedContext name subctx subapi) ctx

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

Associated Types

type CLIResult m (WithNamedContext name subctx subapi) :: Type

type CLIHandler m (WithNamedContext name subctx subapi) r :: Type

Methods

cliPStructWithContext_ :: Proxy m -> Proxy (WithNamedContext name subctx subapi) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (WithNamedContext name subctx subapi)))

cliHandler :: Proxy m -> Proxy (WithNamedContext name subctx subapi) -> Proxy ctx -> CLIHandler m (WithNamedContext name subctx subapi) r -> CLIResult m (WithNamedContext name subctx subapi) -> r

HasCLI m api ctx => HasCLI m (IsSecure :> api) ctx

Defined in Servant.CLI.HasCLI

Associated Types

type CLIResult m (IsSecure :> api) :: Type

type CLIHandler m (IsSecure :> api) r :: Type

Methods

cliPStructWithContext_ :: Proxy m -> Proxy (IsSecure :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (IsSecure :> api)))

cliHandler :: Proxy m -> Proxy (IsSecure :> api) -> Proxy ctx -> CLIHandler m (IsSecure :> api) r -> CLIResult m (IsSecure :> api) -> r

HasCLI m api ctx => HasCLI m (RemoteHost :> api) ctx

Defined in Servant.CLI.HasCLI

Associated Types

type CLIResult m (RemoteHost :> api) :: Type

type CLIHandler m (RemoteHost :> api) r :: Type

Methods

cliPStructWithContext_ :: Proxy m -> Proxy (RemoteHost :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (RemoteHost :> api)))

cliHandler :: Proxy m -> Proxy (RemoteHost :> api) -> Proxy ctx -> CLIHandler m (RemoteHost :> api) r -> CLIResult m (RemoteHost :> api) -> r

HasCLI m api ctx => HasCLI m (Vault :> api) ctx

Defined in Servant.CLI.HasCLI

Associated Types

type CLIResult m (Vault :> api) :: Type

type CLIHandler m (Vault :> api) r :: Type

Methods

cliPStructWithContext_ :: Proxy m -> Proxy (Vault :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (Vault :> api)))

cliHandler :: Proxy m -> Proxy (Vault :> api) -> Proxy ctx -> CLIHandler m (Vault :> api) r -> CLIResult m (Vault :> api) -> r

(KnownSymbol desc, HasCLI m api ctx) => HasCLI m (Description desc :> api) ctx

Description is displayed during --help when it is reached while navigating down subcommands.

Defined in Servant.CLI.HasCLI

Associated Types

type CLIResult m (Description desc :> api) :: Type

type CLIHandler m (Description desc :> api) r :: Type

Methods

cliPStructWithContext_ :: Proxy m -> Proxy (Description desc :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (Description desc :> api)))

cliHandler :: Proxy m -> Proxy (Description desc :> api) -> Proxy ctx -> CLIHandler m (Description desc :> api) r -> CLIResult m (Description desc :> api) -> r

(KnownSymbol desc, HasCLI m api ctx) => HasCLI m (Summary desc :> api) ctx

Summary is displayed during --help when it is reached while navigating down subcommands.

Defined in Servant.CLI.HasCLI

Associated Types

type CLIResult m (Summary desc :> api) :: Type

type CLIHandler m (Summary desc :> api) r :: Type

Methods

cliPStructWithContext_ :: Proxy m -> Proxy (Summary desc :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (Summary desc :> api)))

cliHandler :: Proxy m -> Proxy (Summary desc :> api) -> Proxy ctx -> CLIHandler m (Summary desc :> api) r -> CLIResult m (Summary desc :> api) -> r

HasCLI m api ctx => HasCLI m (HttpVersion :> api) ctx

Using HttpVersion has no affect on CLI operations.

Defined in Servant.CLI.HasCLI

Associated Types

type CLIResult m (HttpVersion :> api) :: Type

type CLIHandler m (HttpVersion :> api) r :: Type

Methods

cliPStructWithContext_ :: Proxy m -> Proxy (HttpVersion :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (HttpVersion :> api)))

cliHandler :: Proxy m -> Proxy (HttpVersion :> api) -> Proxy ctx -> CLIHandler m (HttpVersion :> api) r -> CLIResult m (HttpVersion :> api) -> r

(KnownSymbol sym, FromHttpApiData a, ToHttpApiData a, SBoolI (FoldRequired' False mods), Typeable a, HasCLI m api ctx) => HasCLI m (Header' mods sym a :> api) ctx

A Header' in the middle of a path is interpreted as a command line argument, prefixed with "header". For example, Header "foo" Int is an option for --header-foo.

Like for QueryParam', arguments are associated with the action at their endpoint. After entering all path components and positional arguments, the parser library will begin asking for arguments.

Defined in Servant.CLI.HasCLI

Associated Types

type CLIResult m (Header' mods sym a :> api) :: Type

type CLIHandler m (Header' mods sym a :> api) r :: Type

Methods

cliPStructWithContext_ :: Proxy m -> Proxy (Header' mods sym a :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (Header' mods sym a :> api)))

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

(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

As a part of ctx, asks for a streaming source a.

Defined in Servant.CLI.HasCLI

Associated Types

type CLIResult m (StreamBody' mods framing ctype a :> api) :: Type

type CLIHandler m (StreamBody' mods framing ctype a :> api) r :: Type

Methods

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)))

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

(MimeRender ct a, ParseBody a, HasCLI m api ctx) => HasCLI m (ReqBody' mods (ct ': cts) a :> api) ctx

Request body requirements are interpreted using ParseBody.

Note if more than one ReqBody is in an API endpoint, both parsers will be "run", but only the final one will be used. This shouldn't be an issue, since multiple ReqBodys in a single endpoint should be undefined behavior.

Defined in Servant.CLI.HasCLI

Associated Types

type CLIResult m (ReqBody' mods (ct ': cts) a :> api) :: Type

type CLIHandler m (ReqBody' mods (ct ': cts) a :> api) r :: Type

Methods

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)))

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

(KnownSymbol sym, ToParam (QueryFlag sym), HasCLI m api ctx) => HasCLI m (QueryFlag sym :> api) ctx

Query flags are interpreted as command line flags/switches.

QueryFlag arguments are associated with the action at their endpoint. After entering all path components and positional arguments, the parser library will begin asking for arguments.

Note that these require ToParam instances from servant-docs, to provide appropriate help messages.

Defined in Servant.CLI.HasCLI

Associated Types

type CLIResult m (QueryFlag sym :> api) :: Type

type CLIHandler m (QueryFlag sym :> api) r :: Type

Methods

cliPStructWithContext_ :: Proxy m -> Proxy (QueryFlag sym :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (QueryFlag sym :> api)))

cliHandler :: Proxy m -> Proxy (QueryFlag sym :> api) -> Proxy ctx -> CLIHandler m (QueryFlag sym :> api) r -> CLIResult m (QueryFlag sym :> api) -> r

(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

Query parameters are interpreted as command line options.

QueryParam' arguments are associated with the action at their endpoint. After entering all path components and positional arguments, the parser library will begin asking for arguments.

Note that these require ToParam instances from servant-docs, to provide appropriate help messages.

Defined in Servant.CLI.HasCLI

Associated Types

type CLIResult m (QueryParam' mods sym a :> api) :: Type

type CLIHandler m (QueryParam' mods sym a :> api) r :: Type

Methods

cliPStructWithContext_ :: Proxy m -> Proxy (QueryParam' mods sym a :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (QueryParam' mods sym a :> api)))

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

(FromHttpApiData a, ToHttpApiData a, Typeable a, ToCapture (CaptureAll sym a), HasCLI m api ctx) => HasCLI m (CaptureAll sym a :> api) ctx

A CaptureAll is interpreted as arbitrarily many command line arguments. If there is more than one final endpoint method, the method must be given as a command line option before beginning the arguments.

Defined in Servant.CLI.HasCLI

Associated Types

type CLIResult m (CaptureAll sym a :> api) :: Type

type CLIHandler m (CaptureAll sym a :> api) r :: Type

Methods

cliPStructWithContext_ :: Proxy m -> Proxy (CaptureAll sym a :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (CaptureAll sym a :> api)))

cliHandler :: Proxy m -> Proxy (CaptureAll sym a :> api) -> Proxy ctx -> CLIHandler m (CaptureAll sym a :> api) r -> CLIResult m (CaptureAll sym a :> api) -> r

(FromHttpApiData a, ToHttpApiData a, Typeable a, ToCapture (Capture sym a), HasCLI m api ctx) => HasCLI m (Capture' mods sym a :> api) ctx

A Capture is interpreted as a positional required command line argument.

Note that these require ToCapture instances from servant-docs, to provide appropriate help messages.

Defined in Servant.CLI.HasCLI

Associated Types

type CLIResult m (Capture' mods sym a :> api) :: Type

type CLIHandler m (Capture' mods sym a :> api) r :: Type

Methods

cliPStructWithContext_ :: Proxy m -> Proxy (Capture' mods sym a :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (Capture' mods sym a :> api)))

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

(KnownSymbol path, HasCLI m api ctx) => HasCLI m (path :> api) ctx

A path component is interpreted as a "subcommand".

Defined in Servant.CLI.HasCLI

Associated Types

type CLIResult m (path :> api) :: Type

type CLIHandler m (path :> api) r :: Type

Methods

cliPStructWithContext_ :: Proxy m -> Proxy (path :> api) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (path :> api)))

cliHandler :: Proxy m -> Proxy (path :> api) -> Proxy ctx -> CLIHandler m (path :> api) r -> CLIResult m (path :> api) -> r

(HasClient m (Verb method status cts' a), ReflectMethod method) => HasCLI m (Verb method status cts' a) ctx

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 (GET, POST, etc.) will be treated as an extra final command. After that, you may begin entering in options.

Defined in Servant.CLI.HasCLI

Associated Types

type CLIResult m (Verb method status cts' a) :: Type

type CLIHandler m (Verb method status cts' a) r :: Type

Methods

cliPStructWithContext_ :: Proxy m -> Proxy (Verb method status cts' a) -> Rec (ContextFor m) ctx -> PStruct (Request -> m (CLIResult m (Verb method status cts' a)))

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

(RunStreamingClient m, MimeUnrender ct chunk, ReflectMethod method, FramingUnrender framing, FromSourceIO chunk a) => HasCLI m (Stream method status framing ct a) ctx

Same semantics in parsing command line options as Verb.

Defined in Servant.CLI.HasCLI

Associated Types

type CLIResult m (Stream method status framing ct a) :: Type

type CLIHandler m (Stream method status framing ct a) r :: Type

Methods

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)))

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

Context

data family ContextFor (m :: Type -> Type) :: Type -> Type

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)

Defined in Servant.CLI.HasCLI

data ContextFor m (BasicAuth realm usr) = GenBasicAuthData {

• genBasicAuthData :: m BasicAuthData

}

data ContextFor m (AuthProtect tag)

Defined in Servant.CLI.HasCLI

data ContextFor m (AuthProtect tag) = GenAuthReq {

• genAuthReq :: m (AuthenticatedRequest (AuthProtect tag))

}

data ContextFor m (NamedContext m name subContext)

Defined in Servant.CLI.HasCLI

data ContextFor m (NamedContext m name subContext) = NC (NamedContext m name subContext)

data ContextFor m (StreamBody' mods framing ctype a)

Defined in Servant.CLI.HasCLI

data ContextFor m (StreamBody' mods framing ctype a) = GenStreamBody {

• genStreamBody :: m a

}

newtype NamedContext m (name :: Symbol) (subContext :: [Type])

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.

Constructors

NamedContext (Rec (ContextFor m) subContext)

Instances

data ContextFor m (NamedContext m name subContext)

Defined in Servant.CLI.HasCLI

data ContextFor m (NamedContext m name subContext) = NC (NamedContext m name subContext)

descendIntoNamedContext :: forall (name :: Symbol) context subContext m. NamedContext m name subContext ∈ context => Proxy name -> Rec (ContextFor m) context -> Rec (ContextFor m) subContext

Allows you to access NamedContexts inside a context.