golf

README

golf

Go long flag: a light-weight long and short command line option parser.

Description

golf is a modest options parsing library for Go command line interface programs. Meant to be small, like flag included in Go's standard library, golf does not re-architect how you make command line programs, nor request you use a DSL for describing your command line program. It merely allows you to specify which options your program accepts, and provides the values to your program based on the user's arguments.

• Fully POSIX-compliant flags, including short & long flags.
• Helpful functions for printing help and usage information.
• Optional space between short flag and its argument.
• No new concepts to learn beyond typical use of flag library.
• Supports GNU extension allowing flags to appear intermixed with other command line arguments.

Usage Example

Documentation is available via .

Basic usage is nearly identical to the standard library flag package. There are only a very small set of features this library does not support from the flag library. However, it provides all the functions that most command line programs would require.

golf is designed such that you can change every flag package prefix to golf, recompile your program, and be able to use more POSIX friendly command line options. Both Type and TypeVar style flag declarations are supported, as shown below:

var optVerbose bool

optLimit := golf.Int("limit", 0, "Limit output to specified number of lines")
golf.BoolVar(&optVerbose, "v", false, "Display verbose output")

golf.Parse()

When the flag package prefix is changed to golf, your program will require a single-hyphen when the flag name is one rune long, and a double-hyphen prefix when the flag is more than one rune long.

$ example -v --limit 3

Features

golf allows specifying both a short and a long flag name by calling the same function stem but with a P suffix, as shown below. When declaring a short and long flag pair, the short flag type is a rune, to prevent accidentally initializing a command line flag pair with two multi-rune strings, which is not allowed. (The reason for this compromise is because the command line flag declaration pattern used by flag provides no means for signalling an error.)

optRaw := golf.BoolP('r', "raw", false, "Display raw output")
optServer := golf.StringP('s', "server", "", "Send query to specified server")
optTheshold := golf.FloatP('t', "threshold", 0, "Set minimum threshold")
optVerbose := golf.BoolP('v', "verbose", false, "Display verbose output")
golf.Parse()

All of the below examples result in the same flag values being set:

$ example -sfoo.example.com -t3.14
$ example -s foo.example.com -t 3.14
$ example --server foo.example.com --threshold 3.14

golf allows boolean options to be grouped together when using their single letter equivalents, such as common in many UNIX programs. all of the following are equivalent:

$ example -rv -t 4 -shost.example.com
$ example -rv -t4 -s host.example.com
$ example -rv --threshold 4 --server host.example.com
$ example -v -r --threshold 4 --server host.example.com

golf also allow concatenation of one or more boolean short flags with at most one short flag that requires an argument provided the flag that requires the argument is the last flag in the parameter. Both of the following are legal, although the second example happens to parse oddly in my brain, because v and t appear grouped closer than the t and the 4. Nevertheless, both are equivalent and unambiguous:

$ example -vt4
$ example -vt 4

To prevent ambiguities, however, golf does not allow placing any additional flags after a flag that requires an argument, even if it may appear to be legal, in the same argument. For instance, if the i takes an integer and the s flag takes a string, this will still result in a parsing error:

$ example -i4sfoo.example.com
ERROR: strconv.ParseInt: parsing "4sfoo.example.com": invalid syntax

This however is legal:

$ example -i4 -sfoo.example.com

In an attempt to be largely compatible with the flag library, specifying an option flag has no error return value, so attempting to create a flag with illegal arguments will panic. While causing a panic is poor practice for a library, if command line options are not correctly defined by the program the case will be caught early by running the program.

This library supports a common practice in GNU command line argument parsing that allows command line flags and command line arguments to be intermixed. For instance, the following invocations would be equivalent.

$ example -t 3.14 arg1 arg2
$ example arg1 -t3.14 arg2
$ example arg1 arg2 -t 3.14

Help Example

Invoking golf.Usage() will display the program name, followed by a list of command line option flags. The short and long flag names are displayed if they are both defined, otherwise, just the short or the long is displayed. After the flag name will be a token representing the expected value data type, so the user knows what type of parsing will be invoked on any value provided for that flag.

On a separate line after each flag is printed a tab character, followed by the description and the default value for that flag.

example version 1.2.3
	example program

Usage of example:
  -h, --help
	Display command line help and exit (default: false)
  -l, --limit int
	Limit output to specified number of lines (default: 0)
  -q, --quiet
	Do not print intermediate errors to stderr (default: false)
  -v, --verbose
	Print verbose output to stderr (default: false)
  -V, --version
	Print version to stderr and exit (default: false)
  -s, --servers string
	Some string (default: host1,host2)
  -t string
	Another string (default: host3,host4)
  --flubbers string
	Yet another string (default: host5)

TODO

• Support remaining functions from flag package in the standard library.

Documentation

Index

