mflag

package
v1.0.4 Latest Latest
Warning

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

 Go to latest Published: Dec 9, 2022 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var CommandLine = NewFlagSet(os.Args[0], ExitOnError)

CommandLine is the default set of command-line flags, parsed from os.Args.

View Source 
var ErrHelp = errors.New("pflag: help requested")

ErrHelp is the error returned if the flag -help is invoked but no such flag is defined.

View Source 
var Usage = func() {
	fmt.Fprintf(os.Stderr, "Usage of %s:\n", os.Args[0])
	PrintDefaults()
}

Usage prints to standard error a usage message documenting all defined command-line flags. The function is a variable that may be changed to point to a custom function. By default it prints a simple header and calls PrintDefaults; for details about the format of the output and how to control it, see the documentation for PrintDefaults.

Functions

func Arg 

func Arg(i int) string

Arg returns the i'th command-line argument. Arg(0) is the first remaining argument after flags have been processed.

func Args 

func Args() []string

Args returns the non-flag command-line arguments.

func Bool 

func Bool(name string, value bool, usage string) *bool

Bool defines a bool flag with specified name, default value, and usage string. The return value is the address of a bool variable that stores the value of the flag.

func BoolP 

func BoolP(name, shorthand string, value bool, usage string) *bool

BoolP is like Bool, but accepts a shorthand letter that can be used after a single dash.

func BoolVar 

func BoolVar(p *bool, name string, value bool, usage string)

BoolVar defines a bool flag with specified name, default value, and usage string. The argument p points to a bool variable in which to store the value of the flag.

func BoolVarP 

func BoolVarP(p *bool, name, shorthand string, value bool, usage string)

BoolVarP is like BoolVar, but accepts a shorthand letter that can be used after a single dash.

func NArg 

func NArg() int

NArg is the number of arguments remaining after flags have been processed.

func NFlag 

func NFlag() int

NFlag returns the number of command-line flags that have been set.

func Parse 

func Parse()

Parse parses the command-line flags from os.Args[1:]. Must be called after all flags are defined and before flags are accessed by the program.

func ParseAll 

func ParseAll(fn func(flag *Flag, value string) error)

ParseAll parses the command-line flags from os.Args[1:] and called fn for each. The arguments for fn are flag and value. Must be called after all flags are defined and before flags are accessed by the program.

func Parsed 

func Parsed() bool

Parsed returns true if the command-line flags have been parsed.

func PrintDefaults 

func PrintDefaults()

PrintDefaults prints to standard error the default values of all defined command-line flags.

func Set 

func Set(name, value string) error

Set sets the value of the named command-line flag.

func SetInterspersed 

func SetInterspersed(interspersed bool)

SetInterspersed sets whether to support interspersed option/non-option arguments.

func UnquoteUsage 

func UnquoteUsage(flag *Flag) (name string, usage string)

UnquoteUsage extracts a back-quoted name from the usage string for a flag and returns it and the un-quoted usage. Given "a `name` to show" it returns ("name", "a name to show"). If there are no back quotes, the name is an educated guess of the type of the flag's value, or the empty string if the flag is boolean.

func Var 

func Var(value Value, name string, usage string)

Var defines a flag with the specified name and usage string. The type and value of the flag are represented by the first argument, of type Value, which typically holds a user-defined implementation of Value. For instance, the caller could create a flag that turns a comma-separated string into a slice of strings by giving the slice the methods of Value; in particular, Set would decompose the comma-separated string into the slice.

func VarP 

func VarP(value Value, name, shorthand, usage string)

VarP is like Var, but accepts a shorthand letter that can be used after a single dash.

func Visit 

func Visit(fn func(*Flag))

Visit visits the command-line flags in lexicographical order or in primordial order if f.SortFlags is false, calling fn for each. It visits only those flags that have been set.

func VisitAll 

func VisitAll(fn func(*Flag))

VisitAll visits the command-line flags in lexicographical order or in primordial order if f.SortFlags is false, calling fn for each. It visits all flags, even those not set.

Types

type ErrorHandling 

type ErrorHandling int

ErrorHandling defines how to handle flag parsing errors. 

const (
	// ContinueOnError will return an err from Parse() if an error is found
	ContinueOnError ErrorHandling = iota
	// ExitOnError will call os.Exit(2) if an error is found when parsing
	ExitOnError
	// PanicOnError will panic() if an error is found when parsing flags
	PanicOnError
)

type Flag 

type Flag struct {
	Name                string              // name as it appears on command line
	Shorthand           string              // one-letter abbreviated flag
	Usage               string              // help message
	Value               Value               // value as set
	DefValue            string              // default value (as text); for usage message
	Changed             bool                // If the user set the value (or if left to default)
	NoOptDefVal         string              // default value (as text); if the flag is on the command line without any options
	Deprecated          string              // If this flag is deprecated, this string is the new or now thing to use
	Hidden              bool                // used by cobra.Command to allow flags to be hidden from help/usage text
	ShorthandDeprecated string              // If the shorthand of this flag is deprecated, this string is the new or now thing to use
	Annotations         map[string][]string // used by cobra.Command bash autocomple code
}

