6 Package flag implements command-line flag parsing.
10 Define flags using [flag.String], [Bool], [Int], etc.
12 This declares an integer flag, -n, stored in the pointer nFlag, with type *int:
14 	import "flag"
15 	var nFlag = flag.Int("n", 1234, "help message for flag n")
17 If you like, you can bind the flag to a variable using the Var() functions.
21 		flag.IntVar(&flagvar, "flagname", 1234, "help message for flagname")
25 pointer receivers) and couple them to flag parsing by
27 	flag.Var(&flagVal, "name", "help message for flagname")
33 	flag.Parse()
44 slice [flag.Args] or individually as [flag.Arg](i).
45 The arguments are indexed from 0 through [flag.NArg]-1.
47 # Command line flag syntax
51 	-flag
52 	--flag   // double dashes are also permitted
53 	-flag=x
54 	-flag x  // non-boolean flags only
63 called 0, false, etc. You must use the -flag=false form to turn
64 off a boolean flag.
66 Flag parsing stops just before the first non-flag argument
67 ("-" is a non-flag argument) or after the terminator "--".
81 flag set.
83 package flag  package
99 // ErrHelp is the error returned if the -help or -h flag is invoked
100 // but no such flag is defined.
101 var ErrHelp = errors.New("flag: help requested")
103 // errParse is returned by Set if a flag's value fails to parse, such as with an invalid integer fo…
107 // errRange is returned by Set if a flag's value is out of range.
350 // Value is the interface to the dynamic value stored in a flag.
357 // Set is called once, in command line order, for each flag present.
358 // The flag package may call the [String] method with a zero-valued receiver,
387 // [Flag] names must be unique within a FlagSet. An attempt to define a flag whose
399 	actual        map[string]*Flag
400 	formal        map[string]*Flag
407 // A Flag represents the state of a flag.
408 type Flag struct {  struct
416 func sortFlags(flags map[string]*Flag) []*Flag {  argument
417 	result := make([]*Flag, len(flags))
423 	slices.SortFunc(result, func(a, b *Flag) int {
438 // Name returns the name of the flag set.
443 // ErrorHandling returns the error handling behavior of the flag set.
456 func (f *FlagSet) VisitAll(fn func(*Flag)) {
457 	for _, flag := range sortFlags(f.formal) {
458 		fn(flag)
464 func VisitAll(fn func(*Flag)) {  argument
470 func (f *FlagSet) Visit(fn func(*Flag)) {
471 	for _, flag := range sortFlags(f.actual) {
472 		fn(flag)
478 func Visit(fn func(*Flag)) {  argument
482 // Lookup returns the [Flag] structure of the named flag, returning nil if none exists.
483 func (f *FlagSet) Lookup(name string) *Flag {
487 // Lookup returns the [Flag] structure of the named command-line flag,
489 func Lookup(name string) *Flag {
493 // Set sets the value of the named flag.
498 	flag, ok := f.formal[name]
500 		// Remember that a flag that isn't defined is being set.
502 		// subsequently that flag is defined, we want to panic
518 		return fmt.Errorf("no such flag -%v", name)
520 	err := flag.Value.Set(value)
525 		f.actual = make(map[string]*Flag)
527 	f.actual[name] = flag
531 // Set sets the value of the named command-line flag.
537 // value for a flag.
538 func isZeroValue(flag *Flag, value string) (ok bool, err error) {  argument
539 	// Build a zero value of the flag's Value type, and see if the
542 	typ := reflect.TypeOf(flag.Value)
557 			err = fmt.Errorf("panic calling String method on zero %v for flag %s: %v", typ, flag.Name, e)
564 // string for a flag and returns it and the un-quoted usage.
567 // type of the flag's value, or the empty string if the flag is boolean.
568 func UnquoteUsage(flag *Flag) (name string, usage string) {  argument
570 	usage = flag.Usage
585 	switch fv := flag.Value.(type) {
609 	f.VisitAll(func(flag *Flag) {
611 		fmt.Fprintf(&b, "  -%s", flag.Name) // Two spaces before -; see next two comments.
612 		name, usage := UnquoteUsage(flag)
629 		// for this flag type.
630 		if isZero, err := isZeroValue(flag, flag.DefValue); err != nil {
633 			if _, ok := flag.Value.(*stringValue); ok {
635 				fmt.Fprintf(&b, " (default %q)", flag.DefValue)
637 				fmt.Fprintf(&b, " (default %v)", flag.DefValue)
642 	// If calling String on any zero flag.Values triggered a panic, print
656 // For an integer valued flag x, the default output has the form
662 // a bool flag with a one-byte name. For bool flags, the type is
663 // omitted and if the flag name is one byte the usage message appears
666 // can be changed by placing a back-quoted name in the flag's usage
671 //	flag.String("I", "", "search `directory` for include files")
678 // To change the destination for flag messages, call [CommandLine].SetOutput.
694 // because it serves (via godoc flag Usage) as the example
740 // Args returns the non-flag arguments.
743 // Args returns the non-flag command-line arguments.
746 // BoolVar defines a bool flag with specified name, default value, and usage string.
747 // The argument p points to a bool variable in which to store the value of the flag.
752 // BoolVar defines a bool flag with specified name, default value, and usage string.
753 // The argument p points to a bool variable in which to store the value of the flag.
758 // Bool defines a bool flag with specified name, default value, and usage string.
759 // The return value is the address of a bool variable that stores the value of the flag.
766 // Bool defines a bool flag with specified name, default value, and usage string.
767 // The return value is the address of a bool variable that stores the value of the flag.
772 // IntVar defines an int flag with specified name, default value, and usage string.
773 // The argument p points to an int variable in which to store the value of the flag.
778 // IntVar defines an int flag with specified name, default value, and usage string.
779 // The argument p points to an int variable in which to store the value of the flag.
784 // Int defines an int flag with specified name, default value, and usage string.
785 // The return value is the address of an int variable that stores the value of the flag.
792 // Int defines an int flag with specified name, default value, and usage string.
793 // The return value is the address of an int variable that stores the value of the flag.
798 // Int64Var defines an int64 flag with specified name, default value, and usage string.
799 // The argument p points to an int64 variable in which to store the value of the flag.
804 // Int64Var defines an int64 flag with specified name, default value, and usage string.
805 // The argument p points to an int64 variable in which to store the value of the flag.
810 // Int64 defines an int64 flag with specified name, default value, and usage string.
811 // The return value is the address of an int64 variable that stores the value of the flag.
818 // Int64 defines an int64 flag with specified name, default value, and usage string.
819 // The return value is the address of an int64 variable that stores the value of the flag.
824 // UintVar defines a uint flag with specified name, default value, and usage string.
825 // The argument p points to a uint variable in which to store the value of the flag.
830 // UintVar defines a uint flag with specified name, default value, and usage string.
831 // The argument p points to a uint variable in which to store the value of the flag.
836 // Uint defines a uint flag with specified name, default value, and usage string.
837 // The return value is the address of a uint variable that stores the value of the flag.
844 // Uint defines a uint flag with specified name, default value, and usage string.
845 // The return value is the address of a uint variable that stores the value of the flag.
850 // Uint64Var defines a uint64 flag with specified name, default value, and usage string.
851 // The argument p points to a uint64 variable in which to store the value of the flag.
856 // Uint64Var defines a uint64 flag with specified name, default value, and usage string.
857 // The argument p points to a uint64 variable in which to store the value of the flag.
862 // Uint64 defines a uint64 flag with specified name, default value, and usage string.
863 // The return value is the address of a uint64 variable that stores the value of the flag.
870 // Uint64 defines a uint64 flag with specified name, default value, and usage string.
871 // The return value is the address of a uint64 variable that stores the value of the flag.
876 // StringVar defines a string flag with specified name, default value, and usage string.
877 // The argument p points to a string variable in which to store the value of the flag.
882 // StringVar defines a string flag with specified name, default value, and usage string.
883 // The argument p points to a string variable in which to store the value of the flag.
888 // String defines a string flag with specified name, default value, and usage string.
889 // The return value is the address of a string variable that stores the value of the flag.
896 // String defines a string flag with specified name, default value, and usage string.
897 // The return value is the address of a string variable that stores the value of the flag.
902 // Float64Var defines a float64 flag with specified name, default value, and usage string.
903 // The argument p points to a float64 variable in which to store the value of the flag.
908 // Float64Var defines a float64 flag with specified name, default value, and usage string.
909 // The argument p points to a float64 variable in which to store the value of the flag.
914 // Float64 defines a float64 flag with specified name, default value, and usage string.
915 // The return value is the address of a float64 variable that stores the value of the flag.
922 // Float64 defines a float64 flag with specified name, default value, and usage string.
923 // The return value is the address of a float64 variable that stores the value of the flag.
928 // DurationVar defines a time.Duration flag with specified name, default value, and usage string.
929 // The argument p points to a time.Duration variable in which to store the value of the flag.
930 // The flag accepts a value acceptable to time.ParseDuration.
935 // DurationVar defines a time.Duration flag with specified name, default value, and usage string.
936 // The argument p points to a time.Duration variable in which to store the value of the flag.
937 // The flag accepts a value acceptable to time.ParseDuration.
942 // Duration defines a time.Duration flag with specified name, default value, and usage string.
943 // The return value is the address of a time.Duration variable that stores the value of the flag.
944 // The flag accepts a value acceptable to time.ParseDuration.
951 // Duration defines a time.Duration flag with specified name, default value, and usage string.
952 // The return value is the address of a time.Duration variable that stores the value of the flag.
953 // The flag accepts a value acceptable to time.ParseDuration.
958 // TextVar defines a flag with a specified name, default value, and usage string.
960 // of the flag, and p must implement encoding.TextUnmarshaler.
961 // If the flag is used, the flag value will be passed to p's UnmarshalText method.
967 // TextVar defines a flag with a specified name, default value, and usage string.
969 // of the flag, and p must implement encoding.TextUnmarshaler.
970 // If the flag is used, the flag value will be passed to p's UnmarshalText method.
976 // Func defines a flag with the specified name and usage string.
977 // Each time the flag is seen, fn is called with the value of the flag.
978 // If fn returns a non-nil error, it will be treated as a flag value parsing error.
983 // Func defines a flag with the specified name and usage string.
984 // Each time the flag is seen, fn is called with the value of the flag.
985 // If fn returns a non-nil error, it will be treated as a flag value parsing error.
990 // BoolFunc defines a flag with the specified name and usage string without requiring values.
991 // Each time the flag is seen, fn is called with the value of the flag.
992 // If fn returns a non-nil error, it will be treated as a flag value parsing error.
997 // BoolFunc defines a flag with the specified name and usage string without requiring values.
998 // Each time the flag is seen, fn is called with the value of the flag.
999 // If fn returns a non-nil error, it will be treated as a flag value parsing error.
1004 // Var defines a flag with the specified name and usage string. The type and
1005 // value of the flag are represented by the first argument, of type [Value], which
1007 // caller could create a flag that turns a comma-separated string into a slice
1011 	// Flag must not begin "-" or contain "=".
1013 		panic(f.sprintf("flag %q begins with -", name))
1015 		panic(f.sprintf("flag %q contains =", name))
1019 	flag := &Flag{name, usage, value, value.String()}
1024 			msg = f.sprintf("flag redefined: %s", name)
1026 			msg = f.sprintf("%s flag redefined: %s", f.name, name)
1031 		panic(fmt.Sprintf("flag %s set at %s before being defined", name, pos))
1034 		f.formal = make(map[string]*Flag)
1036 	f.formal[name] = flag
1039 // Var defines a flag with the specified name and usage string. The type and
1040 // value of the flag are represented by the first argument, of type [Value], which
1042 // caller could create a flag that turns a comma-separated string into a slice
1064 // usage calls the Usage method for the flag set if one is specified,
1074 // parseOne parses one flag. It reports whether a flag was seen.
1093 		return false, f.failf("bad flag syntax: %s", s)
1096 	// it's a flag. does it have an argument?
1109 	flag, ok := f.formal[name]
1115 		return false, f.failf("flag provided but not defined: -%s", name)
1118 	if fv, ok := flag.Value.(boolFlag); ok && fv.IsBoolFlag() { // special case: doesn't need an arg
1125 				return false, f.failf("invalid boolean flag %s: %v", name, err)
1136 			return false, f.failf("flag needs an argument: -%s", name)
1138 		if err := flag.Value.Set(value); err != nil {
1139 			return false, f.failf("invalid value %q for flag -%s: %v", value, name, err)
1143 		f.actual = make(map[string]*Flag)
1145 	f.actual[name] = flag
1149 // Parse parses flag definitions from the argument list, which should not
1213 // NewFlagSet returns a new, empty flag set with the specified name and
1225 // Init sets the name and error handling property for a flag set.