• Variables
• func Arg(i int) string
• func Args() []string
• func Bool(flag string, value bool, description string) *bool
• func BoolP(short rune, long string, value bool, description string) *bool
• func BoolVar(pv *bool, flag string, value bool, description string)
• func BoolVarP(pv *bool, short rune, long string, value bool, description string)
• func Duration(flag string, value time.Duration, description string) *time.Duration
• func DurationP(short rune, long string, value time.Duration, description string) *time.Duration
• func DurationVar(pv *time.Duration, flag string, value time.Duration, description string)
• func DurationVarP(pv *time.Duration, short rune, long string, value time.Duration, ...)
• func Float(flag string, value float64, description string) *float64
• func FloatP(short rune, long string, value float64, description string) *float64
• func FloatVar(pv *float64, flag string, value float64, description string)
• func FloatVarP(pv *float64, short rune, long string, value float64, description string)
• func Int(flag string, value int, description string) *int
• func Int64(flag string, value int64, description string) *int64
• func Int64P(short rune, long string, value int64, description string) *int64
• func Int64Var(pv *int64, flag string, value int64, description string)
• func Int64VarP(pv *int64, short rune, long string, value int64, description string)
• func IntP(short rune, long string, value int, description string) *int
• func IntVar(pv *int, flag string, value int, description string)
• func IntVarP(pv *int, short rune, long string, value int, description string)
• func NArg() int
• func NFlag() int
• func Parse()
• func Parsed() bool
• func PrintDefaults()
• func PrintDefaultsTo(w io.Writer)
• func String(flag string, value string, description string) *string
• func StringP(short rune, long string, value string, description string) *string
• func StringVar(pv *string, flag string, value string, description string)
• func StringVarP(pv *string, short rune, long string, value string, description string)
• func Uint(flag string, value uint, description string) *uint
• func Uint64(flag string, value uint64, description string) *uint64
• func Uint64P(short rune, long string, value uint64, description string) *uint64
• func Uint64Var(pv *uint64, flag string, value uint64, description string)
• func Uint64VarP(pv *uint64, short rune, long string, value uint64, description string)
• func UintP(short rune, long string, value uint, description string) *uint
• func UintVar(pv *uint, flag string, value uint, description string)
• func UintVarP(pv *uint, short rune, long string, value uint, description string)
• func Wrap(input string) string
• type LineWrapper
  • func (w LineWrapper) Wrap(input string) string

Variables

var Usage = func() {
	fmt.Fprintf(os.Stderr, "Usage of %s:\n", os.Args[0])
	PrintDefaults()
}

Usage prints command line usage to stderr, but may be overridden by programs that need to customize the usage information.

Functions

func Arg

func Arg(i int) string

Arg returns the i'th command-line argument. Arg(0) is the first remaining argument after flags have been processed. Arg returns an empty string if the requested element does not exist.

func Args

func Args() []string

Args returns the non-flag command-line arguments.

func Bool

func Bool(flag string, value bool, description string) *bool

Bool returns a pointer to a bool command line option, allowing for either a short or a long flag. If both are desired, use the BoolP function.

func BoolP

func BoolP(short rune, long string, value bool, description string) *bool

BoolP returns a pointer to a bool command line option, allowing for both a short and a long flag.

func BoolVar

func BoolVar(pv *bool, flag string, value bool, description string)

BoolVar binds an existing boolean variable to a flag, allowing for either a short or a long flag. If both are desired, use the BoolVarP function.

func BoolVarP

func BoolVarP(pv *bool, short rune, long string, value bool, description string)

BoolVarP binds an existing boolean variable to a flag, allowing for both a short and a long flag.

func Duration

func Duration(flag string, value time.Duration, description string) *time.Duration

Duration returns a pointer to a time.Duration command line option, allowing for either a short or a long flag. If both are desired, use the DurationP function.

func DurationP

func DurationP(short rune, long string, value time.Duration, description string) *time.Duration

DurationP returns a pointer to a time.Duration command line option, allowing for both a short and a long flag.

func DurationVar

func DurationVar(pv *time.Duration, flag string, value time.Duration, description string)

DurationVar binds an existing time.Duration variable to a flag, allowing for either a short or a long flag. If both are desired, use the DurationVarP function.

func DurationVarP

func DurationVarP(pv *time.Duration, short rune, long string, value time.Duration, description string)

DurationVarP binds an existing time.Duration variable to a flag, allowing for both a short and a long flag.

func Float

func Float(flag string, value float64, description string) *float64

Float returns a pointer to a float64 command line option, allowing for either a short or a long flag. If both are desired, use the FloatP function.

func FloatP

func FloatP(short rune, long string, value float64, description string) *float64

FloatP returns a pointer to a float64 command line option, allowing for both a short and a long flag.

func FloatVar

func FloatVar(pv *float64, flag string, value float64, description string)

FloatVar binds an existing float64 variable to a flag, allowing for either a short or a long flag. If both are desired, use the FloatVarP function.

func FloatVarP

func FloatVarP(pv *float64, short rune, long string, value float64, description string)

FloatVarP binds an existing float64 variable to a flag, allowing for both a short and a long flag.

func Int

