1067 lines
39 KiB
Plaintext
1067 lines
39 KiB
Plaintext
package cli // import "github.com/urfave/cli/v3"
|
|
|
|
Package cli provides a minimal framework for creating and organizing command
|
|
line Go applications. cli is designed to be easy to understand and write,
|
|
the most simple cli application can be written as follows:
|
|
|
|
func main() {
|
|
(&cli.Command{}).Run(context.Background(), os.Args)
|
|
}
|
|
|
|
Of course this application does not do much, so let's make this an actual
|
|
application:
|
|
|
|
func main() {
|
|
cmd := &cli.Command{
|
|
Name: "greet",
|
|
Usage: "say a greeting",
|
|
Action: func(c *cli.Context) error {
|
|
fmt.Println("Greetings")
|
|
return nil
|
|
},
|
|
}
|
|
|
|
cmd.Run(context.Background(), os.Args)
|
|
}
|
|
|
|
VARIABLES
|
|
|
|
var (
|
|
SuggestFlag SuggestFlagFunc = suggestFlag
|
|
SuggestCommand SuggestCommandFunc = suggestCommand
|
|
SuggestDidYouMeanTemplate string = suggestDidYouMeanTemplate
|
|
)
|
|
var AnyArguments = []Argument{
|
|
&StringArg{
|
|
Max: -1,
|
|
},
|
|
}
|
|
AnyArguments to differentiate between no arguments(nil) vs aleast one
|
|
|
|
var CommandHelpTemplate = `NAME:
|
|
{{template "helpNameTemplate" .}}
|
|
|
|
USAGE:
|
|
{{template "usageTemplate" .}}{{if .Category}}
|
|
|
|
CATEGORY:
|
|
{{.Category}}{{end}}{{if .Description}}
|
|
|
|
DESCRIPTION:
|
|
{{template "descriptionTemplate" .}}{{end}}{{if .VisibleFlagCategories}}
|
|
|
|
OPTIONS:{{template "visibleFlagCategoryTemplate" .}}{{else if .VisibleFlags}}
|
|
|
|
OPTIONS:{{template "visibleFlagTemplate" .}}{{end}}{{if .VisiblePersistentFlags}}
|
|
|
|
GLOBAL OPTIONS:{{template "visiblePersistentFlagTemplate" .}}{{end}}
|
|
`
|
|
CommandHelpTemplate is the text template for the command help topic. cli.go
|
|
uses text/template to render templates. You can render custom help text by
|
|
setting this variable.
|
|
|
|
var DefaultInverseBoolPrefix = "no-"
|
|
var ErrWriter io.Writer = os.Stderr
|
|
ErrWriter is used to write errors to the user. This can be anything
|
|
implementing the io.Writer interface and defaults to os.Stderr.
|
|
|
|
var FishCompletionTemplate = `# {{ .Command.Name }} fish shell completion
|
|
|
|
function __fish_{{ .Command.Name }}_no_subcommand --description 'Test if there has been any subcommand yet'
|
|
for i in (commandline -opc)
|
|
if contains -- $i{{ range $v := .AllCommands }} {{ $v }}{{ end }}
|
|
return 1
|
|
end
|
|
end
|
|
return 0
|
|
end
|
|
|
|
{{ range $v := .Completions }}{{ $v }}
|
|
{{ end }}`
|
|
var NewFloatSlice = NewSliceBase[float64, NoConfig, floatValue]
|
|
var NewIntSlice = NewSliceBase[int64, IntegerConfig, intValue]
|
|
var NewStringMap = NewMapBase[string, StringConfig, stringValue]
|
|
var NewStringSlice = NewSliceBase[string, StringConfig, stringValue]
|
|
var NewUintSlice = NewSliceBase[uint64, IntegerConfig, uintValue]
|
|
var OsExiter = os.Exit
|
|
OsExiter is the function used when the app exits. If not set defaults to
|
|
os.Exit.
|
|
|
|
var RootCommandHelpTemplate = `NAME:
|
|
{{template "helpNameTemplate" .}}
|
|
|
|
USAGE:
|
|
{{if .UsageText}}{{wrap .UsageText 3}}{{else}}{{.FullName}} {{if .VisibleFlags}}[global options]{{end}}{{if .VisibleCommands}} [command [command options]]{{end}}{{if .ArgsUsage}} {{.ArgsUsage}}{{else}}{{if .Arguments}} [arguments...]{{end}}{{end}}{{end}}{{if .Version}}{{if not .HideVersion}}
|
|
|
|
VERSION:
|
|
{{.Version}}{{end}}{{end}}{{if .Description}}
|
|
|
|
DESCRIPTION:
|
|
{{template "descriptionTemplate" .}}{{end}}
|
|
{{- if len .Authors}}
|
|
|
|
AUTHOR{{template "authorsTemplate" .}}{{end}}{{if .VisibleCommands}}
|
|
|
|
COMMANDS:{{template "visibleCommandCategoryTemplate" .}}{{end}}{{if .VisibleFlagCategories}}
|
|
|
|
GLOBAL OPTIONS:{{template "visibleFlagCategoryTemplate" .}}{{else if .VisibleFlags}}
|
|
|
|
GLOBAL OPTIONS:{{template "visibleFlagTemplate" .}}{{end}}{{if .Copyright}}
|
|
|
|
COPYRIGHT:
|
|
{{template "copyrightTemplate" .}}{{end}}
|
|
`
|
|
RootCommandHelpTemplate is the text template for the Default help topic.
|
|
cli.go uses text/template to render templates. You can render custom help
|
|
text by setting this variable.
|
|
|
|
var SubcommandHelpTemplate = `NAME:
|
|
{{template "helpNameTemplate" .}}
|
|
|
|
USAGE:
|
|
{{if .UsageText}}{{wrap .UsageText 3}}{{else}}{{.FullName}}{{if .VisibleCommands}} [command [command options]] {{end}}{{if .ArgsUsage}} {{.ArgsUsage}}{{else}}{{if .Arguments}} [arguments...]{{end}}{{end}}{{end}}{{if .Category}}
|
|
|
|
CATEGORY:
|
|
{{.Category}}{{end}}{{if .Description}}
|
|
|
|
DESCRIPTION:
|
|
{{template "descriptionTemplate" .}}{{end}}{{if .VisibleCommands}}
|
|
|
|
COMMANDS:{{template "visibleCommandTemplate" .}}{{end}}{{if .VisibleFlagCategories}}
|
|
|
|
OPTIONS:{{template "visibleFlagCategoryTemplate" .}}{{else if .VisibleFlags}}
|
|
|
|
OPTIONS:{{template "visibleFlagTemplate" .}}{{end}}
|
|
`
|
|
SubcommandHelpTemplate is the text template for the subcommand help topic.
|
|
cli.go uses text/template to render templates. You can render custom help
|
|
text by setting this variable.
|
|
|
|
var VersionPrinter = printVersion
|
|
VersionPrinter prints the version for the App
|
|
|
|
var HelpPrinter helpPrinter = printHelp
|
|
HelpPrinter is a function that writes the help output. If not set
|
|
explicitly, this calls HelpPrinterCustom using only the default template
|
|
functions.
|
|
|
|
If custom logic for printing help is required, this function can be
|
|
overridden. If the ExtraInfo field is defined on an App, this function
|
|
should not be modified, as HelpPrinterCustom will be used directly in order
|
|
to capture the extra information.
|
|
|
|
var HelpPrinterCustom helpPrinterCustom = printHelpCustom
|
|
HelpPrinterCustom is a function that writes the help output. It is used as
|
|
the default implementation of HelpPrinter, and may be called directly if the
|
|
ExtraInfo field is set on an App.
|
|
|
|
In the default implementation, if the customFuncs argument contains a
|
|
"wrapAt" key, which is a function which takes no arguments and returns an
|
|
int, this int value will be used to produce a "wrap" function used by the
|
|
default template to wrap long lines.
|
|
|
|
|
|
FUNCTIONS
|
|
|
|
func DefaultAppComplete(ctx context.Context, cmd *Command)
|
|
DefaultAppComplete prints the list of subcommands as the default app
|
|
completion method
|
|
|
|
func DefaultCompleteWithFlags(ctx context.Context, cmd *Command)
|
|
func FlagNames(name string, aliases []string) []string
|
|
func HandleExitCoder(err error)
|
|
HandleExitCoder handles errors implementing ExitCoder by printing their
|
|
message and calling OsExiter with the given exit code.
|
|
|
|
If the given error instead implements MultiError, each error will be checked
|
|
for the ExitCoder interface, and OsExiter will be called with the last exit
|
|
code found, or exit code 1 if no ExitCoder is found.
|
|
|
|
This function is the default error-handling behavior for an App.
|
|
|
|
func ShowAppHelp(cmd *Command) error
|
|
ShowAppHelp is an action that displays the help.
|
|
|
|
func ShowAppHelpAndExit(cmd *Command, exitCode int)
|
|
ShowAppHelpAndExit - Prints the list of subcommands for the app and exits
|
|
with exit code.
|
|
|
|
func ShowCommandHelp(ctx context.Context, cmd *Command, commandName string) error
|
|
ShowCommandHelp prints help for the given command
|
|
|
|
func ShowCommandHelpAndExit(ctx context.Context, cmd *Command, command string, code int)
|
|
ShowCommandHelpAndExit - exits with code after showing help
|
|
|
|
func ShowSubcommandHelp(cmd *Command) error
|
|
ShowSubcommandHelp prints help for the given subcommand
|
|
|
|
func ShowSubcommandHelpAndExit(cmd *Command, exitCode int)
|
|
ShowSubcommandHelpAndExit - Prints help for the given subcommand and exits
|
|
with exit code.
|
|
|
|
func ShowVersion(cmd *Command)
|
|
ShowVersion prints the version number of the App
|
|
|
|
|
|
TYPES
|
|
|
|
type ActionFunc func(context.Context, *Command) error
|
|
ActionFunc is the action to execute when no subcommands are specified
|
|
|
|
type ActionableFlag interface {
|
|
RunAction(context.Context, *Command) error
|
|
}
|
|
ActionableFlag is an interface that wraps Flag interface and RunAction
|
|
operation.
|
|
|
|
type AfterFunc func(context.Context, *Command) error
|
|
AfterFunc is an action that executes after any subcommands are run and have
|
|
finished. The AfterFunc is run even if Action() panics.
|
|
|
|
type Args interface {
|
|
// Get returns the nth argument, or else a blank string
|
|
Get(n int) string
|
|
// First returns the first argument, or else a blank string
|
|
First() string
|
|
// Tail returns the rest of the arguments (not the first one)
|
|
// or else an empty string slice
|
|
Tail() []string
|
|
// Len returns the length of the wrapped slice
|
|
Len() int
|
|
// Present checks if there are any arguments present
|
|
Present() bool
|
|
// Slice returns a copy of the internal slice
|
|
Slice() []string
|
|
}
|
|
|
|
type Argument interface {
|
|
Parse([]string) ([]string, error)
|
|
Usage() string
|
|
}
|
|
|
|
type ArgumentBase[T any, C any, VC ValueCreator[T, C]] struct {
|
|
Name string `json:"name"` // the name of this argument
|
|
Value T `json:"value"` // the default value of this argument
|
|
Destination *T `json:"-"` // the destination point for this argument
|
|
Values *[]T `json:"-"` // all the values of this argument, only if multiple are supported
|
|
UsageText string `json:"usageText"` // the usage text to show
|
|
Min int `json:"minTimes"` // the min num of occurrences of this argument
|
|
Max int `json:"maxTimes"` // the max num of occurrences of this argument, set to -1 for unlimited
|
|
Config C `json:"config"` // config for this argument similar to Flag Config
|
|
}
|
|
|
|
func (a *ArgumentBase[T, C, VC]) Parse(s []string) ([]string, error)
|
|
|
|
func (a *ArgumentBase[T, C, VC]) Usage() string
|
|
|
|
type BeforeFunc func(context.Context, *Command) (context.Context, error)
|
|
BeforeFunc is an action that executes prior to any subcommands being run
|
|
once the context is ready. If a non-nil error is returned, no subcommands
|
|
are run.
|
|
|
|
type BoolConfig struct {
|
|
Count *int
|
|
}
|
|
BoolConfig defines the configuration for bool flags
|
|
|
|
type BoolFlag = FlagBase[bool, BoolConfig, boolValue]
|
|
|
|
type BoolWithInverseFlag struct {
|
|
// The BoolFlag which the positive and negative flags are generated from
|
|
*BoolFlag
|
|
|
|
// The prefix used to indicate a negative value
|
|
// Default: `env` becomes `no-env`
|
|
InversePrefix string
|
|
|
|
// Has unexported fields.
|
|
}
|
|
|
|
func (parent *BoolWithInverseFlag) Apply(set *flag.FlagSet) error
|
|
|
|
func (parent *BoolWithInverseFlag) Flags() []Flag
|
|
|
|
func (parent *BoolWithInverseFlag) IsSet() bool
|
|
|
|
func (parent *BoolWithInverseFlag) Names() []string
|
|
|
|
func (parent *BoolWithInverseFlag) RunAction(ctx context.Context, cmd *Command) error
|
|
|
|
func (parent *BoolWithInverseFlag) String() string
|
|
String implements the standard Stringer interface.
|
|
|
|
Example for BoolFlag{Name: "env"} --[no-]env (default: false)
|
|
|
|
func (parent *BoolWithInverseFlag) Value() bool
|
|
|
|
type CategorizableFlag interface {
|
|
// Returns the category of the flag
|
|
GetCategory() string
|
|
|
|
// Sets the category of the flag
|
|
SetCategory(string)
|
|
}
|
|
CategorizableFlag is an interface that allows us to potentially use a flag
|
|
in a categorized representation.
|
|
|
|
type Command struct {
|
|
// The name of the command
|
|
Name string `json:"name"`
|
|
// A list of aliases for the command
|
|
Aliases []string `json:"aliases"`
|
|
// A short description of the usage of this command
|
|
Usage string `json:"usage"`
|
|
// Text to override the USAGE section of help
|
|
UsageText string `json:"usageText"`
|
|
// A short description of the arguments of this command
|
|
ArgsUsage string `json:"argsUsage"`
|
|
// Version of the command
|
|
Version string `json:"version"`
|
|
// Longer explanation of how the command works
|
|
Description string `json:"description"`
|
|
// DefaultCommand is the (optional) name of a command
|
|
// to run if no command names are passed as CLI arguments.
|
|
DefaultCommand string `json:"defaultCommand"`
|
|
// The category the command is part of
|
|
Category string `json:"category"`
|
|
// List of child commands
|
|
Commands []*Command `json:"commands"`
|
|
// List of flags to parse
|
|
Flags []Flag `json:"flags"`
|
|
// Boolean to hide built-in help command and help flag
|
|
HideHelp bool `json:"hideHelp"`
|
|
// Ignored if HideHelp is true.
|
|
HideHelpCommand bool `json:"hideHelpCommand"`
|
|
// Boolean to hide built-in version flag and the VERSION section of help
|
|
HideVersion bool `json:"hideVersion"`
|
|
// Boolean to enable shell completion commands
|
|
EnableShellCompletion bool `json:"-"`
|
|
// Shell Completion generation command name
|
|
ShellCompletionCommandName string `json:"-"`
|
|
// The function to call when checking for shell command completions
|
|
ShellComplete ShellCompleteFunc `json:"-"`
|
|
// 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 BeforeFunc `json:"-"`
|
|
// An action to execute after any subcommands are run, but after the subcommand has finished
|
|
// It is run even if Action() panics
|
|
After AfterFunc `json:"-"`
|
|
// The function to call when this command is invoked
|
|
Action ActionFunc `json:"-"`
|
|
// Execute this function if the proper command cannot be found
|
|
CommandNotFound CommandNotFoundFunc `json:"-"`
|
|
// Execute this function if a usage error occurs.
|
|
OnUsageError OnUsageErrorFunc `json:"-"`
|
|
// Execute this function when an invalid flag is accessed from the context
|
|
InvalidFlagAccessHandler InvalidFlagAccessFunc `json:"-"`
|
|
// Boolean to hide this command from help or completion
|
|
Hidden bool `json:"hidden"`
|
|
// List of all authors who contributed (string or fmt.Stringer)
|
|
// TODO: ~string | fmt.Stringer when interface unions are available
|
|
Authors []any `json:"authors"`
|
|
// Copyright of the binary if any
|
|
Copyright string `json:"copyright"`
|
|
// Reader reader to write input to (useful for tests)
|
|
Reader io.Reader `json:"-"`
|
|
// Writer writer to write output to
|
|
Writer io.Writer `json:"-"`
|
|
// ErrWriter writes error output
|
|
ErrWriter io.Writer `json:"-"`
|
|
// ExitErrHandler processes any error encountered while running an App before
|
|
// it is returned to the caller. If no function is provided, HandleExitCoder
|
|
// is used as the default behavior.
|
|
ExitErrHandler ExitErrHandlerFunc `json:"-"`
|
|
// Other custom info
|
|
Metadata map[string]interface{} `json:"metadata"`
|
|
// Carries a function which returns app specific info.
|
|
ExtraInfo func() map[string]string `json:"-"`
|
|
// CustomRootCommandHelpTemplate the text template for app help topic.
|
|
// cli.go uses text/template to render templates. You can
|
|
// render custom help text by setting this variable.
|
|
CustomRootCommandHelpTemplate string `json:"-"`
|
|
// SliceFlagSeparator is used to customize the separator for SliceFlag, the default is ","
|
|
SliceFlagSeparator string `json:"sliceFlagSeparator"`
|
|
// DisableSliceFlagSeparator is used to disable SliceFlagSeparator, the default is false
|
|
DisableSliceFlagSeparator bool `json:"disableSliceFlagSeparator"`
|
|
// Boolean to enable short-option handling so user can combine several
|
|
// single-character bool arguments into one
|
|
// i.e. foobar -o -v -> foobar -ov
|
|
UseShortOptionHandling bool `json:"useShortOptionHandling"`
|
|
// Enable suggestions for commands and flags
|
|
Suggest bool `json:"suggest"`
|
|
// Allows global flags set by libraries which use flag.XXXVar(...) directly
|
|
// to be parsed through this library
|
|
AllowExtFlags bool `json:"allowExtFlags"`
|
|
// Treat all flags as normal arguments if true
|
|
SkipFlagParsing bool `json:"skipFlagParsing"`
|
|
// CustomHelpTemplate the text template for the command help topic.
|
|
// cli.go uses text/template to render templates. You can
|
|
// render custom help text by setting this variable.
|
|
CustomHelpTemplate string `json:"-"`
|
|
// Use longest prefix match for commands
|
|
PrefixMatchCommands bool `json:"prefixMatchCommands"`
|
|
// Custom suggest command for matching
|
|
SuggestCommandFunc SuggestCommandFunc `json:"-"`
|
|
// Flag exclusion group
|
|
MutuallyExclusiveFlags []MutuallyExclusiveFlags `json:"mutuallyExclusiveFlags"`
|
|
// Arguments to parse for this command
|
|
Arguments []Argument `json:"arguments"`
|
|
// Whether to read arguments from stdin
|
|
// applicable to root command only
|
|
ReadArgsFromStdin bool `json:"readArgsFromStdin"`
|
|
|
|
// Has unexported fields.
|
|
}
|
|
Command contains everything needed to run an application that accepts a
|
|
string slice of arguments such as os.Args. A given Command may contain Flags
|
|
and sub-commands in Commands.
|
|
|
|
func (cmd *Command) Args() Args
|
|
Args returns the command line arguments associated with the command.
|
|
|
|
func (cmd *Command) Bool(name string) bool
|
|
|
|
func (cmd *Command) Command(name string) *Command
|
|
|
|
func (cmd *Command) Count(name string) int
|
|
Count returns the num of occurrences of this flag
|
|
|
|
func (cmd *Command) Duration(name string) time.Duration
|
|
|
|
func (cmd *Command) FlagNames() []string
|
|
FlagNames returns a slice of flag names used by the this command and all of
|
|
its parent commands.
|
|
|
|
func (cmd *Command) Float(name string) float64
|
|
Float looks up the value of a local FloatFlag, returns 0 if not found
|
|
|
|
func (cmd *Command) FloatSlice(name string) []float64
|
|
FloatSlice looks up the value of a local FloatSliceFlag, returns nil if not
|
|
found
|
|
|
|
func (cmd *Command) FullName() string
|
|
FullName returns the full name of the command. For commands with parents
|
|
this ensures that the parent commands are part of the command path.
|
|
|
|
func (cmd *Command) Generic(name string) Value
|
|
Generic looks up the value of a local GenericFlag, returns nil if not found
|
|
|
|
func (cmd *Command) HasName(name string) bool
|
|
HasName returns true if Command.Name matches given name
|
|
|
|
func (cmd *Command) Int(name string) int64
|
|
Int looks up the value of a local Int64Flag, returns 0 if not found
|
|
|
|
func (cmd *Command) IntSlice(name string) []int64
|
|
IntSlice looks up the value of a local IntSliceFlag, returns nil if not
|
|
found
|
|
|
|
func (cmd *Command) IsSet(name string) bool
|
|
IsSet determines if the flag was actually set
|
|
|
|
func (cmd *Command) Lineage() []*Command
|
|
Lineage returns *this* command and all of its ancestor commands in order
|
|
from child to parent
|
|
|
|
func (cmd *Command) LocalFlagNames() []string
|
|
LocalFlagNames returns a slice of flag names used in this command.
|
|
|
|
func (cmd *Command) NArg() int
|
|
NArg returns the number of the command line arguments.
|
|
|
|
func (cmd *Command) Names() []string
|
|
Names returns the names including short names and aliases.
|
|
|
|
func (cmd *Command) NumFlags() int
|
|
NumFlags returns the number of flags set
|
|
|
|
func (cmd *Command) Root() *Command
|
|
Root returns the Command at the root of the graph
|
|
|
|
func (cmd *Command) Run(ctx context.Context, osArgs []string) (deferErr error)
|
|
Run is the entry point to the command graph. The positional arguments are
|
|
parsed according to the Flag and Command definitions and the matching Action
|
|
functions are run.
|
|
|
|
func (cmd *Command) Set(name, value string) error
|
|
Set sets a context flag to a value.
|
|
|
|
func (cmd *Command) String(name string) string
|
|
|
|
func (cmd *Command) StringMap(name string) map[string]string
|
|
StringMap looks up the value of a local StringMapFlag, returns nil if not
|
|
found
|
|
|
|
func (cmd *Command) StringSlice(name string) []string
|
|
StringSlice looks up the value of a local StringSliceFlag, returns nil if
|
|
not found
|
|
|
|
func (cmd *Command) Timestamp(name string) time.Time
|
|
Timestamp gets the timestamp from a flag name
|
|
|
|
func (cmd *Command) ToFishCompletion() (string, error)
|
|
ToFishCompletion creates a fish completion string for the `*App` The
|
|
function errors if either parsing or writing of the string fails.
|
|
|
|
func (cmd *Command) Uint(name string) uint64
|
|
Uint looks up the value of a local Uint64Flag, returns 0 if not found
|
|
|
|
func (cmd *Command) UintSlice(name string) []uint64
|
|
UintSlice looks up the value of a local UintSliceFlag, returns nil if not
|
|
found
|
|
|
|
func (cmd *Command) Value(name string) interface{}
|
|
Value returns the value of the flag corresponding to `name`
|
|
|
|
func (cmd *Command) VisibleCategories() []CommandCategory
|
|
VisibleCategories returns a slice of categories and commands that are
|
|
Hidden=false
|
|
|
|
func (cmd *Command) VisibleCommands() []*Command
|
|
VisibleCommands returns a slice of the Commands with Hidden=false
|
|
|
|
func (cmd *Command) VisibleFlagCategories() []VisibleFlagCategory
|
|
VisibleFlagCategories returns a slice containing all the visible flag
|
|
categories with the flags they contain
|
|
|
|
func (cmd *Command) VisibleFlags() []Flag
|
|
VisibleFlags returns a slice of the Flags with Hidden=false
|
|
|
|
func (cmd *Command) VisiblePersistentFlags() []Flag
|
|
VisiblePersistentFlags returns a slice of LocalFlag with Persistent=true and
|
|
Hidden=false.
|
|
|
|
type CommandCategories interface {
|
|
// AddCommand adds a command to a category, creating a new category if necessary.
|
|
AddCommand(category string, command *Command)
|
|
// Categories returns a slice of categories sorted by name
|
|
Categories() []CommandCategory
|
|
}
|
|
CommandCategories interface allows for category manipulation
|
|
|
|
type CommandCategory interface {
|
|
// Name returns the category name string
|
|
Name() string
|
|
// VisibleCommands returns a slice of the Commands with Hidden=false
|
|
VisibleCommands() []*Command
|
|
}
|
|
CommandCategory is a category containing commands.
|
|
|
|
type CommandNotFoundFunc func(context.Context, *Command, string)
|
|
CommandNotFoundFunc is executed if the proper command cannot be found
|
|
|
|
type Countable interface {
|
|
Count() int
|
|
}
|
|
Countable is an interface to enable detection of flag values which support
|
|
repetitive flags
|
|
|
|
type DocGenerationFlag interface {
|
|
// TakesValue returns true if the flag takes a value, otherwise false
|
|
TakesValue() bool
|
|
|
|
// GetUsage returns the usage string for the flag
|
|
GetUsage() string
|
|
|
|
// GetValue returns the flags value as string representation and an empty
|
|
// string if the flag takes no value at all.
|
|
GetValue() string
|
|
|
|
// GetDefaultText returns the default text for this flag
|
|
GetDefaultText() string
|
|
|
|
// GetEnvVars returns the env vars for this flag
|
|
GetEnvVars() []string
|
|
|
|
// IsDefaultVisible returns whether the default value should be shown in
|
|
// help text
|
|
IsDefaultVisible() bool
|
|
}
|
|
DocGenerationFlag is an interface that allows documentation generation for
|
|
the flag
|
|
|
|
type DocGenerationMultiValueFlag interface {
|
|
DocGenerationFlag
|
|
|
|
// IsMultiValueFlag returns true for flags that can be given multiple times.
|
|
IsMultiValueFlag() bool
|
|
}
|
|
DocGenerationMultiValueFlag extends DocGenerationFlag for slice/map based
|
|
flags.
|
|
|
|
type DurationFlag = FlagBase[time.Duration, NoConfig, durationValue]
|
|
|
|
type EnvValueSource interface {
|
|
IsFromEnv() bool
|
|
Key() string
|
|
}
|
|
EnvValueSource is to specifically detect env sources when printing help text
|
|
|
|
type ErrorFormatter interface {
|
|
Format(s fmt.State, verb rune)
|
|
}
|
|
ErrorFormatter is the interface that will suitably format the error output
|
|
|
|
type ExitCoder interface {
|
|
error
|
|
ExitCode() int
|
|
}
|
|
ExitCoder is the interface checked by `App` and `Command` for a custom exit
|
|
code
|
|
|
|
func Exit(message interface{}, exitCode int) ExitCoder
|
|
Exit wraps a message and exit code into an error, which by default is
|
|
handled with a call to os.Exit during default error handling.
|
|
|
|
This is the simplest way to trigger a non-zero exit code for an App
|
|
without having to call os.Exit manually. During testing, this behavior
|
|
can be avoided by overriding the ExitErrHandler function on an App or the
|
|
package-global OsExiter function.
|
|
|
|
type ExitErrHandlerFunc func(context.Context, *Command, error)
|
|
ExitErrHandlerFunc is executed if provided in order to handle exitError
|
|
values returned by Actions and Before/After functions.
|
|
|
|
type Flag interface {
|
|
fmt.Stringer
|
|
|
|
// Apply Flag settings to the given flag set
|
|
Apply(*flag.FlagSet) error
|
|
|
|
// All possible names for this flag
|
|
Names() []string
|
|
|
|
// Whether the flag has been set or not
|
|
IsSet() bool
|
|
}
|
|
Flag is a common interface related to parsing flags in cli. For more
|
|
advanced flag parsing techniques, it is recommended that this interface be
|
|
implemented.
|
|
|
|
var GenerateShellCompletionFlag Flag = &BoolFlag{
|
|
Name: "generate-shell-completion",
|
|
Hidden: true,
|
|
}
|
|
GenerateShellCompletionFlag enables shell completion
|
|
|
|
var HelpFlag Flag = &BoolFlag{
|
|
Name: "help",
|
|
Aliases: []string{"h"},
|
|
Usage: "show help",
|
|
HideDefault: true,
|
|
Local: true,
|
|
}
|
|
HelpFlag prints the help for all commands and subcommands. Set to nil to
|
|
disable the flag. The subcommand will still be added unless HideHelp or
|
|
HideHelpCommand is set to true.
|
|
|
|
var VersionFlag Flag = &BoolFlag{
|
|
Name: "version",
|
|
Aliases: []string{"v"},
|
|
Usage: "print the version",
|
|
HideDefault: true,
|
|
Local: true,
|
|
}
|
|
VersionFlag prints the version for the application
|
|
|
|
type FlagBase[T any, C any, VC ValueCreator[T, C]] struct {
|
|
Name string `json:"name"` // name of the flag
|
|
Category string `json:"category"` // category of the flag, if any
|
|
DefaultText string `json:"defaultText"` // default text of the flag for usage purposes
|
|
HideDefault bool `json:"hideDefault"` // whether to hide the default value in output
|
|
Usage string `json:"usage"` // usage string for help output
|
|
Sources ValueSourceChain `json:"-"` // sources to load flag value from
|
|
Required bool `json:"required"` // whether the flag is required or not
|
|
Hidden bool `json:"hidden"` // whether to hide the flag in help output
|
|
Local bool `json:"local"` // whether the flag needs to be applied to subcommands as well
|
|
Value T `json:"defaultValue"` // default value for this flag if not set by from any source
|
|
Destination *T `json:"-"` // destination pointer for value when set
|
|
Aliases []string `json:"aliases"` // Aliases that are allowed for this flag
|
|
TakesFile bool `json:"takesFileArg"` // whether this flag takes a file argument, mainly for shell completion purposes
|
|
Action func(context.Context, *Command, T) error `json:"-"` // Action callback to be called when flag is set
|
|
Config C `json:"config"` // Additional/Custom configuration associated with this flag type
|
|
OnlyOnce bool `json:"onlyOnce"` // whether this flag can be duplicated on the command line
|
|
Validator func(T) error `json:"-"` // custom function to validate this flag value
|
|
ValidateDefaults bool `json:"validateDefaults"` // whether to validate defaults or not
|
|
|
|
// Has unexported fields.
|
|
}
|
|
FlagBase [T,C,VC] is a generic flag base which can be used as a boilerplate
|
|
to implement the most common interfaces used by urfave/cli.
|
|
|
|
T specifies the type
|
|
C specifies the configuration required(if any for that flag type)
|
|
VC specifies the value creator which creates the flag.Value emulation
|
|
|
|
func (f *FlagBase[T, C, V]) Apply(set *flag.FlagSet) error
|
|
Apply populates the flag given the flag set and environment
|
|
|
|
func (f *FlagBase[T, C, V]) GetCategory() string
|
|
GetCategory returns the category of the flag
|
|
|
|
func (f *FlagBase[T, C, V]) GetDefaultText() string
|
|
GetDefaultText returns the default text for this flag
|
|
|
|
func (f *FlagBase[T, C, V]) GetEnvVars() []string
|
|
GetEnvVars returns the env vars for this flag
|
|
|
|
func (f *FlagBase[T, C, V]) GetUsage() string
|
|
GetUsage returns the usage string for the flag
|
|
|
|
func (f *FlagBase[T, C, V]) GetValue() string
|
|
GetValue returns the flags value as string representation and an empty
|
|
string if the flag takes no value at all.
|
|
|
|
func (f *FlagBase[T, C, V]) IsDefaultVisible() bool
|
|
IsDefaultVisible returns true if the flag is not hidden, otherwise false
|
|
|
|
func (f *FlagBase[T, C, VC]) IsLocal() bool
|
|
IsLocal returns false if flag needs to be persistent across subcommands
|
|
|
|
func (f *FlagBase[T, C, VC]) IsMultiValueFlag() bool
|
|
IsMultiValueFlag returns true if the value type T can take multiple values
|
|
from cmd line. This is true for slice and map type flags
|
|
|
|
func (f *FlagBase[T, C, V]) IsRequired() bool
|
|
IsRequired returns whether or not the flag is required
|
|
|
|
func (f *FlagBase[T, C, V]) IsSet() bool
|
|
IsSet returns whether or not the flag has been set through env or file
|
|
|
|
func (f *FlagBase[T, C, V]) IsVisible() bool
|
|
IsVisible returns true if the flag is not hidden, otherwise false
|
|
|
|
func (f *FlagBase[T, C, V]) Names() []string
|
|
Names returns the names of the flag
|
|
|
|
func (f *FlagBase[T, C, V]) RunAction(ctx context.Context, cmd *Command) error
|
|
RunAction executes flag action if set
|
|
|
|
func (f *FlagBase[T, C, V]) SetCategory(c string)
|
|
|
|
func (f *FlagBase[T, C, V]) String() string
|
|
String returns a readable representation of this value (for usage defaults)
|
|
|
|
func (f *FlagBase[T, C, V]) TakesValue() bool
|
|
TakesValue returns true if the flag takes a value, otherwise false
|
|
|
|
type FlagCategories interface {
|
|
// AddFlags adds a flag to a category, creating a new category if necessary.
|
|
AddFlag(category string, fl Flag)
|
|
// VisibleCategories returns a slice of visible flag categories sorted by name
|
|
VisibleCategories() []VisibleFlagCategory
|
|
}
|
|
FlagCategories interface allows for category manipulation
|
|
|
|
type FlagEnvHintFunc func(envVars []string, str string) string
|
|
FlagEnvHintFunc is used by the default FlagStringFunc to annotate flag help
|
|
with the environment variable details.
|
|
|
|
var FlagEnvHinter FlagEnvHintFunc = withEnvHint
|
|
FlagEnvHinter annotates flag help message with the environment variable
|
|
details. This is used by the default FlagStringer.
|
|
|
|
type FlagFileHintFunc func(filePath, str string) string
|
|
FlagFileHintFunc is used by the default FlagStringFunc to annotate flag help
|
|
with the file path details.
|
|
|
|
var FlagFileHinter FlagFileHintFunc = withFileHint
|
|
FlagFileHinter annotates flag help message with the environment variable
|
|
details. This is used by the default FlagStringer.
|
|
|
|
type FlagNamePrefixFunc func(fullName []string, placeholder string) string
|
|
FlagNamePrefixFunc is used by the default FlagStringFunc to create prefix
|
|
text for a flag's full name.
|
|
|
|
var FlagNamePrefixer FlagNamePrefixFunc = prefixedNames
|
|
FlagNamePrefixer converts a full flag name and its placeholder into the help
|
|
message flag prefix. This is used by the default FlagStringer.
|
|
|
|
type FlagStringFunc func(Flag) string
|
|
FlagStringFunc is used by the help generation to display a flag, which is
|
|
expected to be a single line.
|
|
|
|
var FlagStringer FlagStringFunc = stringifyFlag
|
|
FlagStringer converts a flag definition to a string. This is used by help to
|
|
display a flag.
|
|
|
|
type FlagsByName []Flag
|
|
FlagsByName is a slice of Flag.
|
|
|
|
func (f FlagsByName) Len() int
|
|
|
|
func (f FlagsByName) Less(i, j int) bool
|
|
|
|
func (f FlagsByName) Swap(i, j int)
|
|
|
|
type FloatArg = ArgumentBase[float64, NoConfig, floatValue]
|
|
|
|
type FloatFlag = FlagBase[float64, NoConfig, floatValue]
|
|
|
|
type FloatSlice = SliceBase[float64, NoConfig, floatValue]
|
|
|
|
type FloatSliceFlag = FlagBase[[]float64, NoConfig, FloatSlice]
|
|
|
|
type GenericFlag = FlagBase[Value, NoConfig, genericValue]
|
|
|
|
type IntArg = ArgumentBase[int64, IntegerConfig, intValue]
|
|
|
|
type IntFlag = FlagBase[int64, IntegerConfig, intValue]
|
|
|
|
type IntSlice = SliceBase[int64, IntegerConfig, intValue]
|
|
|
|
type IntSliceFlag = FlagBase[[]int64, IntegerConfig, IntSlice]
|
|
|
|
type IntegerConfig struct {
|
|
Base int
|
|
}
|
|
IntegerConfig is the configuration for all integer type flags
|
|
|
|
type InvalidFlagAccessFunc func(context.Context, *Command, string)
|
|
InvalidFlagAccessFunc is executed when an invalid flag is accessed from the
|
|
context.
|
|
|
|
type LocalFlag interface {
|
|
IsLocal() bool
|
|
}
|
|
LocalFlag is an interface to enable detection of flags which are local to
|
|
current command
|
|
|
|
type MapBase[T any, C any, VC ValueCreator[T, C]] struct {
|
|
// Has unexported fields.
|
|
}
|
|
MapBase wraps map[string]T to satisfy flag.Value
|
|
|
|
func NewMapBase[T any, C any, VC ValueCreator[T, C]](defaults map[string]T) *MapBase[T, C, VC]
|
|
NewMapBase makes a *MapBase with default values
|
|
|
|
func (i MapBase[T, C, VC]) Create(val map[string]T, p *map[string]T, c C) Value
|
|
|
|
func (i *MapBase[T, C, VC]) Get() interface{}
|
|
Get returns the mapping of values set by this flag
|
|
|
|
func (i *MapBase[T, C, VC]) Serialize() string
|
|
Serialize allows MapBase to fulfill Serializer
|
|
|
|
func (i *MapBase[T, C, VC]) Set(value string) error
|
|
Set parses the value and appends it to the list of values
|
|
|
|
func (i *MapBase[T, C, VC]) String() string
|
|
String returns a readable representation of this value (for usage defaults)
|
|
|
|
func (i MapBase[T, C, VC]) ToString(t map[string]T) string
|
|
|
|
func (i *MapBase[T, C, VC]) Value() map[string]T
|
|
Value returns the mapping of values set by this flag
|
|
|
|
type MapSource interface {
|
|
fmt.Stringer
|
|
fmt.GoStringer
|
|
|
|
// Lookup returns the value from the source based on key
|
|
// and if it was found
|
|
// or returns an empty string and false
|
|
Lookup(string) (any, bool)
|
|
}
|
|
MapSource is a source which can be used to look up a value based on a key
|
|
typically for use with a cli.Flag
|
|
|
|
func NewMapSource(name string, m map[any]any) MapSource
|
|
|
|
type MultiError interface {
|
|
error
|
|
Errors() []error
|
|
}
|
|
MultiError is an error that wraps multiple errors.
|
|
|
|
type MutuallyExclusiveFlags struct {
|
|
// Flag list
|
|
Flags [][]Flag
|
|
|
|
// whether this group is required
|
|
Required bool
|
|
|
|
// Category to apply to all flags within group
|
|
Category string
|
|
}
|
|
MutuallyExclusiveFlags defines a mutually exclusive flag group Multiple
|
|
option paths can be provided out of which only one can be defined on cmdline
|
|
So for example [ --foo | [ --bar something --darth somethingelse ] ]
|
|
|
|
type NoConfig struct{}
|
|
NoConfig is for flags which dont need a custom configuration
|
|
|
|
type OnUsageErrorFunc func(ctx context.Context, cmd *Command, err error, isSubcommand bool) error
|
|
OnUsageErrorFunc is executed if a usage error occurs. This is useful for
|
|
displaying customized usage error messages. This function is able to replace
|
|
the original error messages. If this function is not set, the "Incorrect
|
|
usage" is displayed and the execution is interrupted.
|
|
|
|
type RequiredFlag interface {
|
|
// whether the flag is a required flag or not
|
|
IsRequired() bool
|
|
}
|
|
RequiredFlag is an interface that allows us to mark flags as required
|
|
it allows flags required flags to be backwards compatible with the Flag
|
|
interface
|
|
|
|
type Serializer interface {
|
|
Serialize() string
|
|
}
|
|
Serializer is used to circumvent the limitations of flag.FlagSet.Set
|
|
|
|
type ShellCompleteFunc func(context.Context, *Command)
|
|
ShellCompleteFunc is an action to execute when the shell completion flag is
|
|
set
|
|
|
|
type SliceBase[T any, C any, VC ValueCreator[T, C]] struct {
|
|
// Has unexported fields.
|
|
}
|
|
SliceBase wraps []T to satisfy flag.Value
|
|
|
|
func NewSliceBase[T any, C any, VC ValueCreator[T, C]](defaults ...T) *SliceBase[T, C, VC]
|
|
NewSliceBase makes a *SliceBase with default values
|
|
|
|
func (i SliceBase[T, C, VC]) Create(val []T, p *[]T, c C) Value
|
|
|
|
func (i *SliceBase[T, C, VC]) Get() interface{}
|
|
Get returns the slice of values set by this flag
|
|
|
|
func (i *SliceBase[T, C, VC]) Serialize() string
|
|
Serialize allows SliceBase to fulfill Serializer
|
|
|
|
func (i *SliceBase[T, C, VC]) Set(value string) error
|
|
Set parses the value and appends it to the list of values
|
|
|
|
func (i *SliceBase[T, C, VC]) String() string
|
|
String returns a readable representation of this value (for usage defaults)
|
|
|
|
func (i SliceBase[T, C, VC]) ToString(t []T) string
|
|
|
|
func (i *SliceBase[T, C, VC]) Value() []T
|
|
Value returns the slice of values set by this flag
|
|
|
|
type StringArg = ArgumentBase[string, StringConfig, stringValue]
|
|
|
|
type StringConfig struct {
|
|
// Whether to trim whitespace of parsed value
|
|
TrimSpace bool
|
|
}
|
|
StringConfig defines the configuration for string flags
|
|
|
|
type StringFlag = FlagBase[string, StringConfig, stringValue]
|
|
|
|
type StringMap = MapBase[string, StringConfig, stringValue]
|
|
|
|
type StringMapArg = ArgumentBase[map[string]string, StringConfig, StringMap]
|
|
|
|
type StringMapFlag = FlagBase[map[string]string, StringConfig, StringMap]
|
|
|
|
type StringSlice = SliceBase[string, StringConfig, stringValue]
|
|
|
|
type StringSliceFlag = FlagBase[[]string, StringConfig, StringSlice]
|
|
|
|
type SuggestCommandFunc func(commands []*Command, provided string) string
|
|
|
|
type SuggestFlagFunc func(flags []Flag, provided string, hideHelp bool) string
|
|
|
|
type TimestampArg = ArgumentBase[time.Time, TimestampConfig, timestampValue]
|
|
|
|
type TimestampConfig struct {
|
|
Timezone *time.Location
|
|
// Available layouts for flag value.
|
|
//
|
|
// Note that value for formats with missing year/date will be interpreted as current year/date respectively.
|
|
//
|
|
// Read more about time layouts: https://pkg.go.dev/time#pkg-constants
|
|
Layouts []string
|
|
}
|
|
TimestampConfig defines the config for timestamp flags
|
|
|
|
type TimestampFlag = FlagBase[time.Time, TimestampConfig, timestampValue]
|
|
|
|
type UintArg = ArgumentBase[uint64, IntegerConfig, uintValue]
|
|
|
|
type UintFlag = FlagBase[uint64, IntegerConfig, uintValue]
|
|
|
|
type UintSlice = SliceBase[uint64, IntegerConfig, uintValue]
|
|
|
|
type UintSliceFlag = FlagBase[[]uint64, IntegerConfig, UintSlice]
|
|
|
|
type Value interface {
|
|
flag.Value
|
|
flag.Getter
|
|
}
|
|
Value represents a value as used by cli. For now it implements the golang
|
|
flag.Value interface
|
|
|
|
type ValueCreator[T any, C any] interface {
|
|
Create(T, *T, C) Value
|
|
ToString(T) string
|
|
}
|
|
ValueCreator is responsible for creating a flag.Value emulation as well as
|
|
custom formatting
|
|
|
|
T specifies the type
|
|
C specifies the config for the type
|
|
|
|
type ValueSource interface {
|
|
fmt.Stringer
|
|
fmt.GoStringer
|
|
|
|
// Lookup returns the value from the source and if it was found
|
|
// or returns an empty string and false
|
|
Lookup() (string, bool)
|
|
}
|
|
ValueSource is a source which can be used to look up a value, typically for
|
|
use with a cli.Flag
|
|
|
|
func EnvVar(key string) ValueSource
|
|
|
|
func File(path string) ValueSource
|
|
|
|
func NewMapValueSource(key string, ms MapSource) ValueSource
|
|
|
|
type ValueSourceChain struct {
|
|
Chain []ValueSource
|
|
}
|
|
ValueSourceChain contains an ordered series of ValueSource that allows for
|
|
lookup where the first ValueSource to resolve is returned
|
|
|
|
func EnvVars(keys ...string) ValueSourceChain
|
|
EnvVars is a helper function to encapsulate a number of envVarValueSource
|
|
together as a ValueSourceChain
|
|
|
|
func Files(paths ...string) ValueSourceChain
|
|
Files is a helper function to encapsulate a number of fileValueSource
|
|
together as a ValueSourceChain
|
|
|
|
func NewValueSourceChain(src ...ValueSource) ValueSourceChain
|
|
|
|
func (vsc *ValueSourceChain) Append(other ValueSourceChain)
|
|
|
|
func (vsc *ValueSourceChain) EnvKeys() []string
|
|
|
|
func (vsc *ValueSourceChain) GoString() string
|
|
|
|
func (vsc *ValueSourceChain) Lookup() (string, bool)
|
|
|
|
func (vsc *ValueSourceChain) LookupWithSource() (string, ValueSource, bool)
|
|
|
|
func (vsc *ValueSourceChain) String() string
|
|
|
|
type VisibleFlag interface {
|
|
// IsVisible returns true if the flag is not hidden, otherwise false
|
|
IsVisible() bool
|
|
}
|
|
VisibleFlag is an interface that allows to check if a flag is visible
|
|
|
|
type VisibleFlagCategory interface {
|
|
// Name returns the category name string
|
|
Name() string
|
|
// Flags returns a slice of VisibleFlag sorted by name
|
|
Flags() []Flag
|
|
}
|
|
VisibleFlagCategory is a category containing flags.
|
|
|