flags

Documentation

Overview

Package flags provides tools that are used by all commands to create deprecation flags with strict controls.

Index

• Constants
• type DeprecatedFlag
  • func (flag *DeprecatedFlag) AllowedSubcommandScope() bool
  • func (flag *DeprecatedFlag) Evaluate(ctx context.Context) error
  • func (flag *DeprecatedFlag) GetEnvVars() []string
  • func (flag *DeprecatedFlag) GetHidden() bool
  • func (flag *DeprecatedFlag) Names() []string
  • func (flag *DeprecatedFlag) SetStrictControls(mainFlag *Flag, regControlsFn RegisterStrictControlsFunc)
• type DeprecatedFlags
• type Flag
  • func NewFlag(new cli.Flag, opts ...Option) *Flag
  • func NewMovedFlag(deprecatedFlag cli.Flag, newCommandName string, ...) *Flag
  • func (newFlag *Flag) Apply(set *flag.FlagSet) error
  • func (newFlag *Flag) ParseEnvVars() error
  • func (newFlag *Flag) RunAction(ctx *cli.Context) error
  • func (newFlag *Flag) TakesValue() bool
  • func (newFlag *Flag) Value() cli.FlagValue
• type NewValueFunc
  • func NewValue(val string) NewValueFunc
• type Option
  • func WithDeprecatedFlag(deprecatedFlag cli.Flag, newValueFn NewValueFunc, ...) Option
  • func WithDeprecatedMovedFlag(deprecatedFlag cli.Flag, commandName string, ...) Option
  • func WithDeprecatedName(flagName string, regControlsFn RegisterStrictControlsFunc) Option
  • func WithDeprecatedNames(flagNames []string, regControlsFn RegisterStrictControlsFunc) Option
  • func WithDeprecatedNamesEnvVars(flagNames, envVars []string, regControlsFn RegisterStrictControlsFunc) Option
  • func WithDeprecatedPrefix(prefix Prefix, regControlsFn RegisterStrictControlsFunc) Option
• type Prefix
  • func (prefix Prefix) Append(val string) Prefix
  • func (prefix Prefix) EnvVar(name string) string
  • func (prefix Prefix) EnvVars(names ...string) []string
  • func (prefix Prefix) FlagName(name string) string
  • func (prefix Prefix) FlagNames(names ...string) []string
  • func (prefix Prefix) Prepend(val string) Prefix
• type RegisterStrictControlsFunc
  • func StrictControlsByCommand(strictControls strict.Controls, commandName string, controlNames ...string) RegisterStrictControlsFunc
  • func StrictControlsByGlobalFlags(strictControls strict.Controls, controlNames ...string) RegisterStrictControlsFunc
  • func StrictControlsByMovedGlobalFlags(strictControls strict.Controls, commandName string, controlNames ...string) RegisterStrictControlsFunc

Constants

const (
	// TgPrefix is an environment variable prefix.
	TgPrefix = "TG"

	// TerragruntPrefix is an environment variable deprecated prefix.
	TerragruntPrefix = "TERRAGRUNT"
)

Types

type DeprecatedFlag

type DeprecatedFlag struct {
	cli.Flag
	// contains filtered or unexported fields
}

DeprecatedFlag represents a deprecated flag that is not shown in the CLI help, but its names, envVars, are registered.

func (*DeprecatedFlag) AllowedSubcommandScope

func (flag *DeprecatedFlag) AllowedSubcommandScope() bool

AllowedSubcommandScope implements `cli.Flag` interface.

func (*DeprecatedFlag) Evaluate

func (flag *DeprecatedFlag) Evaluate(ctx context.Context) error

Evaluate returns an error if the one of the controls is enabled otherwise logs warning messages and returns nil.

func (*DeprecatedFlag) GetEnvVars

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

GetEnvVars implements `cli.Flag` interface.

func (*DeprecatedFlag) GetHidden

func (flag *DeprecatedFlag) GetHidden() bool

GetHidden implements `cli.Flag` interface.

func (*DeprecatedFlag) Names

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

Names implements `cli.Flag` interface.

func (*DeprecatedFlag) SetStrictControls

func (flag *DeprecatedFlag) SetStrictControls(mainFlag *Flag, regControlsFn RegisterStrictControlsFunc)

SetStrictControls creates a strict control for the flag and registers it.