func Int(flag string, value int, description string) *int

Int returns a pointer to a int command line option, allowing for either a short or a long flag. If both are desired, use the IntP function.

func Int64

func Int64(flag string, value int64, description string) *int64

Int64 returns a pointer to a int64 command line option, allowing for either a short or a long flag. If both are desired, use the Int64P function.

func Int64P

func Int64P(short rune, long string, value int64, description string) *int64

Int64P returns a pointer to a int64 command line option, allowing for both a short and a long flag.

func Int64Var

func Int64Var(pv *int64, flag string, value int64, description string)

Int64Var binds an existing int64 variable to a flag, allowing for either a short or a long flag. If both are desired, use the Int64VarP function.

func Int64VarP

func Int64VarP(pv *int64, short rune, long string, value int64, description string)

Int64VarP binds an existing int64 variable to a flag, allowing for both a short and a long flag.

func IntP

func IntP(short rune, long string, value int, description string) *int

IntP returns a pointer to a int command line option, allowing for both a short and a long flag.

func IntVar

func IntVar(pv *int, flag string, value int, description string)

IntVar binds an existing int variable to a flag, allowing for either a short or a long flag. If both are desired, use the IntVarP function.

func IntVarP

func IntVarP(pv *int, short rune, long string, value int, description string)

IntVarP binds an existing int variable to a flag, allowing for both a short and a long flag.

func NArg

func NArg() int

NArg returns the number of arguments remaining after flags have been processed.

func NFlag

func NFlag() int

NFlag returns the number of command-line flags that have been set.

func Parse

func Parse()

Parse parses the command line. On error, displays the usage of the command line and exits the program with status code 2.

func Parsed

func Parsed() bool

Parsed reports whether the command-line flags have been parsed.

func PrintDefaults

func PrintDefaults()

PrintDefaults prints to standard error, a usage message showing the default settings of all defined command-line flags.

func PrintDefaultsTo

func PrintDefaultsTo(w io.Writer)

PrintDefaultsTo prints to w, a usage message showing the default settings of all defined command-line flags.

func String

func String(flag string, value string, description string) *string

String returns a postringer to a string command line option, allowing for either a short or a long flag. If both are desired, use the StringP function.

func StringP

func StringP(short rune, long string, value string, description string) *string

StringP returns a postringer to a string command line option, allowing for both a short and a long flag.

func StringVar

func StringVar(pv *string, flag string, value string, description string)

StringVar binds an existing string variable to a flag, allowing for either a short or a long flag. If both are desired, use the StringVarP function.

func StringVarP

func StringVarP(pv *string, short rune, long string, value string, description string)

StringVarP binds an existing string variable to a flag, allowing for both a short and a long flag.

func Uint

func Uint(flag string, value uint, description string) *uint

Uint returns a pouinter to a uint command line option, allowing for either a short or a long flag. If both are desired, use the UintP function.

func Uint64

func Uint64(flag string, value uint64, description string) *uint64

Uint64 returns a pointer to a uint64 command line option, allowing for either a short or a long flag. If both are desired, use the Uint64P function.

func Uint64P

func Uint64P(short rune, long string, value uint64, description string) *uint64

Uint64P returns a pointer to a uint64 command line option, allowing for both a short and a long flag.

func Uint64Var

func Uint64Var(pv *uint64, flag string, value uint64, description string)

Uint64Var binds an existing uint64 variable to a flag, allowing for either a short or a long flag. If both are desired, use the Uint64VarP function.

func Uint64VarP

func Uint64VarP(pv *uint64, short rune, long string, value uint64, description string)

Uint64VarP binds an existing uint64 variable to a flag, allowing for both a short and a long flag.

func UintP

func UintP(short rune, long string, value uint, description string) *uint

UintP returns a pouinter to a uint command line option, allowing for both a short and a long flag.

func UintVar

func UintVar(pv *uint, flag string, value uint, description string)

UintVar binds an existing uint variable to a flag, allowing for either a short or a long flag. If both are desired, use the UintVarP function.

func UintVarP

func UintVarP(pv *uint, short rune, long string, value uint, description string)

UintVarP binds an existing uint variable to a flag, allowing for both a short and a long flag.

func Wrap

func Wrap(input string) string

Wrap returns input string with leading and trailing whitespace removed, with the exception of exactly one trailing newline character, and intraline whitespace normalized to single spaces, except in cases where a word would exceed a line length of 80 columns, in which case a newline will be used rather than a space.

Types

type LineWrapper

type LineWrapper struct {
	// Prefix is the optional string to be places at the start of every output
	// line.
	Prefix string

	// Max is the optional maximum number of columns to wrap the text to. When
	// 0, the LineWrapper will wrap lines fit on in 80 columns.
	Max int
}

LineWrapper wraps input strings to specified maximum number of columns, or when zero, 80 columns. When Prefix is not empty string, it prefixes each line with the prefix string.

func (LineWrapper) Wrap

func (w LineWrapper) Wrap(input string) string