Repository files navigation

Package getopt provides traditional getopt processing for implementingcommands that use traditional command lines. The standard Go flag packagecannot be used to write a program that parses flags the way ls or ssh does,for example. There are two versions, v1 and v2, both named getopt, thatuse the following import paths:

"github.com/pborman/getopt"     // version 1"github.com/pborman/getopt/v2"  // version 2

This README describes version 2 of the package, which has a simplified API.

Getopt supports functionality found in both the standard BSD getopt as wellas (one of the many versions of) the GNU getopt_long. Being a Go package,this package makes common usage easy, but still enables more controlled usageif needed.

Typical usage:

Declare flags and have getopt return pointers to the values.helpFlag := getopt.Bool('?', "display help")cmdFlag := getopt.StringLong("command", 'c', "default", "the command")Declare flags against existing variables.var (fileName = "/the/default/path"timeout = time.Second * 5verbose bool)func init() {getopt.Flag(&verbose, 'v', "be verbose")getopt.FlagLong(&fileName, "path", 0, "the path")getopt.FlagLong(&timeout, "timeout", 't', "some timeout")}func main() {Parse the program argumentsgetopt.Parse()Get the remaining positional parametersargs := getopt.Args()...

If you don't want the program to exit on error, use getopt.Getopt:

err := getopt.Getopt(nil)if err != nil {code to handle errorfmt.Fprintln(os.Stderr, err)}

Support is provided for both short (-f) and long (--flag) options. A singleoption may have both a short and a long name. Each option may be a flag or avalue. A value takes an argument.

Declaring no long names causes this package to process arguments like thetraditional BSD getopt.

Short flags may be combined into a single parameter. For example, "-a -b -c"may also be expressed "-abc". Long flags must stand on their own "--alpha--beta"

Values require an argument. For short options the argument may either beimmediately following the short name or as the next argument. Only one shortvalue may be combined with short flags in a single argument; the short valuemust be after all short flags. For example, if f is a flag and v is a value,then:

-vvalue    (sets v to "value")-v value   (sets v to "value")-fvvalue   (sets f, and sets v to "value")-fv value  (sets f, and sets v to "value")-vf value  (set v to "f" and value is the first parameter)

For the long value option val:

--val value (sets val to "value")--val=value (sets val to "value")--valvalue  (invalid option "valvalue")

Values with an optional value only set the value if the value is part of thesame argument. In any event, the option count is increased and the option ismarked as seen.

-v -f          (sets v and f as being seen)-vvalue -f     (sets v to "value" and sets f)--val -f       (sets v and f as being seen)--val=value -f (sets v to "value" and sets f)

There is no convience function defined for making the value optional. TheSetOptional method must be called on the actual Option.

v := String("val", 'v', "", "the optional v")Lookup("v").SetOptional()var s stringFlagLong(&s, "val", 'v', "the optional v).SetOptional()

Parsing continues until the first non-option or "--" is encountered.

The short name "-" can be used, but it either is specified as "-" or as partof a group of options, for example "-f-". If there are no long optionsspecified then "--f" could also be used. If "-" is not declared as an optionthen the single "-" will also terminate the option processing but unlike"--", the "-" will be part of the remaining arguments.

Normally the parsing is performed by calling the Parse function. If it isimportant to see the order of the options then the Getopt function should beused. The standard Parse function does the equivalent of:

func Parse() {if err := getopt.Getopt(os.Args, nil); err != nil {fmt.Fprintln(os.Stderr, err)s.usage()os.Exit(1)}}

When calling Getopt it is the responsibility of the caller to print anyerrors.

Normally the default option set, CommandLine, is used. Other option sets maybe created with New.

After parsing, the sets Args will contain the non-option arguments. If anerror is encountered then Args will begin with argument that caused theerror.

It is valid to call a set's Parse a second time to amend the current set offlags or values. As an example:

var a = getopt.Bool('a', "", "The a flag")var b = getopt.Bool('b', "", "The a flag")var cmd = ""var opts = getopt.CommandLineopts.Parse(os.Args)if opts.NArgs() > 0 {cmd = opts.Arg(0)opts.Parse(opts.Args())}

If called with set to { "prog", "-a", "cmd", "-b", "arg" } then both a andb would be set, cmd would be set to "cmd", and opts.Args() would return {"arg" }.

Unless an option type explicitly prohibits it, an option may appear more thanonce in the arguments. The last value provided to the option is the value.

The Flag and FlagLong functions support most standard Go types. For thelist, see the description of FlagLong below for a list of supported types.

There are also helper routines to allow single line flag declarations. Thesetypes are: Bool, Counter, Duration, Enum, Int16, Int32, Int64, Int, List,Signed, String, Uint16, Uint32, Uint64, Uint, and Unsigned.

Each comes in a short and long flavor, e.g., Bool and BoolLong and includefunctions to set the flags on the standard command line or for a specific Setof flags.

Except for the Counter, Enum, Signed and Unsigned types, all of these typescan be declared using Flag and FlagLong by passing in a pointer to theappropriate type.

A pointer to any type that implements the Value interface may be passed toFlag or FlagLong.

All non-flag options are created with a "valuehelp" as the last parameter.Valuehelp should be 0, 1, or 2 strings. The first string, if provided, isthe usage message for the option. If the second string, if provided, is thename to use for the value when displaying the usage. If not provided theterm "value" is assumed.

The usage message for the option created with

StringLong("option", 'o', "defval", "a string of letters")

is

-o, -option=value

while the usage message for the option created with

StringLong("option", 'o', "defval", "a string of letters", "string")

is

-o, -option=string