type DeprecatedFlags

type DeprecatedFlags []*DeprecatedFlag

DeprecatedFlags are multiple of DeprecatedFlag flags.

type Flag

type Flag struct {
	cli.Flag
	// contains filtered or unexported fields
}

Flag is a wrapper for `cli.Flag` that avoids displaying deprecated flags in help, but registers their flag names and environment variables.

func NewFlag

func NewFlag(new cli.Flag, opts ...Option) *Flag

NewFlag returns a new Flag instance.

func NewMovedFlag

func NewMovedFlag(deprecatedFlag cli.Flag, newCommandName string, regControlsFn RegisterStrictControlsFunc) *Flag

func (*Flag) Apply

func (newFlag *Flag) Apply(set *flag.FlagSet) error

Apply implements `cli.Flag` interface.

func (*Flag) ParseEnvVars

func (newFlag *Flag) ParseEnvVars() error

ParseEnvVars parses env vars values specified in the flag. The value will be assigned to the `Destination` field. The value can also be retrieved using `flag.Value().Get()`.

func (*Flag) RunAction

func (newFlag *Flag) RunAction(ctx *cli.Context) error

RunAction implements `cli.Flag` interface.

func (*Flag) TakesValue

func (newFlag *Flag) TakesValue() bool

TakesValue implements `github.com/urfave/cli.DocGenerationFlag` required to generate help. TakesValue returns `true` for all flags except boolean ones that are `false` or `true` inverted.

func (*Flag) Value

func (newFlag *Flag) Value() cli.FlagValue

Value implements `cli.Flag` interface.

type NewValueFunc

type NewValueFunc func(flagValue cli.FlagValue) string

NewValueFunc represents a function that returns a new value for the current flag if a deprecated flag is called. Used when the current flag and the deprecated flag are of different types. For example, the string `log-format` flag must be set to `json` when deprecated bool `terragrunt-json-log` flag is used. More examples:

terragrunt-disable-log-formatting replaced with: log-format=key-value terragrunt-json-log replaced with: log-format=json terragrunt-tf-logs-to-json replaced with: log-format=json

func NewValue

func NewValue(val string) NewValueFunc

NewValue returns a callback function that is used to get a new value for the current flag.

type Option

type Option func(*Flag)

Option is used to set options to the `Flag`.

func WithDeprecatedFlag

func WithDeprecatedFlag(deprecatedFlag cli.Flag, newValueFn NewValueFunc, regControlsFn RegisterStrictControlsFunc) Option

WithDeprecatedFlag returns an `Option` that will register the given `deprecatedFlag` as a deprecated flag. `newValueFn` is called to get a value for the new flag when this deprecated flag triggers. For example:

NewFlag(&cli.GenericFlag[string]{
  Name:    "log-format",
}, WithDeprecatedFlag(&cli.BoolFlag{
  Name:    "terragrunt-json-log",
}, flags.NewValue("json"), nil))

func WithDeprecatedMovedFlag

func WithDeprecatedMovedFlag(deprecatedFlag cli.Flag, commandName string, regControlsFn RegisterStrictControlsFunc) Option

WithDeprecatedMovedFlag returns an `Option` that will register the given `deprecatedFlag` as a deprecated flag that is moved to the given `commandName`. For example:

NewFlag(nil, WithDeprecatedMovedFlag(&cli.BoolFlag{
  Name:    "no-auto-init",
}, "run", nil))

Log output: WARN The `--no-auto-init` global flag is moved to `run` command and will be removed from the global flags in a future version. Use `run --no-auto-init` instead.

func WithDeprecatedName

func WithDeprecatedName(flagName string, regControlsFn RegisterStrictControlsFunc) Option

WithDeprecatedName does the same as `WithDeprecatedNames`, but with a single name.

func WithDeprecatedNames

func WithDeprecatedNames(flagNames []string, regControlsFn RegisterStrictControlsFunc) Option

WithDeprecatedNames returns an `Option` that will create a deprecated flag. The given `flagNames` names will assign both names (converting to lowercase,dash) and env vars (converting to uppercase,underscore). For example:

WithDeprecatedNames([]string{"NO_COLOR", "working-dir"}, nil)

The deprecated flag will have "no-color","working-dir" names and "NO_COLOR","WORKING_DIR" env vars.

