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/ogier/pflag 24 25Run tests by running: 26 27 go test github.com/ogier/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/ogier/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 87After parsing, the arguments after the flag are available as the 88slice flag.Args() or individually as flag.Arg(i). 89The arguments are indexed from 0 through flag.NArg()-1. 90 91The pflag package also defines some new functions that are not in flag, 92that give one-letter shorthands for flags. You can use these by appending 93'P' to the name of any function that defines a flag. 94 95``` go 96var ip = flag.IntP("flagname", "f", 1234, "help message") 97var flagvar bool 98func init() { 99 flag.BoolVarP("boolname", "b", true, "help message") 100} 101flag.VarP(&flagVar, "varname", "v", 1234, "help message") 102``` 103 104Shorthand letters can be used with single dashes on the command line. 105Boolean shorthand flags can be combined with other shorthand flags. 106 107The default set of command-line flags is controlled by 108top-level functions. The FlagSet type allows one to define 109independent sets of flags, such as to implement subcommands 110in a command-line interface. The methods of FlagSet are 111analogous to the top-level functions for the command-line 112flag set. 113 114## Command line flag syntax 115 116``` 117--flag // boolean flags only 118--flag=x 119``` 120 121Unlike the flag package, a single dash before an option means something 122different than a double dash. Single dashes signify a series of shorthand 123letters for flags. All but the last shorthand letter must be boolean flags. 124 125``` 126// boolean flags 127-f 128-abc 129 130// non-boolean flags 131-n 1234 132-Ifile 133 134// mixed 135-abcs "hello" 136-abcn1234 137``` 138 139Flag parsing stops after the terminator "--". Unlike the flag package, 140flags can be interspersed with arguments anywhere on the command line 141before this terminator. 142 143Integer flags accept 1234, 0664, 0x1234 and may be negative. 144Boolean flags (in their long form) accept 1, 0, t, f, true, false, 145TRUE, FALSE, True, False. 146Duration flags accept any input valid for time.ParseDuration. 147 148## Mutating or "Normalizing" Flag names 149 150It 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. 151 152**Example #1**: You want -, _, and . in flags to compare the same. aka --my-flag == --my_flag == --my.flag 153 154```go 155func wordSepNormalizeFunc(f *pflag.FlagSet, name string) pflag.NormalizedName { 156 from := []string{"-", "_"} 157 to := "." 158 for _, sep := range from { 159 name = strings.Replace(name, sep, to, -1) 160 } 161 return pflag.NormalizedName(name) 162} 163 164myFlagSet.SetNormalizeFunc(wordSepNormalizeFunc) 165``` 166 167**Example #2**: You want to alias two flags. aka --old-flag-name == --new-flag-name 168 169```go 170func aliasNormalizeFunc(f *pflag.FlagSet, name string) pflag.NormalizedName { 171 switch name { 172 case "old-flag-name": 173 name = "new-flag-name" 174 break 175 } 176 return pflag.NormalizedName(name) 177} 178 179myFlagSet.SetNormalizeFunc(aliasNormalizeFunc) 180``` 181 182## More info 183 184You can see the full reference documentation of the pflag package 185[at godoc.org][3], or through go's standard documentation system by 186running `godoc -http=:6060` and browsing to 187[http://localhost:6060/pkg/github.com/ogier/pflag][2] after 188installation. 189 190[2]: http://localhost:6060/pkg/github.com/ogier/pflag 191[3]: http://godoc.org/github.com/ogier/pflag 192