Source file src/github.com/spf13/pflag/flag.go

Documentation: github.com/spf13/pflag

     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 pflag is a drop-in replacement for Go's flag package, implementing
     7  POSIX/GNU-style --flags.
     8  
     9  pflag is compatible with the GNU extensions to the POSIX recommendations
    10  for command-line options. See
    11  http://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html
    12  
    13  Usage:
    14  
    15  pflag is a drop-in replacement of Go's native flag package. If you import
    16  pflag under the name "flag" then all code should continue to function
    17  with no changes.
    18  
    19  	import flag "github.com/spf13/pflag"
    20  
    21  There is one exception to this: if you directly instantiate the Flag struct
    22  there is one more field "Shorthand" that you will need to set.
    23  Most code never instantiates this struct directly, and instead uses
    24  functions such as String(), BoolVar(), and Var(), and is therefore
    25  unaffected.
    26  
    27  Define flags using flag.String(), Bool(), Int(), etc.
    28  
    29  This declares an integer flag, -flagname, stored in the pointer ip, with type *int.
    30  	var ip = flag.Int("flagname", 1234, "help message for flagname")
    31  If you like, you can bind the flag to a variable using the Var() functions.
    32  	var flagvar int
    33  	func init() {
    34  		flag.IntVar(&flagvar, "flagname", 1234, "help message for flagname")
    35  	}
    36  Or you can create custom flags that satisfy the Value interface (with
    37  pointer receivers) and couple them to flag parsing by
    38  	flag.Var(&flagVal, "name", "help message for flagname")
    39  For such flags, the default value is just the initial value of the variable.
    40  
    41  After all flags are defined, call
    42  	flag.Parse()
    43  to parse the command line into the defined flags.
    44  
    45  Flags may then be used directly. If you're using the flags themselves,
    46  they are all pointers; if you bind to variables, they're values.
    47  	fmt.Println("ip has value ", *ip)
    48  	fmt.Println("flagvar has value ", flagvar)
    49  
    50  After parsing, the arguments after the flag are available as the
    51  slice flag.Args() or individually as flag.Arg(i).
    52  The arguments are indexed from 0 through flag.NArg()-1.
    53  
    54  The pflag package also defines some new functions that are not in flag,
    55  that give one-letter shorthands for flags. You can use these by appending
    56  'P' to the name of any function that defines a flag.
    57  	var ip = flag.IntP("flagname", "f", 1234, "help message")
    58  	var flagvar bool
    59  	func init() {
    60  		flag.BoolVarP(&flagvar, "boolname", "b", true, "help message")
    61  	}
    62  	flag.VarP(&flagval, "varname", "v", "help message")
    63  Shorthand letters can be used with single dashes on the command line.
    64  Boolean shorthand flags can be combined with other shorthand flags.
    65  
    66  Command line flag syntax:
    67  	--flag    // boolean flags only
    68  	--flag=x
    69  
    70  Unlike the flag package, a single dash before an option means something
    71  different than a double dash. Single dashes signify a series of shorthand
    72  letters for flags. All but the last shorthand letter must be boolean flags.
    73  	// boolean flags
    74  	-f
    75  	-abc
    76  	// non-boolean flags
    77  	-n 1234
    78  	-Ifile
    79  	// mixed
    80  	-abcs "hello"
    81  	-abcn1234
    82  
    83  Flag parsing stops after the terminator "--". Unlike the flag package,
    84  flags can be interspersed with arguments anywhere on the command line
    85  before this terminator.
    86  
    87  Integer flags accept 1234, 0664, 0x1234 and may be negative.
    88  Boolean flags (in their long form) accept 1, 0, t, f, true, false,
    89  TRUE, FALSE, True, False.
    90  Duration flags accept any input valid for time.ParseDuration.
    91  
    92  The default set of command-line flags is controlled by
    93  top-level functions.  The FlagSet type allows one to define
    94  independent sets of flags, such as to implement subcommands
    95  in a command-line interface. The methods of FlagSet are
    96  analogous to the top-level functions for the command-line
    97  flag set.
    98  */
    99  package pflag
   100  
   101  import (
   102  	"bytes"
   103  	"errors"
   104  	goflag "flag"
   105  	"fmt"
   106  	"io"
   107  	"os"
   108  	"sort"
   109  	"strings"
   110  )
   111  
   112  // ErrHelp is the error returned if the flag -help is invoked but no such flag is defined.
   113  var ErrHelp = errors.New("pflag: help requested")
   114  
   115  // ErrorHandling defines how to handle flag parsing errors.
   116  type ErrorHandling int
   117  
   118  const (
   119  	// ContinueOnError will return an err from Parse() if an error is found
   120  	ContinueOnError ErrorHandling = iota
   121  	// ExitOnError will call os.Exit(2) if an error is found when parsing
   122  	ExitOnError
   123  	// PanicOnError will panic() if an error is found when parsing flags
   124  	PanicOnError
   125  )
   126  
   127  // ParseErrorsWhitelist defines the parsing errors that can be ignored
   128  type ParseErrorsWhitelist struct {
   129  	// UnknownFlags will ignore unknown flags errors and continue parsing rest of the flags
   130  	UnknownFlags bool
   131  }
   132  
   133  // NormalizedName is a flag name that has been normalized according to rules
   134  // for the FlagSet (e.g. making '-' and '_' equivalent).
   135  type NormalizedName string
   136  
   137  // A FlagSet represents a set of defined flags.
   138  type FlagSet struct {
   139  	// Usage is the function called when an error occurs while parsing flags.
   140  	// The field is a function (not a method) that may be changed to point to
   141  	// a custom error handler.
   142  	Usage func()
   143  
   144  	// SortFlags is used to indicate, if user wants to have sorted flags in
   145  	// help/usage messages.
   146  	SortFlags bool
   147  
   148  	// ParseErrorsWhitelist is used to configure a whitelist of errors
   149  	ParseErrorsWhitelist ParseErrorsWhitelist
   150  
   151  	name              string
   152  	parsed            bool
   153  	actual            map[NormalizedName]*Flag
   154  	orderedActual     []*Flag
   155  	sortedActual      []*Flag
   156  	formal            map[NormalizedName]*Flag
   157  	orderedFormal     []*Flag
   158  	sortedFormal      []*Flag
   159  	shorthands        map[byte]*Flag
   160  	args              []string // arguments after flags
   161  	argsLenAtDash     int      // len(args) when a '--' was located when parsing, or -1 if no --
   162  	errorHandling     ErrorHandling
   163  	output            io.Writer // nil means stderr; use out() accessor
   164  	interspersed      bool      // allow interspersed option/non-option args
   165  	normalizeNameFunc func(f *FlagSet, name string) NormalizedName
   166  
   167  	addedGoFlagSets []*goflag.FlagSet
   168  }
   169  
   170  // A Flag represents the state of a flag.
   171  type Flag struct {
   172  	Name                string              // name as it appears on command line
   173  	Shorthand           string              // one-letter abbreviated flag
   174  	Usage               string              // help message
   175  	Value               Value               // value as set
   176  	DefValue            string              // default value (as text); for usage message
   177  	Changed             bool                // If the user set the value (or if left to default)
   178  	NoOptDefVal         string              // default value (as text); if the flag is on the command line without any options
   179  	Deprecated          string              // If this flag is deprecated, this string is the new or now thing to use
   180  	Hidden              bool                // used by cobra.Command to allow flags to be hidden from help/usage text
   181  	ShorthandDeprecated string              // If the shorthand of this flag is deprecated, this string is the new or now thing to use
   182  	Annotations         map[string][]string // used by cobra.Command bash autocomple code
   183  }
   184  
   185  // Value is the interface to the dynamic value stored in a flag.
   186  // (The default value is represented as a string.)
   187  type Value interface {
   188  	String() string
   189  	Set(string) error
   190  	Type() string
   191  }
   192  
   193  // SliceValue is a secondary interface to all flags which hold a list
   194  // of values.  This allows full control over the value of list flags,
   195  // and avoids complicated marshalling and unmarshalling to csv.
   196  type SliceValue interface {
   197  	// Append adds the specified value to the end of the flag value list.
   198  	Append(string) error
   199  	// Replace will fully overwrite any data currently in the flag value list.
   200  	Replace([]string) error
   201  	// GetSlice returns the flag value list as an array of strings.
   202  	GetSlice() []string
   203  }
   204  
   205  // sortFlags returns the flags as a slice in lexicographical sorted order.
   206  func sortFlags(flags map[NormalizedName]*Flag) []*Flag {
   207  	list := make(sort.StringSlice, len(flags))
   208  	i := 0
   209  	for k := range flags {
   210  		list[i] = string(k)
   211  		i++
   212  	}
   213  	list.Sort()
   214  	result := make([]*Flag, len(list))
   215  	for i, name := range list {
   216  		result[i] = flags[NormalizedName(name)]
   217  	}
   218  	return result
   219  }
   220  
   221  // SetNormalizeFunc allows you to add a function which can translate flag names.
   222  // Flags added to the FlagSet will be translated and then when anything tries to
   223  // look up the flag that will also be translated. So it would be possible to create
   224  // a flag named "getURL" and have it translated to "geturl".  A user could then pass
   225  // "--getUrl" which may also be translated to "geturl" and everything will work.
   226  func (f *FlagSet) SetNormalizeFunc(n func(f *FlagSet, name string) NormalizedName) {
   227  	f.normalizeNameFunc = n
   228  	f.sortedFormal = f.sortedFormal[:0]
   229  	for fname, flag := range f.formal {
   230  		nname := f.normalizeFlagName(flag.Name)
   231  		if fname == nname {
   232  			continue
   233  		}
   234  		flag.Name = string(nname)
   235  		delete(f.formal, fname)
   236  		f.formal[nname] = flag
   237  		if _, set := f.actual[fname]; set {
   238  			delete(f.actual, fname)
   239  			f.actual[nname] = flag
   240  		}
   241  	}
   242  }
   243  
   244  // GetNormalizeFunc returns the previously set NormalizeFunc of a function which
   245  // does no translation, if not set previously.
   246  func (f *FlagSet) GetNormalizeFunc() func(f *FlagSet, name string) NormalizedName {
   247  	if f.normalizeNameFunc != nil {
   248  		return f.normalizeNameFunc
   249  	}
   250  	return func(f *FlagSet, name string) NormalizedName { return NormalizedName(name) }
   251  }
   252  
   253  func (f *FlagSet) normalizeFlagName(name string) NormalizedName {
   254  	n := f.GetNormalizeFunc()
   255  	return n(f, name)
   256  }
   257  
   258  func (f *FlagSet) out() io.Writer {
   259  	if f.output == nil {
   260  		return os.Stderr
   261  	}
   262  	return f.output
   263  }
   264  
   265  // SetOutput sets the destination for usage and error messages.
   266  // If output is nil, os.Stderr is used.
   267  func (f *FlagSet) SetOutput(output io.Writer) {
   268  	f.output = output
   269  }
   270  
   271  // VisitAll visits the flags in lexicographical order or
   272  // in primordial order if f.SortFlags is false, calling fn for each.
   273  // It visits all flags, even those not set.
   274  func (f *FlagSet) VisitAll(fn func(*Flag)) {
   275  	if len(f.formal) == 0 {
   276  		return
   277  	}
   278  
   279  	var flags []*Flag
   280  	if f.SortFlags {
   281  		if len(f.formal) != len(f.sortedFormal) {
   282  			f.sortedFormal = sortFlags(f.formal)
   283  		}
   284  		flags = f.sortedFormal
   285  	} else {
   286  		flags = f.orderedFormal
   287  	}
   288  
   289  	for _, flag := range flags {
   290  		fn(flag)
   291  	}
   292  }
   293  
   294  // HasFlags returns a bool to indicate if the FlagSet has any flags defined.
   295  func (f *FlagSet) HasFlags() bool {
   296  	return len(f.formal) > 0
   297  }
   298  
   299  // HasAvailableFlags returns a bool to indicate if the FlagSet has any flags
   300  // that are not hidden.
   301  func (f *FlagSet) HasAvailableFlags() bool {
   302  	for _, flag := range f.formal {
   303  		if !flag.Hidden {
   304  			return true
   305  		}
   306  	}
   307  	return false
   308  }
   309  
   310  // VisitAll visits the command-line flags in lexicographical order or
   311  // in primordial order if f.SortFlags is false, calling fn for each.
   312  // It visits all flags, even those not set.
   313  func VisitAll(fn func(*Flag)) {
   314  	CommandLine.VisitAll(fn)
   315  }
   316  
   317  // Visit visits the flags in lexicographical order or
   318  // in primordial order if f.SortFlags is false, calling fn for each.
   319  // It visits only those flags that have been set.
   320  func (f *FlagSet) Visit(fn func(*Flag)) {
   321  	if len(f.actual) == 0 {
   322  		return
   323  	}
   324  
   325  	var flags []*Flag
   326  	if f.SortFlags {
   327  		if len(f.actual) != len(f.sortedActual) {
   328  			f.sortedActual = sortFlags(f.actual)
   329  		}
   330  		flags = f.sortedActual
   331  	} else {
   332  		flags = f.orderedActual
   333  	}
   334  
   335  	for _, flag := range flags {
   336  		fn(flag)
   337  	}
   338  }
   339  
   340  // Visit visits the command-line flags in lexicographical order or
   341  // in primordial order if f.SortFlags is false, calling fn for each.
   342  // It visits only those flags that have been set.
   343  func Visit(fn func(*Flag)) {
   344  	CommandLine.Visit(fn)
   345  }
   346  
   347  // Lookup returns the Flag structure of the named flag, returning nil if none exists.
   348  func (f *FlagSet) Lookup(name string) *Flag {
   349  	return f.lookup(f.normalizeFlagName(name))
   350  }
   351  
   352  // ShorthandLookup returns the Flag structure of the short handed flag,
   353  // returning nil if none exists.
   354  // It panics, if len(name) > 1.
   355  func (f *FlagSet) ShorthandLookup(name string) *Flag {
   356  	if name == "" {
   357  		return nil
   358  	}
   359  	if len(name) > 1 {
   360  		msg := fmt.Sprintf("can not look up shorthand which is more than one ASCII character: %q", name)
   361  		fmt.Fprintf(f.out(), msg)
   362  		panic(msg)
   363  	}
   364  	c := name[0]
   365  	return f.shorthands[c]
   366  }
   367  
   368  // lookup returns the Flag structure of the named flag, returning nil if none exists.
   369  func (f *FlagSet) lookup(name NormalizedName) *Flag {
   370  	return f.formal[name]
   371  }
   372  
   373  // func to return a given type for a given flag name
   374  func (f *FlagSet) getFlagType(name string, ftype string, convFunc func(sval string) (interface{}, error)) (interface{}, error) {
   375  	flag := f.Lookup(name)
   376  	if flag == nil {
   377  		err := fmt.Errorf("flag accessed but not defined: %s", name)
   378  		return nil, err
   379  	}
   380  
   381  	if flag.Value.Type() != ftype {
   382  		err := fmt.Errorf("trying to get %s value of flag of type %s", ftype, flag.Value.Type())
   383  		return nil, err
   384  	}
   385  
   386  	sval := flag.Value.String()
   387  	result, err := convFunc(sval)
   388  	if err != nil {
   389  		return nil, err
   390  	}
   391  	return result, nil
   392  }
   393  
   394  // ArgsLenAtDash will return the length of f.Args at the moment when a -- was
   395  // found during arg parsing. This allows your program to know which args were
   396  // before the -- and which came after.
   397  func (f *FlagSet) ArgsLenAtDash() int {
   398  	return f.argsLenAtDash
   399  }
   400  
   401  // MarkDeprecated indicated that a flag is deprecated in your program. It will
   402  // continue to function but will not show up in help or usage messages. Using
   403  // this flag will also print the given usageMessage.
   404  func (f *FlagSet) MarkDeprecated(name string, usageMessage string) error {
   405  	flag := f.Lookup(name)
   406  	if flag == nil {
   407  		return fmt.Errorf("flag %q does not exist", name)
   408  	}
   409  	if usageMessage == "" {
   410  		return fmt.Errorf("deprecated message for flag %q must be set", name)
   411  	}
   412  	flag.Deprecated = usageMessage
   413  	flag.Hidden = true
   414  	return nil
   415  }
   416  
   417  // MarkShorthandDeprecated will mark the shorthand of a flag deprecated in your
   418  // program. It will continue to function but will not show up in help or usage
   419  // messages. Using this flag will also print the given usageMessage.
   420  func (f *FlagSet) MarkShorthandDeprecated(name string, usageMessage string) error {
   421  	flag := f.Lookup(name)
   422  	if flag == nil {
   423  		return fmt.Errorf("flag %q does not exist", name)
   424  	}
   425  	if usageMessage == "" {
   426  		return fmt.Errorf("deprecated message for flag %q must be set", name)
   427  	}
   428  	flag.ShorthandDeprecated = usageMessage
   429  	return nil
   430  }
   431  
   432  // MarkHidden sets a flag to 'hidden' in your program. It will continue to
   433  // function but will not show up in help or usage messages.
   434  func (f *FlagSet) MarkHidden(name string) error {
   435  	flag := f.Lookup(name)
   436  	if flag == nil {
   437  		return fmt.Errorf("flag %q does not exist", name)
   438  	}
   439  	flag.Hidden = true
   440  	return nil
   441  }
   442  
   443  // Lookup returns the Flag structure of the named command-line flag,
   444  // returning nil if none exists.
   445  func Lookup(name string) *Flag {
   446  	return CommandLine.Lookup(name)
   447  }
   448  
   449  // ShorthandLookup returns the Flag structure of the short handed flag,
   450  // returning nil if none exists.
   451  func ShorthandLookup(name string) *Flag {
   452  	return CommandLine.ShorthandLookup(name)
   453  }
   454  
   455  // Set sets the value of the named flag.
   456  func (f *FlagSet) Set(name, value string) error {
   457  	normalName := f.normalizeFlagName(name)
   458  	flag, ok := f.formal[normalName]
   459  	if !ok {
   460  		return fmt.Errorf("no such flag -%v", name)
   461  	}
   462  
   463  	err := flag.Value.Set(value)
   464  	if err != nil {
   465  		var flagName string
   466  		if flag.Shorthand != "" && flag.ShorthandDeprecated == "" {
   467  			flagName = fmt.Sprintf("-%s, --%s", flag.Shorthand, flag.Name)
   468  		} else {
   469  			flagName = fmt.Sprintf("--%s", flag.Name)
   470  		}
   471  		return fmt.Errorf("invalid argument %q for %q flag: %v", value, flagName, err)
   472  	}
   473  
   474  	if !flag.Changed {
   475  		if f.actual == nil {
   476  			f.actual = make(map[NormalizedName]*Flag)
   477  		}
   478  		f.actual[normalName] = flag
   479  		f.orderedActual = append(f.orderedActual, flag)
   480  
   481  		flag.Changed = true
   482  	}
   483  
   484  	if flag.Deprecated != "" {
   485  		fmt.Fprintf(f.out(), "Flag --%s has been deprecated, %s\n", flag.Name, flag.Deprecated)
   486  	}
   487  	return nil
   488  }
   489  
   490  // SetAnnotation allows one to set arbitrary annotations on a flag in the FlagSet.
   491  // This is sometimes used by spf13/cobra programs which want to generate additional
   492  // bash completion information.
   493  func (f *FlagSet) SetAnnotation(name, key string, values []string) error {
   494  	normalName := f.normalizeFlagName(name)
   495  	flag, ok := f.formal[normalName]
   496  	if !ok {
   497  		return fmt.Errorf("no such flag -%v", name)
   498  	}
   499  	if flag.Annotations == nil {
   500  		flag.Annotations = map[string][]string{}
   501  	}
   502  	flag.Annotations[key] = values
   503  	return nil
   504  }
   505  
   506  // Changed returns true if the flag was explicitly set during Parse() and false
   507  // otherwise
   508  func (f *FlagSet) Changed(name string) bool {
   509  	flag := f.Lookup(name)
   510  	// If a flag doesn't exist, it wasn't changed....
   511  	if flag == nil {
   512  		return false
   513  	}
   514  	return flag.Changed
   515  }
   516  
   517  // Set sets the value of the named command-line flag.
   518  func Set(name, value string) error {
   519  	return CommandLine.Set(name, value)
   520  }
   521  
   522  // PrintDefaults prints, to standard error unless configured
   523  // otherwise, the default values of all defined flags in the set.
   524  func (f *FlagSet) PrintDefaults() {
   525  	usages := f.FlagUsages()
   526  	fmt.Fprint(f.out(), usages)
   527  }
   528  
   529  // defaultIsZeroValue returns true if the default value for this flag represents
   530  // a zero value.
   531  func (f *Flag) defaultIsZeroValue() bool {
   532  	switch f.Value.(type) {
   533  	case boolFlag:
   534  		return f.DefValue == "false"
   535  	case *durationValue:
   536  		// Beginning in Go 1.7, duration zero values are "0s"
   537  		return f.DefValue == "0" || f.DefValue == "0s"
   538  	case *intValue, *int8Value, *int32Value, *int64Value, *uintValue, *uint8Value, *uint16Value, *uint32Value, *uint64Value, *countValue, *float32Value, *float64Value:
   539  		return f.DefValue == "0"
   540  	case *stringValue:
   541  		return f.DefValue == ""
   542  	case *ipValue, *ipMaskValue, *ipNetValue:
   543  		return f.DefValue == "<nil>"
   544  	case *intSliceValue, *stringSliceValue, *stringArrayValue:
   545  		return f.DefValue == "[]"
   546  	default:
   547  		switch f.Value.String() {
   548  		case "false":
   549  			return true
   550  		case "<nil>":
   551  			return true
   552  		case "":
   553  			return true
   554  		case "0":
   555  			return true
   556  		}
   557  		return false
   558  	}
   559  }
   560  
   561  // UnquoteUsage extracts a back-quoted name from the usage
   562  // string for a flag and returns it and the un-quoted usage.
   563  // Given "a `name` to show" it returns ("name", "a name to show").
   564  // If there are no back quotes, the name is an educated guess of the
   565  // type of the flag's value, or the empty string if the flag is boolean.
   566  func UnquoteUsage(flag *Flag) (name string, usage string) {
   567  	// Look for a back-quoted name, but avoid the strings package.
   568  	usage = flag.Usage
   569  	for i := 0; i < len(usage); i++ {
   570  		if usage[i] == '`' {
   571  			for j := i + 1; j < len(usage); j++ {
   572  				if usage[j] == '`' {
   573  					name = usage[i+1 : j]
   574  					usage = usage[:i] + name + usage[j+1:]
   575  					return name, usage
   576  				}
   577  			}
   578  			break // Only one back quote; use type name.
   579  		}
   580  	}
   581  
   582  	name = flag.Value.Type()
   583  	switch name {
   584  	case "bool":
   585  		name = ""
   586  	case "float64":
   587  		name = "float"
   588  	case "int64":
   589  		name = "int"
   590  	case "uint64":
   591  		name = "uint"
   592  	case "stringSlice":
   593  		name = "strings"
   594  	case "intSlice":
   595  		name = "ints"
   596  	case "uintSlice":
   597  		name = "uints"
   598  	case "boolSlice":
   599  		name = "bools"
   600  	}
   601  
   602  	return
   603  }
   604  
   605  // Splits the string `s` on whitespace into an initial substring up to
   606  // `i` runes in length and the remainder. Will go `slop` over `i` if
   607  // that encompasses the entire string (which allows the caller to
   608  // avoid short orphan words on the final line).
   609  func wrapN(i, slop int, s string) (string, string) {
   610  	if i+slop > len(s) {
   611  		return s, ""
   612  	}
   613  
   614  	w := strings.LastIndexAny(s[:i], " \t\n")
   615  	if w <= 0 {
   616  		return s, ""
   617  	}
   618  	nlPos := strings.LastIndex(s[:i], "\n")
   619  	if nlPos > 0 && nlPos < w {
   620  		return s[:nlPos], s[nlPos+1:]
   621  	}
   622  	return s[:w], s[w+1:]
   623  }
   624  
   625  // Wraps the string `s` to a maximum width `w` with leading indent
   626  // `i`. The first line is not indented (this is assumed to be done by
   627  // caller). Pass `w` == 0 to do no wrapping
   628  func wrap(i, w int, s string) string {
   629  	if w == 0 {
   630  		return strings.Replace(s, "\n", "\n"+strings.Repeat(" ", i), -1)
   631  	}
   632  
   633  	// space between indent i and end of line width w into which
   634  	// we should wrap the text.
   635  	wrap := w - i
   636  
   637  	var r, l string
   638  
   639  	// Not enough space for sensible wrapping. Wrap as a block on
   640  	// the next line instead.
   641  	if wrap < 24 {
   642  		i = 16
   643  		wrap = w - i
   644  		r += "\n" + strings.Repeat(" ", i)
   645  	}
   646  	// If still not enough space then don't even try to wrap.
   647  	if wrap < 24 {
   648  		return strings.Replace(s, "\n", r, -1)
   649  	}
   650  
   651  	// Try to avoid short orphan words on the final line, by
   652  	// allowing wrapN to go a bit over if that would fit in the
   653  	// remainder of the line.
   654  	slop := 5
   655  	wrap = wrap - slop
   656  
   657  	// Handle first line, which is indented by the caller (or the
   658  	// special case above)
   659  	l, s = wrapN(wrap, slop, s)
   660  	r = r + strings.Replace(l, "\n", "\n"+strings.Repeat(" ", i), -1)
   661  
   662  	// Now wrap the rest
   663  	for s != "" {
   664  		var t string
   665  
   666  		t, s = wrapN(wrap, slop, s)
   667  		r = r + "\n" + strings.Repeat(" ", i) + strings.Replace(t, "\n", "\n"+strings.Repeat(" ", i), -1)
   668  	}
   669  
   670  	return r
   671  
   672  }
   673  
   674  // FlagUsagesWrapped returns a string containing the usage information
   675  // for all flags in the FlagSet. Wrapped to `cols` columns (0 for no
   676  // wrapping)
   677  func (f *FlagSet) FlagUsagesWrapped(cols int) string {
   678  	buf := new(bytes.Buffer)
   679  
   680  	lines := make([]string, 0, len(f.formal))
   681  
   682  	maxlen := 0
   683  	f.VisitAll(func(flag *Flag) {
   684  		if flag.Hidden {
   685  			return
   686  		}
   687  
   688  		line := ""
   689  		if flag.Shorthand != "" && flag.ShorthandDeprecated == "" {
   690  			line = fmt.Sprintf("  -%s, --%s", flag.Shorthand, flag.Name)
   691  		} else {
   692  			line = fmt.Sprintf("      --%s", flag.Name)
   693  		}
   694  
   695  		varname, usage := UnquoteUsage(flag)
   696  		if varname != "" {
   697  			line += " " + varname
   698  		}
   699  		if flag.NoOptDefVal != "" {
   700  			switch flag.Value.Type() {
   701  			case "string":
   702  				line += fmt.Sprintf("[=\"%s\"]", flag.NoOptDefVal)
   703  			case "bool":
   704  				if flag.NoOptDefVal != "true" {
   705  					line += fmt.Sprintf("[=%s]", flag.NoOptDefVal)
   706  				}
   707  			case "count":
   708  				if flag.NoOptDefVal != "+1" {
   709  					line += fmt.Sprintf("[=%s]", flag.NoOptDefVal)
   710  				}
   711  			default:
   712  				line += fmt.Sprintf("[=%s]", flag.NoOptDefVal)
   713  			}
   714  		}
   715  
   716  		// This special character will be replaced with spacing once the
   717  		// correct alignment is calculated
   718  		line += "\x00"
   719  		if len(line) > maxlen {
   720  			maxlen = len(line)
   721  		}
   722  
   723  		line += usage
   724  		if !flag.defaultIsZeroValue() {
   725  			if flag.Value.Type() == "string" {
   726  				line += fmt.Sprintf(" (default %q)", flag.DefValue)
   727  			} else {
   728  				line += fmt.Sprintf(" (default %s)", flag.DefValue)
   729  			}
   730  		}
   731  		if len(flag.Deprecated) != 0 {
   732  			line += fmt.Sprintf(" (DEPRECATED: %s)", flag.Deprecated)
   733  		}
   734  
   735  		lines = append(lines, line)
   736  	})
   737  
   738  	for _, line := range lines {
   739  		sidx := strings.Index(line, "\x00")
   740  		spacing := strings.Repeat(" ", maxlen-sidx)
   741  		// maxlen + 2 comes from + 1 for the \x00 and + 1 for the (deliberate) off-by-one in maxlen-sidx
   742  		fmt.Fprintln(buf, line[:sidx], spacing, wrap(maxlen+2, cols, line[sidx+1:]))
   743  	}
   744  
   745  	return buf.String()
   746  }
   747  
   748  // FlagUsages returns a string containing the usage information for all flags in
   749  // the FlagSet
   750  func (f *FlagSet) FlagUsages() string {
   751  	return f.FlagUsagesWrapped(0)
   752  }
   753  
   754  // PrintDefaults prints to standard error the default values of all defined command-line flags.
   755  func PrintDefaults() {
   756  	CommandLine.PrintDefaults()
   757  }
   758  
   759  // defaultUsage is the default function to print a usage message.
   760  func defaultUsage(f *FlagSet) {
   761  	fmt.Fprintf(f.out(), "Usage of %s:\n", f.name)
   762  	f.PrintDefaults()
   763  }
   764  
   765  // NOTE: Usage is not just defaultUsage(CommandLine)
   766  // because it serves (via godoc flag Usage) as the example
   767  // for how to write your own usage function.
   768  
   769  // Usage prints to standard error a usage message documenting all defined command-line flags.
   770  // The function is a variable that may be changed to point to a custom function.
   771  // By default it prints a simple header and calls PrintDefaults; for details about the
   772  // format of the output and how to control it, see the documentation for PrintDefaults.
   773  var Usage = func() {
   774  	fmt.Fprintf(os.Stderr, "Usage of %s:\n", os.Args[0])
   775  	PrintDefaults()
   776  }
   777  
   778  // NFlag returns the number of flags that have been set.
   779  func (f *FlagSet) NFlag() int { return len(f.actual) }
   780  
   781  // NFlag returns the number of command-line flags that have been set.
   782  func NFlag() int { return len(CommandLine.actual) }
   783  
   784  // Arg returns the i'th argument.  Arg(0) is the first remaining argument
   785  // after flags have been processed.
   786  func (f *FlagSet) Arg(i int) string {
   787  	if i < 0 || i >= len(f.args) {
   788  		return ""
   789  	}
   790  	return f.args[i]
   791  }
   792  
   793  // Arg returns the i'th command-line argument.  Arg(0) is the first remaining argument
   794  // after flags have been processed.
   795  func Arg(i int) string {
   796  	return CommandLine.Arg(i)
   797  }
   798  
   799  // NArg is the number of arguments remaining after flags have been processed.
   800  func (f *FlagSet) NArg() int { return len(f.args) }
   801  
   802  // NArg is the number of arguments remaining after flags have been processed.
   803  func NArg() int { return len(CommandLine.args) }
   804  
   805  // Args returns the non-flag arguments.
   806  func (f *FlagSet) Args() []string { return f.args }
   807  
   808  // Args returns the non-flag command-line arguments.
   809  func Args() []string { return CommandLine.args }
   810  
   811  // Var defines a flag with the specified name and usage string. The type and
   812  // value of the flag are represented by the first argument, of type Value, which
   813  // typically holds a user-defined implementation of Value. For instance, the
   814  // caller could create a flag that turns a comma-separated string into a slice
   815  // of strings by giving the slice the methods of Value; in particular, Set would
   816  // decompose the comma-separated string into the slice.
   817  func (f *FlagSet) Var(value Value, name string, usage string) {
   818  	f.VarP(value, name, "", usage)
   819  }
   820  
   821  // VarPF is like VarP, but returns the flag created
   822  func (f *FlagSet) VarPF(value Value, name, shorthand, usage string) *Flag {
   823  	// Remember the default value as a string; it won't change.
   824  	flag := &Flag{
   825  		Name:      name,
   826  		Shorthand: shorthand,
   827  		Usage:     usage,
   828  		Value:     value,
   829  		DefValue:  value.String(),
   830  	}
   831  	f.AddFlag(flag)
   832  	return flag
   833  }
   834  
   835  // VarP is like Var, but accepts a shorthand letter that can be used after a single dash.
   836  func (f *FlagSet) VarP(value Value, name, shorthand, usage string) {
   837  	f.VarPF(value, name, shorthand, usage)
   838  }
   839  
   840  // AddFlag will add the flag to the FlagSet
   841  func (f *FlagSet) AddFlag(flag *Flag) {
   842  	normalizedFlagName := f.normalizeFlagName(flag.Name)
   843  
   844  	_, alreadyThere := f.formal[normalizedFlagName]
   845  	if alreadyThere {
   846  		msg := fmt.Sprintf("%s flag redefined: %s", f.name, flag.Name)
   847  		fmt.Fprintln(f.out(), msg)
   848  		panic(msg) // Happens only if flags are declared with identical names
   849  	}
   850  	if f.formal == nil {
   851  		f.formal = make(map[NormalizedName]*Flag)
   852  	}
   853  
   854  	flag.Name = string(normalizedFlagName)
   855  	f.formal[normalizedFlagName] = flag
   856  	f.orderedFormal = append(f.orderedFormal, flag)
   857  
   858  	if flag.Shorthand == "" {
   859  		return
   860  	}
   861  	if len(flag.Shorthand) > 1 {
   862  		msg := fmt.Sprintf("%q shorthand is more than one ASCII character", flag.Shorthand)
   863  		fmt.Fprintf(f.out(), msg)
   864  		panic(msg)
   865  	}
   866  	if f.shorthands == nil {
   867  		f.shorthands = make(map[byte]*Flag)
   868  	}
   869  	c := flag.Shorthand[0]
   870  	used, alreadyThere := f.shorthands[c]
   871  	if alreadyThere {
   872  		msg := fmt.Sprintf("unable to redefine %q shorthand in %q flagset: it's already used for %q flag", c, f.name, used.Name)
   873  		fmt.Fprintf(f.out(), msg)
   874  		panic(msg)
   875  	}
   876  	f.shorthands[c] = flag
   877  }
   878  
   879  // AddFlagSet adds one FlagSet to another. If a flag is already present in f
   880  // the flag from newSet will be ignored.
   881  func (f *FlagSet) AddFlagSet(newSet *FlagSet) {
   882  	if newSet == nil {
   883  		return
   884  	}
   885  	newSet.VisitAll(func(flag *Flag) {
   886  		if f.Lookup(flag.Name) == nil {
   887  			f.AddFlag(flag)
   888  		}
   889  	})
   890  }
   891  
   892  // Var defines a flag with the specified name and usage string. The type and
   893  // value of the flag are represented by the first argument, of type Value, which
   894  // typically holds a user-defined implementation of Value. For instance, the
   895  // caller could create a flag that turns a comma-separated string into a slice
   896  // of strings by giving the slice the methods of Value; in particular, Set would
   897  // decompose the comma-separated string into the slice.
   898  func Var(value Value, name string, usage string) {
   899  	CommandLine.VarP(value, name, "", usage)
   900  }
   901  
   902  // VarP is like Var, but accepts a shorthand letter that can be used after a single dash.
   903  func VarP(value Value, name, shorthand, usage string) {
   904  	CommandLine.VarP(value, name, shorthand, usage)
   905  }
   906  
   907  // failf prints to standard error a formatted error and usage message and
   908  // returns the error.
   909  func (f *FlagSet) failf(format string, a ...interface{}) error {
   910  	err := fmt.Errorf(format, a...)
   911  	if f.errorHandling != ContinueOnError {
   912  		fmt.Fprintln(f.out(), err)
   913  		f.usage()
   914  	}
   915  	return err
   916  }
   917  
   918  // usage calls the Usage method for the flag set, or the usage function if
   919  // the flag set is CommandLine.
   920  func (f *FlagSet) usage() {
   921  	if f == CommandLine {
   922  		Usage()
   923  	} else if f.Usage == nil {
   924  		defaultUsage(f)
   925  	} else {
   926  		f.Usage()
   927  	}
   928  }
   929  
   930  //--unknown (args will be empty)
   931  //--unknown --next-flag ... (args will be --next-flag ...)
   932  //--unknown arg ... (args will be arg ...)
   933  func stripUnknownFlagValue(args []string) []string {
   934  	if len(args) == 0 {
   935  		//--unknown
   936  		return args
   937  	}
   938  
   939  	first := args[0]
   940  	if len(first) > 0 && first[0] == '-' {
   941  		//--unknown --next-flag ...
   942  		return args
   943  	}
   944  
   945  	//--unknown arg ... (args will be arg ...)
   946  	if len(args) > 1 {
   947  		return args[1:]
   948  	}
   949  	return nil
   950  }
   951  
   952  func (f *FlagSet) parseLongArg(s string, args []string, fn parseFunc) (a []string, err error) {
   953  	a = args
   954  	name := s[2:]
   955  	if len(name) == 0 || name[0] == '-' || name[0] == '=' {
   956  		err = f.failf("bad flag syntax: %s", s)
   957  		return
   958  	}
   959  
   960  	split := strings.SplitN(name, "=", 2)
   961  	name = split[0]
   962  	flag, exists := f.formal[f.normalizeFlagName(name)]
   963  
   964  	if !exists {
   965  		switch {
   966  		case name == "help":
   967  			f.usage()
   968  			return a, ErrHelp
   969  		case f.ParseErrorsWhitelist.UnknownFlags:
   970  			// --unknown=unknownval arg ...
   971  			// we do not want to lose arg in this case
   972  			if len(split) >= 2 {
   973  				return a, nil
   974  			}
   975  
   976  			return stripUnknownFlagValue(a), nil
   977  		default:
   978  			err = f.failf("unknown flag: --%s", name)
   979  			return
   980  		}
   981  	}
   982  
   983  	var value string
   984  	if len(split) == 2 {
   985  		// '--flag=arg'
   986  		value = split[1]
   987  	} else if flag.NoOptDefVal != "" {
   988  		// '--flag' (arg was optional)
   989  		value = flag.NoOptDefVal
   990  	} else if len(a) > 0 {
   991  		// '--flag arg'
   992  		value = a[0]
   993  		a = a[1:]
   994  	} else {
   995  		// '--flag' (arg was required)
   996  		err = f.failf("flag needs an argument: %s", s)
   997  		return
   998  	}
   999  
  1000  	err = fn(flag, value)
  1001  	if err != nil {
  1002  		f.failf(err.Error())
  1003  	}
  1004  	return
  1005  }
  1006  
  1007  func (f *FlagSet) parseSingleShortArg(shorthands string, args []string, fn parseFunc) (outShorts string, outArgs []string, err error) {
  1008  	outArgs = args
  1009  
  1010  	if strings.HasPrefix(shorthands, "test.") {
  1011  		return
  1012  	}
  1013  
  1014  	outShorts = shorthands[1:]
  1015  	c := shorthands[0]
  1016  
  1017  	flag, exists := f.shorthands[c]
  1018  	if !exists {
  1019  		switch {
  1020  		case c == 'h':
  1021  			f.usage()
  1022  			err = ErrHelp
  1023  			return
  1024  		case f.ParseErrorsWhitelist.UnknownFlags:
  1025  			// '-f=arg arg ...'
  1026  			// we do not want to lose arg in this case
  1027  			if len(shorthands) > 2 && shorthands[1] == '=' {
  1028  				outShorts = ""
  1029  				return
  1030  			}
  1031  
  1032  			outArgs = stripUnknownFlagValue(outArgs)
  1033  			return
  1034  		default:
  1035  			err = f.failf("unknown shorthand flag: %q in -%s", c, shorthands)
  1036  			return
  1037  		}
  1038  	}
  1039  
  1040  	var value string
  1041  	if len(shorthands) > 2 && shorthands[1] == '=' {
  1042  		// '-f=arg'
  1043  		value = shorthands[2:]
  1044  		outShorts = ""
  1045  	} else if flag.NoOptDefVal != "" {
  1046  		// '-f' (arg was optional)
  1047  		value = flag.NoOptDefVal
  1048  	} else if len(shorthands) > 1 {
  1049  		// '-farg'
  1050  		value = shorthands[1:]
  1051  		outShorts = ""
  1052  	} else if len(args) > 0 {
  1053  		// '-f arg'
  1054  		value = args[0]
  1055  		outArgs = args[1:]
  1056  	} else {
  1057  		// '-f' (arg was required)
  1058  		err = f.failf("flag needs an argument: %q in -%s", c, shorthands)
  1059  		return
  1060  	}
  1061  
  1062  	if flag.ShorthandDeprecated != "" {
  1063  		fmt.Fprintf(f.out(), "Flag shorthand -%s has been deprecated, %s\n", flag.Shorthand, flag.ShorthandDeprecated)
  1064  	}
  1065  
  1066  	err = fn(flag, value)
  1067  	if err != nil {
  1068  		f.failf(err.Error())
  1069  	}
  1070  	return
  1071  }
  1072  
  1073  func (f *FlagSet) parseShortArg(s string, args []string, fn parseFunc) (a []string, err error) {
  1074  	a = args
  1075  	shorthands := s[1:]
  1076  
  1077  	// "shorthands" can be a series of shorthand letters of flags (e.g. "-vvv").
  1078  	for len(shorthands) > 0 {
  1079  		shorthands, a, err = f.parseSingleShortArg(shorthands, args, fn)
  1080  		if err != nil {
  1081  			return
  1082  		}
  1083  	}
  1084  
  1085  	return
  1086  }
  1087  
  1088  func (f *FlagSet) parseArgs(args []string, fn parseFunc) (err error) {
  1089  	for len(args) > 0 {
  1090  		s := args[0]
  1091  		args = args[1:]
  1092  		if len(s) == 0 || s[0] != '-' || len(s) == 1 {
  1093  			if !f.interspersed {
  1094  				f.args = append(f.args, s)
  1095  				f.args = append(f.args, args...)
  1096  				return nil
  1097  			}
  1098  			f.args = append(f.args, s)
  1099  			continue
  1100  		}
  1101  
  1102  		if s[1] == '-' {
  1103  			if len(s) == 2 { // "--" terminates the flags
  1104  				f.argsLenAtDash = len(f.args)
  1105  				f.args = append(f.args, args...)
  1106  				break
  1107  			}
  1108  			args, err = f.parseLongArg(s, args, fn)
  1109  		} else {
  1110  			args, err = f.parseShortArg(s, args, fn)
  1111  		}
  1112  		if err != nil {
  1113  			return
  1114  		}
  1115  	}
  1116  	return
  1117  }
  1118  
  1119  // Parse parses flag definitions from the argument list, which should not
  1120  // include the command name.  Must be called after all flags in the FlagSet
  1121  // are defined and before flags are accessed by the program.
  1122  // The return value will be ErrHelp if -help was set but not defined.
  1123  func (f *FlagSet) Parse(arguments []string) error {
  1124  	if f.addedGoFlagSets != nil {
  1125  		for _, goFlagSet := range f.addedGoFlagSets {
  1126  			goFlagSet.Parse(nil)
  1127  		}
  1128  	}
  1129  	f.parsed = true
  1130  
  1131  	if len(arguments) < 0 {
  1132  		return nil
  1133  	}
  1134  
  1135  	f.args = make([]string, 0, len(arguments))
  1136  
  1137  	set := func(flag *Flag, value string) error {
  1138  		return f.Set(flag.Name, value)
  1139  	}
  1140  
  1141  	err := f.parseArgs(arguments, set)
  1142  	if err != nil {
  1143  		switch f.errorHandling {
  1144  		case ContinueOnError:
  1145  			return err
  1146  		case ExitOnError:
  1147  			fmt.Println(err)
  1148  			os.Exit(2)
  1149  		case PanicOnError:
  1150  			panic(err)
  1151  		}
  1152  	}
  1153  	return nil
  1154  }
  1155  
  1156  type parseFunc func(flag *Flag, value string) error
  1157  
  1158  // ParseAll parses flag definitions from the argument list, which should not
  1159  // include the command name. The arguments for fn are flag and value. Must be
  1160  // called after all flags in the FlagSet are defined and before flags are
  1161  // accessed by the program. The return value will be ErrHelp if -help was set
  1162  // but not defined.
  1163  func (f *FlagSet) ParseAll(arguments []string, fn func(flag *Flag, value string) error) error {
  1164  	f.parsed = true
  1165  	f.args = make([]string, 0, len(arguments))
  1166  
  1167  	err := f.parseArgs(arguments, fn)
  1168  	if err != nil {
  1169  		switch f.errorHandling {
  1170  		case ContinueOnError:
  1171  			return err
  1172  		case ExitOnError:
  1173  			os.Exit(2)
  1174  		case PanicOnError:
  1175  			panic(err)
  1176  		}
  1177  	}
  1178  	return nil
  1179  }
  1180  
  1181  // Parsed reports whether f.Parse has been called.
  1182  func (f *FlagSet) Parsed() bool {
  1183  	return f.parsed
  1184  }
  1185  
  1186  // Parse parses the command-line flags from os.Args[1:].  Must be called
  1187  // after all flags are defined and before flags are accessed by the program.
  1188  func Parse() {
  1189  	// Ignore errors; CommandLine is set for ExitOnError.
  1190  	CommandLine.Parse(os.Args[1:])
  1191  }
  1192  
  1193  // ParseAll parses the command-line flags from os.Args[1:] and called fn for each.
  1194  // The arguments for fn are flag and value. Must be called after all flags are
  1195  // defined and before flags are accessed by the program.
  1196  func ParseAll(fn func(flag *Flag, value string) error) {
  1197  	// Ignore errors; CommandLine is set for ExitOnError.
  1198  	CommandLine.ParseAll(os.Args[1:], fn)
  1199  }
  1200  
  1201  // SetInterspersed sets whether to support interspersed option/non-option arguments.
  1202  func SetInterspersed(interspersed bool) {
  1203  	CommandLine.SetInterspersed(interspersed)
  1204  }
  1205  
  1206  // Parsed returns true if the command-line flags have been parsed.
  1207  func Parsed() bool {
  1208  	return CommandLine.Parsed()
  1209  }
  1210  
  1211  // CommandLine is the default set of command-line flags, parsed from os.Args.
  1212  var CommandLine = NewFlagSet(os.Args[0], ExitOnError)
  1213  
  1214  // NewFlagSet returns a new, empty flag set with the specified name,
  1215  // error handling property and SortFlags set to true.
  1216  func NewFlagSet(name string, errorHandling ErrorHandling) *FlagSet {
  1217  	f := &FlagSet{
  1218  		name:          name,
  1219  		errorHandling: errorHandling,
  1220  		argsLenAtDash: -1,
  1221  		interspersed:  true,
  1222  		SortFlags:     true,
  1223  	}
  1224  	return f
  1225  }
  1226  
  1227  // SetInterspersed sets whether to support interspersed option/non-option arguments.
  1228  func (f *FlagSet) SetInterspersed(interspersed bool) {
  1229  	f.interspersed = interspersed
  1230  }
  1231  
  1232  // Init sets the name and error handling property for a flag set.
  1233  // By default, the zero FlagSet uses an empty name and the
  1234  // ContinueOnError error handling policy.
  1235  func (f *FlagSet) Init(name string, errorHandling ErrorHandling) {
  1236  	f.name = name
  1237  	f.errorHandling = errorHandling
  1238  	f.argsLenAtDash = -1
  1239  }
  1240  

View as plain text