Documentation

Overview

    Package flag implements command-line flag parsing in the GNU style. It is almost exactly the same as the standard flag package, the only difference being the extra argument to Parse.

    Command line flag syntax:

    -f		// single letter flag
    -fg		// two single letter flags together
    --flag	// multiple letter flag
    --flag x  // non-boolean flags only
    -f x		// non-boolean flags only
    -fx		// if f is a non-boolean flag, x is its argument.
    

    The last three forms are not permitted for boolean flags because the meaning of the command

    cmd -f *
    

    will change if there is a file called 0, false, etc. There is currently no way to turn off a boolean flag.

    Flag parsing stops after the terminator "--", or just before the first non-flag argument ("-" is a non-flag argument) if the interspersed argument to Parse is false.

    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. The top-level functions such as BoolVar, Arg, and so on are wrappers for the methods of CommandLine.

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

        ErrHelp is the error returned if the -help or -h flag 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.

          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 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 Duration

                  func Duration(name string, value time.Duration, usage string) *time.Duration

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

                    func DurationVar

                    func DurationVar(p *time.Duration, name string, value time.Duration, usage string)

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

                      func Float64

                      func Float64(name string, value float64, usage string) *float64

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

                        func Float64Var

                        func Float64Var(p *float64, name string, value float64, usage string)

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

                          func Int

                          func Int(name string, value int, usage string) *int

                            Int defines an int flag with specified name, default value, and usage string. The return value is the address of an int variable that stores the value of the flag.

                            func Int64

                            func Int64(name string, value int64, usage string) *int64

                              Int64 defines an int64 flag with specified name, default value, and usage string. The return value is the address of an int64 variable that stores the value of the flag.

                              func Int64Var

                              func Int64Var(p *int64, name string, value int64, usage string)

                                Int64Var defines an int64 flag with specified name, default value, and usage string. The argument p points to an int64 variable in which to store the value of the flag.

                                func IntVar

                                func IntVar(p *int, name string, value int, usage string)

                                  IntVar defines an int flag with specified name, default value, and usage string. The argument p points to an int variable in which to store the value of the flag.

                                  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(allowIntersperse bool)

                                        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. If allowIntersperse is set, arguments and flags can be interspersed, that is flags can follow positional arguments.

                                        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 String

                                              func String(name string, value string, usage string) *string

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

                                                func StringVar

                                                func StringVar(p *string, name string, value string, usage string)

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

                                                  func Uint

                                                  func Uint(name string, value uint, usage string) *uint

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

                                                    func Uint64

                                                    func Uint64(name string, value uint64, usage string) *uint64

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

                                                      func Uint64Var

                                                      func Uint64Var(p *uint64, name string, value uint64, usage string)

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

                                                        func UintVar

                                                        func UintVar(p *uint, name string, value uint, usage string)

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

                                                          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 Visit

                                                            func Visit(fn func(*Flag))

                                                              Visit visits the command-line flags in lexicographical order, 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, 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 ErrorHandling = iota
                                                                  	ExitOnError
                                                                  	PanicOnError
                                                                  )

                                                                  type Flag

                                                                  type Flag struct {
                                                                  	Name     string // name as it appears on command line
                                                                  	Usage    string // help message
                                                                  	Value    Value  // value as set
                                                                  	DefValue string // default value (as text); for usage message
                                                                  }

                                                                    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.

                                                                      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()
                                                                      	// 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 and error handling property.

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

                                                                                  func (f *FlagSet) Duration(name string, value time.Duration, usage string) *time.Duration

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

                                                                                    func (*FlagSet) DurationVar

                                                                                    func (f *FlagSet) DurationVar(p *time.Duration, name string, value time.Duration, usage string)

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

                                                                                      func (*FlagSet) Float64

                                                                                      func (f *FlagSet) Float64(name string, value float64, usage string) *float64

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

                                                                                        func (*FlagSet) Float64Var

                                                                                        func (f *FlagSet) Float64Var(p *float64, name string, value float64, usage string)

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

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

                                                                                            func (f *FlagSet) Int(name string, value int, usage string) *int

                                                                                              Int defines an int flag with specified name, default value, and usage string. The return value is the address of an int variable that stores the value of the flag.

                                                                                              func (*FlagSet) Int64

                                                                                              func (f *FlagSet) Int64(name string, value int64, usage string) *int64

                                                                                                Int64 defines an int64 flag with specified name, default value, and usage string. The return value is the address of an int64 variable that stores the value of the flag.

                                                                                                func (*FlagSet) Int64Var

                                                                                                func (f *FlagSet) Int64Var(p *int64, name string, value int64, usage string)

                                                                                                  Int64Var defines an int64 flag with specified name, default value, and usage string. The argument p points to an int64 variable in which to store the value of the flag.

                                                                                                  func (*FlagSet) IntVar

                                                                                                  func (f *FlagSet) IntVar(p *int, name string, value int, usage string)

                                                                                                    IntVar defines an int flag with specified name, default value, and usage string. The argument p points to an int variable in which to store the value of the flag.

                                                                                                    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) 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(allowIntersperse bool, 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 or -h was set but not defined. If allowIntersperse is set, arguments and flags can be interspersed, that is flags can follow positional arguments.

                                                                                                            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. If there is more than one name for a given flag, the usage information and default value from the shortest will be printed (or the least alphabetically if there are several equally short flag names).

                                                                                                                func (*FlagSet) Set

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

                                                                                                                  Set sets the value of the named flag.

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

                                                                                                                    func (f *FlagSet) String(name string, value string, usage string) *string

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

                                                                                                                      func (*FlagSet) StringVar

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

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

                                                                                                                        func (*FlagSet) Uint

                                                                                                                        func (f *FlagSet) Uint(name string, value uint, usage string) *uint

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

                                                                                                                          func (*FlagSet) Uint64

                                                                                                                          func (f *FlagSet) Uint64(name string, value uint64, usage string) *uint64

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

                                                                                                                            func (*FlagSet) Uint64Var

                                                                                                                            func (f *FlagSet) Uint64Var(p *uint64, name string, value uint64, usage string)

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

                                                                                                                              func (*FlagSet) UintVar

                                                                                                                              func (f *FlagSet) UintVar(p *uint, name string, value uint, usage string)

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

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

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

                                                                                                                                    Visit visits the flags in lexicographical order, 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, calling fn for each. It visits all flags, even those not set.

                                                                                                                                      type Getter

                                                                                                                                      type Getter interface {
                                                                                                                                      	Value
                                                                                                                                      	Get() interface{}
                                                                                                                                      }

                                                                                                                                        Getter is an interface that allows the contents of a Value to be retrieved. It wraps the Value interface, rather than being part of it, because it appeared after Go 1 and its compatibility rules. All Value types provided by this package satisfy the Getter interface.

                                                                                                                                        type Value

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

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

                                                                                                                                          Source Files