|
|
- // Copyright 2012 Jesse van den Kieboom. All rights reserved.
- // Use of this source code is governed by a BSD-style
- // license that can be found in the LICENSE file.
-
- /*
- Package flags provides an extensive command line option parser.
- The flags package is similar in functionality to the go built-in flag package
- but provides more options and uses reflection to provide a convenient and
- succinct way of specifying command line options.
-
-
- Supported features
-
- The following features are supported in go-flags:
-
- Options with short names (-v)
- Options with long names (--verbose)
- Options with and without arguments (bool v.s. other type)
- Options with optional arguments and default values
- Option default values from ENVIRONMENT_VARIABLES, including slice and map values
- Multiple option groups each containing a set of options
- Generate and print well-formatted help message
- Passing remaining command line arguments after -- (optional)
- Ignoring unknown command line options (optional)
- Supports -I/usr/include -I=/usr/include -I /usr/include option argument specification
- Supports multiple short options -aux
- Supports all primitive go types (string, int{8..64}, uint{8..64}, float)
- Supports same option multiple times (can store in slice or last option counts)
- Supports maps
- Supports function callbacks
- Supports namespaces for (nested) option groups
-
- Additional features specific to Windows:
- Options with short names (/v)
- Options with long names (/verbose)
- Windows-style options with arguments use a colon as the delimiter
- Modify generated help message with Windows-style / options
- Windows style options can be disabled at build time using the "forceposix"
- build tag
-
-
- Basic usage
-
- The flags package uses structs, reflection and struct field tags
- to allow users to specify command line options. This results in very simple
- and concise specification of your application options. For example:
-
- type Options struct {
- Verbose []bool `short:"v" long:"verbose" description:"Show verbose debug information"`
- }
-
- This specifies one option with a short name -v and a long name --verbose.
- When either -v or --verbose is found on the command line, a 'true' value
- will be appended to the Verbose field. e.g. when specifying -vvv, the
- resulting value of Verbose will be {[true, true, true]}.
-
- Slice options work exactly the same as primitive type options, except that
- whenever the option is encountered, a value is appended to the slice.
-
- Map options from string to primitive type are also supported. On the command
- line, you specify the value for such an option as key:value. For example
-
- type Options struct {
- AuthorInfo string[string] `short:"a"`
- }
-
- Then, the AuthorInfo map can be filled with something like
- -a name:Jesse -a "surname:van den Kieboom".
-
- Finally, for full control over the conversion between command line argument
- values and options, user defined types can choose to implement the Marshaler
- and Unmarshaler interfaces.
-
-
- Available field tags
-
- The following is a list of tags for struct fields supported by go-flags:
-
- short: the short name of the option (single character)
- long: the long name of the option
- required: if non empty, makes the option required to appear on the command
- line. If a required option is not present, the parser will
- return ErrRequired (optional)
- description: the description of the option (optional)
- long-description: the long description of the option. Currently only
- displayed in generated man pages (optional)
- no-flag: if non-empty, this field is ignored as an option (optional)
-
- optional: if non-empty, makes the argument of the option optional. When an
- argument is optional it can only be specified using
- --option=argument (optional)
- optional-value: the value of an optional option when the option occurs
- without an argument. This tag can be specified multiple
- times in the case of maps or slices (optional)
- default: the default value of an option. This tag can be specified
- multiple times in the case of slices or maps (optional)
- default-mask: when specified, this value will be displayed in the help
- instead of the actual default value. This is useful
- mostly for hiding otherwise sensitive information from
- showing up in the help. If default-mask takes the special
- value "-", then no default value will be shown at all
- (optional)
- env: the default value of the option is overridden from the
- specified environment variable, if one has been defined.
- (optional)
- env-delim: the 'env' default value from environment is split into
- multiple values with the given delimiter string, use with
- slices and maps (optional)
- value-name: the name of the argument value (to be shown in the help)
- (optional)
- choice: limits the values for an option to a set of values.
- This tag can be specified multiple times (optional)
- hidden: if non-empty, the option is not visible in the help or man page.
-
- base: a base (radix) used to convert strings to integer values, the
- default base is 10 (i.e. decimal) (optional)
-
- ini-name: the explicit ini option name (optional)
- no-ini: if non-empty this field is ignored as an ini option
- (optional)
-
- group: when specified on a struct field, makes the struct
- field a separate group with the given name (optional)
- namespace: when specified on a group struct field, the namespace
- gets prepended to every option's long name and
- subgroup's namespace of this group, separated by
- the parser's namespace delimiter (optional)
- command: when specified on a struct field, makes the struct
- field a (sub)command with the given name (optional)
- subcommands-optional: when specified on a command struct field, makes
- any subcommands of that command optional (optional)
- alias: when specified on a command struct field, adds the
- specified name as an alias for the command. Can be
- be specified multiple times to add more than one
- alias (optional)
- positional-args: when specified on a field with a struct type,
- uses the fields of that struct to parse remaining
- positional command line arguments into (in order
- of the fields). If a field has a slice type,
- then all remaining arguments will be added to it.
- Positional arguments are optional by default,
- unless the "required" tag is specified together
- with the "positional-args" tag. The "required" tag
- can also be set on the individual rest argument
- fields, to require only the first N positional
- arguments. If the "required" tag is set on the
- rest arguments slice, then its value determines
- the minimum amount of rest arguments that needs to
- be provided (e.g. `required:"2"`) (optional)
- positional-arg-name: used on a field in a positional argument struct; name
- of the positional argument placeholder to be shown in
- the help (optional)
-
- Either the `short:` tag or the `long:` must be specified to make the field eligible as an
- option.
-
-
- Option groups
-
- Option groups are a simple way to semantically separate your options. All
- options in a particular group are shown together in the help under the name
- of the group. Namespaces can be used to specify option long names more
- precisely and emphasize the options affiliation to their group.
-
- There are currently three ways to specify option groups.
-
- 1. Use NewNamedParser specifying the various option groups.
- 2. Use AddGroup to add a group to an existing parser.
- 3. Add a struct field to the top-level options annotated with the
- group:"group-name" tag.
-
-
-
- Commands
-
- The flags package also has basic support for commands. Commands are often
- used in monolithic applications that support various commands or actions.
- Take git for example, all of the add, commit, checkout, etc. are called
- commands. Using commands you can easily separate multiple functions of your
- application.
-
- There are currently two ways to specify a command.
-
- 1. Use AddCommand on an existing parser.
- 2. Add a struct field to your options struct annotated with the
- command:"command-name" tag.
-
- The most common, idiomatic way to implement commands is to define a global
- parser instance and implement each command in a separate file. These
- command files should define a go init function which calls AddCommand on
- the global parser.
-
- When parsing ends and there is an active command and that command implements
- the Commander interface, then its Execute method will be run with the
- remaining command line arguments.
-
- Command structs can have options which become valid to parse after the
- command has been specified on the command line, in addition to the options
- of all the parent commands. I.e. considering a -v flag on the parser and an
- add command, the following are equivalent:
-
- ./app -v add
- ./app add -v
-
- However, if the -v flag is defined on the add command, then the first of
- the two examples above would fail since the -v flag is not defined before
- the add command.
-
-
- Completion
-
- go-flags has builtin support to provide bash completion of flags, commands
- and argument values. To use completion, the binary which uses go-flags
- can be invoked in a special environment to list completion of the current
- command line argument. It should be noted that this `executes` your application,
- and it is up to the user to make sure there are no negative side effects (for
- example from init functions).
-
- Setting the environment variable `GO_FLAGS_COMPLETION=1` enables completion
- by replacing the argument parsing routine with the completion routine which
- outputs completions for the passed arguments. The basic invocation to
- complete a set of arguments is therefore:
-
- GO_FLAGS_COMPLETION=1 ./completion-example arg1 arg2 arg3
-
- where `completion-example` is the binary, `arg1` and `arg2` are
- the current arguments, and `arg3` (the last argument) is the argument
- to be completed. If the GO_FLAGS_COMPLETION is set to "verbose", then
- descriptions of possible completion items will also be shown, if there
- are more than 1 completion items.
-
- To use this with bash completion, a simple file can be written which
- calls the binary which supports go-flags completion:
-
- _completion_example() {
- # All arguments except the first one
- args=("${COMP_WORDS[@]:1:$COMP_CWORD}")
-
- # Only split on newlines
- local IFS=$'\n'
-
- # Call completion (note that the first element of COMP_WORDS is
- # the executable itself)
- COMPREPLY=($(GO_FLAGS_COMPLETION=1 ${COMP_WORDS[0]} "${args[@]}"))
- return 0
- }
-
- complete -F _completion_example completion-example
-
- Completion requires the parser option PassDoubleDash and is therefore enforced if the environment variable GO_FLAGS_COMPLETION is set.
-
- Customized completion for argument values is supported by implementing
- the flags.Completer interface for the argument value type. An example
- of a type which does so is the flags.Filename type, an alias of string
- allowing simple filename completion. A slice or array argument value
- whose element type implements flags.Completer will also be completed.
- */
- package flags
|