Documentation
¶
Index ¶
- Constants
- type AddsFlags
- type CLI
- func (cli *CLI) Help(cmd Command, cmdArgs []string) (string, error)
- func (c *CLI) Invoke(args []string) Result
- func (c *CLI) InvokeAndExit(args []string)
- func (c *CLI) InvokeWithoutPrinting(args []string) Result
- func (c *CLI) IsSuccess(result Result) bool
- func (c *CLI) ListSubcommands(base Command) []string
- func (c *CLI) OutputResult(result Result)
- func (c *CLI) Prepare(args []string) (*PreparedExecution, error)
- func (c *CLI) SetVerbosity(v Verbosity)
- type Command
- type Commands
- type ErrorResult
- type Executor
- type ExitCode
- type Hooks
- type IOErr
- type InternalErr
- type OSErr
- type Output
- type PreparedExecution
- type Result
- type Subcommander
- type SuccessResult
- type Tipper
- type UnknownErr
- type UsageErr
- type Verbosity
Constants ¶
const ( EX_OK = 0 // successful termination EX_USAGE = 64 // command line usage error EX_DATAERR = 65 // data format error EX_NOINPUT = 66 // cannot open input EX_NOUSER = 67 // addressee unknown EX_NOHOST = 68 // host name unknown EX_UNAVAILABLE = 69 // service unavailable EX_SOFTWARE = 70 // internal software error EX_OSERR = 71 // system error (e.g., can't fork) EX_OSFILE = 72 // critical OS file missing EX_CANTCREAT = 73 // can't create (user) output file EX_IOERR = 74 // input/output error EX_TEMPFAIL = 75 // temp failure; user is invited to retry EX_PROTOCOL = 76 // remote error in protocol EX_NOPERM = 77 // permission denied EX_CONFIG = 78 // configuration error )
const ( // DefaultIndentString is the default indent to use when writing // procedurally to the CLI outputs. It is set to two consecutive spaces, // matching default output from the flag package. DefaultIndentString = " " )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AddsFlags ¶
type AddsFlags interface {
// AddFlags will be passed a flag.FlagSet already named correctly for
// this command. All you need to do is add whatever flag definitions
// apply to this command.
AddFlags(*flag.FlagSet)
}
AddsFlags means this command has flags to add. These flags will be available not only to this command, but will still be read, and have impact on this command, even if the user applies them to deeper subcommands.
type CLI ¶
type CLI struct {
// Root is the root command to execute.
Root Command
// Out is an *Output, defaults to a plain os.Stdout writer if left nil.
Out,
Err *Output
// Env is a map of environment variable names to their values.
Env map[string]string
// Hooks allow you to perform pre and post processing on Commands at
// various points in their lifecycle.
Hooks Hooks
// HelpCommand tells the user how to get help. It should be a command
// they can type in to get help.
HelpCommand string
// GlobalFlagSetFuncs allow global flags to be added to the CLI.
GlobalFlagSetFuncs []func(*flag.FlagSet)
// IndentString is the default indent to use for indenting command
// output when Output.Indent() is called inside a command. If left
// empty, defaults to DefaultIndentString.
IndentString string
}
CLI encapsulates a command line interface, and knows how to execute commands and their subcommands and parse flags.
func (*CLI) Help ¶
Help collects information about a subcommand and its arguments, descends the path down the command tree provided by cmdArgs, finds the lowest subcommand on that path, and returns the help text for that subcommand.
func (*CLI) Invoke ¶
Invoke begins invoking the CLI starting with the base command, and handles all command output. It then returns the result for further processing.
func (*CLI) InvokeAndExit ¶
InvokeAndExit calls Invoke, and exits with the returned exit code.
func (*CLI) InvokeWithoutPrinting ¶
InvokeWithoutPrinting invokes the CLI without printing the results.
func (*CLI) ListSubcommands ¶
ListSubcommands returns a slice of strings with the names of each subcommand as they need to be entered by the user, arranged alphabetically.
func (*CLI) OutputResult ¶ added in v0.0.2
OutputResult formats and outputs a cmdr.Result - handles tips when the result is an error, etc. returns true if the result was a success
func (*CLI) Prepare ¶
func (c *CLI) Prepare(args []string) (*PreparedExecution, error)
Prepare sets up a command for execution, resolving subcommands and flags, and forwarding flags from lower commands to higher ones. This means that flags defined on the base command are also defined by default all its nested subcommands, which is usually a nicer user experience than having to remember strictly which subcommand a flag is applicable to.
type Command ¶
type Command interface {
// Help is the help message for a command. To be a command, all you need
// is a help message.
// Help messages must follow this convention:
// The first line must be 50 characters or fewer, and describe
// succinctly what the command does.
// The second line must be blank.
// The remainder of the string is free-form text.
Help() string
}
Command is a command that can be invoked.
type Commands ¶
Commands is a mapping of strings (the command name) to commands.
func (Commands) SortedKeys ¶
SortedKeys returns the names of the commands in alphabetical order.
type ErrorResult ¶
type ErrorResult interface {
error
Result
WithTip(string) ErrorResult
WithUnderlyingError(error) ErrorResult
Tipper
}
An ErrorResult is both an error and a result, and has a tip for the user.
func EnsureErrorResult ¶
func EnsureErrorResult(err error) ErrorResult
EnsureErrorResult takes an error, and if it is not already also a Result, makes it into an ErrorResult. It tries to wrap well-known errors intelligently, and eventially falls back to UnknownErr if no sensible ErrorResult exists for that error.
type Hooks ¶
type Hooks struct {
// Startup is run at the beginning of every invocation
Startup func(*CLI) error
// Parsed is run on a command when it's found on the command line
Parsed func(Command) error
// PreExecute is run on a command before it executes.
PreExecute func(Command) error
// PreFail is run just before a command exits with an error.
// Is is passed the error, and must return the final ErrorResult.
PreFail func(error) ErrorResult
}
Hooks is a collection of command hooks. If a hook returns a non-nil error it cancels execution and the error is displayed to the user.
type IOErr ¶
type IOErr struct {
// contains filtered or unexported fields
}
IOErr signifies that something went wrong with io, to files, or across the network, for example.
func (IOErr) UnderlyingError ¶
func (e IOErr) UnderlyingError() error
func (IOErr) WithTip ¶
func (e IOErr) WithTip(tip string) ErrorResult
func (IOErr) WithUnderlyingError ¶
func (e IOErr) WithUnderlyingError(err error) ErrorResult
type InternalErr ¶
type InternalErr struct {
// contains filtered or unexported fields
}
InternalErr signifies programmer error. The user only sees these when we mess up.
func InternalErrorf ¶
func InternalErrorf(format string, v ...interface{}) InternalErr
func (InternalErr) ExitCode ¶
func (e InternalErr) ExitCode() int
func (InternalErr) UnderlyingError ¶
func (e InternalErr) UnderlyingError() error
func (InternalErr) WithTip ¶
func (e InternalErr) WithTip(tip string) ErrorResult
func (InternalErr) WithUnderlyingError ¶
func (e InternalErr) WithUnderlyingError(err error) ErrorResult
type OSErr ¶
type OSErr struct {
// contains filtered or unexported fields
}
OSErr signifies that something went wrong starting a process, or performing some other os-level operation.
func (OSErr) UnderlyingError ¶
func (e OSErr) UnderlyingError() error
func (OSErr) WithTip ¶
func (e OSErr) WithTip(tip string) ErrorResult
func (OSErr) WithUnderlyingError ¶
func (e OSErr) WithUnderlyingError(err error) ErrorResult
type Output ¶
type Output struct {
// Verbosity is the verbosity of this output.
Verbosity Verbosity
// Errors contains any errors this output has encountered whilst
// writing to Writer.
Errors []error
// contains filtered or unexported fields
}
Output is a convenience wrapper around an io.Writer that provides extra features for formatting text, such as indentation and the ability to emit tables. It is designed to be used sequentially, writing and changing context on each call to one of its methods.
func NewOutput ¶
NewOutput creates a new Output, you may optionally pass any number of functions, each of which will be called on the Output before it is returned. You can use this to create and configure an output in a single statement.
func (*Output) Println ¶
func (o *Output) Println(v ...interface{})
Println prints a line, respecting current indentation.
func (*Output) WriteString ¶
type PreparedExecution ¶
A PreparedExecution collects all the information needed to execute a command
type Result ¶
type Result interface {
// ExitCode is the exit code the program should exit with based on this
// result.
ExitCode() int
}
Result is a result of a CLI invokation.
type Subcommander ¶
type Subcommander interface {
// Subcommands returns a map of command names to Commands.
Subcommands() Commands
}
Subcommander means this command has subcommands.
type SuccessResult ¶
type SuccessResult struct {
// Data is the real return value of this function, it will be printed to
// stdout by default, for consumption by other commands/pipelines etc.
Data []byte
}
SuccessResult is a successful result.
func Success ¶
func Success(v ...interface{}) SuccessResult
func SuccessData ¶
func SuccessData(d []byte) SuccessResult
func (SuccessResult) ExitCode ¶
func (s SuccessResult) ExitCode() int
func (SuccessResult) String ¶
func (s SuccessResult) String() string
type UnknownErr ¶
type UnknownErr struct {
// contains filtered or unexported fields
}
UnknownErr is the error of last resort, only to be used if none of the other error types is applicable.
func UnknownErrorf ¶
func UnknownErrorf(format string, v ...interface{}) UnknownErr
func (UnknownErr) ExitCode ¶
func (e UnknownErr) ExitCode() int
func (UnknownErr) UnderlyingError ¶
func (e UnknownErr) UnderlyingError() error
func (UnknownErr) WithTip ¶
func (e UnknownErr) WithTip(tip string) ErrorResult
func (UnknownErr) WithUnderlyingError ¶
func (e UnknownErr) WithUnderlyingError(err error) ErrorResult
type UsageErr ¶
type UsageErr struct {
// contains filtered or unexported fields
}
UsageErr signifies that the user made a mistake with the invocation.
func UsageErrorf ¶
func (UsageErr) UnderlyingError ¶
func (e UsageErr) UnderlyingError() error
func (UsageErr) WithTip ¶
func (e UsageErr) WithTip(tip string) ErrorResult
func (UsageErr) WithUnderlyingError ¶
func (e UsageErr) WithUnderlyingError(err error) ErrorResult
type Verbosity ¶
type Verbosity int
Verbosity represents the level of output detail a CLI should give to the user.
const ( // Silent means output absolutely no error or warning messsages, but still // output the result of a command, if it has a real result. Silent Verbosity = iota // Quiet is similar to silent, but will echo error messages if the command // cannot be completed successfully. Quiet // Normal is the default verbosity, and is similar to quiet, but will // additionally output tips and warnings to the user. For long-running // commands, Normal may additionally output status updates, progress meters, // and other information to let the user know it's still working. Normal // Loud is similar to Normal, but outputs additional information. Loud // Debug is similar to Loud, but additionally outputs detailed internal // operations, helpful in debugging problems. Debug )
Source Files
Directories