Documentation ¶
Overview ¶
Package cli provides CLI functionality on top of Go's flag package.
Index ¶
- func ErrorCode(c int) func(*CLI)
- func HelpDescription(s string) func(*CLI)
- func MisuseCode(c int) func(*CLI)
- func Name(s string) func(*CLI)
- func Stderr(w io.Writer) func(*CLI)
- func Stdout(w io.Writer) func(*CLI)
- type Arg
- type ArgList
- type ArgValue
- type BoolOption
- type CLI
- type Command
- type ExecFunc
- type Int64Option
- type IntOption
- type Option
- type OptionDetails
- type Program
- type RepeatingArg
- type StringArg
- type StringOption
- type VarOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HelpDescription ¶
HelpDescription changes the default help description message of the CLI.
func MisuseCode ¶ added in v0.4.0
MisuseCode sets a different misuse code for a CLI. The default is 2.
func Name ¶ added in v0.4.0
Name sets a fixed name for the program. The default is the first string from parsed args.
Types ¶
type Arg ¶
Arg is an interface for a positional argument. It can append an argument to an argument list and can write its own documentation to show on a command's usage instructions.
type ArgList ¶
type ArgList struct {
// contains filtered or unexported fields
}
ArgList is an argument list that holds all arguments set by a command.
type ArgValue ¶
ArgValue is an interface to wrap the parsed arguments. Non-repeating arguments get a single argument slice passed to Set.
type BoolOption ¶
type BoolOption struct { OptionDetails DefValue bool Recipient *bool }
BoolOption represents a boolean flag.
type CLI ¶
type CLI struct {
// contains filtered or unexported fields
}
CLI is a command-line interface wrapper that provides flags, positional arguments and subcommands.
For providing flags, it uses the flag package from the standard library. It overrides some features of the flag package in order to provide a prettier help message and to print help to the correct output depending on the situation, which is:
If the user explicitly ask for help by using either -h or -help, it prints help to stdout. If the user makes a mistake by missing either a subcommand or a positional argument, it prints help to stderr.
func New ¶
New instantiates a new command-line interface with sane defaults, which have outputs set to os.Stdout and os.Stderr.
func (*CLI) ParseAndRun ¶
ParseAndRun parses arguments and runs a command, handling flags, subcommands and positional arguments according to configuration.
It returns a status code and correctly prints error messages followed by usage instructions when necessary.
type Command ¶
type Command struct { Description string // Description describes what the command does. Exec ExecFunc // Exec is the function run by the command. Options map[string]Option // Options are the command's options (also known as flags). Subcommands map[string]*Command // Subcommands store the command's subcommands. Arg Arg // Arg is a positional argument. }
Command is a command line command.
If a command doesn't have an Exec function, it is treated as a help command, which prints help to stdout.
When a command has one or more subcommands, its Arg will be totally ignored.
type ExecFunc ¶
ExecFunc is a function that receives a program information and may return an error, which will be printed to stderr.
type Int64Option ¶
type Int64Option struct { OptionDetails DefValue int64 Recipient *int64 }
Int64Option represents a 64-bit integer flag.
type IntOption ¶
type IntOption struct { OptionDetails DefValue int Recipient *int }
IntOption represents an integer flag.
type Option ¶
Option is a type that is able to define its flags to a flag set and also print its own documentation.
type OptionDetails ¶
OptionDetails are common fields for an option, which are its details.
type RepeatingArg ¶
type RepeatingArg struct { Label string // Label is for documentation purposes. Required bool // Required means one or more occurrences must happen. Recipient *[]string // Recipient is the pointer that will receive the parsed args. }
RepeatingArg is a repeating argument. It can be empty when not required, or must occur one or more times when required.
func (RepeatingArg) AppendTo ¶
func (arg RepeatingArg) AppendTo(a *ArgList)
AppendTo appends the argument as the last one in the list.
func (RepeatingArg) WriteDoc ¶
func (arg RepeatingArg) WriteDoc(w io.Writer)
WriteDoc writes the argument's instruction to w.
type StringArg ¶
type StringArg struct { Label string // Label is for documentation purposes. Required bool // Required triggers an error when the argument is not provided. Recipient *string // Recipient is the pointer to have the value set to. Next Arg // Next is the next positional argument. }
StringArg is the most common type of argument, a simple string.
type StringOption ¶
type StringOption struct { OptionDetails DefValue string Recipient *string }
StringOption represents a string flag.