cobrautil

Documentation

Overview

Package cobrautil defines utility wrapper functions for common cobra flag handling tasks.

Index

• Constants
• func CommandFlagUsages(cmd *cobra.Command, opts UsageFormatOptions) string
• func GroupedFlagUsages(f *pflag.FlagSet, gopts FlagGroupingOptions, format Formatter, ...) string
• func InheritedFlagUsages(cmd *cobra.Command, opts UsageFormatOptions) string
• func LocalFlagUsages(cmd *cobra.Command, opts UsageFormatOptions) string
• func MarkFlagCustom(f *pflag.Flag, bashFunction string)
• func MarkFlagDirname(f *pflag.Flag)
• func MarkFlagFilename(f *pflag.Flag, extensions ...string)
• func MarkFlagRequired(f *pflag.Flag)
• func MarkFlagsMutuallyExclusive(cmd *cobra.Command, flags ...*pflag.Flag)
• func MarkFlagsOneRequired(cmd *cobra.Command, flags ...*pflag.Flag)
• func MarkFlagsRequiredTogether(cmd *cobra.Command, flags ...*pflag.Flag)
• func ParseEnvOverrides(cmd *cobra.Command) error
• func RegisterFlagCompletionFunc(cmd *cobra.Command, flag *pflag.Flag, f FlagCompletionFunc) error
• func WalkCommands(root *cobra.Command, f func(cmd *cobra.Command))
• func WithCustomUsage(cmd *cobra.Command, opts UsageFormatOptions)
• type FlagCompletionFunc
  • func GetFlagCompletionFunc(cmd *cobra.Command, flag *pflag.Flag) (FlagCompletionFunc, bool)
• type FlagGroupingOptions
• type Formatter
  • func (f *Formatter) Default()
• type SectionFormatter
• type UsageFormatOptions

Constants

const (
	DefaultLocalFlagHeader  = "Options:"
	DefaultGlobalFlagHeader = "Global options:"
)

Default values for the flag section headers.

Functions

func CommandFlagUsages

func CommandFlagUsages(cmd *cobra.Command, opts UsageFormatOptions) string

CommandFlagUsages returns flag usage description for all flags of a command.

{{if .HasAvailableLocalFlags}}

{{localFlagUsages .LocalFlags | trimTrailingWhitespaces}}{{end}}{{if .HasAvailableInheritedFlags}}

{{inheritedFlagUsages .InheritedFlags | trimTrailingWhitespaces}}{{end}}

func GroupedFlagUsages

func GroupedFlagUsages(f *pflag.FlagSet, gopts FlagGroupingOptions, format Formatter, opts flagutil.UsageFormatOptions) string

GroupedFlagUsages returns a string containing the usage information for all flags in the FlagSet. Wrapped to `cols` columns (0 for no wrapping)

func InheritedFlagUsages

func InheritedFlagUsages(cmd *cobra.Command, opts UsageFormatOptions) string

InheritedFlagUsages returns flag usage for a command's inherited flags.

func LocalFlagUsages

func LocalFlagUsages(cmd *cobra.Command, opts UsageFormatOptions) string

LocalFlagUsages returns flag usage for a command's local flags.

func MarkFlagCustom

func MarkFlagCustom(f *pflag.Flag, bashFunction string)

MarkFlagCustom adds the BashCompCustom annotation to the named flag, if it exists. The bash completion script will call the bash function f for the flag.

This will only work for bash completion. It is recommended to instead use c.RegisterFlagCompletionFunc(...) which allows to register a Go function which will work across all shells.

Wrapper for cobra.MarkFlagCustom accepting a flag object instead of its name.

func MarkFlagDirname

func MarkFlagDirname(f *pflag.Flag)

MarkFlagDirname instructs the various shell completion implementations to limit completions for the named flag to directory names.

Wrapper for cobra.MarkFlagDirname accepting a flag object instead of its name.

func MarkFlagFilename

func MarkFlagFilename(f *pflag.Flag, extensions ...string)

MarkFlagFilename instructs the various shell completion implementations to limit completions for the named flag to the specified file extensions.

Wrapper for cobra.MarkFlagFilename accepting a flag object instead of its name.

func MarkFlagRequired

func MarkFlagRequired(f *pflag.Flag)

