options

Overview ¶

Package options provides a command line option parser.

This package is meant as an alternative to the core flag package. It is more powerful without attempting to support every possible feature some parsing library ever introduced. It is arguably easier to use.

Usage:

Create an OptionSpec that documents your program's allowed flags. This begins with a free-text synopsis of your command line interface, then a line containing only two dashes, then a series of option specifications:

import "github.com/gaal/go-options/options"
s := options.NewOptions(`
cat - concatenate files to standard input
Usage: cat [OPTIONS] file...
This version of cat supports character set conversion.
Fancifully, you can say "-r 3" and have everything told you three times.
--
n,numerate,number     number input lines
e,escape              escape nonprintable characters
i,input-encoding=     charset input is encoded in [utf-8]
o,output-encoding=    charset output is encoded in [utf-8]
r,repeat=             repeat every line some number of times [1]
v,verbose             be verbose
`)

Then parse the command line:

opt := s.Parse(os.Args[1:])

This return value is of Options type and has the parsed command line (for an alternate way of parsing the command line, see the "Callback interface" descibed below).

Options may have any number of aliases; the last one is the "canonical" name and the one your program must use when reading values.

opt.Get("input-encoding")  // Returns "utf-8", or whatever user set.
opt.Get("i")               // Error! No option with that canonical name.
opt.Get("number")          // Returns "" if the user didn't specify it.

Get returns a string. Several very simple conversions are provided but you are encouraged to write your own if you need more.

opt.GetBool("escape")      // false (by default)
opt.GetBool("number")      // false (by default)
opt.GetInt("repeat")       // 1 (by default)

Options either take a required argument or take no argument. Non-argument options have useful values exposed as bool and ints.

// cat -v -v -v, or alternatively,
// cat -vvv
opt.GetBool("verbose")     // true
opt.GetInt("verbose")      // 3

The user can say either "--foo=bar" or "--foo bar". Short options may be clustered; "-abc foo" means the same as "-a -b -c=foo".

Parsing stops if "--" is given on the command line.

The "Extra" field of the returned Options contains all non-option command line input. In the case of a cat command, this would be the filenames to concat.

By default, options permits such extra values. Setting UnknownValuesFatal causes it to panic when it enconters them instead.

The "Flags" field of the returned Options contains the series of flags as given on the command line, including repeated ones (which are suppressed in opt -- it only contains the last value). This allows you to do your own handling of repeated options easily.

By default, options does not permit unknown flags. Setting UnknownOptionsFatal to false causes them to be recorded in "flags" instead. Note that since they have no canonical name, they cannot be accessed via opt. Also note that since options does not know about the meaning of these flags, it has to guess whether they consume the next argument or not. This is currently done naively by peeking at the first character of the next argument.

Callback interface:

If you prefer a more type-safe, static interface to your options, you can use options to get that too. Instead of looking at opt and friends, set OptionSpec.ParseCallback:

var (foo string; bar int; baz float64; lst []string; verbose bool)

func myParseCallback(spec *OptionSpec, option string, argument *string) {
  if argument != nil {
    switch option {
    case "string-option":  foo = *argument
    case "int-option":     fmt.Sscanf(*argument, "%d", &bar)
    case "decimal-option": fmt.Sscanf(*argument, "%f", &baz)
    case "list-option":    lst = append(lst, *argument)
    default: spec.PrintUsageAndExit("Unknown option: " + option)
    }
  } else {
    switch option {
    case "verbose": verbose = true
    case "help":    spec.PrintUsageAndExit("")  // No error
    default:        spec.PrintUsageAndExit("Unknown option: " + option)
  }
}

spec.ParseCallback = myParseCallback
opt := spec.Parse(os.Args[1:])
// Note that the opt.Get won't work when using a custom parse callback.