Documentation
¶
Overview ¶
Package cli provides an easy way to build command line applications.
If the value for a subcommand is nil, it is treated as if the command didn't even exist. This is useful for disabling the builtin subcommands like completion and help.
Index ¶
- Variables
- func AutoEnv(c *Context)
- func EnvPrefix(s string) func(*Context)
- func NoValidate(c *Context)
- func Run(name string, cmd Command, args []string, opts ...Option) error
- func RunThenExit(name string, cmd Command, opts ...Option)
- func ShowEnvHelp(c *Context)
- func Validate(name string, cmd Command, opts ...Option) error
- type Command
- type Completer
- type Completion
- type Context
- func (c *Context) Args() []string
- func (c *Context) ChildContext(subcommand string) (*Context, error)
- func (c *Context) Command() Command
- func (c *Context) Flags() []*Flag
- func (c *Context) FullName() string
- func (c *Context) Help() string
- func (c *Context) InvalidArg(typ InvalidArgType, arg string, flag *Flag, err error) error
- func (c *Context) Name() string
- func (c *Context) Parent() *Context
- func (c *Context) PrintHelp()
- func (c *Context) Program() string
- func (c *Context) Root() *Context
- type Default
- type Flag
- type Helper
- type Info
- type InvalidArg
- type InvalidArgHelper
- type InvalidArgType
- type Option
- type Runner
- type Subcommands
- type Version
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidArg = errors.New("cli: invalid command line argument")
ErrInvalidArg indicates that there was an invalid command line argument. It can be used as the target to errors.Is to test if the returned error from Run calls was as a result of mistyped command line arguments.
Functions ¶
func AutoEnv ¶
func AutoEnv(c *Context)
AutoEnv enables the automatic derivation of environment variable names from the exported field names of Command structs. By default, the program name will be converted to SCREAMING_CASE with a trailing underscore, and used as a prefix for all generated environment variables. This can be controlled using the EnvPrefix Option.
func EnvPrefix ¶
EnvPrefix enables AutoEnv and overrides the default prefix of the program name when automatically deriving environment variables. Use an empty string if the environment variables should be unprefixed.
This function will panic if the given prefix is not empty or is invalid, i.e. not made up of uppercase letters and underscores. Non-empty values must not have a trailing underscore. One will be appended automatically.
func NoValidate ¶
func NoValidate(c *Context)
NoValidate disables the automatic validation of all commands and subcommands. Validation adds to the startup time, and can be instead done by calling the Validate function from within tests.
func Run ¶
Run processes the command line arguments in the context of the given Command. The given program name will be used to auto-generate help text and error messages.
func RunThenExit ¶
RunThenExit provides a utility function that:
* Calls Run with os.Args.
* If Run returns an error, prints the error as long as it's not InvalidArg related.
* Exits with a status code of 0 on success, 2 on InvalidArg, and 1 otherwise.
The function will use process.Exit instead of os.Exit so that any registered exit handlers will run.
func ShowEnvHelp ¶
func ShowEnvHelp(c *Context)
ShowEnvHelp emits the associated environment variable names when auto-generating help text.
Types ¶
type Command ¶
type Command interface {
About() *Info
}
Command specifies the basic interface that a command needs to implement. For more fine-grained control, commands can also implement any of the Completer, Helper, InvalidArgHelper, and Runner interfaces.
type Completer ¶
type Completer interface {
Complete(c *Context) Completion
}
Completer defines the interface that a command should implement if it wants to provide custom autocompletion on command line arguments.
type Completion ¶
type Completion struct {
}
type Context ¶
type Context struct {
// contains filtered or unexported fields
}
Context provides a way to access processed command line info at specific points within the command hierarchy.
func (*Context) ChildContext ¶
ChildContext tries to create a child Context for a subcommand.
func (*Context) Command ¶
Command returns the Command associated with the current context. By doing a type assertion on the returned value, this can be used to access field values of the parent or root context.
func (*Context) FullName ¶
FullName returns the space separated sequence of command names, all the way from the root to the current context.
func (*Context) Help ¶
Help returns the help text for a command. Commands wishing to override the auto-generated help text, must implement the Helper interface.
func (*Context) InvalidArg ¶
func (*Context) PrintHelp ¶
func (c *Context) PrintHelp()
PrintHelp outputs the command's help text to stdout.
type Default ¶
type Default struct {
Info *Info `cli:"-"`
Subcommands Subcommands
}
Default makes it super easy to create tools with subcommands. Just instantiate the struct, with the relevant Info, Subcommands, and pass it to RunThenExit.
type Flag ¶
type Flag struct {
// contains filtered or unexported fields
}
Flag defines a command line flag derived from a Command struct.
func (*Flag) Label ¶
Label returns the descriptive label for the flag option. This is primarily used to generate the help text, e.g.
--input-file path
Boolean flags will always result in an empty string as the label. For all other types, the following sources are used in priority order:
- Any non-empty value set using the "label" struct tag on the field.
- Any labels that can be extracted from the help info by looking for the first non-whitespace separated set of characters enclosed within {braces} within the "help" struct tag on the field.
- The field type, e.g. string, int, duration, etc. For non-builtin types, this will simply state "value".
func (*Flag) ShortFlags ¶
ShortFlags returns the associated short flags.
type Helper ¶
Helper defines the interface that a command should implement if it wants fine-grained control over the help text. Otherwise, the text is auto-generated from the command name, About() output, and struct fields.
type InvalidArg ¶
type InvalidArg struct {
Arg string
Context *Context
Err error
Flag *Flag
Type InvalidArgType
}
InvalidArg
func (*InvalidArg) Details ¶
func (i *InvalidArg) Details() string
func (*InvalidArg) Error ¶
func (i *InvalidArg) Error() string
func (*InvalidArg) Is ¶
func (i *InvalidArg) Is(target error) bool
type InvalidArgHelper ¶
type InvalidArgHelper interface {
InvalidArg(ia *InvalidArg) string
}
InvalidArgHelper defines the interface that a command should implement to control the error output when an invalid command line argument is encountered.
The returned string is assumed to be contextual help based on the InvalidArg, and will be emitted to stdout. Non-empty strings will have a newline appended to them if they don't already include one.
If this interface isn't implemented, commands will default to printing an error about the invalid argument to stderr, followed by auto-generated contextual help text.
type InvalidArgType ¶
type InvalidArgType int
const ( UnspecifiedInvalidArg InvalidArgType = iota InvalidEnv InvalidFlag InvalidValue MissingFlag MissingValue RepeatedFlag UnknownSubcommand )
Invalid argument types.
func (InvalidArgType) String ¶
func (i InvalidArgType) String() string
type Runner ¶
Runner defines the interface that a command should implement to handle command line arguments.
type Subcommands ¶
Subcommands defines the field type for defining subcommands on a struct.
Source Files