A Flag represents the state of a flag.

func Lookup 

func Lookup(name string) *Flag

Lookup returns the Flag structure of the named command-line flag, returning nil if none exists.

func ShorthandLookup 

func ShorthandLookup(name string) *Flag

ShorthandLookup returns the Flag structure of the short handed flag, returning nil if none exists.

type FlagSet 

type FlagSet struct {
	// Usage is the function called when an error occurs while parsing flags.
	// The field is a function (not a method) that may be changed to point to
	// a custom error handler.
	Usage func()

	// SortFlags is used to indicate, if user wants to have sorted flags in
	// help/usage messages.
	SortFlags bool

	// ParseErrorsWhitelist is used to configure a whitelist of errors
	ParseErrorsWhitelist ParseErrorsWhitelist
	// contains filtered or unexported fields
}

A FlagSet represents a set of defined flags.

func NewFlagSet 

func NewFlagSet(name string, errorHandling ErrorHandling) *FlagSet

NewFlagSet returns a new, empty flag set with the specified name, error handling property and SortFlags set to true.

func (*FlagSet) AddFlag 

func (f *FlagSet) AddFlag(flag *Flag)

AddFlag will add the flag to the FlagSet

func (*FlagSet) AddFlagSet 

func (f *FlagSet) AddFlagSet(newSet *FlagSet)

AddFlagSet adds one FlagSet to another. If a flag is already present in f the flag from newSet will be ignored.

func (*FlagSet) Arg 

func (f *FlagSet) Arg(i int) string

Arg returns the i'th argument. Arg(0) is the first remaining argument after flags have been processed.

func (*FlagSet) Args 

func (f *FlagSet) Args() []string

Args returns the non-flag arguments.

func (*FlagSet) ArgsLenAtDash 

func (f *FlagSet) ArgsLenAtDash() int

ArgsLenAtDash will return the length of f.Args at the moment when a -- was found during arg parsing. This allows your program to know which args were before the -- and which came after.

func (*FlagSet) Bool 

func (f *FlagSet) Bool(name string, value bool, usage string) *bool

Bool defines a bool flag with specified name, default value, and usage string. The return value is the address of a bool variable that stores the value of the flag.

func (*FlagSet) BoolP 

func (f *FlagSet) BoolP(name, shorthand string, value bool, usage string) *bool

BoolP is like Bool, but accepts a shorthand letter that can be used after a single dash.

func (*FlagSet) BoolVar 

func (f *FlagSet) BoolVar(p *bool, name string, value bool, usage string)

BoolVar defines a bool flag with specified name, default value, and usage string. The argument p points to a bool variable in which to store the value of the flag.

func (*FlagSet) BoolVarP 

func (f *FlagSet) BoolVarP(p *bool, name, shorthand string, value bool, usage string)

BoolVarP is like BoolVar, but accepts a shorthand letter that can be used after a single dash.

func (*FlagSet) Changed 

func (f *FlagSet) Changed(name string) bool

Changed returns true if the flag was explicitly set during Parse() and false otherwise

func (*FlagSet) FlagUsages 

func (f *FlagSet) FlagUsages() string

FlagUsages returns a string containing the usage information for all flags in the FlagSet

func (*FlagSet) FlagUsagesWrapped 

func (f *FlagSet) FlagUsagesWrapped(cols int) string

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

func (*FlagSet) GetBool 

func (f *FlagSet) GetBool(name string) (bool, error)

GetBool return the bool value of a flag with the given name

func (*FlagSet) GetNormalizeFunc 

func (f *FlagSet) GetNormalizeFunc() func(f *FlagSet, name string) NormalizedName

GetNormalizeFunc returns the previously set NormalizeFunc of a function which does no translation, if not set previously.

func (*FlagSet) HasAvailableFlags 

func (f *FlagSet) HasAvailableFlags() bool

HasAvailableFlags returns a bool to indicate if the FlagSet has any flags that are not hidden.

func (*FlagSet) HasFlags 

func (f *FlagSet) HasFlags() bool

HasFlags returns a bool to indicate if the FlagSet has any flags defined.

func (*FlagSet) Init 

func (f *FlagSet) Init(name string, errorHandling ErrorHandling)

Init sets the name and error handling property for a flag set. By default, the zero FlagSet uses an empty name and the ContinueOnError error handling policy.

func (*FlagSet) Lookup 

func (f *FlagSet) Lookup(name string) *Flag

Lookup returns the Flag structure of the named flag, returning nil if none exists.

func (*FlagSet) MarkDeprecated 

func (f *FlagSet) MarkDeprecated(name string, usageMessage string) error

MarkDeprecated indicated that a flag is deprecated in your program. It will continue to function but will not show up in help or usage messages. Using this flag will also print the given usageMessage.

func (*FlagSet) MarkHidden 

func (f *FlagSet) MarkHidden(name string) error

MarkHidden sets a flag to 'hidden' in your program. It will continue to function but will not show up in help or usage messages.

func (*FlagSet) MarkShorthandDeprecated 

func (f *FlagSet) MarkShorthandDeprecated(name string, usageMessage string) error

