getopt style option parsing for Go
Switch branches/tags
Nothing to show
Clone or download
Permalink
Failed to load latest commit information.
v2 Add a pointer in the documentation to the options package. Aug 11, 2018
AUTHORS Initial AUTHORS and LICENSE files Feb 12, 2013
CONTRIBUTING.md Add CONTRIBUTING.md per Google lawyers. Feb 16, 2016
LICENSE Update to version 2 of the getopt package. This version eliminates all Jan 11, 2017
README.md Fix formatting Jan 11, 2017
bool.go Change to Google license Feb 21, 2013
bool_test.go Change to Google license Feb 21, 2013
breakup_test.go Change to Google license Feb 21, 2013
counter.go Change to Google license Feb 21, 2013
counter_test.go Change to Google license Feb 21, 2013
duration.go Add duration flag type Oct 20, 2015
duration_test.go Add duration flag type Oct 20, 2015
enum.go Change to Google license Feb 21, 2013
enum_test.go Change to Google license Feb 21, 2013
error.go Change to Google license Feb 21, 2013
getopt.go Remove unreachable panics. Add blank line after generic.go copyright. Jan 12, 2017
int.go Change to Google license Feb 21, 2013
int16.go Change to Google license Feb 21, 2013
int16_test.go Change to Google license Feb 21, 2013
int32.go Change to Google license Feb 21, 2013
int32_test.go Change to Google license Feb 21, 2013
int64.go Change to Google license Feb 21, 2013
int64_test.go Change to Google license Feb 21, 2013
int_test.go Change to Google license Feb 21, 2013
list.go Change to Google license Feb 21, 2013
list_test.go Change to Google license Feb 21, 2013
option.go Update to version 2 of the getopt package. This version eliminates all Jan 11, 2017
set.go Update to version 2 of the getopt package. This version eliminates all Jan 11, 2017
signed.go Update to version 2 of the getopt package. This version eliminates all Jan 11, 2017
signed_test.go Change to Google license Feb 21, 2013
string.go Change to Google license Feb 21, 2013
string_test.go Change to Google license Feb 21, 2013
uint.go Change to Google license Feb 21, 2013
uint16.go Change to Google license Feb 21, 2013
uint16_test.go Change to Google license Feb 21, 2013
uint32.go Change to Google license Feb 21, 2013
uint32_test.go Change to Google license Feb 21, 2013
uint64.go Change to Google license Feb 21, 2013
uint64_test.go Change to Google license Feb 21, 2013
uint_test.go Change to Google license Feb 21, 2013
unsigned.go Update to version 2 of the getopt package. This version eliminates all Jan 11, 2017
unsigned_test.go Change to Google license Feb 21, 2013
util_test.go Change to Google license Feb 21, 2013
var.go Update to version 2 of the getopt package. This version eliminates all Jan 11, 2017

README.md

getopt

Package getopt provides traditional getopt processing for implementing commands that use traditional command lines. The standard Go flag package cannot 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, that use 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.

Usage

Getopt supports functionality found in both the standard BSD getopt as well as (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 usage if 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 * 5
		verbose 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 arguments
		getopt.Parse()
		Get the remaining positional parameters
		args := 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 error
			fmt.Fprintln(os.Stderr, err)
		}

Flag Syntax

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

Declaring no long names causes this package to process arguments like the traditional 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 be immediately following the short name or as the next argument. Only one short value may be combined with short flags in a single argument; the short value must 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 the same argument. In any event, the option count is increased and the option is marked 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. The SetOptional method must be called on the actual Option.

	v := String("val", 'v', "", "the optional v")
	Lookup("v").SetOptional()

	var s string
	FlagLong(&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 part of a group of options, for example "-f-". If there are no long options specified then "--f" could also be used. If "-" is not declared as an option then the single "-" will also terminate the option processing but unlike "--", the "-" will be part of the remaining arguments.

Advanced Usage

Normally the parsing is performed by calling the Parse function. If it is important to see the order of the options then the Getopt function should be used. 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 any errors.

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

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

It is valid to call a set's Parse a second time to amend the current set of flags 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.CommandLine

	opts.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 and and b 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 than once in the arguments. The last value provided to the option is the value.

Builtin Types

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

There are also helper routines to allow single line flag declarations. These types 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 include functions to set the flags on the standard command line or for a specific Set of flags.

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

Declaring New Flag Types

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

VALUEHELP

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, is the usage message for the option. If the second string, if provided, is the name to use for the value when displaying the usage. If not provided the term "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