README
¶
rsc.io/getopt
[For full package documentation, see https://godoc.org/rsc.io/getopt.]
package getopt // import "rsc.io/getopt"
Package getopt parses command lines using getopt(3) syntax. It is a
replacement for flag.Parse but still expects flags themselves to be defined
in package flag.
Flags defined with one-letter names are available as short flags (invoked
using one dash, as in -x) and all flags are available as long flags (invoked
using two dashes, as in --x or --xylophone).
To use, define flags as usual with package flag. Then introduce any aliases
by calling getopt.Alias:
getopt.Alias("v", "verbose")
Or call getopt.Aliases to define a list of aliases:
getopt.Aliases(
"v", "verbose",
"x", "xylophone",
)
One name in each pair must already be defined in package flag (so either "v" or "verbose", and also either "x" or "xylophone").
Then parse the command-line:
getopt.Parse()
If it encounters an error, Parse calls flag.Usage and then exits the
program.
When writing a custom flag.Usage function, call getopt.PrintDefaults instead
of flag.PrintDefaults to get a usage message that includes the
names of aliases in flag descriptions.
At initialization time, package getopt installs a new flag.Usage that is the same
as the default flag.Usage except that it calls getopt.PrintDefaults instead
of flag.PrintDefaults.
This package also defines a FlagSet wrapping the standard flag.FlagSet.
Caveat
In general Go flag parsing is preferred for new programs, because it is not
as pedantic about the number of dashes used to invoke a flag (you can write
-verbose or --verbose and the program does not care). This package is meant
to be used in situations where, for legacy reasons, it is important to use
exactly getopt(3) syntax, such as when rewriting in Go an existing tool that
already uses getopt(3).
Documentation
¶
Overview ¶
Package getopt parses command lines using getopt(3) syntax. It is a replacement for flag.Parse but still expects flags themselves to be defined in package flag.
Flags defined with one-letter names are available as short flags (invoked using one dash, as in -x) and all flags are available as long flags (invoked using two dashes, as in --x or --xylophone).
To use, define flags as usual with package flag. Then introduce any aliases by calling getopt.Alias:
getopt.Alias("n", "dry-run")
getopt.Alias("v", "verbose")
Or call getopt.Aliases to define a list of aliases:
getopt.Aliases( "n", "dry-run", "v", "verbose", )
One name in each pair must already be defined in package flag (so either "n" or "dry-run", and also either "v" or "verbose").
Then parse the command-line:
getopt.Parse()
If it encounters an error, Parse calls flag.Usage and then exits the program.
When writing a custom flag.Usage function, call getopt.PrintDefaults instead of flag.PrintDefaults to get a usage message that includes the names of aliases in flag descriptions.
At initialization time, this package installs a new flag.Usage that is the same as the default flag.Usage except that it calls getopt.PrintDefaults instead of flag.PrintDefaults.
This package also defines a FlagSet wrapping the standard flag.FlagSet.
Caveat ¶
In general Go flag parsing is preferred for new programs, because it is not as pedantic about the number of dashes used to invoke a flag (you can write -verbose or --verbose and the program does not care). This package is meant to be used in situations where, for legacy reasons, it is important to use exactly getopt(3) syntax, such as when rewriting in Go an existing tool that already uses getopt(3).
Index ¶
- func Alias(short, long string)
- func Aliases(list ...string)
- func Parse()
- func PrintDefaults()
- type FlagSet
- func (f *FlagSet) Alias(short, long string)
- func (f *FlagSet) Aliases(list ...string)
- func (f *FlagSet) Init(name string, errorHandling flag.ErrorHandling)
- func (f *FlagSet) Lookup(name string) *flag.Flag
- func (f *FlagSet) Parse(args []string) error
- func (f *FlagSet) PrintDefaults()
- func (f *FlagSet) SetOutput(output io.Writer)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Alias ¶
func Alias(short, long string)
Alias introduces an alias for an existing flag name. The short name must be a single letter, and the long name must be multiple letters. Exactly one name must be defined as a flag already: the undefined name is introduced as an alias for the defined name. Alias panics if both names are already defined or if both are undefined.
For example, if a flag named "v" is already defined using package flag, then it is available as -v (or --v). Calling Alias("v", "verbose") makes the same flag also available as --verbose.
func Aliases ¶
func Aliases(list ...string)
Aliases introduces zero or more aliases. The argument list must consist of an even number of strings making up a sequence of short, long pairs to be passed to Alias.
func PrintDefaults ¶
func PrintDefaults()
PrintDefaults is like flag.PrintDefaults but includes information about short/long alias pairs and prints the correct syntax for long flags.
Types ¶
type FlagSet ¶
A FlagSet is a set of defined flags. It wraps and provides the same interface as flag.FlagSet but parses command line arguments using getopt syntax.
Note that "go doc" shows only the methods customized by package getopt; FlagSet also provides all the methods of the embedded flag.FlagSet, like Bool, Int, NArg, and so on.
var CommandLine FlagSet
func NewFlagSet ¶
func NewFlagSet(name string, errorHandling flag.ErrorHandling) *FlagSet
NewFlagSet returns a new, empty flag set with the specified name and error handling property.
func (*FlagSet) Alias ¶
Alias introduces an alias for an existing flag name. The short name must be a single letter, and the long name must be multiple letters. Exactly one name must be defined as a flag already: the undefined name is introduced as an alias for the defined name. Alias panics if both names are already defined or if both are undefined.
For example, if a flag named "v" is already defined using package flag, then it is available as -v (or --v). Calling Alias("v", "verbose") makes the same flag also available as --verbose.
func (*FlagSet) Aliases ¶
Aliases introduces zero or more aliases. The argument list must consist of an even number of strings making up a sequence of short, long pairs to be passed to Alias.
func (*FlagSet) Init ¶
func (f *FlagSet) Init(name string, errorHandling flag.ErrorHandling)
Init sets the name and error handling proprety for a flag set.
func (*FlagSet) Lookup ¶
Lookup returns the Flag structure of the named flag, returning nil if none exists. If name is a defined alias for a defined flag, Lookup returns the original flag; in this case the Name field in the result will differ from the name passed to Lookup.
func (*FlagSet) Parse ¶
Parse parses flag definitions from the argument list, which should not include the command name. Parse must be called after all flags and aliases in the FlagSet are defined and before flags are accessed by the program. The return value will be flag.ErrHelp if -h or --help were used but not defined.
func (*FlagSet) PrintDefaults ¶
func (f *FlagSet) PrintDefaults()
PrintDefaults is like flag.PrintDefaults but includes information about short/long alias pairs and prints the correct syntax for long flags.
Source Files