func WithDeprecatedNamesEnvVars

func WithDeprecatedNamesEnvVars(flagNames, envVars []string, regControlsFn RegisterStrictControlsFunc) Option

WithDeprecatedNamesEnvVars returns an `Option` that will create a deprecated flag, with the given `flagNames`, `envVars` assigned to the flag names and environment variables as is.

func WithDeprecatedPrefix

func WithDeprecatedPrefix(prefix Prefix, regControlsFn RegisterStrictControlsFunc) Option

WithDeprecatedPrefix returns an `Option` that will create a deprecated flag with the same name as the new flag, but with the specified `prefix` prepended to the names and environment variables. Should be used with caution, as changing the name of the new flag will change the name of the deprecated flag. For example:

NewFlag(&cli.GenericFlag[string]{
  Name:    "no-color",
  Aliases: []string{"disable-color"},
  EnvVars: []string{"NO_COLOR","DISABLE_COLOR"},
}, WithDeprecatedPrefix(Prefix{"terragrunt"}, nil))

The deprecated flag will have "terragrunt-no-color","terragrunt-disable-color" names and "TERRAGRUNT_NO_COLOR","TERRAGRUNT_DISABLE_COLOR" env vars. NOTE: This function is currently unused but retained for future flag deprecation needs.

type Prefix

type Prefix []string

Prefix helps to combine strings into flag names or environment variables in a convenient way. Can be passed to subcommands and contain the names of parent commands, thus creating env vars as a chain of "TG prefix, parent command names, command name, flag name". For example: `TG_HLC_FMT_FILE`, where `hcl` is the parent command, `fmt` is the command and `file` is a flag. Example of use:

func main () {
	ParentCommand(Prefix{TgPrefix})
}

func ParentCommand(prefix Prefix) {
	Command(prefix.Append("hcl"))
}

func Command(prefix Prefix) {
	Flag(prefix.Append("fmt"))
}

func Flag(prefix Prefix) {
	envName := prefix.EnvVar("file") // TG_HCL_FMT_FILE
}

func (Prefix) Append

func (prefix Prefix) Append(val string) Prefix

Append adds a value to the end of the slice.

func (Prefix) EnvVar

func (prefix Prefix) EnvVar(name string) string

EnvVar returns a string that is the concatenation of the slice values with the given `name`, using underscores as separators, replacing dashes with underscores, converting to uppercase.

func (Prefix) EnvVars

func (prefix Prefix) EnvVars(names ...string) []string

EnvVars does the same `EnvVar`, except it takes and returns the slice.

func (Prefix) FlagName

func (prefix Prefix) FlagName(name string) string

FlagName returns a string that is the concatenation of the slice values with the given `name`, using dashes as separators, replacing dashes with underscores, converting to lowercase.

func (Prefix) FlagNames

func (prefix Prefix) FlagNames(names ...string) []string

FlagNames does the same `FlagName`, except it takes and returns the slice.

func (Prefix) Prepend

func (prefix Prefix) Prepend(val string) Prefix

Prepend adds a value to the beginning of the slice.

type RegisterStrictControlsFunc

type RegisterStrictControlsFunc func(flagNameControl, envVarControl strict.Control) bool

RegisterStrictControlsFunc represents a callback func that registers the given controls in the `opts.StrictControls` stict control tree .

func StrictControlsByCommand

func StrictControlsByCommand(strictControls strict.Controls, commandName string, controlNames ...string) RegisterStrictControlsFunc

StrictControlsByCommand returns a callback function that adds the taken controls as subcontrols for the given `controlNames`. Using the given `commandName` as categories.

func StrictControlsByGlobalFlags

func StrictControlsByGlobalFlags(strictControls strict.Controls, controlNames ...string) RegisterStrictControlsFunc

StrictControlsByGlobalFlags returns a callback function that adds the taken controls as subcontrols for the given `controlNames`. And assigns the "Global Flag" category to these controls.

func StrictControlsByMovedGlobalFlags

func StrictControlsByMovedGlobalFlags(strictControls strict.Controls, commandName string, controlNames ...string) RegisterStrictControlsFunc

StrictControlsByMovedGlobalFlags returns a callback function that adds the taken controls as subcontrols for the given `controlNames`. And assigns the "Moved to other %s command global flags" category to these controls.