1[![Build Status](https://travis-ci.org/spf13/pflag.svg?branch=master)](https://travis-ci.org/spf13/pflag) 2 3## Description 4 5pflag is a drop-in replacement for Go's flag package, implementing 6POSIX/GNU-style --flags. 7 8pflag is compatible with the [GNU extensions to the POSIX recommendations 9for command-line options][1]. For a more precise description, see the 10"Command-line flag syntax" section below. 11 12[1]: http://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html 13 14pflag is available under the same style of BSD license as the Go language, 15which can be found in the LICENSE file. 16 17## Installation 18 19pflag is available using the standard `go get` command. 20 21Install by running: 22 23 go get github.com/spf13/pflag 24 25Run tests by running: 26 27 go test github.com/spf13/pflag 28 29## Usage 30 31pflag is a drop-in replacement of Go's native flag package. If you import 32pflag under the name "flag" then all code should continue to function 33with no changes. 34 35``` go 36import flag "github.com/spf13/pflag" 37``` 38 39There is one exception to this: if you directly instantiate the Flag struct 40there is one more field "Shorthand" that you will need to set. 41Most code never instantiates this struct directly, and instead uses 42functions such as String(), BoolVar(), and Var(), and is therefore 43unaffected. 44 45Define flags using flag.String(), Bool(), Int(), etc. 46 47This declares an integer flag, -flagname, stored in the pointer ip, with type *int. 48 49``` go 50var ip *int = flag.Int("flagname", 1234, "help message for flagname") 51``` 52 53If you like, you can bind the flag to a variable using the Var() functions. 54 55``` go 56var flagvar int 57func init() { 58 flag.IntVar(&flagvar, "flagname", 1234, "help message for flagname") 59} 60``` 61 62Or you can create custom flags that satisfy the Value interface (with 63pointer receivers) and couple them to flag parsing by 64 65``` go 66flag.Var(&flagVal, "name", "help message for flagname") 67``` 68 69For such flags, the default value is just the initial value of the variable. 70 71After all flags are defined, call 72 73``` go 74flag.Parse() 75``` 76 77to parse the command line into the defined flags. 78 79Flags may then be used directly. If you're using the flags themselves, 80they are all pointers; if you bind to variables, they're values. 81 82``` go 83fmt.Println("ip has value ", *ip) 84fmt.Println("flagvar has value ", flagvar) 85``` 86 87There are helpers function to get values later if you have the FlagSet but 88it was difficult to keep up with all of the flag pointers in your code. 89If you have a pflag.FlagSet with a flag called 'flagname' of type int you 90can use GetInt() to get the int value. But notice that 'flagname' must exist 91and it must be an int. GetString("flagname") will fail. 92 93``` go 94i, err := flagset.GetInt("flagname") 95``` 96 97After parsing, the arguments after the flag are available as the 98slice flag.Args() or individually as flag.Arg(i). 99The arguments are indexed from 0 through flag.NArg()-1. 100 101The pflag package also defines some new functions that are not in flag, 102that give one-letter shorthands for flags. You can use these by appending 103'P' to the name of any function that defines a flag. 104 105``` go 106var ip = flag.IntP("flagname", "f", 1234, "help message") 107var flagvar bool 108func init() { 109 flag.BoolVarP("boolname", "b", true, "help message") 110} 111flag.VarP(&flagVar, "varname", "v", 1234, "help message") 112``` 113 114Shorthand letters can be used with single dashes on the command line. 115Boolean shorthand flags can be combined with other shorthand flags. 116 117The default set of command-line flags is controlled by 118top-level functions. The FlagSet type allows one to define 119independent sets of flags, such as to implement subcommands 120in a command-line interface. The methods of FlagSet are 121analogous to the top-level functions for the command-line 122flag set. 123 124## Setting no option default values for flags 125 126After you create a flag it is possible to set the pflag.NoOptDefVal for 127the given flag. Doing this changes the meaning of the flag slightly. If 128a flag has a NoOptDefVal and the flag is set on the command line without 129an option the flag will be set to the NoOptDefVal. For example given: 130 131``` go 132var ip = flag.IntP("flagname", "f", 1234, "help message") 133flag.Lookup("flagname").NoOptDefVal = "4321" 134``` 135 136Would result in something like 137 138| Parsed Arguments | Resulting Value | 139| ------------- | ------------- | 140| --flagname=1357 | ip=1357 | 141| --flagname | ip=4321 | 142| [nothing] | ip=1234 | 143 144## Command line flag syntax 145 146``` 147--flag // boolean flags, or flags with no option default values 148--flag x // only on flags without a default value 149--flag=x 150``` 151 152Unlike the flag package, a single dash before an option means something 153different than a double dash. Single dashes signify a series of shorthand 154letters for flags. All but the last shorthand letter must be boolean flags 155or a flag with a default value 156 157``` 158// boolean or flags where the 'no option default value' is set 159-f 160-f=true 161-abc 162but 163-b true is INVALID 164 165// non-boolean and flags without a 'no option default value' 166-n 1234 167-n=1234 168-n1234 169 170// mixed 171-abcs "hello" 172-absd="hello" 173-abcs1234 174``` 175 176Flag parsing stops after the terminator "--". Unlike the flag package, 177flags can be interspersed with arguments anywhere on the command line 178before this terminator. 179 180Integer flags accept 1234, 0664, 0x1234 and may be negative. 181Boolean flags (in their long form) accept 1, 0, t, f, true, false, 182TRUE, FALSE, True, False. 183Duration flags accept any input valid for time.ParseDuration. 184 185## Mutating or "Normalizing" Flag names 186 187It 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. 188 189**Example #1**: You want -, _, and . in flags to compare the same. aka --my-flag == --my_flag == --my.flag 190 191``` go 192func wordSepNormalizeFunc(f *pflag.FlagSet, name string) pflag.NormalizedName { 193 from := []string{"-", "_"} 194 to := "." 195 for _, sep := range from { 196 name = strings.Replace(name, sep, to, -1) 197 } 198 return pflag.NormalizedName(name) 199} 200 201myFlagSet.SetNormalizeFunc(wordSepNormalizeFunc) 202``` 203 204**Example #2**: You want to alias two flags. aka --old-flag-name == --new-flag-name 205 206``` go 207func aliasNormalizeFunc(f *pflag.FlagSet, name string) pflag.NormalizedName { 208 switch name { 209 case "old-flag-name": 210 name = "new-flag-name" 211 break 212 } 213 return pflag.NormalizedName(name) 214} 215 216myFlagSet.SetNormalizeFunc(aliasNormalizeFunc) 217``` 218 219## Deprecating a flag or its shorthand 220It 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. 221 222**Example #1**: You want to deprecate a flag named "badflag" as well as inform the users what flag they should use instead. 223```go 224// deprecate a flag by specifying its name and a usage message 225flags.MarkDeprecated("badflag", "please use --good-flag instead") 226``` 227This hides "badflag" from help text, and prints `Flag --badflag has been deprecated, please use --good-flag instead` when "badflag" is used. 228 229**Example #2**: You want to keep a flag name "noshorthandflag" but deprecate its shortname "n". 230```go 231// deprecate a flag shorthand by specifying its flag name and a usage message 232flags.MarkShorthandDeprecated("noshorthandflag", "please use --noshorthandflag only") 233``` 234This 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. 235 236Note that usage message is essential here, and it should not be empty. 237 238## Hidden flags 239It is possible to mark a flag as hidden, meaning it will still function as normal, however will not show up in usage/help text. 240 241**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. 242```go 243// hide a flag by specifying its name 244flags.MarkHidden("secretFlag") 245``` 246 247## More info 248 249You can see the full reference documentation of the pflag package 250[at godoc.org][3], or through go's standard documentation system by 251running `godoc -http=:6060` and browsing to 252[http://localhost:6060/pkg/github.com/ogier/pflag][2] after 253installation. 254 255[2]: http://localhost:6060/pkg/github.com/ogier/pflag 256[3]: http://godoc.org/github.com/ogier/pflag 257