MarkShorthandDeprecated will mark the shorthand of a flag deprecated in your program. It will continue to function but will not show up in help or usage messages. Using this flag will also print the given usageMessage.

func (*FlagSet) NArg 

func (f *FlagSet) NArg() int

NArg is the number of arguments remaining after flags have been processed.

func (*FlagSet) NFlag 

func (f *FlagSet) NFlag() int

NFlag returns the number of flags that have been set.

func (*FlagSet) Parse 

func (f *FlagSet) Parse(arguments []string) error

Parse parses flag definitions from the argument list, which should not include the command name. Must be called after all flags in the FlagSet are defined and before flags are accessed by the program. The return value will be ErrHelp if -help was set but not defined.

func (*FlagSet) ParseAll 

func (f *FlagSet) ParseAll(arguments []string, fn func(flag *Flag, value string) error) error

ParseAll parses flag definitions from the argument list, which should not include the command name. The arguments for fn are flag and value. Must be called after all flags in the FlagSet are defined and before flags are accessed by the program. The return value will be ErrHelp if -help was set but not defined.

func (*FlagSet) Parsed 

func (f *FlagSet) Parsed() bool

Parsed reports whether f.Parse has been called.

func (*FlagSet) PrintDefaults 

func (f *FlagSet) PrintDefaults()

PrintDefaults prints, to standard error unless configured otherwise, the default values of all defined flags in the set.

func (*FlagSet) Set 

func (f *FlagSet) Set(name, value string) error

Set sets the value of the named flag.

func (*FlagSet) SetAnnotation 

func (f *FlagSet) SetAnnotation(name, key string, values []string) error

SetAnnotation allows one to set arbitrary annotations on a flag in the FlagSet. This is sometimes used by spf13/cobra programs which want to generate additional bash completion information.

func (*FlagSet) SetInterspersed 

func (f *FlagSet) SetInterspersed(interspersed bool)

SetInterspersed sets whether to support interspersed option/non-option arguments.

func (*FlagSet) SetNormalizeFunc 

func (f *FlagSet) SetNormalizeFunc(n func(f *FlagSet, name string) NormalizedName)

SetNormalizeFunc allows you to add a function which can translate flag names. Flags added to the FlagSet will be translated and then when anything tries to look up the flag that will also be translated. So it would be possible to create a flag named "getURL" and have it translated to "geturl". A user could then pass "--getUrl" which may also be translated to "geturl" and everything will work.

func (*FlagSet) SetOutput 

func (f *FlagSet) SetOutput(output io.Writer)

SetOutput sets the destination for usage and error messages. If output is nil, os.Stderr is used.

func (*FlagSet) ShorthandLookup 

func (f *FlagSet) ShorthandLookup(name string) *Flag

ShorthandLookup returns the Flag structure of the short handed flag, returning nil if none exists. It panics, if len(name) > 1.

func (*FlagSet) Var 

func (f *FlagSet) Var(value Value, name string, usage string)

Var defines a flag with the specified name and usage string. The type and value of the flag are represented by the first argument, of type Value, which typically holds a user-defined implementation of Value. For instance, the caller could create a flag that turns a comma-separated string into a slice of strings by giving the slice the methods of Value; in particular, Set would decompose the comma-separated string into the slice.

func (*FlagSet) VarP 

func (f *FlagSet) VarP(value Value, name, shorthand, usage string)

VarP is like Var, but accepts a shorthand letter that can be used after a single dash.

func (*FlagSet) VarPF 

func (f *FlagSet) VarPF(value Value, name, shorthand, usage string) *Flag

VarPF is like VarP, but returns the flag created

func (*FlagSet) Visit 

func (f *FlagSet) Visit(fn func(*Flag))

Visit visits the flags in lexicographical order or in primordial order if f.SortFlags is false, calling fn for each. It visits only those flags that have been set.

func (*FlagSet) VisitAll 

func (f *FlagSet) VisitAll(fn func(*Flag))

VisitAll visits the flags in lexicographical order or in primordial order if f.SortFlags is false, calling fn for each. It visits all flags, even those not set.

type NormalizedName 

type NormalizedName string

NormalizedName is a flag name that has been normalized according to rules for the FlagSet (e.g. making '-' and '_' equivalent).

type ParseErrorsWhitelist 

type ParseErrorsWhitelist struct {
	// UnknownFlags will ignore unknown flags errors and continue parsing rest of the flags
	UnknownFlags bool
}

ParseErrorsWhitelist defines the parsing errors that can be ignored

type SliceValue 

type SliceValue interface {
	// Append adds the specified value to the end of the flag value list.
	Append(string) error
	// Replace will fully overwrite any data currently in the flag value list.
	Replace([]string) error
	// GetSlice returns the flag value list as an array of strings.
	GetSlice() []string
}

SliceValue is a secondary interface to all flags which hold a list of values. This allows full control over the value of list flags, and avoids complicated marshalling and unmarshalling to csv.

type Value 

type Value interface {
	String() string
	Set(string) error
	Type() string
}

Value is the interface to the dynamic value stored in a flag. (The default value is represented as a string.)

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.