Source file src/pkg/flag/flag.go

     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 after the flag are available as the
    35		slice flag.Args() or individually as flag.Arg(i).
    36		The arguments are indexed from 0 up to flag.NArg().
    37	
    38		Command line flag syntax:
    39			-flag
    40			-flag=x
    41			-flag x  // non-boolean flags only
    42		One or two minus signs may be used; they are equivalent.
    43		The last form is not permitted for boolean flags because the
    44		meaning of the command
    45			cmd -x *
    46		will change if there is a file called 0, false, etc.  You must
    47		use the -flag=false form to turn off a boolean flag.
    48	
    49		Flag parsing stops just before the first non-flag argument
    50		("-" is a non-flag argument) or after the terminator "--".
    51	
    52		Integer flags accept 1234, 0664, 0x1234 and may be negative.
    53		Boolean flags may be 1, 0, t, f, true, false, TRUE, FALSE, True, False.
    54		Duration flags accept any input valid for time.ParseDuration.
    55	
    56		The default set of command-line flags is controlled by
    57		top-level functions.  The FlagSet type allows one to define
    58		independent sets of flags, such as to implement subcommands
    59		in a command-line interface. The methods of FlagSet are
    60		analogous to the top-level functions for the command-line
    61		flag set.
    62	*/
    63	package flag
    64	
    65	import (
    66		"errors"
    67		"fmt"
    68		"io"
    69		"os"
    70		"sort"
    71		"strconv"
    72		"time"
    73	)
    74	
    75	// ErrHelp is the error returned if the flag -help is invoked but no such flag is defined.
    76	var ErrHelp = errors.New("flag: help requested")
    77	
    78	// -- bool Value
    79	type boolValue bool
    80	
    81	func newBoolValue(val bool, p *bool) *boolValue {
    82		*p = val
    83		return (*boolValue)(p)
    84	}
    85	
    86	func (b *boolValue) Set(s string) error {
    87		v, err := strconv.ParseBool(s)
    88		*b = boolValue(v)
    89		return err
    90	}
    91	
    92	func (b *boolValue) String() string { return fmt.Sprintf("%v", *b) }
    93	
    94	// -- int Value
    95	type intValue int
    96	
    97	func newIntValue(val int, p *int) *intValue {
    98		*p = val
    99		return (*intValue)(p)
   100	}
   101	
   102	func (i *intValue) Set(s string) error {
   103		v, err := strconv.ParseInt(s, 0, 64)
   104		*i = intValue(v)
   105		return err
   106	}
   107	
   108	func (i *intValue) String() string { return fmt.Sprintf("%v", *i) }
   109	
   110	// -- int64 Value
   111	type int64Value int64
   112	
   113	func newInt64Value(val int64, p *int64) *int64Value {
   114		*p = val
   115		return (*int64Value)(p)
   116	}
   117	
   118	func (i *int64Value) Set(s string) error {
   119		v, err := strconv.ParseInt(s, 0, 64)
   120		*i = int64Value(v)
   121		return err
   122	}
   123	
   124	func (i *int64Value) String() string { return fmt.Sprintf("%v", *i) }
   125	
   126	// -- uint Value
   127	type uintValue uint
   128	
   129	func newUintValue(val uint, p *uint) *uintValue {
   130		*p = val
   131		return (*uintValue)(p)
   132	}
   133	
   134	func (i *uintValue) Set(s string) error {
   135		v, err := strconv.ParseUint(s, 0, 64)
   136		*i = uintValue(v)
   137		return err
   138	}
   139	
   140	func (i *uintValue) String() string { return fmt.Sprintf("%v", *i) }
   141	
   142	// -- uint64 Value
   143	type uint64Value uint64
   144	
   145	func newUint64Value(val uint64, p *uint64) *uint64Value {
   146		*p = val
   147		return (*uint64Value)(p)
   148	}
   149	
   150	func (i *uint64Value) Set(s string) error {
   151		v, err := strconv.ParseUint(s, 0, 64)
   152		*i = uint64Value(v)
   153		return err
   154	}
   155	
   156	func (i *uint64Value) String() string { return fmt.Sprintf("%v", *i) }
   157	
   158	// -- string Value
   159	type stringValue string
   160	
   161	func newStringValue(val string, p *string) *stringValue {
   162		*p = val
   163		return (*stringValue)(p)
   164	}
   165	
   166	func (s *stringValue) Set(val string) error {
   167		*s = stringValue(val)
   168		return nil
   169	}
   170	
   171	func (s *stringValue) String() string { return fmt.Sprintf("%s", *s) }
   172	
   173	// -- float64 Value
   174	type float64Value float64
   175	
   176	func newFloat64Value(val float64, p *float64) *float64Value {
   177		*p = val
   178		return (*float64Value)(p)
   179	}
   180	
   181	func (f *float64Value) Set(s string) error {
   182		v, err := strconv.ParseFloat(s, 64)
   183		*f = float64Value(v)
   184		return err
   185	}
   186	
   187	func (f *float64Value) String() string { return fmt.Sprintf("%v", *f) }
   188	
   189	// -- time.Duration Value
   190	type durationValue time.Duration
   191	
   192	func newDurationValue(val time.Duration, p *time.Duration) *durationValue {
   193		*p = val
   194		return (*durationValue)(p)
   195	}
   196	
   197	func (d *durationValue) Set(s string) error {
   198		v, err := time.ParseDuration(s)
   199		*d = durationValue(v)
   200		return err
   201	}
   202	
   203	func (d *durationValue) String() string { return (*time.Duration)(d).String() }
   204	
   205	// Value is the interface to the dynamic value stored in a flag.
   206	// (The default value is represented as a string.)
   207	type Value interface {
   208		String() string
   209		Set(string) error
   210	}
   211	
   212	// ErrorHandling defines how to handle flag parsing errors.
   213	type ErrorHandling int
   214	
   215	const (
   216		ContinueOnError ErrorHandling = iota
   217		ExitOnError
   218		PanicOnError
   219	)
   220	
   221	// A FlagSet represents a set of defined flags.
   222	type FlagSet struct {
   223		// Usage is the function called when an error occurs while parsing flags.
   224		// The field is a function (not a method) that may be changed to point to
   225		// a custom error handler.
   226		Usage func()
   227	
   228		name          string
   229		parsed        bool
   230		actual        map[string]*Flag
   231		formal        map[string]*Flag
   232		args          []string // arguments after flags
   233		exitOnError   bool     // does the program exit if there's an error?
   234		errorHandling ErrorHandling
   235		output        io.Writer // nil means stderr; use out() accessor
   236	}
   237	
   238	// A Flag represents the state of a flag.
   239	type Flag struct {
   240		Name     string // name as it appears on command line
   241		Usage    string // help message
   242		Value    Value  // value as set
   243		DefValue string // default value (as text); for usage message
   244	}
   245	
   246	// sortFlags returns the flags as a slice in lexicographical sorted order.
   247	func sortFlags(flags map[string]*Flag) []*Flag {
   248		list := make(sort.StringSlice, len(flags))
   249		i := 0
   250		for _, f := range flags {
   251			list[i] = f.Name
   252			i++
   253		}
   254		list.Sort()
   255		result := make([]*Flag, len(list))
   256		for i, name := range list {
   257			result[i] = flags[name]
   258		}
   259		return result
   260	}
   261	
   262	func (f *FlagSet) out() io.Writer {
   263		if f.output == nil {
   264			return os.Stderr
   265		}
   266		return f.output
   267	}
   268	
   269	// SetOutput sets the destination for usage and error messages.
   270	// If output is nil, os.Stderr is used.
   271	func (f *FlagSet) SetOutput(output io.Writer) {
   272		f.output = output
   273	}
   274	
   275	// VisitAll visits the flags in lexicographical order, calling fn for each.
   276	// It visits all flags, even those not set.
   277	func (f *FlagSet) VisitAll(fn func(*Flag)) {
   278		for _, flag := range sortFlags(f.formal) {
   279			fn(flag)
   280		}
   281	}
   282	
   283	// VisitAll visits the command-line flags in lexicographical order, calling
   284	// fn for each.  It visits all flags, even those not set.
   285	func VisitAll(fn func(*Flag)) {
   286		commandLine.VisitAll(fn)
   287	}
   288	
   289	// Visit visits the flags in lexicographical order, calling fn for each.
   290	// It visits only those flags that have been set.
   291	func (f *FlagSet) Visit(fn func(*Flag)) {
   292		for _, flag := range sortFlags(f.actual) {
   293			fn(flag)
   294		}
   295	}
   296	
   297	// Visit visits the command-line flags in lexicographical order, calling fn
   298	// for each.  It visits only those flags that have been set.
   299	func Visit(fn func(*Flag)) {
   300		commandLine.Visit(fn)
   301	}
   302	
   303	// Lookup returns the Flag structure of the named flag, returning nil if none exists.
   304	func (f *FlagSet) Lookup(name string) *Flag {
   305		return f.formal[name]
   306	}
   307	
   308	// Lookup returns the Flag structure of the named command-line flag,
   309	// returning nil if none exists.
   310	func Lookup(name string) *Flag {
   311		return commandLine.formal[name]
   312	}
   313	
   314	// Set sets the value of the named flag.
   315	func (f *FlagSet) Set(name, value string) error {
   316		flag, ok := f.formal[name]
   317		if !ok {
   318			return fmt.Errorf("no such flag -%v", name)
   319		}
   320		err := flag.Value.Set(value)
   321		if err != nil {
   322			return err
   323		}
   324		if f.actual == nil {
   325			f.actual = make(map[string]*Flag)
   326		}
   327		f.actual[name] = flag
   328		return nil
   329	}
   330	
   331	// Set sets the value of the named command-line flag.
   332	func Set(name, value string) error {
   333		return commandLine.Set(name, value)
   334	}
   335	
   336	// PrintDefaults prints, to standard error unless configured
   337	// otherwise, the default values of all defined flags in the set.
   338	func (f *FlagSet) PrintDefaults() {
   339		f.VisitAll(func(flag *Flag) {
   340			format := "  -%s=%s: %s\n"
   341			if _, ok := flag.Value.(*stringValue); ok {
   342				// put quotes on the value
   343				format = "  -%s=%q: %s\n"
   344			}
   345			fmt.Fprintf(f.out(), format, flag.Name, flag.DefValue, flag.Usage)
   346		})
   347	}
   348	
   349	// PrintDefaults prints to standard error the default values of all defined command-line flags.
   350	func PrintDefaults() {
   351		commandLine.PrintDefaults()
   352	}
   353	
   354	// defaultUsage is the default function to print a usage message.
   355	func defaultUsage(f *FlagSet) {
   356		fmt.Fprintf(f.out(), "Usage of %s:\n", f.name)
   357		f.PrintDefaults()
   358	}
   359	
   360	// NOTE: Usage is not just defaultUsage(commandLine)
   361	// because it serves (via godoc flag Usage) as the example
   362	// for how to write your own usage function.
   363	
   364	// Usage prints to standard error a usage message documenting all defined command-line flags.
   365	// The function is a variable that may be changed to point to a custom function.
   366	var Usage = func() {
   367		fmt.Fprintf(os.Stderr, "Usage of %s:\n", os.Args[0])
   368		PrintDefaults()
   369	}
   370	
   371	// NFlag returns the number of flags that have been set.
   372	func (f *FlagSet) NFlag() int { return len(f.actual) }
   373	
   374	// NFlag returns the number of command-line flags that have been set.
   375	func NFlag() int { return len(commandLine.actual) }
   376	
   377	// Arg returns the i'th argument.  Arg(0) is the first remaining argument
   378	// after flags have been processed.
   379	func (f *FlagSet) Arg(i int) string {
   380		if i < 0 || i >= len(f.args) {
   381			return ""
   382		}
   383		return f.args[i]
   384	}
   385	
   386	// Arg returns the i'th command-line argument.  Arg(0) is the first remaining argument
   387	// after flags have been processed.
   388	func Arg(i int) string {
   389		return commandLine.Arg(i)
   390	}
   391	
   392	// NArg is the number of arguments remaining after flags have been processed.
   393	func (f *FlagSet) NArg() int { return len(f.args) }
   394	
   395	// NArg is the number of arguments remaining after flags have been processed.
   396	func NArg() int { return len(commandLine.args) }
   397	
   398	// Args returns the non-flag arguments.
   399	func (f *FlagSet) Args() []string { return f.args }
   400	
   401	// Args returns the non-flag command-line arguments.
   402	func Args() []string { return commandLine.args }
   403	
   404	// BoolVar defines a bool flag with specified name, default value, and usage string.
   405	// The argument p points to a bool variable in which to store the value of the flag.
   406	func (f *FlagSet) BoolVar(p *bool, name string, value bool, usage string) {
   407		f.Var(newBoolValue(value, p), name, usage)
   408	}
   409	
   410	// BoolVar defines a bool flag with specified name, default value, and usage string.
   411	// The argument p points to a bool variable in which to store the value of the flag.
   412	func BoolVar(p *bool, name string, value bool, usage string) {
   413		commandLine.Var(newBoolValue(value, p), name, usage)
   414	}
   415	
   416	// Bool defines a bool flag with specified name, default value, and usage string.
   417	// The return value is the address of a bool variable that stores the value of the flag.
   418	func (f *FlagSet) Bool(name string, value bool, usage string) *bool {
   419		p := new(bool)
   420		f.BoolVar(p, name, value, usage)
   421		return p
   422	}
   423	
   424	// Bool defines a bool flag with specified name, default value, and usage string.
   425	// The return value is the address of a bool variable that stores the value of the flag.
   426	func Bool(name string, value bool, usage string) *bool {
   427		return commandLine.Bool(name, value, usage)
   428	}
   429	
   430	// IntVar defines an int flag with specified name, default value, and usage string.
   431	// The argument p points to an int variable in which to store the value of the flag.
   432	func (f *FlagSet) IntVar(p *int, name string, value int, usage string) {
   433		f.Var(newIntValue(value, p), name, usage)
   434	}
   435	
   436	// IntVar defines an int flag with specified name, default value, and usage string.
   437	// The argument p points to an int variable in which to store the value of the flag.
   438	func IntVar(p *int, name string, value int, usage string) {
   439		commandLine.Var(newIntValue(value, p), name, usage)
   440	}
   441	
   442	// Int defines an int flag with specified name, default value, and usage string.
   443	// The return value is the address of an int variable that stores the value of the flag.
   444	func (f *FlagSet) Int(name string, value int, usage string) *int {
   445		p := new(int)
   446		f.IntVar(p, name, value, usage)
   447		return p
   448	}
   449	
   450	// Int defines an int flag with specified name, default value, and usage string.
   451	// The return value is the address of an int variable that stores the value of the flag.
   452	func Int(name string, value int, usage string) *int {
   453		return commandLine.Int(name, value, usage)
   454	}
   455	
   456	// Int64Var defines an int64 flag with specified name, default value, and usage string.
   457	// The argument p points to an int64 variable in which to store the value of the flag.
   458	func (f *FlagSet) Int64Var(p *int64, name string, value int64, usage string) {
   459		f.Var(newInt64Value(value, p), name, usage)
   460	}
   461	
   462	// Int64Var defines an int64 flag with specified name, default value, and usage string.
   463	// The argument p points to an int64 variable in which to store the value of the flag.
   464	func Int64Var(p *int64, name string, value int64, usage string) {
   465		commandLine.Var(newInt64Value(value, p), name, usage)
   466	}
   467	
   468	// Int64 defines an int64 flag with specified name, default value, and usage string.
   469	// The return value is the address of an int64 variable that stores the value of the flag.
   470	func (f *FlagSet) Int64(name string, value int64, usage string) *int64 {
   471		p := new(int64)
   472		f.Int64Var(p, name, value, usage)
   473		return p
   474	}
   475	
   476	// Int64 defines an int64 flag with specified name, default value, and usage string.
   477	// The return value is the address of an int64 variable that stores the value of the flag.
   478	func Int64(name string, value int64, usage string) *int64 {
   479		return commandLine.Int64(name, value, usage)
   480	}
   481	
   482	// UintVar defines a uint flag with specified name, default value, and usage string.
   483	// The argument p points to a uint variable in which to store the value of the flag.
   484	func (f *FlagSet) UintVar(p *uint, name string, value uint, usage string) {
   485		f.Var(newUintValue(value, p), name, usage)
   486	}
   487	
   488	// UintVar defines a uint flag with specified name, default value, and usage string.
   489	// The argument p points to a uint  variable in which to store the value of the flag.
   490	func UintVar(p *uint, name string, value uint, usage string) {
   491		commandLine.Var(newUintValue(value, p), name, usage)
   492	}
   493	
   494	// Uint defines a uint flag with specified name, default value, and usage string.
   495	// The return value is the address of a uint  variable that stores the value of the flag.
   496	func (f *FlagSet) Uint(name string, value uint, usage string) *uint {
   497		p := new(uint)
   498		f.UintVar(p, name, value, usage)
   499		return p
   500	}
   501	
   502	// Uint defines a uint flag with specified name, default value, and usage string.
   503	// The return value is the address of a uint  variable that stores the value of the flag.
   504	func Uint(name string, value uint, usage string) *uint {
   505		return commandLine.Uint(name, value, usage)
   506	}
   507	
   508	// Uint64Var defines a uint64 flag with specified name, default value, and usage string.
   509	// The argument p points to a uint64 variable in which to store the value of the flag.
   510	func (f *FlagSet) Uint64Var(p *uint64, name string, value uint64, usage string) {
   511		f.Var(newUint64Value(value, p), name, usage)
   512	}
   513	
   514	// Uint64Var defines a uint64 flag with specified name, default value, and usage string.
   515	// The argument p points to a uint64 variable in which to store the value of the flag.
   516	func Uint64Var(p *uint64, name string, value uint64, usage string) {
   517		commandLine.Var(newUint64Value(value, p), name, usage)
   518	}
   519	
   520	// Uint64 defines a uint64 flag with specified name, default value, and usage string.
   521	// The return value is the address of a uint64 variable that stores the value of the flag.
   522	func (f *FlagSet) Uint64(name string, value uint64, usage string) *uint64 {
   523		p := new(uint64)
   524		f.Uint64Var(p, name, value, usage)
   525		return p
   526	}
   527	
   528	// Uint64 defines a uint64 flag with specified name, default value, and usage string.
   529	// The return value is the address of a uint64 variable that stores the value of the flag.
   530	func Uint64(name string, value uint64, usage string) *uint64 {
   531		return commandLine.Uint64(name, value, usage)
   532	}
   533	
   534	// StringVar defines a string flag with specified name, default value, and usage string.
   535	// The argument p points to a string variable in which to store the value of the flag.
   536	func (f *FlagSet) StringVar(p *string, name string, value string, usage string) {
   537		f.Var(newStringValue(value, p), name, usage)
   538	}
   539	
   540	// StringVar defines a string flag with specified name, default value, and usage string.
   541	// The argument p points to a string variable in which to store the value of the flag.
   542	func StringVar(p *string, name string, value string, usage string) {
   543		commandLine.Var(newStringValue(value, p), name, usage)
   544	}
   545	
   546	// String defines a string flag with specified name, default value, and usage string.
   547	// The return value is the address of a string variable that stores the value of the flag.
   548	func (f *FlagSet) String(name string, value string, usage string) *string {
   549		p := new(string)
   550		f.StringVar(p, name, value, usage)
   551		return p
   552	}
   553	
   554	// String defines a string flag with specified name, default value, and usage string.
   555	// The return value is the address of a string variable that stores the value of the flag.
   556	func String(name string, value string, usage string) *string {
   557		return commandLine.String(name, value, usage)
   558	}
   559	
   560	// Float64Var defines a float64 flag with specified name, default value, and usage string.
   561	// The argument p points to a float64 variable in which to store the value of the flag.
   562	func (f *FlagSet) Float64Var(p *float64, name string, value float64, usage string) {
   563		f.Var(newFloat64Value(value, p), name, usage)
   564	}
   565	
   566	// Float64Var defines a float64 flag with specified name, default value, and usage string.
   567	// The argument p points to a float64 variable in which to store the value of the flag.
   568	func Float64Var(p *float64, name string, value float64, usage string) {
   569		commandLine.Var(newFloat64Value(value, p), name, usage)
   570	}
   571	
   572	// Float64 defines a float64 flag with specified name, default value, and usage string.
   573	// The return value is the address of a float64 variable that stores the value of the flag.
   574	func (f *FlagSet) Float64(name string, value float64, usage string) *float64 {
   575		p := new(float64)
   576		f.Float64Var(p, name, value, usage)
   577		return p
   578	}
   579	
   580	// Float64 defines a float64 flag with specified name, default value, and usage string.
   581	// The return value is the address of a float64 variable that stores the value of the flag.
   582	func Float64(name string, value float64, usage string) *float64 {
   583		return commandLine.Float64(name, value, usage)
   584	}
   585	
   586	// DurationVar defines a time.Duration flag with specified name, default value, and usage string.
   587	// The argument p points to a time.Duration variable in which to store the value of the flag.
   588	func (f *FlagSet) DurationVar(p *time.Duration, name string, value time.Duration, usage string) {
   589		f.Var(newDurationValue(value, p), name, usage)
   590	}
   591	
   592	// DurationVar defines a time.Duration flag with specified name, default value, and usage string.
   593	// The argument p points to a time.Duration variable in which to store the value of the flag.
   594	func DurationVar(p *time.Duration, name string, value time.Duration, usage string) {
   595		commandLine.Var(newDurationValue(value, p), name, usage)
   596	}
   597	
   598	// Duration defines a time.Duration flag with specified name, default value, and usage string.
   599	// The return value is the address of a time.Duration variable that stores the value of the flag.
   600	func (f *FlagSet) Duration(name string, value time.Duration, usage string) *time.Duration {
   601		p := new(time.Duration)
   602		f.DurationVar(p, name, value, usage)
   603		return p
   604	}
   605	
   606	// Duration defines a time.Duration flag with specified name, default value, and usage string.
   607	// The return value is the address of a time.Duration variable that stores the value of the flag.
   608	func Duration(name string, value time.Duration, usage string) *time.Duration {
   609		return commandLine.Duration(name, value, usage)
   610	}
   611	
   612	// Var defines a flag with the specified name and usage string. The type and
   613	// value of the flag are represented by the first argument, of type Value, which
   614	// typically holds a user-defined implementation of Value. For instance, the
   615	// caller could create a flag that turns a comma-separated string into a slice
   616	// of strings by giving the slice the methods of Value; in particular, Set would
   617	// decompose the comma-separated string into the slice.
   618	func (f *FlagSet) Var(value Value, name string, usage string) {
   619		// Remember the default value as a string; it won't change.
   620		flag := &Flag{name, usage, value, value.String()}
   621		_, alreadythere := f.formal[name]
   622		if alreadythere {
   623			fmt.Fprintf(f.out(), "%s flag redefined: %s\n", f.name, name)
   624			panic("flag redefinition") // Happens only if flags are declared with identical names
   625		}
   626		if f.formal == nil {
   627			f.formal = make(map[string]*Flag)
   628		}
   629		f.formal[name] = flag
   630	}
   631	
   632	// Var defines a flag with the specified name and usage string. The type and
   633	// value of the flag are represented by the first argument, of type Value, which
   634	// typically holds a user-defined implementation of Value. For instance, the
   635	// caller could create a flag that turns a comma-separated string into a slice
   636	// of strings by giving the slice the methods of Value; in particular, Set would
   637	// decompose the comma-separated string into the slice.
   638	func Var(value Value, name string, usage string) {
   639		commandLine.Var(value, name, usage)
   640	}
   641	
   642	// failf prints to standard error a formatted error and usage message and
   643	// returns the error.
   644	func (f *FlagSet) failf(format string, a ...interface{}) error {
   645		err := fmt.Errorf(format, a...)
   646		fmt.Fprintln(f.out(), err)
   647		f.usage()
   648		return err
   649	}
   650	
   651	// usage calls the Usage method for the flag set, or the usage function if
   652	// the flag set is commandLine.
   653	func (f *FlagSet) usage() {
   654		if f == commandLine {
   655			Usage()
   656		} else if f.Usage == nil {
   657			defaultUsage(f)
   658		} else {
   659			f.Usage()
   660		}
   661	}
   662	
   663	// parseOne parses one flag. It returns whether a flag was seen.
   664	func (f *FlagSet) parseOne() (bool, error) {
   665		if len(f.args) == 0 {
   666			return false, nil
   667		}
   668		s := f.args[0]
   669		if len(s) == 0 || s[0] != '-' || len(s) == 1 {
   670			return false, nil
   671		}
   672		num_minuses := 1
   673		if s[1] == '-' {
   674			num_minuses++
   675			if len(s) == 2 { // "--" terminates the flags
   676				f.args = f.args[1:]
   677				return false, nil
   678			}
   679		}
   680		name := s[num_minuses:]
   681		if len(name) == 0 || name[0] == '-' || name[0] == '=' {
   682			return false, f.failf("bad flag syntax: %s", s)
   683		}
   684	
   685		// it's a flag. does it have an argument?
   686		f.args = f.args[1:]
   687		has_value := false
   688		value := ""
   689		for i := 1; i < len(name); i++ { // equals cannot be first
   690			if name[i] == '=' {
   691				value = name[i+1:]
   692				has_value = true
   693				name = name[0:i]
   694				break
   695			}
   696		}
   697		m := f.formal
   698		flag, alreadythere := m[name] // BUG
   699		if !alreadythere {
   700			if name == "help" || name == "h" { // special case for nice help message.
   701				f.usage()
   702				return false, ErrHelp
   703			}
   704			return false, f.failf("flag provided but not defined: -%s", name)
   705		}
   706		if fv, ok := flag.Value.(*boolValue); ok { // special case: doesn't need an arg
   707			if has_value {
   708				if err := fv.Set(value); err != nil {
   709					f.failf("invalid boolean value %q for  -%s: %v", value, name, err)
   710				}
   711			} else {
   712				fv.Set("true")
   713			}
   714		} else {
   715			// It must have a value, which might be the next argument.
   716			if !has_value && len(f.args) > 0 {
   717				// value is the next arg
   718				has_value = true
   719				value, f.args = f.args[0], f.args[1:]
   720			}
   721			if !has_value {
   722				return false, f.failf("flag needs an argument: -%s", name)
   723			}
   724			if err := flag.Value.Set(value); err != nil {
   725				return false, f.failf("invalid value %q for flag -%s: %v", value, name, err)
   726			}
   727		}
   728		if f.actual == nil {
   729			f.actual = make(map[string]*Flag)
   730		}
   731		f.actual[name] = flag
   732		return true, nil
   733	}
   734	
   735	// Parse parses flag definitions from the argument list, which should not
   736	// include the command name.  Must be called after all flags in the FlagSet
   737	// are defined and before flags are accessed by the program.
   738	// The return value will be ErrHelp if -help was set but not defined.
   739	func (f *FlagSet) Parse(arguments []string) error {
   740		f.parsed = true
   741		f.args = arguments
   742		for {
   743			seen, err := f.parseOne()
   744			if seen {
   745				continue
   746			}
   747			if err == nil {
   748				break
   749			}
   750			switch f.errorHandling {
   751			case ContinueOnError:
   752				return err
   753			case ExitOnError:
   754				os.Exit(2)
   755			case PanicOnError:
   756				panic(err)
   757			}
   758		}
   759		return nil
   760	}
   761	
   762	// Parsed reports whether f.Parse has been called.
   763	func (f *FlagSet) Parsed() bool {
   764		return f.parsed
   765	}
   766	
   767	// Parse parses the command-line flags from os.Args[1:].  Must be called
   768	// after all flags are defined and before flags are accessed by the program.
   769	func Parse() {
   770		// Ignore errors; commandLine is set for ExitOnError.
   771		commandLine.Parse(os.Args[1:])
   772	}
   773	
   774	// Parsed returns true if the command-line flags have been parsed.
   775	func Parsed() bool {
   776		return commandLine.Parsed()
   777	}
   778	
   779	// The default set of command-line flags, parsed from os.Args.
   780	var commandLine = NewFlagSet(os.Args[0], ExitOnError)
   781	
   782	// NewFlagSet returns a new, empty flag set with the specified name and
   783	// error handling property.
   784	func NewFlagSet(name string, errorHandling ErrorHandling) *FlagSet {
   785		f := &FlagSet{
   786			name:          name,
   787			errorHandling: errorHandling,
   788		}
   789		return f
   790	}
   791	
   792	// Init sets the name and error handling property for a flag set.
   793	// By default, the zero FlagSet uses an empty name and the
   794	// ContinueOnError error handling policy.
   795	func (f *FlagSet) Init(name string, errorHandling ErrorHandling) {
   796		f.name = name
   797		f.errorHandling = errorHandling
   798	}