options

README

Options - self documenting go-lang command line parsing

The list of options a program wishes to use is specified as a lengthy, multi-line string. This string also serves as the help-string for the options.

Here is an example option specification:

Usage: example-tool
A short description of the command
--
flag        --flag,-f,FLAG           A description for this flag
option=     --option=,-o=,OPTION=    A description for this option
                                     the description continues here
!required=  --required,-r=,REQUIRED= A required option
--
env_var=    ENV_VAR=                 An environment variable
--
help        help,h                   Show this help message
run         run                      Run some function
--
Additional help for options or defaults etc. go here.

Read the documentation

Notes

Forked and modified from github.com/fd/options. I've retained the original license. Sadly, I didn't do a proper fork; so, my list of changes list is lost.

The godoc is here.

Documentation

Overview

Package options implements a self-documenting command line options parsing framework.

The list of options a program wishes to use is specified as a lengthy, multi-line string. This string also serves as the help-string for the options.

Here is an example option specification:

usage: example-tool
A short description of the command
--
flag        --flag,-f,FLAG           A description for this flag
option=     --option=,-o=,OPTION=    A description for this option
                                     the description continues here
!required=  --required,-r=,REQUIRED= A required option
--
env_var=    ENV_VAR=                 An environment variable
--
help        help,h                   Show this help message
run         run                      Run some function
--
Additional help for options or defaults etc. go here.

Index

• type Options
  • func (opts *Options) Get(nm string) (string, bool)
  • func (opts *Options) GetBool(nm string) bool
  • func (opts *Options) GetInt(nm string) (int64, bool)
  • func (opts *Options) GetMulti(nm string) []string
  • func (opts *Options) GetUint(nm string) (uint64, bool)
  • func (opts *Options) IsSet(nm string) bool
• type Spec
  • func MustParse(desc string) *Spec
  • func Parse(desc string) (spec *Spec, err error)
  • func (spec *Spec) Interpret(args []string, environ []string) (o *Options, err error)
  • func (this *Spec) MustInterpret(args []string, environ []string) *Options
  • func (spec *Spec) PrintUsage()
  • func (spec *Spec) PrintUsageAndExit()
  • func (spec *Spec) PrintUsageWithError(err error)

Examples

• Parse

Types

type Options

type Options struct {
	Command string
	Args    []string
	// contains filtered or unexported fields
}

Representation of parsed command line arguments according to a given option specification

func (*Options) Get

func (opts *Options) Get(nm string) (string, bool)

Return the option corresponding to 'nm'. If the option is not set (provided on the command line), the bool retval will be False.

func (*Options) GetBool

func (opts *Options) GetBool(nm string) bool

Interpret the option corresponding to the key 'nm' as a Bool and parse it. A failed parse defaults to False.

func (*Options) GetInt

func (opts *Options) GetInt(nm string) (int64, bool)

Interpret the option corresponding to the key 'nm' as a signed integer (auto-detected base). The second retval will be false if the parse fails or the key is not found.

func (*Options) GetMulti

func (opts *Options) GetMulti(nm string) []string

For options that are providd multiple times, return all of them in a slice. A nil slice implies the option was not set on the command line.

func (*Options) GetUint

func (opts *Options) GetUint(nm string) (uint64, bool)

Interpret the option corresponding to the key 'nm' as an unsigned integer (auto-detected base). The second retval will be false if the parse fails or the key is not found.

func (*Options) IsSet

func (opts *Options) IsSet(nm string) bool

Return true if the option with the key 'nm' is set (i.e., provided on the command line).

type Spec

type Spec struct {
	// contains filtered or unexported fields
}

Representation of a parsed option specification.

func MustParse

func MustParse(desc string) *Spec

Parse a spec string and die if it fails

func Parse

func Parse(desc string) (spec *Spec, err error)

Parse a spec string and return a Spec object

Example

spec, err := Parse(`
    usage: example-tool
    A short description of the command
    --
    flag        --flag,-f,FLAG           A description for this flag
    option=     --option=,-o=,OPTION=    A description for this option
                                         the description continues here
    !required=  --required,-r=,REQUIRED= A required option
    --
    env_var=    ENV_VAR=                 An environment variable
    --
    help        help,h                   Show this help message
    run         run                      Run some function
    --
    More freestyle text
    `)
if err != nil {
	spec.PrintUsageWithError(err)
}

opts, err := spec.Interpret([]string{"example-tool", "--required", "hello world"}, []string{})
if err != nil {
	spec.PrintUsageWithError(err)
}

v, _ := opts.Get("required")
fmt.Printf("required: %s", v)

Output:

required: hello world

func (*Spec) Interpret

func (spec *Spec) Interpret(args []string, environ []string) (o *Options, err error)

Parse the command line arguments in 'args' and the environment variables in 'environ'. Return the resulting, parsed options in 'o' and any error in 'err'.

func (*Spec) MustInterpret

func (this *Spec) MustInterpret(args []string, environ []string) *Options

Parse the command line arguments in 'args' and the environment variables in 'environ'. This expects the parsing to succeed and exits with usage string and error if the parsing fails.

func (*Spec) PrintUsage

func (spec *Spec) PrintUsage()

Print the usage string to STDOUT

func (*Spec) PrintUsageAndExit

func (spec *Spec) PrintUsageAndExit()

Print the usage string to STDOUT and exit with a non-zero code.

func (*Spec) PrintUsageWithError

func (spec *Spec) PrintUsageWithError(err error)

Print the error string corresponding to 'err' and then show the usage string. Both are sent to STDERR. Exit with a non-zero code.