MarkFlagRequired instructs the various shell completion implementations to prioritize the named flag when performing completion, and causes your command to report an error if invoked without the flag.

Wrapper for cobra.MarkFlagRequired accepting a flag object instead of its name.

func MarkFlagsMutuallyExclusive

func MarkFlagsMutuallyExclusive(cmd *cobra.Command, flags ...*pflag.Flag)

MarkFlagsMutuallyExclusive marks the given flags with annotations so that Cobra errors if the command is invoked with more than one flag from the given set of flags.

Wrapper for cobra.Command.MarkFlagsOneRequired accepting flag objects instead of names.

func MarkFlagsOneRequired

func MarkFlagsOneRequired(cmd *cobra.Command, flags ...*pflag.Flag)

MarkFlagsOneRequired marks the given flags with annotations so that Cobra errors if the command is invoked without at least one flag from the given set of flags.

Wrapper for cobra.Command.MarkFlagsOneRequired accepting flag objects instead of names.

func MarkFlagsRequiredTogether

func MarkFlagsRequiredTogether(cmd *cobra.Command, flags ...*pflag.Flag)

MarkFlagsRequiredTogether marks the given flags with annotations so that Cobra errors if the command is invoked with a subset (but not all) of the given flags.

Wrapper for cobra.Command.MarkFlagsRequiredTogether accepting flag objects instead of names.

func ParseEnvOverrides

func ParseEnvOverrides(cmd *cobra.Command) error

ParseEnvOverrides receives a flag set after it has been parsed and parses environment variables to set the value of any unset flags in the FlagSet, if they have an environment variable defined. Flag environment variables can be set with [SetEnvName]. The flag creation functions in pkg/options/flags.go set an environment variable for the flag if Option.Env is set.

Parsing errors are handled with cmd.FlagErrorFunc(). The first non-nil error returned from cmd.FlagErrorFunc() is returned.

func RegisterFlagCompletionFunc

func RegisterFlagCompletionFunc(cmd *cobra.Command, flag *pflag.Flag, f FlagCompletionFunc) error

RegisterFlagCompletionFunc should be called to register a function to provide completion for a flag.

Wrapper for cobra.Command.RegisterFlagCompletionFunc accepting a flag object instead of its name.

func WalkCommands

func WalkCommands(root *cobra.Command, f func(cmd *cobra.Command))

WalkCommands calls f for the root command and all subcommands recursively.

func WithCustomUsage

func WithCustomUsage(cmd *cobra.Command, opts UsageFormatOptions)

WithCustomUsage modifies a command's usage function according to the UsageFormatOptions.

Types

type FlagCompletionFunc

type FlagCompletionFunc = func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)

FlagCompletionFunc defines a shell completion function for a flag, used by cobra commands.

func GetFlagCompletionFunc

func GetFlagCompletionFunc(cmd *cobra.Command, flag *pflag.Flag) (FlagCompletionFunc, bool)

GetFlagCompletionFunc returns the completion function for the given flag of the command, if available.

Wrapper for cobra.Command.GetFlagCompletionFunc accepting a flag object instead of its name.

type FlagGroupingOptions

type FlagGroupingOptions struct {
	GroupFlags      bool   // Set true to organize flags by group.
	UngroupedHeader string // Header for section of flags without group.
}

FlagGroupingOptions is used to group flags.

type Formatter

type Formatter struct {
	Header         func(s string) string // Formats all header lines
	Command        func(s string) string // Formats all command names
	Args           func(s string) string // Formats all command arg placeholders
	CommandAndArgs func(s string) string // Formats all command+arg snippets (supersedes Command and Args)
	Example        func(s string) string // Formats command examples
}

Formatter defines general formatting functions.

func (*Formatter) Default

func (f *Formatter) Default()

Default initializes the formatter so it is safe to call all of its functions without nil checks.

type SectionFormatter

type SectionFormatter struct {
	CommandAndArgs func() // Formats all
}

SectionFormatter formats entire sections.

type UsageFormatOptions

type UsageFormatOptions struct {
	Format         Formatter                   // General formatting functions
	FlagOptions    flagutil.UsageFormatOptions // Flag formatting options
	LocalFlags     FlagGroupingOptions         // Flag grouping options (for local flags)
	InheritedFlags FlagGroupingOptions         // Flag grouping options (for inherited flags)
}

UsageFormatOptions is used to format flag usage output.