Source file src/flag/flag.go

Documentation: flag

     1  // Copyright 2009 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  /*
     6  	Package flag implements command-line flag parsing.
     7  
     8  	Usage
     9  
    10  	Define flags using flag.String(), Bool(), Int(), etc.
    11  
    12  	This declares an integer flag, -flagname, stored in the pointer ip, with type *int.
    13  		import "flag"
    14  		var ip = flag.Int("flagname", 1234, "help message for flagname")
    15  	If you like, you can bind the flag to a variable using the Var() functions.
    16  		var flagvar int
    17  		func init() {
    18  			flag.IntVar(&flagvar, "flagname", 1234, "help message for flagname")
    19  		}
    20  	Or you can create custom flags that satisfy the Value interface (with
    21  	pointer receivers) and couple them to flag parsing by
    22  		flag.Var(&flagVal, "name", "help message for flagname")
    23  	For such flags, the default value is just the initial value of the variable.
    24  
    25  	After all flags are defined, call
    26  		flag.Parse()
    27  	to parse the command line into the defined flags.
    28  
    29  	Flags may then be used directly. If you're using the flags themselves,
    30  	they are all pointers; if you bind to variables, they're values.
    31  		fmt.Println("ip has value ", *ip)
    32  		fmt.Println("flagvar has value ", flagvar)
    33  
    34  	After parsing, the arguments following the flags are available as the
    35  	slice flag.Args() or individually as flag.Arg(i).
    36  	The arguments are indexed from 0 through flag.NArg()-1.
    37  
    38  	Command line flag syntax
    39  
    40  	The following forms are permitted:
    41  
    42  		-flag
    43  		-flag=x
    44  		-flag x  // non-boolean flags only
    45  	One or two minus signs may be used; they are equivalent.
    46  	The last form is not permitted for boolean flags because the
    47  	meaning of the command
    48  		cmd -x *
    49  	where * is a Unix shell wildcard, will change if there is a file
    50  	called 0, false, etc. You must use the -flag=false form to turn
    51  	off a boolean flag.
    52  
    53  	Flag parsing stops just before the first non-flag argument
    54  	("-" is a non-flag argument) or after the terminator "--".
    55  
    56  	Integer flags accept 1234, 0664, 0x1234 and may be negative.
    57  	Boolean flags may be:
    58  		1, 0, t, f, T, F, true, false, TRUE, FALSE, True, False
    59  	Duration flags accept any input valid for time.ParseDuration.
    60  
    61  	The default set of command-line flags is controlled by
    62  	top-level functions.  The FlagSet type allows one to define
    63  	independent sets of flags, such as to implement subcommands
    64  	in a command-line interface. The methods of FlagSet are
    65  	analogous to the top-level functions for the command-line
    66  	flag set.
    67  */
    68  package flag
    69  
    70  import (
    71  	"errors"
    72  	"fmt"
    73  	"io"
    74  	"os"
    75  	"reflect"
    76  	"sort"
    77  	"strconv"
    78  	"strings"
    79  	"time"
    80  )
    81  
    82  // ErrHelp is the error returned if the -help or -h flag is invoked
    83  // but no such flag is defined.
    84  var ErrHelp = errors.New("flag: help requested")
    85  
    86  // errParse is returned by Set if a flag's value fails to parse, such as with an invalid integer for Int.
    87  // It then gets wrapped through failf to provide more information.
    88  var errParse = errors.New("parse error")
    89  
    90  // errRange is returned by Set if a flag's value is out of range.
    91  // It then gets wrapped through failf to provide more information.
    92  var errRange = errors.New("value out of range")
    93  
    94  func numError(err error) error {
    95  	ne, ok := err.(*strconv.NumError)
    96  	if !ok {
    97  		return err
    98  	}
    99  	if ne.Err == strconv.ErrSyntax {
   100  		return errParse
   101  	}
   102  	if ne.Err == strconv.ErrRange {
   103  		return errRange
   104  	}
   105  	return err
   106  }
   107  
   108  // -- bool Value
   109  type boolValue bool
   110  
   111  func newBoolValue(val bool, p *bool) *boolValue {
   112  	*p = val
   113  	return (*boolValue)(p)
   114  }
   115  
   116  func (b *boolValue) Set(s string) error {
   117  	v, err := strconv.ParseBool(s)
   118  	if err != nil {
   119  		err = errParse
   120  	}
   121  	*b = boolValue(v)
   122  	return err
   123  }
   124  
   125  func (b *boolValue) Get() interface{} { return bool(*b) }
   126  
   127  func (b *boolValue) String() string { return strconv.FormatBool(bool(*b)) }
   128  
   129  func (b *boolValue) IsBoolFlag() bool { return true }
   130  
   131  // optional interface to indicate boolean flags that can be
   132  // supplied without "=value" text
   133  type boolFlag interface {
   134  	Value
   135  	IsBoolFlag() bool
   136  }
   137  
   138  // -- int Value
   139  type intValue int
   140  
   141  func newIntValue(val int, p *int) *intValue {
   142  	*p = val
   143  	return (*intValue)(p)
   144  }
   145  
   146  func (i *intValue) Set(s string) error {
   147  	v, err := strconv.ParseInt(s, 0, strconv.IntSize)
   148  	if err != nil {
   149  		err = numError(err)
   150  	}
   151  	*i = intValue(v)
   152  	return err
   153  }
   154  
   155  func (i *intValue) Get() interface{} { return int(*i) }
   156  
   157  func (i *intValue) String() string { return strconv.Itoa(int(*i)) }
   158  
   159  // -- int64 Value
   160  type int64Value int64
   161  
   162  func newInt64Value(val int64, p *int64) *int64Value {
   163  	*p = val
   164  	return (*int64Value)(p)
   165  }
   166  
   167  func (i *int64Value) Set(s string) error {
   168  	v, err := strconv.ParseInt(s, 0, 64)
   169  	if err != nil {
   170  		err = numError(err)
   171  	}
   172  	*i = int64Value(v)
   173  	return err
   174  }
   175  
   176  func (i *int64Value) Get() interface{} { return int64(*i) }
   177  
   178  func (i *int64Value) String() string { return strconv.FormatInt(int64(*i), 10) }
   179  
   180  // -- uint Value
   181  type uintValue uint
   182  
   183  func newUintValue(val uint, p *uint) *uintValue {
   184  	*p = val
   185  	return (*uintValue)(p)
   186  }
   187  
   188  func (i *uintValue) Set(s string) error {
   189  	v, err := strconv.ParseUint(s, 0, strconv.IntSize)
   190  	if err != nil {
   191  		err = numError(err)
   192  	}
   193  	*i = uintValue(v)
   194  	return err
   195  }
   196  
   197  func (i *uintValue) Get() interface{} { return uint(*i) }
   198  
   199  func (i *uintValue) String() string { return strconv.FormatUint(uint64(*i), 10) }
   200  
   201  // -- uint64 Value
   202  type uint64Value uint64
   203  
   204  func newUint64Value(val uint64, p *uint64) *uint64Value {
   205  	*p = val
   206  	return (*uint64Value)(p)
   207  }
   208  
   209  func (i *uint64Value) Set(s string) error {
   210  	v, err := strconv.ParseUint(s, 0, 64)
   211  	if err != nil {
   212  		err = numError(err)
   213  	}
   214  	*i = uint64Value(v)
   215  	return err
   216  }
   217  
   218  func (i *uint64Value) Get() interface{} { return uint64(*i) }
   219  
   220  func (i *uint64Value) String() string { return strconv.FormatUint(uint64(*i), 10) }
   221  
   222  // -- string Value
   223  type stringValue string
   224  
   225  func newStringValue(val string, p *string) *stringValue {
   226  	*p = val
   227  	return (*stringValue)(p)
   228  }
   229  
   230  func (s *stringValue) Set(val string) error {
   231  	*s = stringValue(val)
   232  	return nil
   233  }
   234  
   235  func (s *stringValue) Get() interface{} { return string(*s) }
   236  
   237  func (s *stringValue) String() string { return string(*s) }
   238  
   239  // -- float64 Value
   240  type float64Value float64
   241  
   242  func newFloat64Value(val float64, p *float64) *float64Value {
   243  	*p = val
   244  	return (*float64Value)(p)
   245  }
   246  
   247  func (f *float64Value) Set(s string) error {
   248  	v, err := strconv.ParseFloat(s, 64)
   249  	if err != nil {
   250  		err = numError(err)
   251  	}
   252  	*f = float64Value(v)
   253  	return err
   254  }
   255  
   256  func (f *float64Value) Get() interface{} { return float64(*f) }
   257  
   258  func (f *float64Value) String() string { return strconv.FormatFloat(float64(*f), 'g', -1, 64) }
   259  
   260  // -- time.Duration Value
   261  type durationValue time.Duration
   262  
   263  func newDurationValue(val time.Duration, p *time.Duration) *durationValue {
   264  	*p = val
   265  	return (*durationValue)(p)
   266  }
   267  
   268  func (d *durationValue) Set(s string) error {
   269  	v, err := time.ParseDuration(s)
   270  	if err != nil {
   271  		err = errParse
   272  	}
   273  	*d = durationValue(v)
   274  	return err
   275  }
   276  
   277  func (d *durationValue) Get() interface{} { return time.Duration(*d) }
   278  
   279  func (d *durationValue) String() string { return (*time.Duration)(d).String() }
   280  
   281  // Value is the interface to the dynamic value stored in a flag.
   282  // (The default value is represented as a string.)
   283  //
   284  // If a Value has an IsBoolFlag() bool method returning true,
   285  // the command-line parser makes -name equivalent to -name=true
   286  // rather than using the next command-line argument.
   287  //
   288  // Set is called once, in command line order, for each flag present.
   289  // The flag package may call the String method with a zero-valued receiver,
   290  // such as a nil pointer.
   291  type Value interface {
   292  	String() string
   293  	Set(string) error
   294  }
   295  
   296  // Getter is an interface that allows the contents of a Value to be retrieved.
   297  // It wraps the Value interface, rather than being part of it, because it
   298  // appeared after Go 1 and its compatibility rules. All Value types provided
   299  // by this package satisfy the Getter interface.
   300  type Getter interface {
   301  	Value
   302  	Get() interface{}
   303  }
   304  
   305  // ErrorHandling defines how FlagSet.Parse behaves if the parse fails.
   306  type ErrorHandling int
   307  
   308  // These constants cause FlagSet.Parse to behave as described if the parse fails.
   309  const (
   310  	ContinueOnError ErrorHandling = iota // Return a descriptive error.
   311  	ExitOnError                          // Call os.Exit(2).
   312  	PanicOnError                         // Call panic with a descriptive error.
   313  )
   314  
   315  // A FlagSet represents a set of defined flags. The zero value of a FlagSet
   316  // has no name and has ContinueOnError error handling.
   317  type FlagSet struct {
   318  	// Usage is the function called when an error occurs while parsing flags.
   319  	// The field is a function (not a method) that may be changed to point to
   320  	// a custom error handler. What happens after Usage is called depends
   321  	// on the ErrorHandling setting; for the command line, this defaults
   322  	// to ExitOnError, which exits the program after calling Usage.
   323  	Usage func()
   324  
   325  	name          string
   326  	parsed        bool
   327  	actual        map[string]*Flag
   328  	formal        map[string]*Flag
   329  	args          []string // arguments after flags
   330  	errorHandling ErrorHandling
   331  	output        io.Writer // nil means stderr; use out() accessor
   332  }
   333  
   334  // A Flag represents the state of a flag.
   335  type Flag struct {
   336  	Name     string // name as it appears on command line
   337  	Usage    string // help message
   338  	Value    Value  // value as set
   339  	DefValue string // default value (as text); for usage message
   340  }
   341  
   342  // sortFlags returns the flags as a slice in lexicographical sorted order.
   343  func sortFlags(flags map[string]*Flag) []*Flag {
   344  	result := make([]*Flag, len(flags))
   345  	i := 0
   346  	for _, f := range flags {
   347  		result[i] = f
   348  		i++
   349  	}
   350  	sort.Slice(result, func(i, j int) bool {
   351  		return result[i].Name < result[j].Name
   352  	})
   353  	return result
   354  }
   355  
   356  // Output returns the destination for usage and error messages. os.Stderr is returned if
   357  // output was not set or was set to nil.
   358  func (f *FlagSet) Output() io.Writer {
   359  	if f.output == nil {
   360  		return os.Stderr
   361  	}
   362  	return f.output
   363  }
   364  
   365  // Name returns the name of the flag set.
   366  func (f *FlagSet) Name() string {
   367  	return f.name
   368  }
   369  
   370  // ErrorHandling returns the error handling behavior of the flag set.
   371  func (f *FlagSet) ErrorHandling() ErrorHandling {
   372  	return f.errorHandling
   373  }
   374  
   375  // SetOutput sets the destination for usage and error messages.
   376  // If output is nil, os.Stderr is used.
   377  func (f *FlagSet) SetOutput(output io.Writer) {
   378  	f.output = output
   379  }
   380  
   381  // VisitAll visits the flags in lexicographical order, calling fn for each.
   382  // It visits all flags, even those not set.
   383  func (f *FlagSet) VisitAll(fn func(*Flag)) {
   384  	for _, flag := range sortFlags(f.formal) {
   385  		fn(flag)
   386  	}
   387  }
   388  
   389  // VisitAll visits the command-line flags in lexicographical order, calling
   390  // fn for each. It visits all flags, even those not set.
   391  func VisitAll(fn func(*Flag)) {
   392  	CommandLine.VisitAll(fn)
   393  }
   394  
   395  // Visit visits the flags in lexicographical order, calling fn for each.
   396  // It visits only those flags that have been set.
   397  func (f *FlagSet) Visit(fn func(*Flag)) {
   398  	for _, flag := range sortFlags(f.actual) {
   399  		fn(flag)
   400  	}
   401  }
   402  
   403  // Visit visits the command-line flags in lexicographical order, calling fn
   404  // for each. It visits only those flags that have been set.
   405  func Visit(fn func(*Flag)) {
   406  	CommandLine.Visit(fn)
   407  }
   408  
   409  // Lookup returns the Flag structure of the named flag, returning nil if none exists.
   410  func (f *FlagSet) Lookup(name string) *Flag {
   411  	return f.formal[name]
   412  }
   413  
   414  // Lookup returns the Flag structure of the named command-line flag,
   415  // returning nil if none exists.
   416  func Lookup(name string) *Flag {
   417  	return CommandLine.formal[name]
   418  }
   419  
   420  // Set sets the value of the named flag.
   421  func (f *FlagSet) Set(name, value string) error {
   422  	flag, ok := f.formal[name]
   423  	if !ok {
   424  		return fmt.Errorf("no such flag -%v", name)
   425  	}
   426  	err := flag.Value.Set(value)
   427  	if err != nil {
   428  		return err
   429  	}
   430  	if f.actual == nil {
   431  		f.actual = make(map[string]*Flag)
   432  	}
   433  	f.actual[name] = flag
   434  	return nil
   435  }
   436  
   437  // Set sets the value of the named command-line flag.
   438  func Set(name, value string) error {
   439  	return CommandLine.Set(name, value)
   440  }
   441  
   442  // isZeroValue determines whether the string represents the zero
   443  // value for a flag.
   444  func isZeroValue(flag *Flag, value string) bool {
   445  	// Build a zero value of the flag's Value type, and see if the
   446  	// result of calling its String method equals the value passed in.
   447  	// This works unless the Value type is itself an interface type.
   448  	typ := reflect.TypeOf(flag.Value)
   449  	var z reflect.Value
   450  	if typ.Kind() == reflect.Ptr {
   451  		z = reflect.New(typ.Elem())
   452  	} else {
   453  		z = reflect.Zero(typ)
   454  	}
   455  	return value == z.Interface().(Value).String()
   456  }
   457  
   458  // UnquoteUsage extracts a back-quoted name from the usage
   459  // string for a flag and returns it and the un-quoted usage.
   460  // Given "a `name` to show" it returns ("name", "a name to show").
   461  // If there are no back quotes, the name is an educated guess of the
   462  // type of the flag's value, or the empty string if the flag is boolean.
   463  func UnquoteUsage(flag *Flag) (name string, usage string) {
   464  	// Look for a back-quoted name, but avoid the strings package.
   465  	usage = flag.Usage
   466  	for i := 0; i < len(usage); i++ {
   467  		if usage[i] == '`' {
   468  			for j := i + 1; j < len(usage); j++ {
   469  				if usage[j] == '`' {
   470  					name = usage[i+1 : j]
   471  					usage = usage[:i] + name + usage[j+1:]
   472  					return name, usage
   473  				}
   474  			}
   475  			break // Only one back quote; use type name.
   476  		}
   477  	}
   478  	// No explicit name, so use type if we can find one.
   479  	name = "value"
   480  	switch flag.Value.(type) {
   481  	case boolFlag:
   482  		name = ""
   483  	case *durationValue:
   484  		name = "duration"
   485  	case *float64Value:
   486  		name = "float"
   487  	case *intValue, *int64Value:
   488  		name = "int"
   489  	case *stringValue:
   490  		name = "string"
   491  	case *uintValue, *uint64Value:
   492  		name = "uint"
   493  	}
   494  	return
   495  }
   496  
   497  // PrintDefaults prints, to standard error unless configured otherwise, the
   498  // default values of all defined command-line flags in the set. See the
   499  // documentation for the global function PrintDefaults for more information.
   500  func (f *FlagSet) PrintDefaults() {
   501  	f.VisitAll(func(flag *Flag) {
   502  		s := fmt.Sprintf("  -%s", flag.Name) // Two spaces before -; see next two comments.
   503  		name, usage := UnquoteUsage(flag)
   504  		if len(name) > 0 {
   505  			s += " " + name
   506  		}
   507  		// Boolean flags of one ASCII letter are so common we
   508  		// treat them specially, putting their usage on the same line.
   509  		if len(s) <= 4 { // space, space, '-', 'x'.
   510  			s += "\t"
   511  		} else {
   512  			// Four spaces before the tab triggers good alignment
   513  			// for both 4- and 8-space tab stops.
   514  			s += "\n    \t"
   515  		}
   516  		s += strings.ReplaceAll(usage, "\n", "\n    \t")
   517  
   518  		if !isZeroValue(flag, flag.DefValue) {
   519  			if _, ok := flag.Value.(*stringValue); ok {
   520  				// put quotes on the value
   521  				s += fmt.Sprintf(" (default %q)", flag.DefValue)
   522  			} else {
   523  				s += fmt.Sprintf(" (default %v)", flag.DefValue)
   524  			}
   525  		}
   526  		fmt.Fprint(f.Output(), s, "\n")
   527  	})
   528  }
   529  
   530  // PrintDefaults prints, to standard error unless configured otherwise,
   531  // a usage message showing the default settings of all defined
   532  // command-line flags.
   533  // For an integer valued flag x, the default output has the form
   534  //	-x int
   535  //		usage-message-for-x (default 7)
   536  // The usage message will appear on a separate line for anything but
   537  // a bool flag with a one-byte name. For bool flags, the type is
   538  // omitted and if the flag name is one byte the usage message appears
   539  // on the same line. The parenthetical default is omitted if the
   540  // default is the zero value for the type. The listed type, here int,
   541  // can be changed by placing a back-quoted name in the flag's usage
   542  // string; the first such item in the message is taken to be a parameter
   543  // name to show in the message and the back quotes are stripped from
   544  // the message when displayed. For instance, given
   545  //	flag.String("I", "", "search `directory` for include files")
   546  // the output will be
   547  //	-I directory
   548  //		search directory for include files.
   549  //
   550  // To change the destination for flag messages, call CommandLine.SetOutput.
   551  func PrintDefaults() {
   552  	CommandLine.PrintDefaults()
   553  }
   554  
   555  // defaultUsage is the default function to print a usage message.
   556  func (f *FlagSet) defaultUsage() {
   557  	if f.name == "" {
   558  		fmt.Fprintf(f.Output(), "Usage:\n")
   559  	} else {
   560  		fmt.Fprintf(f.Output(), "Usage of %s:\n", f.name)
   561  	}
   562  	f.PrintDefaults()
   563  }
   564  
   565  // NOTE: Usage is not just defaultUsage(CommandLine)
   566  // because it serves (via godoc flag Usage) as the example
   567  // for how to write your own usage function.
   568  
   569  // Usage prints a usage message documenting all defined command-line flags
   570  // to CommandLine's output, which by default is os.Stderr.
   571  // It is called when an error occurs while parsing flags.
   572  // The function is a variable that may be changed to point to a custom function.
   573  // By default it prints a simple header and calls PrintDefaults; for details about the
   574  // format of the output and how to control it, see the documentation for PrintDefaults.
   575  // Custom usage functions may choose to exit the program; by default exiting
   576  // happens anyway as the command line's error handling strategy is set to
   577  // ExitOnError.
   578  var Usage = func() {
   579  	fmt.Fprintf(CommandLine.Output(), "Usage of %s:\n", os.Args[0])
   580  	PrintDefaults()
   581  }
   582  
   583  // NFlag returns the number of flags that have been set.
   584  func (f *FlagSet) NFlag() int { return len(f.actual) }
   585  
   586  // NFlag returns the number of command-line flags that have been set.
   587  func NFlag() int { return len(CommandLine.actual) }
   588  
   589  // Arg returns the i'th argument. Arg(0) is the first remaining argument
   590  // after flags have been processed. Arg returns an empty string if the
   591  // requested element does not exist.
   592  func (f *FlagSet) Arg(i int) string {
   593  	if i < 0 || i >= len(f.args) {
   594  		return ""
   595  	}
   596  	return f.args[i]
   597  }
   598  
   599  // Arg returns the i'th command-line argument. Arg(0) is the first remaining argument
   600  // after flags have been processed. Arg returns an empty string if the
   601  // requested element does not exist.
   602  func Arg(i int) string {
   603  	return CommandLine.Arg(i)
   604  }
   605  
   606  // NArg is the number of arguments remaining after flags have been processed.
   607  func (f *FlagSet) NArg() int { return len(f.args) }
   608  
   609  // NArg is the number of arguments remaining after flags have been processed.
   610  func NArg() int { return len(CommandLine.args) }
   611  
   612  // Args returns the non-flag arguments.
   613  func (f *FlagSet) Args() []string { return f.args }
   614  
   615  // Args returns the non-flag command-line arguments.
   616  func Args() []string { return CommandLine.args }
   617  
   618  // BoolVar defines a bool flag with specified name, default value, and usage string.
   619  // The argument p points to a bool variable in which to store the value of the flag.
   620  func (f *FlagSet) BoolVar(p *bool, name string, value bool, usage string) {
   621  	f.Var(newBoolValue(value, p), name, usage)
   622  }
   623  
   624  // BoolVar defines a bool flag with specified name, default value, and usage string.
   625  // The argument p points to a bool variable in which to store the value of the flag.
   626  func BoolVar(p *bool, name string, value bool, usage string) {
   627  	CommandLine.Var(newBoolValue(value, p), name, usage)
   628  }
   629  
   630  // Bool defines a bool flag with specified name, default value, and usage string.
   631  // The return value is the address of a bool variable that stores the value of the flag.
   632  func (f *FlagSet) Bool(name string, value bool, usage string) *bool {
   633  	p := new(bool)
   634  	f.BoolVar(p, name, value, usage)
   635  	return p
   636  }
   637  
   638  // Bool defines a bool flag with specified name, default value, and usage string.
   639  // The return value is the address of a bool variable that stores the value of the flag.
   640  func Bool(name string, value bool, usage string) *bool {
   641  	return CommandLine.Bool(name, value, usage)
   642  }
   643  
   644  // IntVar defines an int flag with specified name, default value, and usage string.
   645  // The argument p points to an int variable in which to store the value of the flag.
   646  func (f *FlagSet) IntVar(p *int, name string, value int, usage string) {
   647  	f.Var(newIntValue(value, p), name, usage)
   648  }
   649  
   650  // IntVar defines an int flag with specified name, default value, and usage string.
   651  // The argument p points to an int variable in which to store the value of the flag.
   652  func IntVar(p *int, name string, value int, usage string) {
   653  	CommandLine.Var(newIntValue(value, p), name, usage)
   654  }
   655  
   656  // Int defines an int flag with specified name, default value, and usage string.
   657  // The return value is the address of an int variable that stores the value of the flag.
   658  func (f *FlagSet) Int(name string, value int, usage string) *int {
   659  	p := new(int)
   660  	f.IntVar(p, name, value, usage)
   661  	return p
   662  }
   663  
   664  // Int defines an int flag with specified name, default value, and usage string.
   665  // The return value is the address of an int variable that stores the value of the flag.
   666  func Int(name string, value int, usage string) *int {
   667  	return CommandLine.Int(name, value, usage)
   668  }
   669  
   670  // Int64Var defines an int64 flag with specified name, default value, and usage string.
   671  // The argument p points to an int64 variable in which to store the value of the flag.
   672  func (f *FlagSet) Int64Var(p *int64, name string, value int64, usage string) {
   673  	f.Var(newInt64Value(value, p), name, usage)
   674  }
   675  
   676  // Int64Var defines an int64 flag with specified name, default value, and usage string.
   677  // The argument p points to an int64 variable in which to store the value of the flag.
   678  func Int64Var(p *int64, name string, value int64, usage string) {
   679  	CommandLine.Var(newInt64Value(value, p), name, usage)
   680  }
   681  
   682  // Int64 defines an int64 flag with specified name, default value, and usage string.
   683  // The return value is the address of an int64 variable that stores the value of the flag.
   684  func (f *FlagSet) Int64(name string, value int64, usage string) *int64 {
   685  	p := new(int64)
   686  	f.Int64Var(p, name, value, usage)
   687  	return p
   688  }
   689  
   690  // Int64 defines an int64 flag with specified name, default value, and usage string.
   691  // The return value is the address of an int64 variable that stores the value of the flag.
   692  func Int64(name string, value int64, usage string) *int64 {
   693  	return CommandLine.Int64(name, value, usage)
   694  }
   695  
   696  // UintVar defines a uint flag with specified name, default value, and usage string.
   697  // The argument p points to a uint variable in which to store the value of the flag.
   698  func (f *FlagSet) UintVar(p *uint, name string, value uint, usage string) {
   699  	f.Var(newUintValue(value, p), name, usage)
   700  }
   701  
   702  // UintVar defines a uint flag with specified name, default value, and usage string.
   703  // The argument p points to a uint variable in which to store the value of the flag.
   704  func UintVar(p *uint, name string, value uint, usage string) {
   705  	CommandLine.Var(newUintValue(value, p), name, usage)
   706  }
   707  
   708  // Uint defines a uint flag with specified name, default value, and usage string.
   709  // The return value is the address of a uint variable that stores the value of the flag.
   710  func (f *FlagSet) Uint(name string, value uint, usage string) *uint {
   711  	p := new(uint)
   712  	f.UintVar(p, name, value, usage)
   713  	return p
   714  }
   715  
   716  // Uint defines a uint flag with specified name, default value, and usage string.
   717  // The return value is the address of a uint variable that stores the value of the flag.
   718  func Uint(name string, value uint, usage string) *uint {
   719  	return CommandLine.Uint(name, value, usage)
   720  }
   721  
   722  // Uint64Var defines a uint64 flag with specified name, default value, and usage string.
   723  // The argument p points to a uint64 variable in which to store the value of the flag.
   724  func (f *FlagSet) Uint64Var(p *uint64, name string, value uint64, usage string) {
   725  	f.Var(newUint64Value(value, p), name, usage)
   726  }
   727  
   728  // Uint64Var defines a uint64 flag with specified name, default value, and usage string.
   729  // The argument p points to a uint64 variable in which to store the value of the flag.
   730  func Uint64Var(p *uint64, name string, value uint64, usage string) {
   731  	CommandLine.Var(newUint64Value(value, p), name, usage)
   732  }
   733  
   734  // Uint64 defines a uint64 flag with specified name, default value, and usage string.
   735  // The return value is the address of a uint64 variable that stores the value of the flag.
   736  func (f *FlagSet) Uint64(name string, value uint64, usage string) *uint64 {
   737  	p := new(uint64)
   738  	f.Uint64Var(p, name, value, usage)
   739  	return p
   740  }
   741  
   742  // Uint64 defines a uint64 flag with specified name, default value, and usage string.
   743  // The return value is the address of a uint64 variable that stores the value of the flag.
   744  func Uint64(name string, value uint64, usage string) *uint64 {
   745  	return CommandLine.Uint64(name, value, usage)
   746  }
   747  
   748  // StringVar defines a string flag with specified name, default value, and usage string.
   749  // The argument p points to a string variable in which to store the value of the flag.
   750  func (f *FlagSet) StringVar(p *string, name string, value string, usage string) {
   751  	f.Var(newStringValue(value, p), name, usage)
   752  }
   753  
   754  // StringVar defines a string flag with specified name, default value, and usage string.
   755  // The argument p points to a string variable in which to store the value of the flag.
   756  func StringVar(p *string, name string, value string, usage string) {
   757  	CommandLine.Var(newStringValue(value, p), name, usage)
   758  }
   759  
   760  // String defines a string flag with specified name, default value, and usage string.
   761  // The return value is the address of a string variable that stores the value of the flag.
   762  func (f *FlagSet) String(name string, value string, usage string) *string {
   763  	p := new(string)
   764  	f.StringVar(p, name, value, usage)
   765  	return p
   766  }
   767  
   768  // String defines a string flag with specified name, default value, and usage string.
   769  // The return value is the address of a string variable that stores the value of the flag.
   770  func String(name string, value string, usage string) *string {
   771  	return CommandLine.String(name, value, usage)
   772  }
   773  
   774  // Float64Var defines a float64 flag with specified name, default value, and usage string.
   775  // The argument p points to a float64 variable in which to store the value of the flag.
   776  func (f *FlagSet) Float64Var(p *float64, name string, value float64, usage string) {
   777  	f.Var(newFloat64Value(value, p), name, usage)
   778  }
   779  
   780  // Float64Var defines a float64 flag with specified name, default value, and usage string.
   781  // The argument p points to a float64 variable in which to store the value of the flag.
   782  func Float64Var(p *float64, name string, value float64, usage string) {
   783  	CommandLine.Var(newFloat64Value(value, p), name, usage)
   784  }
   785  
   786  // Float64 defines a float64 flag with specified name, default value, and usage string.
   787  // The return value is the address of a float64 variable that stores the value of the flag.
   788  func (f *FlagSet) Float64(name string, value float64, usage string) *float64 {
   789  	p := new(float64)
   790  	f.Float64Var(p, name, value, usage)
   791  	return p
   792  }
   793  
   794  // Float64 defines a float64 flag with specified name, default value, and usage string.
   795  // The return value is the address of a float64 variable that stores the value of the flag.
   796  func Float64(name string, value float64, usage string) *float64 {
   797  	return CommandLine.Float64(name, value, usage)
   798  }
   799  
   800  // DurationVar defines a time.Duration flag with specified name, default value, and usage string.
   801  // The argument p points to a time.Duration variable in which to store the value of the flag.
   802  // The flag accepts a value acceptable to time.ParseDuration.
   803  func (f *FlagSet) DurationVar(p *time.Duration, name string, value time.Duration, usage string) {
   804  	f.Var(newDurationValue(value, p), name, usage)
   805  }
   806  
   807  // DurationVar defines a time.Duration flag with specified name, default value, and usage string.
   808  // The argument p points to a time.Duration variable in which to store the value of the flag.
   809  // The flag accepts a value acceptable to time.ParseDuration.
   810  func DurationVar(p *time.Duration, name string, value time.Duration, usage string) {
   811  	CommandLine.Var(newDurationValue(value, p), name, usage)
   812  }
   813  
   814  // Duration defines a time.Duration flag with specified name, default value, and usage string.
   815  // The return value is the address of a time.Duration variable that stores the value of the flag.
   816  // The flag accepts a value acceptable to time.ParseDuration.
   817  func (f *FlagSet) Duration(name string, value time.Duration, usage string) *time.Duration {
   818  	p := new(time.Duration)
   819  	f.DurationVar(p, name, value, usage)
   820  	return p
   821  }
   822  
   823  // Duration defines a time.Duration flag with specified name, default value, and usage string.
   824  // The return value is the address of a time.Duration variable that stores the value of the flag.
   825  // The flag accepts a value acceptable to time.ParseDuration.
   826  func Duration(name string, value time.Duration, usage string) *time.Duration {
   827  	return CommandLine.Duration(name, value, usage)
   828  }
   829  
   830  // Var defines a flag with the specified name and usage string. The type and
   831  // value of the flag are represented by the first argument, of type Value, which
   832  // typically holds a user-defined implementation of Value. For instance, the
   833  // caller could create a flag that turns a comma-separated string into a slice
   834  // of strings by giving the slice the methods of Value; in particular, Set would
   835  // decompose the comma-separated string into the slice.
   836  func (f *FlagSet) Var(value Value, name string, usage string) {
   837  	// Remember the default value as a string; it won't change.
   838  	flag := &Flag{name, usage, value, value.String()}
   839  	_, alreadythere := f.formal[name]
   840  	if alreadythere {
   841  		var msg string
   842  		if f.name == "" {
   843  			msg = fmt.Sprintf("flag redefined: %s", name)
   844  		} else {
   845  			msg = fmt.Sprintf("%s flag redefined: %s", f.name, name)
   846  		}
   847  		fmt.Fprintln(f.Output(), msg)
   848  		panic(msg) // Happens only if flags are declared with identical names
   849  	}
   850  	if f.formal == nil {
   851  		f.formal = make(map[string]*Flag)
   852  	}
   853  	f.formal[name] = flag
   854  }
   855  
   856  // Var defines a flag with the specified name and usage string. The type and
   857  // value of the flag are represented by the first argument, of type Value, which
   858  // typically holds a user-defined implementation of Value. For instance, the
   859  // caller could create a flag that turns a comma-separated string into a slice
   860  // of strings by giving the slice the methods of Value; in particular, Set would
   861  // decompose the comma-separated string into the slice.
   862  func Var(value Value, name string, usage string) {
   863  	CommandLine.Var(value, name, usage)
   864  }
   865  
   866  // failf prints to standard error a formatted error and usage message and
   867  // returns the error.
   868  func (f *FlagSet) failf(format string, a ...interface{}) error {
   869  	err := fmt.Errorf(format, a...)
   870  	fmt.Fprintln(f.Output(), err)
   871  	f.usage()
   872  	return err
   873  }
   874  
   875  // usage calls the Usage method for the flag set if one is specified,
   876  // or the appropriate default usage function otherwise.
   877  func (f *FlagSet) usage() {
   878  	if f.Usage == nil {
   879  		f.defaultUsage()
   880  	} else {
   881  		f.Usage()
   882  	}
   883  }
   884  
   885  // parseOne parses one flag. It reports whether a flag was seen.
   886  func (f *FlagSet) parseOne() (bool, error) {
   887  	if len(f.args) == 0 {
   888  		return false, nil
   889  	}
   890  	s := f.args[0]
   891  	if len(s) < 2 || s[0] != '-' {
   892  		return false, nil
   893  	}
   894  	numMinuses := 1
   895  	if s[1] == '-' {
   896  		numMinuses++
   897  		if len(s) == 2 { // "--" terminates the flags
   898  			f.args = f.args[1:]
   899  			return false, nil
   900  		}
   901  	}
   902  	name := s[numMinuses:]
   903  	if len(name) == 0 || name[0] == '-' || name[0] == '=' {
   904  		return false, f.failf("bad flag syntax: %s", s)
   905  	}
   906  
   907  	// it's a flag. does it have an argument?
   908  	f.args = f.args[1:]
   909  	hasValue := false
   910  	value := ""
   911  	for i := 1; i < len(name); i++ { // equals cannot be first
   912  		if name[i] == '=' {
   913  			value = name[i+1:]
   914  			hasValue = true
   915  			name = name[0:i]
   916  			break
   917  		}
   918  	}
   919  	m := f.formal
   920  	flag, alreadythere := m[name] // BUG
   921  	if !alreadythere {
   922  		if name == "help" || name == "h" { // special case for nice help message.
   923  			f.usage()
   924  			return false, ErrHelp
   925  		}
   926  		return false, f.failf("flag provided but not defined: -%s", name)
   927  	}
   928  
   929  	if fv, ok := flag.Value.(boolFlag); ok && fv.IsBoolFlag() { // special case: doesn't need an arg
   930  		if hasValue {
   931  			if err := fv.Set(value); err != nil {
   932  				return false, f.failf("invalid boolean value %q for -%s: %v", value, name, err)
   933  			}
   934  		} else {
   935  			if err := fv.Set("true"); err != nil {
   936  				return false, f.failf("invalid boolean flag %s: %v", name, err)
   937  			}
   938  		}
   939  	} else {
   940  		// It must have a value, which might be the next argument.
   941  		if !hasValue && len(f.args) > 0 {
   942  			// value is the next arg
   943  			hasValue = true
   944  			value, f.args = f.args[0], f.args[1:]
   945  		}
   946  		if !hasValue {
   947  			return false, f.failf("flag needs an argument: -%s", name)
   948  		}
   949  		if err := flag.Value.Set(value); err != nil {
   950  			return false, f.failf("invalid value %q for flag -%s: %v", value, name, err)
   951  		}
   952  	}
   953  	if f.actual == nil {
   954  		f.actual = make(map[string]*Flag)
   955  	}
   956  	f.actual[name] = flag
   957  	return true, nil
   958  }
   959  
   960  // Parse parses flag definitions from the argument list, which should not
   961  // include the command name. Must be called after all flags in the FlagSet
   962  // are defined and before flags are accessed by the program.
   963  // The return value will be ErrHelp if -help or -h were set but not defined.
   964  func (f *FlagSet) Parse(arguments []string) error {
   965  	f.parsed = true
   966  	f.args = arguments
   967  	for {
   968  		seen, err := f.parseOne()
   969  		if seen {
   970  			continue
   971  		}
   972  		if err == nil {
   973  			break
   974  		}
   975  		switch f.errorHandling {
   976  		case ContinueOnError:
   977  			return err
   978  		case ExitOnError:
   979  			os.Exit(2)
   980  		case PanicOnError:
   981  			panic(err)
   982  		}
   983  	}
   984  	return nil
   985  }
   986  
   987  // Parsed reports whether f.Parse has been called.
   988  func (f *FlagSet) Parsed() bool {
   989  	return f.parsed
   990  }
   991  
   992  // Parse parses the command-line flags from os.Args[1:]. Must be called
   993  // after all flags are defined and before flags are accessed by the program.
   994  func Parse() {
   995  	// Ignore errors; CommandLine is set for ExitOnError.
   996  	CommandLine.Parse(os.Args[1:])
   997  }
   998  
   999  // Parsed reports whether the command-line flags have been parsed.
  1000  func Parsed() bool {
  1001  	return CommandLine.Parsed()
  1002  }
  1003  
  1004  // CommandLine is the default set of command-line flags, parsed from os.Args.
  1005  // The top-level functions such as BoolVar, Arg, and so on are wrappers for the
  1006  // methods of CommandLine.
  1007  var CommandLine = NewFlagSet(os.Args[0], ExitOnError)
  1008  
  1009  func init() {
  1010  	// Override generic FlagSet default Usage with call to global Usage.
  1011  	// Note: This is not CommandLine.Usage = Usage,
  1012  	// because we want any eventual call to use any updated value of Usage,
  1013  	// not the value it has when this line is run.
  1014  	CommandLine.Usage = commandLineUsage
  1015  }
  1016  
  1017  func commandLineUsage() {
  1018  	Usage()
  1019  }
  1020  
  1021  // NewFlagSet returns a new, empty flag set with the specified name and
  1022  // error handling property. If the name is not empty, it will be printed
  1023  // in the default usage message and in error messages.
  1024  func NewFlagSet(name string, errorHandling ErrorHandling) *FlagSet {
  1025  	f := &FlagSet{
  1026  		name:          name,
  1027  		errorHandling: errorHandling,
  1028  	}
  1029  	f.Usage = f.defaultUsage
  1030  	return f
  1031  }
  1032  
  1033  // Init sets the name and error handling property for a flag set.
  1034  // By default, the zero FlagSet uses an empty name and the
  1035  // ContinueOnError error handling policy.
  1036  func (f *FlagSet) Init(name string, errorHandling ErrorHandling) {
  1037  	f.name = name
  1038  	f.errorHandling = errorHandling
  1039  }
  1040  

View as plain text