blob: 7c3d19b06bbbad5d28b4ce47816fd0a6b25c2862 [file] [log] [blame]
// 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 builtin flag package
// but provides more options and uses reflection to provide a convenient and
// succinct way of specifying command line options.
// Supported features:
// 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
// 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
// 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
// The flags package uses structs, reflection and struct field tags
// to allow users to specify command line options. This results in very simple
// and consise 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:
// short: the short name of the option (single character)
// long: the long name of the option
// description: the description of the option (optional)
// optional: whether an argument of the option is optional (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)
// required: whether an option is required to appear on the command
// line. If a required option is not present, the parser
// will return ErrRequired.
// base: a base (radix) used to convert strings to integer values,
// the default base is 10 (i.e. decimal) (optional)
// value-name: the name of the argument value (to be shown in the help,
// (optional)
// group: when specified on a struct field, makes the struct field
// a separate group with the given name (optional).
// command: when specified on a struct field, makes the struct field
// a (sub)command with the given name (optional).
// name: the display name of the command. This name is the name
// shown in the builtin generated help and can be used
// to provide a more informative title of a command. If not
// specified this defaults to the name given in the command
// command tag (optional).
// Either short: or 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. The
// only real difference is in how your options will appear in the builtin
// generated help. All options in a particular group are shown together in the
// help under the name of the 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 toplevel 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 specifiy 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 Command interface, then its Execute method will be run providing the
// remaining arguments.
// Command structs can have options which become valid to parse after the
// command has been specified on the command line. It is currently not valid
// to specify options from the parent level of the command after the command
// name has occurred. Thus, given a toplevel option "-v" and a command "add":
// Valid: ./app -v add
// Invalid: ./app add -v
package flags