cli

package
v0.59.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 13, 2024 License: MIT Imports: 15 Imported by: 1

Documentation

Index

Constants

This section is empty.

Variables

View Source 
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 = ""
)
View Source 
var (
	MapFlagEnvVarSep = ","
	MapFlagKeyValSep = "="
)
View Source 
var DefaultComplete = defaultComplete
View Source 
var (
	// FlagSplitter uses to separate arguments and env vars with multiple values.
	FlagSplitter = strings.Split
)
View Source 
var (
	SliceFlagEnvVarSep = ","
)

Functions

func LexicographicLess 

func LexicographicLess(i, j string) bool

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 ShowAppHelp 

func ShowAppHelp(ctx *Context) error

ShowAppHelp prints App help.

func ShowCommandHelp 

func ShowCommandHelp(ctx *Context, cmdName string) error

ShowCommandHelp prints help for the given command.

func ShowCompletions added in v0.53.4 

func ShowCompletions(ctx *Context) error

ShowCompletions prints the lists of commands within a given context

func ShowVersion 

func ShowVersion(ctx *Context) error

Types

type ActionFunc 

type ActionFunc func(ctx *Context) error

ActionFunc is the action to execute when no commands/subcommands are specified.

type ActionableFlag 

type ActionableFlag interface {
	Flag
	RunAction(*Context) error
}

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 NewApp 

func NewApp() *App

NewApp returns app new App instance.

func (*App) AddCommands 

func (app *App) AddCommands(cmds ...*Command)

AddCommands adds new commands.

func (*App) AddFlags 

func (app *App) AddFlags(flags ...Flag)

AddFlags adds new flags.

func (*App) Run 

func (app *App) Run(arguments []string) error

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 

func (app *App) RunContext(ctx context.Context, arguments []string) (err error)

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 

func (app *App) VisibleFlags() Flags

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 

func (args Args) CommandName() string

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) First 

func (args Args) First() string

First returns the first argument or a blank string

func (Args) Get 

func (args Args) Get(n int) string

Get returns the nth argument, or else a blank string

func (Args) Last added in v0.53.4 

func (args Args) Last() string

Last returns the last argument or a blank string

func (Args) Len 

func (args Args) Len() int

Len returns the length of the wrapped slice

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

func (Args) Present 

func (args Args) Present() bool

Present checks if there are any arguments present

func (Args) Slice 

func (args Args) Slice() []string

Slice returns a copy of the internal slice

func (Args) Tail 

func (args Args) Tail() []string

Tail returns the rest of the arguments (not the first one) or else an empty string slice

type AutocompleteInstaller added in v0.53.4 

type AutocompleteInstaller interface {
	Install(string) error
	Uninstall(string) error
}

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 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 ActionFunc
	// 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
	// contains filtered or unexported fields
}

func (*BoolFlag) Apply 

func (flag *BoolFlag) Apply(set *libflag.FlagSet) error

Apply applies Flag settings to the given flag set.

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 

func (flag *BoolFlag) GetDefaultText() string

GetDefaultText returns the flags value as string representation and an empty string if the flag takes no value at all.

func (*BoolFlag) GetEnvVars 

func (flag *BoolFlag) GetEnvVars() []string

GetEnvVars returns the env vars for this flag.

func (*BoolFlag) GetUsage 

func (flag *BoolFlag) GetUsage() string

GetUsage returns the usage string for the flag.

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) LookupEnv 

func (flag *BoolFlag) LookupEnv(envVar string) *string

func (*BoolFlag) Names 

func (flag *BoolFlag) Names() []string

Names returns the names of the flag.

func (*BoolFlag) RunAction 

func (flag *BoolFlag) RunAction(ctx *Context) error

RunAction implements ActionableFlag.RunAction

func (*BoolFlag) String 

func (flag *BoolFlag) String() 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.

func (*BoolFlag) Value 

func (flag *BoolFlag) Value() FlagValue

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) HasName 

func (cmd *Command) HasName(name string) bool

HasName returns true if Command.Name matches given name

func (*Command) Names 

func (cmd *Command) Names() []string

Names returns the names including short names and aliases.

func (*Command) Run 

func (cmd *Command) Run(ctx *Context, args Args) (err error)

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 

func (cmd *Command) Subcommand(name string) *Command

Subcommand returns a subcommand that matches the given name.

func (*Command) VisibleFlags 

func (cmd *Command) VisibleFlags() Flags

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) Add 

func (commands *Commands) Add(cmd *Command)

Add adds a new cmd to the list.

func (Commands) Filter 

func (commands Commands) Filter(names []string) Commands

Filter returns a list of commands filtered by the given names.

func (Commands) Get 

func (commands Commands) Get(name string) *Command

Get returns a Command by the given name.

func (Commands) Len 

func (commands Commands) Len() int

func (Commands) Less 

func (commands Commands) Less(i, j int) bool

func (Commands) SkipRunning 

func (commands Commands) SkipRunning() Commands

SkipRunning prevents running commands as the final commands, but keep showing them in help.

func (Commands) Swap 

func (commands Commands) Swap(i, j int)

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 

type CompleteFunc func(ctx *Context) error

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.

func (*Context) Args 

func (ctx *Context) Args() Args

Args returns the command line arguments associated with the context.

func (*Context) Clone 

func (ctx *Context) Clone(command *Command, args Args) *Context

func (*Context) Value 

