Documentation ¶
Index ¶
- Variables
- func LexicographicLess(i, j string) bool
- func NewExitError(message interface{}, exitCode int) cli.ExitCoder
- func ShowAppHelp(ctx *Context) error
- func ShowCommandHelp(ctx *Context, cmdName string) error
- func ShowCompletions(ctx *Context) error
- func ShowVersion(ctx *Context) error
- type ActionFunc
- type ActionableFlag
- type App
- type Args
- func (args Args) CommandName() string
- func (args Args) Contains(target string) bool
- func (args Args) First() string
- func (args Args) Get(n int) string
- func (args Args) Last() string
- func (args Args) Len() int
- func (args Args) Normalize(acts ...NormalizeActsType) Args
- func (args Args) Present() bool
- func (args Args) Slice() []string
- func (args Args) Tail() Args
- type AutocompleteInstaller
- type BoolActionFunc
- type BoolFlag
- func (flag *BoolFlag) Apply(set *libflag.FlagSet) error
- func (flag *BoolFlag) GetCategory() string
- func (flag *BoolFlag) GetDefaultText() string
- func (flag *BoolFlag) GetEnvVars() []string
- func (flag *BoolFlag) GetHidden() bool
- func (flag *BoolFlag) GetUsage() string
- func (flag *BoolFlag) GetValue() string
- func (flag *BoolFlag) IsSet() bool
- func (flag *BoolFlag) LookupEnv(envVar string) *string
- func (flag *BoolFlag) Names() []string
- func (flag *BoolFlag) RunAction(ctx *Context) error
- func (flag *BoolFlag) String() string
- func (flag *BoolFlag) TakesValue() bool
- func (flag *BoolFlag) Value() FlagValue
- type Command
- func (cmd *Command) HasName(name string) bool
- func (cmd *Command) Names() []string
- func (cmd *Command) Run(ctx *Context, args Args) (err error)
- func (cmd *Command) Subcommand(name string) *Command
- func (cmd *Command) VisibleFlags() Flags
- func (cmd Command) VisibleSubcommands() []*cli.Command
- func (cmd Command) WrapAction(fn func(ctx *Context, action ActionFunc) error) *Command
- type Commands
- func (commands *Commands) Add(cmd *Command)
- func (commands Commands) Filter(names []string) Commands
- func (commands Commands) Get(name string) *Command
- func (commands Commands) Len() int
- func (commands Commands) Less(i, j int) bool
- func (commands Commands) SkipRunning() Commands
- func (commands Commands) Swap(i, j int)
- func (commands Commands) VisibleCommands() []*cli.Command
- func (commands Commands) WrapAction(fn func(ctx *Context, action ActionFunc) error) Commands
- type CompleteFunc
- type Context
- type Flag
- type FlagType
- type FlagValue
- type Flags
- func (flags *Flags) Add(newFlags ...Flag)
- func (flags Flags) Filter(names []string) Flags
- func (flags Flags) Get(name string) Flag
- func (flags Flags) Len() int
- func (flags Flags) Less(i, j int) bool
- func (flags Flags) RunActions(ctx *Context) error
- func (flags Flags) Sort() Flags
- func (flags Flags) Swap(i, j int)
- func (flags Flags) VisibleFlags() Flags
- type GenericActionFunc
- type GenericFlag
- func (flag *GenericFlag[T]) Apply(set *libflag.FlagSet) error
- func (flag *GenericFlag) GetCategory() string
- func (flag *GenericFlag[T]) GetDefaultText() string
- func (flag *GenericFlag[T]) GetEnvVars() []string
- func (flag *GenericFlag[T]) GetHidden() bool
- func (flag *GenericFlag[T]) GetUsage() string
- func (flag *GenericFlag) GetValue() string
- func (flag *GenericFlag) IsSet() bool
- func (flag *GenericFlag) LookupEnv(envVar string) *string
- func (flag *GenericFlag[T]) Names() []string
- func (flag *GenericFlag[T]) RunAction(ctx *Context) error
- func (flag *GenericFlag[T]) String() string
- func (flag *GenericFlag) TakesValue() bool
- func (flag *GenericFlag) Value() FlagValue
- type GenericType
- type InvalidCommandNameError
- type InvalidKeyValueError
- type LookupEnvFuncType
- type MapActionFunc
- type MapFlag
- func (flag *MapFlag[K, V]) Apply(set *libflag.FlagSet) error
- func (flag *MapFlag) GetCategory() string
- func (flag *MapFlag[K, V]) GetDefaultText() string
- func (flag *MapFlag[K, V]) GetEnvVars() []string
- func (flag *MapFlag[K, V]) GetHidden() bool
- func (flag *MapFlag[K, V]) GetUsage() string
- func (flag *MapFlag) GetValue() string
- func (flag *MapFlag) IsSet() bool
- func (flag *MapFlag) LookupEnv(envVar string) *string
- func (flag *MapFlag[K, V]) Names() []string
- func (flag *MapFlag[K, V]) RunAction(ctx *Context) error
- func (flag *MapFlag[K, V]) String() string
- func (flag *MapFlag) TakesValue() bool
- func (flag *MapFlag) Value() FlagValue
- type MapFlagKeyType
- type MapFlagValueType
- type NormalizeActsType
- type SliceActionFunc
- type SliceFlag
- func (flag *SliceFlag[T]) Apply(set *libflag.FlagSet) error
- func (flag *SliceFlag) GetCategory() string
- func (flag *SliceFlag[T]) GetDefaultText() string
- func (flag *SliceFlag[T]) GetEnvVars() []string
- func (flag *SliceFlag[T]) GetHidden() bool
- func (flag *SliceFlag[T]) GetUsage() string
- func (flag *SliceFlag) GetValue() string
- func (flag *SliceFlag) IsSet() bool
- func (flag *SliceFlag) LookupEnv(envVar string) *string
- func (flag *SliceFlag[T]) Names() []string
- func (flag *SliceFlag[T]) RunAction(ctx *Context) error
- func (flag *SliceFlag[T]) String() string
- func (flag *SliceFlag) TakesValue() bool
- func (flag *SliceFlag) Value() FlagValue
- type SliceFlagType
- type SplitterFunc
Constants ¶
This section is empty.
Variables ¶
var ( // AppVersionTemplate is the text template for the Default version topic. AppVersionTemplate = "" // AppHelpTemplate is the text template for the Default help topic. AppHelpTemplate = "" // CommandHelpTemplate is the text template for the command help topic. CommandHelpTemplate = "" )
var ( MapFlagEnvVarSep = "," MapFlagKeyValSep = "=" )
var DefaultComplete = defaultComplete
var ( // FlagSplitter uses to separate arguments and env vars with multiple values. FlagSplitter = strings.Split )
var (
SliceFlagEnvVarSep = ","
)
Functions ¶
func LexicographicLess ¶
LexicographicLess compares strings alphabetically considering case.
func NewExitError ¶
func NewExitError(message interface{}, exitCode int) cli.ExitCoder
NewExitError calls Exit to create a new ExitCoder.
func ShowCommandHelp ¶
ShowCommandHelp prints help for the given command.
func ShowCompletions ¶ added in v0.53.4
ShowCompletions prints the lists of commands within a given context
func ShowVersion ¶
Types ¶
type ActionFunc ¶
ActionFunc is the action to execute when no commands/subcommands are specified.
type ActionableFlag ¶
ActionableFlag is an interface that wraps Flag interface and RunAction operation.
type App ¶
type App struct { *cli.App // List of commands to execute Commands Commands // List of flags to parse Flags Flags // CustomAppVersionTemplate text template for app version topic. CustomAppVersionTemplate string // Contributor Author string // The function to call when checking for command completions Complete CompleteFunc // An action to execute before any subcommands are run, but after the context is ready // If a non-nil error is returned, no subcommands are run Before ActionFunc // An action to execute after any subcommands are run, but after the subcommand has finished After ActionFunc // The action to execute when no subcommands are specified Action ActionFunc // DefaultCommand is the (optional) command // to run if no command names are passed as CLI arguments. DefaultCommand *Command // OsExiter is the function used when the app exits. If not set defaults to os.Exit. OsExiter func(code int) // Autocomplete enables or disables subcommand auto-completion support. // This is enabled by default when NewApp is called. Otherwise, this // must enabled explicitly. // // Autocomplete requires the "Name" option to be set on CLI. This name // should be set exactly to the binary name that is autocompleted. Autocomplete bool // AutocompleteInstallFlag and AutocompleteUninstallFlag are the global flag // names for installing and uninstalling the autocompletion handlers // for the user's shell. The flag should omit the hyphen(s) in front of // the value. Both single and double hyphens will automatically be supported // for the flag name. These default to `autocomplete-install` and // `autocomplete-uninstall` respectively. AutocompleteInstallFlag string AutocompleteUninstallFlag string // Autocompletion is supported via the github.com/posener/complete // library. This library supports bash, zsh and fish. To add support // for other shells, please see that library. AutocompleteInstaller AutocompleteInstaller }
App is a wrapper for `urfave`'s `cli.App` struct. It should be created with the cli.NewApp() function. The main purpose of this wrapper is to parse commands and flags in the way we need, namely, if during parsing we find undefined commands or flags, instead of returning an error, we consider them as arguments, regardless of their position among the others registered commands and flags.
For example, CLI command: `terragrunt run-all apply --terragrunt-log-level debug --auto-approve --terragrunt-non-interactive` The `App` will runs the registered command `run-all`, define the registered flags `--terragrunt-log-level`, `--terragrunt-non-interactive`, and define args `apply --auto-approve` which can be obtained from the App context, ctx.Args().Slice()
func (*App) AddCommands ¶
AddCommands adds new commands.
func (*App) Run ¶
Run is the entry point to the cli app. Parses the arguments slice and routes to the proper flag/args combination.
func (*App) RunContext ¶ added in v0.56.4
RunContext is like Run except it takes a Context that will be passed to its commands and sub-commands. Through this, you can propagate timeouts and cancellation requests
func (*App) VisibleCommands ¶
func (app *App) VisibleCommands() []*cli.Command
VisibleCommands returns a slice of the Commands used for help.
func (*App) VisibleFlags ¶
VisibleFlags returns a slice of the Flags used for help.
type Args ¶
type Args []string
Args provides convenient access to CLI arguments.
func (Args) CommandName ¶
CommandName returns the first value if it starts without a dash `-`, otherwise that means the args do not consist any command and an empty string is returned.
func (Args) Contains ¶ added in v0.67.5
Contains returns true if args contains the given `target` arg.
func (Args) Normalize ¶
func (args Args) Normalize(acts ...NormalizeActsType) Args
Normalize formats the arguments according to the given actions. if the given act is:
`SingleDashFlag` - converts all arguments containing double dashes to single dashes `DoubleDashFlag` - converts all arguments containing signle dashes to double dashes
type AutocompleteInstaller ¶ added in v0.53.4
AutocompleteInstaller is an interface to be implemented to perform the autocomplete installation and uninstallation with a CLI.
This interface is not exported because it only exists for unit tests to be able to test that the installation is called properly.
type BoolActionFunc ¶ added in v0.67.5
BoolActionFunc is the action to execute when the flag has been set either via a flag or via an environment variable.
type BoolFlag ¶
type BoolFlag struct { // The name of the flag. Name string // The default value of the flag to display in the help, if it is empty, the value is taken from `Destination`. DefaultText string // A short usage description to display in help. Usage string // Aliases are usually used for the short flag name, like `-h`. Aliases []string // The name of the env variable that is parsed and assigned to `Destination` before the flag value. EnvVar string // The action to execute when flag is specified Action BoolActionFunc[bool] // The pointer to which the value of the flag or env var is assigned. // It also uses as the default value displayed in the help. Destination *bool // If set to true, then the assigned flag value will be inverted Negative bool // Hidden hides the flag from the help, if set to true. Hidden bool // contains filtered or unexported fields }
func (*BoolFlag) GetCategory ¶
func (flag *BoolFlag) GetCategory() string
GetCategory returns the category for the flag. Implements `cli.DocGenerationFlag.GetCategory` required to generate help.
func (*BoolFlag) GetDefaultText ¶
GetDefaultText returns the flags value as string representation and an empty string if the flag takes no value at all.
func (*BoolFlag) GetEnvVars ¶
GetEnvVars returns the env vars for this flag.
func (*BoolFlag) GetHidden ¶ added in v0.67.0
GetHidden returns true if the flag should be hidden from the help.
func (*BoolFlag) GetValue ¶
func (flag *BoolFlag) GetValue() string
GetValue returns the flags value as string representation and an empty string if the flag takes no value at all. Implements `cli.DocGenerationFlag.GetValue` required to generate help.
func (*BoolFlag) IsSet ¶
func (flag *BoolFlag) IsSet() bool
IsSet returns true if the flag was set either evn, by env var or arg flag. Implements `cli.flag.IsSet` required to generate help.
func (*BoolFlag) String ¶
String returns a readable representation of this value (for usage defaults).
func (*BoolFlag) TakesValue ¶
func (flag *BoolFlag) TakesValue() bool
TakesValue returns true of the flag takes a value, otherwise false. Implements `cli.DocGenerationFlag.TakesValue` required to generate help.
type Command ¶
type Command struct { // The name of the cmd Name string // A list of aliases for the cmd Aliases []string // A short description of the usage of this cmd Usage string // Custom text to show on USAGE section of help UsageText string // A longer explanation of how the cmd works Description string // List of flags to parse Flags Flags // if DisallowUndefinedFlags is true, any undefined flag will cause the application to exit and return an error. DisallowUndefinedFlags bool // Full name of cmd for help, defaults to full cmd name, including parent commands. HelpName string // if this is a root "special" cmd IsRoot bool // Boolean to hide this cmd from help Hidden bool // CustomHelpTemplate the text template for the cmd help topic. // cli.go uses text/template to render templates. You can // render custom help text by setting this variable. CustomHelpTemplate string // List of child commands Subcommands Commands // Treat all flags as normal arguments if true SkipFlagParsing bool // Boolean to disable the parsing command, but it will still be shown in the help. SkipRunning bool // The function to call when checking for command completions Complete CompleteFunc // An action to execute before any subcommands are run, but after the context is ready // If a non-nil error is returned, no subcommands are run Before ActionFunc // An action to execute after any subcommands are run, but after the subcommand has finished After ActionFunc // The action to execute when no subcommands are specified Action ActionFunc }
func (*Command) Run ¶
Run parses the given args for the presence of flags as well as subcommands. If this is the final command, starts its execution.
func (*Command) Subcommand ¶
Subcommand returns a subcommand that matches the given name.
func (*Command) VisibleFlags ¶
VisibleFlags returns a slice of the Flags, used by `urfave/cli` package to generate help.
func (Command) VisibleSubcommands ¶
func (cmd Command) VisibleSubcommands() []*cli.Command
VisibleSubCommands returns a slice of the Commands with Hidden=false. Used by `urfave/cli` package to generate help.
func (Command) WrapAction ¶ added in v0.58.9
func (cmd Command) WrapAction(fn func(ctx *Context, action ActionFunc) error) *Command
type Commands ¶
type Commands []*Command
func (Commands) SkipRunning ¶
SkipRunning prevents running commands as the final commands, but keep showing them in help.
func (Commands) VisibleCommands ¶
func (commands Commands) VisibleCommands() []*cli.Command
VisibleCommands returns a slice of the Commands with Hidden=false. Used by `urfave/cli` package to generate help.
func (Commands) WrapAction ¶ added in v0.58.9
func (commands Commands) WrapAction(fn func(ctx *Context, action ActionFunc) error) Commands
type CompleteFunc ¶ added in v0.53.4
CompleteFunc is an action to execute when the shell completion flag is set
type Context ¶
type Context struct { context.Context *App Command *Command // contains filtered or unexported fields }
Context can be used to retrieve context-specific args and parsed command-line options.
type Flags ¶
type Flags []Flag
func (Flags) RunActions ¶
func (Flags) VisibleFlags ¶
VisibleFlags returns a slice of the Flags. Used by `urfave/cli` package to generate help.
type GenericActionFunc ¶ added in v0.67.5
type GenericActionFunc[T GenericType] func(ctx *Context, value T) error
GenericActionFunc is the action to execute when the flag has been set either via a flag or via an environment variable.
type GenericFlag ¶
type GenericFlag[T GenericType] struct { // The name of the flag. Name string // The default value of the flag to display in the help, if it is empty, the value is taken from `Destination`. DefaultText string // A short usage description to display in help. Usage string // Aliases are usually used for the short flag name, like `-h`. Aliases []string // The name of the env variable that is parsed and assigned to `Destination` before the flag value. EnvVar string // The action to execute when flag is specified Action GenericActionFunc[T] // The pointer to which the value of the flag or env var is assigned. // It also uses as the default value displayed in the help. Destination *T // Hidden hides the flag from the help, if set to true. Hidden bool // contains filtered or unexported fields }
func (*GenericFlag[T]) Apply ¶
func (flag *GenericFlag[T]) Apply(set *libflag.FlagSet) error
Apply applies Flag settings to the given flag set.
func (*GenericFlag) GetCategory ¶
func (flag *GenericFlag) GetCategory() string
GetCategory returns the category for the flag. Implements `cli.DocGenerationFlag.GetCategory` required to generate help.
func (*GenericFlag[T]) GetDefaultText ¶
func (flag *GenericFlag[T]) GetDefaultText() string
GetDefaultText returns the flags value as string representation and an empty string if the flag takes no value at all.
func (*GenericFlag[T]) GetEnvVars ¶
func (flag *GenericFlag[T]) GetEnvVars() []string
GetEnvVars returns the env vars for this flag.
func (*GenericFlag[T]) GetHidden ¶ added in v0.67.0
func (flag *GenericFlag[T]) GetHidden() bool
GetHidden returns true if the flag should be hidden from the help.
func (*GenericFlag[T]) GetUsage ¶
func (flag *GenericFlag[T]) GetUsage() string
GetUsage returns the usage string for the flag.
func (*GenericFlag) GetValue ¶
func (flag *GenericFlag) GetValue() string
GetValue returns the flags value as string representation and an empty string if the flag takes no value at all. Implements `cli.DocGenerationFlag.GetValue` required to generate help.
func (*GenericFlag) IsSet ¶
func (flag *GenericFlag) IsSet() bool
IsSet returns true if the flag was set either evn, by env var or arg flag. Implements `cli.flag.IsSet` required to generate help.
func (*GenericFlag[T]) Names ¶
func (flag *GenericFlag[T]) Names() []string
Names returns the names of the flag.
func (*GenericFlag[T]) RunAction ¶
func (flag *GenericFlag[T]) RunAction(ctx *Context) error
RunAction implements ActionableFlag.RunAction
func (*GenericFlag[T]) String ¶
func (flag *GenericFlag[T]) String() string
String returns a readable representation of this value (for usage defaults).
func (*GenericFlag) TakesValue ¶
func (flag *GenericFlag) TakesValue() bool
TakesValue returns true of the flag takes a value, otherwise false. Implements `cli.DocGenerationFlag.TakesValue` required to generate help.
type InvalidCommandNameError ¶
type InvalidCommandNameError string
func (InvalidCommandNameError) Error ¶
func (cmdName InvalidCommandNameError) Error() string
type InvalidKeyValueError ¶
type InvalidKeyValueError struct {
// contains filtered or unexported fields
}
func NewInvalidKeyValueError ¶
func NewInvalidKeyValueError(sep, value string) *InvalidKeyValueError
func (InvalidKeyValueError) Error ¶
func (err InvalidKeyValueError) Error() string
type LookupEnvFuncType ¶
type MapActionFunc ¶ added in v0.67.5
type MapActionFunc[K MapFlagKeyType, V MapFlagValueType] func(ctx *Context, value map[K]V) error
MapActionFunc is the action to execute when the flag has been set either via a flag or via an environment variable.
type MapFlag ¶
type MapFlag[K MapFlagKeyType, V MapFlagValueType] struct { // The name of the flag. Name string // The default value of the flag to display in the help, if it is empty, the value is taken from `Destination`. DefaultText string // A short usage description to display in help. Usage string // Aliases are usually used for the short flag name, like `-h`. Aliases []string // The action to execute when flag is specified Action MapActionFunc[K, V] // The name of the env variable that is parsed and assigned to `Destination` before the flag value. EnvVar string // The pointer to which the value of the flag or env var is assigned. // It also uses as the default value displayed in the help. Destination *map[K]V // The func used to split the EvnVar, by default `strings.Split` Splitter SplitterFunc // The EnvVarSep value is passed to the Splitter function as an argument to split the args. EnvVarSep string // The KeyValSep value is passed to the Splitter function as an argument to split `key` and `val` of the arg. KeyValSep string // Hidden hides the flag from the help, if set to true. Hidden bool // contains filtered or unexported fields }
MapFlag is a key value flag.
func (*MapFlag) GetCategory ¶
func (flag *MapFlag) GetCategory() string
GetCategory returns the category for the flag. Implements `cli.DocGenerationFlag.GetCategory` required to generate help.
func (*MapFlag[K, V]) GetDefaultText ¶
GetDefaultText returns the flags value as string representation and an empty string if the flag takes no value at all.
func (*MapFlag[K, V]) GetEnvVars ¶
GetEnvVars returns the env vars for this flag.
func (*MapFlag[K, V]) GetHidden ¶ added in v0.67.0
GetHidden returns true if the flag should be hidden from the help.
func (*MapFlag) GetValue ¶
func (flag *MapFlag) GetValue() string
GetValue returns the flags value as string representation and an empty string if the flag takes no value at all. Implements `cli.DocGenerationFlag.GetValue` required to generate help.
func (*MapFlag) IsSet ¶
func (flag *MapFlag) IsSet() bool
IsSet returns true if the flag was set either evn, by env var or arg flag. Implements `cli.flag.IsSet` required to generate help.
func (*MapFlag[K, V]) String ¶
String returns a readable representation of this value (for usage defaults).
func (*MapFlag) TakesValue ¶
func (flag *MapFlag) TakesValue() bool
TakesValue returns true of the flag takes a value, otherwise false. Implements `cli.DocGenerationFlag.TakesValue` required to generate help.
type MapFlagKeyType ¶
type MapFlagKeyType interface { GenericType }
type MapFlagValueType ¶
type MapFlagValueType interface { GenericType | bool }
type NormalizeActsType ¶
type NormalizeActsType byte
const ( SingleDashFlag NormalizeActsType = iota DoubleDashFlag )
type SliceActionFunc ¶ added in v0.67.5
type SliceActionFunc[T SliceFlagType] func(ctx *Context, value []T) error
SliceActionFunc is the action to execute when the flag has been set either via a flag or via an environment variable.
type SliceFlag ¶
type SliceFlag[T SliceFlagType] struct { // The name of the flag. Name string // The default value of the flag to display in the help, if it is empty, the value is taken from `Destination`. DefaultText string // A short usage description to display in help. Usage string // Aliases are usually used for the short flag name, like `-h`. Aliases []string // The name of the env variable that is parsed and assigned to `Destination` before the flag value. EnvVar string // The action to execute when flag is specified Action SliceActionFunc[T] // The pointer to which the value of the flag or env var is assigned. // It also uses as the default value displayed in the help. Destination *[]T // The func used to split the EvnVar, by default `strings.Split` Splitter SplitterFunc // The EnvVarSep value is passed to the Splitter function as an argument. EnvVarSep string // Hidden hides the flag from the help, if set to true. Hidden bool // contains filtered or unexported fields }
SliceFlag is a multiple flag.
func (*SliceFlag) GetCategory ¶
func (flag *SliceFlag) GetCategory() string
GetCategory returns the category for the flag. Implements `cli.DocGenerationFlag.GetCategory` required to generate help.
func (*SliceFlag[T]) GetDefaultText ¶
GetDefaultText returns the flags value as string representation and an empty string if the flag takes no value at all.
func (*SliceFlag[T]) GetEnvVars ¶
GetEnvVars returns the env vars for this flag.
func (*SliceFlag[T]) GetHidden ¶ added in v0.67.0
GetHidden returns true if the flag should be hidden from the help.
func (*SliceFlag) GetValue ¶
func (flag *SliceFlag) GetValue() string
GetValue returns the flags value as string representation and an empty string if the flag takes no value at all. Implements `cli.DocGenerationFlag.GetValue` required to generate help.
func (*SliceFlag) IsSet ¶
func (flag *SliceFlag) IsSet() bool
IsSet returns true if the flag was set either evn, by env var or arg flag. Implements `cli.flag.IsSet` required to generate help.
func (*SliceFlag[T]) String ¶
String returns a readable representation of this value (for usage defaults).
func (*SliceFlag) TakesValue ¶
func (flag *SliceFlag) TakesValue() bool
TakesValue returns true of the flag takes a value, otherwise false. Implements `cli.DocGenerationFlag.TakesValue` required to generate help.
type SliceFlagType ¶
type SliceFlagType interface { GenericType }
type SplitterFunc ¶
SplitterFunc is used to parse flags containing multiple values.