1 [![Build Status](https://travis-ci.org/spf13/pflag.svg?branch=master)](https://travis-ci.org/spf13/pflag)
2 [![Go Report Card](https://goreportcard.com/badge/github.com/spf13/pflag)](https://goreportcard.com/report/github.com/spf13/pflag)
3 [![GoDoc](https://godoc.org/github.com/spf13/pflag?status.svg)](https://godoc.org/github.com/spf13/pflag)
7 pflag is a drop-in replacement for Go's flag package, implementing
8 POSIX/GNU-style --flags.
10 pflag is compatible with the [GNU extensions to the POSIX recommendations
11 for command-line options][1]. For a more precise description, see the
12 "Command-line flag syntax" section below.
14 [1]: http://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html
16 pflag is available under the same style of BSD license as the Go language,
17 which can be found in the LICENSE file.
21 pflag is available using the standard `go get` command.
25 go get github.com/spf13/pflag
29 go test github.com/spf13/pflag
33 pflag is a drop-in replacement of Go's native flag package. If you import
34 pflag under the name "flag" then all code should continue to function
38 import flag "github.com/spf13/pflag"
41 There is one exception to this: if you directly instantiate the Flag struct
42 there is one more field "Shorthand" that you will need to set.
43 Most code never instantiates this struct directly, and instead uses
44 functions such as String(), BoolVar(), and Var(), and is therefore
47 Define flags using flag.String(), Bool(), Int(), etc.
49 This declares an integer flag, -flagname, stored in the pointer ip, with type *int.
52 var ip *int = flag.Int("flagname", 1234, "help message for flagname")
55 If you like, you can bind the flag to a variable using the Var() functions.
60 flag.IntVar(&flagvar, "flagname", 1234, "help message for flagname")
64 Or you can create custom flags that satisfy the Value interface (with
65 pointer receivers) and couple them to flag parsing by
68 flag.Var(&flagVal, "name", "help message for flagname")
71 For such flags, the default value is just the initial value of the variable.
73 After all flags are defined, call
79 to parse the command line into the defined flags.
81 Flags may then be used directly. If you're using the flags themselves,
82 they are all pointers; if you bind to variables, they're values.
85 fmt.Println("ip has value ", *ip)
86 fmt.Println("flagvar has value ", flagvar)
89 There are helpers function to get values later if you have the FlagSet but
90 it was difficult to keep up with all of the flag pointers in your code.
91 If you have a pflag.FlagSet with a flag called 'flagname' of type int you
92 can use GetInt() to get the int value. But notice that 'flagname' must exist
93 and it must be an int. GetString("flagname") will fail.
96 i, err := flagset.GetInt("flagname")
99 After parsing, the arguments after the flag are available as the
100 slice flag.Args() or individually as flag.Arg(i).
101 The arguments are indexed from 0 through flag.NArg()-1.
103 The pflag package also defines some new functions that are not in flag,
104 that give one-letter shorthands for flags. You can use these by appending
105 'P' to the name of any function that defines a flag.
108 var ip = flag.IntP("flagname", "f", 1234, "help message")
111 flag.BoolVarP(&flagvar, "boolname", "b", true, "help message")
113 flag.VarP(&flagVal, "varname", "v", "help message")
116 Shorthand letters can be used with single dashes on the command line.
117 Boolean shorthand flags can be combined with other shorthand flags.
119 The default set of command-line flags is controlled by
120 top-level functions. The FlagSet type allows one to define
121 independent sets of flags, such as to implement subcommands
122 in a command-line interface. The methods of FlagSet are
123 analogous to the top-level functions for the command-line
126 ## Setting no option default values for flags
128 After you create a flag it is possible to set the pflag.NoOptDefVal for
129 the given flag. Doing this changes the meaning of the flag slightly. If
130 a flag has a NoOptDefVal and the flag is set on the command line without
131 an option the flag will be set to the NoOptDefVal. For example given:
134 var ip = flag.IntP("flagname", "f", 1234, "help message")
135 flag.Lookup("flagname").NoOptDefVal = "4321"
138 Would result in something like
140 | Parsed Arguments | Resulting Value |
141 | ------------- | ------------- |
142 | --flagname=1357 | ip=1357 |
143 | --flagname | ip=4321 |
144 | [nothing] | ip=1234 |
146 ## Command line flag syntax
149 --flag // boolean flags, or flags with no option default values
150 --flag x // only on flags without a default value
154 Unlike the flag package, a single dash before an option means something
155 different than a double dash. Single dashes signify a series of shorthand
156 letters for flags. All but the last shorthand letter must be boolean flags
157 or a flag with a default value
160 // boolean or flags where the 'no option default value' is set
167 // non-boolean and flags without a 'no option default value'
178 Flag parsing stops after the terminator "--". Unlike the flag package,
179 flags can be interspersed with arguments anywhere on the command line
180 before this terminator.
182 Integer flags accept 1234, 0664, 0x1234 and may be negative.
183 Boolean flags (in their long form) accept 1, 0, t, f, true, false,
184 TRUE, FALSE, True, False.
185 Duration flags accept any input valid for time.ParseDuration.
187 ## Mutating or "Normalizing" Flag names
189 It is possible to set a custom flag name 'normalization function.' It allows flag names to be mutated both when created in the code and when used on the command line to some 'normalized' form. The 'normalized' form is used for comparison. Two examples of using the custom normalization func follow.
191 **Example #1**: You want -, _, and . in flags to compare the same. aka --my-flag == --my_flag == --my.flag
194 func wordSepNormalizeFunc(f *pflag.FlagSet, name string) pflag.NormalizedName {
195 from := []string{"-", "_"}
197 for _, sep := range from {
198 name = strings.Replace(name, sep, to, -1)
200 return pflag.NormalizedName(name)
203 myFlagSet.SetNormalizeFunc(wordSepNormalizeFunc)
206 **Example #2**: You want to alias two flags. aka --old-flag-name == --new-flag-name
209 func aliasNormalizeFunc(f *pflag.FlagSet, name string) pflag.NormalizedName {
211 case "old-flag-name":
212 name = "new-flag-name"
215 return pflag.NormalizedName(name)
218 myFlagSet.SetNormalizeFunc(aliasNormalizeFunc)
221 ## Deprecating a flag or its shorthand
222 It is possible to deprecate a flag, or just its shorthand. Deprecating a flag/shorthand hides it from help text and prints a usage message when the deprecated flag/shorthand is used.
224 **Example #1**: You want to deprecate a flag named "badflag" as well as inform the users what flag they should use instead.
226 // deprecate a flag by specifying its name and a usage message
227 flags.MarkDeprecated("badflag", "please use --good-flag instead")
229 This hides "badflag" from help text, and prints `Flag --badflag has been deprecated, please use --good-flag instead` when "badflag" is used.
231 **Example #2**: You want to keep a flag name "noshorthandflag" but deprecate its shortname "n".
233 // deprecate a flag shorthand by specifying its flag name and a usage message
234 flags.MarkShorthandDeprecated("noshorthandflag", "please use --noshorthandflag only")
236 This hides the shortname "n" from help text, and prints `Flag shorthand -n has been deprecated, please use --noshorthandflag only` when the shorthand "n" is used.
238 Note that usage message is essential here, and it should not be empty.
241 It is possible to mark a flag as hidden, meaning it will still function as normal, however will not show up in usage/help text.
243 **Example**: You have a flag named "secretFlag" that you need for internal use only and don't want it showing up in help text, or for its usage text to be available.
245 // hide a flag by specifying its name
246 flags.MarkHidden("secretFlag")
249 ## Disable sorting of flags
250 `pflag` allows you to disable sorting of flags for help and usage message.
254 flags.BoolP("verbose", "v", false, "verbose output")
255 flags.String("coolflag", "yeaah", "it's really cool flag")
256 flags.Int("usefulflag", 777, "sometimes it's very useful")
257 flags.SortFlags = false
258 flags.PrintDefaults()
262 -v, --verbose verbose output
263 --coolflag string it's really cool flag (default "yeaah")
264 --usefulflag int sometimes it's very useful (default 777)
268 ## Supporting Go flags when using pflag
269 In order to support flags defined using Go's `flag` package, they must be added to the `pflag` flagset. This is usually necessary
270 to support flags defined by third-party dependencies (e.g. `golang/glog`).
272 **Example**: You want to add the Go flags to the `CommandLine` flagset
276 flag "github.com/spf13/pflag"
279 var ip *int = flag.Int("flagname", 1234, "help message for flagname")
282 flag.CommandLine.AddGoFlagSet(goflag.CommandLine)
289 You can see the full reference documentation of the pflag package
290 [at godoc.org][3], or through go's standard documentation system by
291 running `godoc -http=:6060` and browsing to
292 [http://localhost:6060/pkg/github.com/spf13/pflag][2] after
295 [2]: http://localhost:6060/pkg/github.com/spf13/pflag
296 [3]: http://godoc.org/github.com/spf13/pflag