1// Copyright 2012 Jesse van den Kieboom. 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/* 6Package flags provides an extensive command line option parser. 7The flags package is similar in functionality to the go built-in flag package 8but provides more options and uses reflection to provide a convenient and 9succinct way of specifying command line options. 10 11 12Supported features 13 14The following features are supported in go-flags: 15 16 Options with short names (-v) 17 Options with long names (--verbose) 18 Options with and without arguments (bool v.s. other type) 19 Options with optional arguments and default values 20 Option default values from ENVIRONMENT_VARIABLES, including slice and map values 21 Multiple option groups each containing a set of options 22 Generate and print well-formatted help message 23 Passing remaining command line arguments after -- (optional) 24 Ignoring unknown command line options (optional) 25 Supports -I/usr/include -I=/usr/include -I /usr/include option argument specification 26 Supports multiple short options -aux 27 Supports all primitive go types (string, int{8..64}, uint{8..64}, float) 28 Supports same option multiple times (can store in slice or last option counts) 29 Supports maps 30 Supports function callbacks 31 Supports namespaces for (nested) option groups 32 33Additional features specific to Windows: 34 Options with short names (/v) 35 Options with long names (/verbose) 36 Windows-style options with arguments use a colon as the delimiter 37 Modify generated help message with Windows-style / options 38 Windows style options can be disabled at build time using the "forceposix" 39 build tag 40 41 42Basic usage 43 44The flags package uses structs, reflection and struct field tags 45to allow users to specify command line options. This results in very simple 46and concise specification of your application options. For example: 47 48 type Options struct { 49 Verbose []bool `short:"v" long:"verbose" description:"Show verbose debug information"` 50 } 51 52This specifies one option with a short name -v and a long name --verbose. 53When either -v or --verbose is found on the command line, a 'true' value 54will be appended to the Verbose field. e.g. when specifying -vvv, the 55resulting value of Verbose will be {[true, true, true]}. 56 57Slice options work exactly the same as primitive type options, except that 58whenever the option is encountered, a value is appended to the slice. 59 60Map options from string to primitive type are also supported. On the command 61line, you specify the value for such an option as key:value. For example 62 63 type Options struct { 64 AuthorInfo string[string] `short:"a"` 65 } 66 67Then, the AuthorInfo map can be filled with something like 68-a name:Jesse -a "surname:van den Kieboom". 69 70Finally, for full control over the conversion between command line argument 71values and options, user defined types can choose to implement the Marshaler 72and Unmarshaler interfaces. 73 74 75Available field tags 76 77The following is a list of tags for struct fields supported by go-flags: 78 79 short: the short name of the option (single character) 80 long: the long name of the option 81 required: if non empty, makes the option required to appear on the command 82 line. If a required option is not present, the parser will 83 return ErrRequired (optional) 84 description: the description of the option (optional) 85 long-description: the long description of the option. Currently only 86 displayed in generated man pages (optional) 87 no-flag: if non-empty, this field is ignored as an option (optional) 88 89 optional: if non-empty, makes the argument of the option optional. When an 90 argument is optional it can only be specified using 91 --option=argument (optional) 92 optional-value: the value of an optional option when the option occurs 93 without an argument. This tag can be specified multiple 94 times in the case of maps or slices (optional) 95 default: the default value of an option. This tag can be specified 96 multiple times in the case of slices or maps (optional) 97 default-mask: when specified, this value will be displayed in the help 98 instead of the actual default value. This is useful 99 mostly for hiding otherwise sensitive information from 100 showing up in the help. If default-mask takes the special 101 value "-", then no default value will be shown at all 102 (optional) 103 env: the default value of the option is overridden from the 104 specified environment variable, if one has been defined. 105 (optional) 106 env-delim: the 'env' default value from environment is split into 107 multiple values with the given delimiter string, use with 108 slices and maps (optional) 109 value-name: the name of the argument value (to be shown in the help) 110 (optional) 111 choice: limits the values for an option to a set of values. 112 This tag can be specified multiple times (optional) 113 hidden: if non-empty, the option is not visible in the help or man page. 114 115 base: a base (radix) used to convert strings to integer values, the 116 default base is 10 (i.e. decimal) (optional) 117 118 ini-name: the explicit ini option name (optional) 119 no-ini: if non-empty this field is ignored as an ini option 120 (optional) 121 122 group: when specified on a struct field, makes the struct 123 field a separate group with the given name (optional) 124 namespace: when specified on a group struct field, the namespace 125 gets prepended to every option's long name and 126 subgroup's namespace of this group, separated by 127 the parser's namespace delimiter (optional) 128 command: when specified on a struct field, makes the struct 129 field a (sub)command with the given name (optional) 130 subcommands-optional: when specified on a command struct field, makes 131 any subcommands of that command optional (optional) 132 alias: when specified on a command struct field, adds the 133 specified name as an alias for the command. Can be 134 be specified multiple times to add more than one 135 alias (optional) 136 positional-args: when specified on a field with a struct type, 137 uses the fields of that struct to parse remaining 138 positional command line arguments into (in order 139 of the fields). If a field has a slice type, 140 then all remaining arguments will be added to it. 141 Positional arguments are optional by default, 142 unless the "required" tag is specified together 143 with the "positional-args" tag. The "required" tag 144 can also be set on the individual rest argument 145 fields, to require only the first N positional 146 arguments. If the "required" tag is set on the 147 rest arguments slice, then its value determines 148 the minimum amount of rest arguments that needs to 149 be provided (e.g. `required:"2"`) (optional) 150 positional-arg-name: used on a field in a positional argument struct; name 151 of the positional argument placeholder to be shown in 152 the help (optional) 153 154Either the `short:` tag or the `long:` must be specified to make the field eligible as an 155option. 156 157 158Option groups 159 160Option groups are a simple way to semantically separate your options. All 161options in a particular group are shown together in the help under the name 162of the group. Namespaces can be used to specify option long names more 163precisely and emphasize the options affiliation to their group. 164 165There are currently three ways to specify option groups. 166 167 1. Use NewNamedParser specifying the various option groups. 168 2. Use AddGroup to add a group to an existing parser. 169 3. Add a struct field to the top-level options annotated with the 170 group:"group-name" tag. 171 172 173 174Commands 175 176The flags package also has basic support for commands. Commands are often 177used in monolithic applications that support various commands or actions. 178Take git for example, all of the add, commit, checkout, etc. are called 179commands. Using commands you can easily separate multiple functions of your 180application. 181 182There are currently two ways to specify a command. 183 184 1. Use AddCommand on an existing parser. 185 2. Add a struct field to your options struct annotated with the 186 command:"command-name" tag. 187 188The most common, idiomatic way to implement commands is to define a global 189parser instance and implement each command in a separate file. These 190command files should define a go init function which calls AddCommand on 191the global parser. 192 193When parsing ends and there is an active command and that command implements 194the Commander interface, then its Execute method will be run with the 195remaining command line arguments. 196 197Command structs can have options which become valid to parse after the 198command has been specified on the command line, in addition to the options 199of all the parent commands. I.e. considering a -v flag on the parser and an 200add command, the following are equivalent: 201 202 ./app -v add 203 ./app add -v 204 205However, if the -v flag is defined on the add command, then the first of 206the two examples above would fail since the -v flag is not defined before 207the add command. 208 209 210Completion 211 212go-flags has builtin support to provide bash completion of flags, commands 213and argument values. To use completion, the binary which uses go-flags 214can be invoked in a special environment to list completion of the current 215command line argument. It should be noted that this `executes` your application, 216and it is up to the user to make sure there are no negative side effects (for 217example from init functions). 218 219Setting the environment variable `GO_FLAGS_COMPLETION=1` enables completion 220by replacing the argument parsing routine with the completion routine which 221outputs completions for the passed arguments. The basic invocation to 222complete a set of arguments is therefore: 223 224 GO_FLAGS_COMPLETION=1 ./completion-example arg1 arg2 arg3 225 226where `completion-example` is the binary, `arg1` and `arg2` are 227the current arguments, and `arg3` (the last argument) is the argument 228to be completed. If the GO_FLAGS_COMPLETION is set to "verbose", then 229descriptions of possible completion items will also be shown, if there 230are more than 1 completion items. 231 232To use this with bash completion, a simple file can be written which 233calls the binary which supports go-flags completion: 234 235 _completion_example() { 236 # All arguments except the first one 237 args=("${COMP_WORDS[@]:1:$COMP_CWORD}") 238 239 # Only split on newlines 240 local IFS=$'\n' 241 242 # Call completion (note that the first element of COMP_WORDS is 243 # the executable itself) 244 COMPREPLY=($(GO_FLAGS_COMPLETION=1 ${COMP_WORDS[0]} "${args[@]}")) 245 return 0 246 } 247 248 complete -F _completion_example completion-example 249 250Completion requires the parser option PassDoubleDash and is therefore enforced if the environment variable GO_FLAGS_COMPLETION is set. 251 252Customized completion for argument values is supported by implementing 253the flags.Completer interface for the argument value type. An example 254of a type which does so is the flags.Filename type, an alias of string 255allowing simple filename completion. A slice or array argument value 256whose element type implements flags.Completer will also be completed. 257*/ 258package flags 259