Documentation ¶
Overview ¶
Package claptrap processes the command-line arguments of getopt(3) syntax. This package provides the ability to process the root command, sub commands, command-line arguments and command-line flags.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Arg ¶
type Arg struct { // name of the argument Name string // contains filtered or unexported fields }
Arg holds the structured information about an argument.
func (Arg) Bool ¶
Bool returns the Arg value as a bool, or the default if no argument was given. It returns false anif the Arg was declared as a different type.
func (Arg) Durations ¶ added in v1.2.0
Durations returns the Arg value as an array of type duration, or the defaults if no argument was given. It returns an empty array if the Arg was declared as a different type.
func (Arg) Floats ¶ added in v1.2.0
Floats returns the Arg value as an array of type float, or the defaults if no argument was given. It returns an empty array if the Arg was declared as a different type.
func (Arg) Ints ¶ added in v1.2.0
Ints returns the Arg value as an array of type int, or the defaults if no argument was given. It returns an empty array if the Arg was declared as a different type.
func (Arg) IsSet ¶ added in v1.4.0
IsSet returns true if the Argument was provided with a value in the Parsed data.
func (Arg) Strings ¶ added in v1.2.0
Strings returns the Arg value as an array of type string, or the defaults if no argument was given. It returns an empty array if the Arg was declared as a different type.
type BadArgument ¶
BadArguments are returned when the command line arguments are invalid
func (BadArgument) Error ¶
func (e BadArgument) Error() string
type CommandConfig ¶
type CommandConfig struct { // name of the sub-command ("" for the root command) Name string // command-line flags Flags map[string]*Flag // registered command argument values Args map[string]*Arg // list of the argument names (for ordered iteration) ArgNames []string // was the command provided on the command line? IsSet bool // contains filtered or unexported fields }
CommandConfig type holds the structure and values of the command-line arguments of command.
func (*CommandConfig) AddArg ¶
func (commandConfig *CommandConfig) AddArg(name string, defaultValue interface{}) *Arg
AddArg creates a named argument. Args are placeholders for non-flagged arguments; command-line elements are consumed into Args, in the order they are defined. The very last Arg created (on a command) can be variadic, which means it consumes all of the remaining arguments.
If more elements are provided than there are Args, and the last Arg is *not* variadic, a parse error will result.
Arguments can be made mandatory with a ! prefix in the name. Because Args are consumed in order, this has the effect of making _all_ arguments before the mandatory argument required.
Arguments are strongly typed. The type of an argument is derived from the default value. The supported type
- int
- string
- float64
- bool
- time.Time
- time.Duration
If the provided defaultValue is an array of one of the above types, then that array defines a set of legal values; any provided parameter that doesn't match a value in the array will result in a parse error.
Boolean arguments differ from other types in that:
- boolean Args may *not* be variadic, and will produce an error - the getter, `Bool()`, always returns a single value -- not an array, like the rest - boolean Args may not have array defaults; the options are always `true` and `false`
Values are retrieved using one of the type getters. If the wrong type is retrieved, an empty array is provided. If the argument was not provided by the user, the default is provided. An argument can be tested whether it is a default, or was provided by the user, with the `Arg.IsSet()` function.
func (*CommandConfig) AddFlag ¶
func (commandConfig *CommandConfig) AddFlag(name string, shortName string, defaultValue interface{}) (*Flag, error)
AddFlag creates a flag of a given type and defaults. Do not provide the dashes in the names.
The rules for flags are the same as for args, but in addition:
- The `name` argument is the long-name of the flag. The long name can be prefixed with `!`, in which case it is mandatory. It can also be suffixed with `...`, in which case it is variadic.
- Unlike Args, any flag can be variadic.
- The `shortName` argument should be a single character.
- Boolean Flags don't accept arguments; if the flagis provided on the command line, it is true; otherwise, it is the default.
- Boolean flags automatically get a `no-<longname>` option, which if provided, returns `false' for the flag.
- Regardless of the default, boolean flags are true if provided, and false if inverted
On the command line, Flags are prefixed with dashes. Unlike Args, Flag names are always provided on input. With the exceptions above, Flags follow all the rules and features of arguments: mandatory, variadic, defaults, choices, and types.
type Flag ¶
Flag type holds the structured information about a flag. Because a Flag is an Arg, all of the Arg getters apply and are used to get Flag values.
Note that Flags differ slightly from args, as boolean Flags take no arguments (and Args _are_ arguments): `Bool()` returns `true` if the flag was in the Parsed array, `false` if `no-<longname>` was provided, and the default otherwise.
type MissingMandatoryOption ¶
type MissingMandatoryOption struct {
Name string
}
func (MissingMandatoryOption) Error ¶
func (e MissingMandatoryOption) Error() string
type Registry ¶
type Registry map[string]*CommandConfig
Registry holds the configuration of the registered commands.
func (Registry) Parse ¶
func (registry Registry) Parse(values []string) (*CommandConfig, error)
Parse parses an array of arguments and returns a command object, or an error if any of the parameter validations fail. If no root command is registered, the first array item must be a registered command.
See the rules for `AddArg()` and `AddFlag()` for specific parse rules.
func (Registry) Register ¶
func (registry Registry) Register(name string) *CommandConfig
Register creates a command. If the command name is an empty string, the command created is the root command. If a command is already registered, already created command is returned. Example ``` r := NewRegistry() a := r.Register("").AddArg("X", "") c := r.Parse([]string{"abc"}) // No explicit command, just an arg if c.Args["X"].Strings() != []string{"abc"} { panic() } ````
type UnknownCommand ¶
type UnknownCommand struct {
Name string
}
UnknownCommand represents errors when command-line arguments contain an unregistered command.
func (UnknownCommand) Error ¶
func (e UnknownCommand) Error() string
type UnknownFlag ¶
type UnknownFlag struct {
Name string
}
UnknownFlag represents an error when command-line arguments contain an unregistered flag.
func (UnknownFlag) Error ¶
func (e UnknownFlag) Error() string