func (ctx *Context) Value(key any) any

func (Context) WithValue 

func (ctx Context) WithValue(key, val any) *Context

type Flag 

type Flag interface {
	Value() FlagValue

	// `urfave/cli/v2` uses to generate help
	cli.DocGenerationFlag
}

type FlagType 

type FlagType[T any] interface {
	libflag.Getter
	Clone(dest *T) FlagType[T]
}

type FlagValue 

type FlagValue interface {
	libflag.Getter

	GetDefaultText() string

	IsSet() bool

	// optional interface to indicate boolean flags that can be
	// supplied without "=value" text
	IsBoolFlag() bool
}

type Flags 

type Flags []Flag

func (*Flags) Add 

func (flags *Flags) Add(newFlags ...Flag)

Add adds a new flag to the list.

func (Flags) Filter 

func (flags Flags) Filter(names []string) Flags

Filter returns a list of flags filtered by the given names.

func (Flags) Get 

func (flags Flags) Get(name string) Flag

Get returns a Flag by the given name.

func (Flags) Len 

func (flags Flags) Len() int

func (Flags) Less 

func (flags Flags) Less(i, j int) bool

func (Flags) RunActions 

func (flags Flags) RunActions(ctx *Context) error

func (Flags) Sort 

func (flags Flags) Sort() Flags

func (Flags) Swap 

func (flags Flags) Swap(i, j int)

func (Flags) VisibleFlags 

func (flags Flags) VisibleFlags() Flags

VisibleFlags returns a slice of the Flags. Used by `urfave/cli` package to generate help.

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 ActionFunc
	// 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
	// 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]) 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) LookupEnv 

func (flag *GenericFlag) LookupEnv(envVar string) *string

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.

func (*GenericFlag) Value 

func (flag *GenericFlag) Value() FlagValue

type GenericType 

type GenericType interface {
	string | int | int64 | uint
}

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 LookupEnvFuncType func(key string) (string, bool)

type MapFlag 

type MapFlag[K MapFlagKeyType, V MapFlagValueType] struct {
	Name        string
	DefaultText string
	Usage       string
	Aliases     []string
	Action      ActionFunc
	EnvVar      string

	Destination *map[K]V
	Splitter    SplitterFunc
	EnvVarSep   string
	KeyValSep   string
	// contains filtered or unexported fields
}

MapFlag is a key value flag.

func (*MapFlag[K, V]) Apply 

func (flag *MapFlag[K, V]) Apply(set *libflag.FlagSet) error

Apply applies Flag settings to the given flag set.

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 

func (flag *MapFlag[K, V]) GetDefaultText() string

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 

func (flag *MapFlag[K, V]) GetEnvVars() []string

GetEnvVars returns the env vars for this flag.

func (*MapFlag[K, V]) GetUsage 

func (flag *MapFlag[K, V]) GetUsage() string

GetUsage returns the usage string for the flag.

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) LookupEnv 

func (flag *MapFlag) LookupEnv(envVar string) *string

func (*MapFlag[K, V]) Names 

func (flag *MapFlag[K, V]) Names() []string

Names returns the names of the flag.

func (*MapFlag[K, V]) RunAction 

func (flag *MapFlag[K, V]) RunAction(ctx *Context) error

RunAction implements ActionableFlag.RunAction

func (*MapFlag[K, V]) String 

func (flag *MapFlag[K, V]) String() 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.

func (*MapFlag) Value 

func (flag *MapFlag) Value() FlagValue

type MapFlagKeyType 

type MapFlagKeyType interface {
	GenericType
}

type MapFlagValueType 

type MapFlagValueType interface {
	GenericType | bool
}

type NormalizeActsType 

type NormalizeActsType byte
const (
	SingleDashFlag NormalizeActsType = iota
	DoubleDashFlag NormalizeActsType = iota
)

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 ActionFunc
	// 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 Env Var separator that is passed to the Splitter function as an argument
	EnvVarSep string
	// contains filtered or unexported fields
}

SliceFlag is a multiple flag.

func (*SliceFlag[T]) Apply 

func (flag *SliceFlag[T]) Apply(set *libflag.FlagSet) error

Apply applies Flag settings to the given flag set.

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 

func (flag *SliceFlag[T]) GetDefaultText() string

GetDefaultText returns the flags value as string representation and an empty string if the flag takes no value at all.

func (*SliceFlag[T]) GetEnvVars 

func (flag *SliceFlag[T]) GetEnvVars() []string

GetEnvVars returns the env vars for this flag.

func (*SliceFlag[T]) GetUsage 

func (flag *SliceFlag[T]) GetUsage() string

GetUsage returns the usage string for the flag.

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) LookupEnv 

func (flag *SliceFlag) LookupEnv(envVar string) *string

func (*SliceFlag[T]) Names 

func (flag *SliceFlag[T]) Names() []string

Names returns the names of the flag.

func (*SliceFlag[T]) RunAction 

func (flag *SliceFlag[T]) RunAction(ctx *Context) error

RunAction implements ActionableFlag.RunAction

func (*SliceFlag[T]) String 

func (flag *SliceFlag[T]) String() 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.

func (*SliceFlag) Value 

func (flag *SliceFlag) Value() FlagValue

type SliceFlagType 

type SliceFlagType interface {
	GenericType
}

type SplitterFunc 

type SplitterFunc func(s, sep string) []string

SplitterFunc is used to parse flags containing multiple values.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.