goopt

README

goopt

A getopt-like processor of command-line flags. It works much like the "flag" package, only it processes arguments in a way that is compatible with the getopt_long syntax, which is an extension of the syntax recommended by POSIX.

Example program

The example program named example/example.go, is meant to be more useful for someone trying to see how the package works. It comes with a makefile demonstrating how to do some nice tricks, such as enabling bash completion on your flags, and generating man pages and html versions of the man page (see the man page for the example program).

Test suite

The test suite is the file .test, which compiles and verifies the output of the program in the test-program directory, as well as the example program. You can configure git to run the test suite automatically by running the setup-git.sh script.

Documentation

Once the package is installed via goinstall, use the following to view the documentation:

godoc --http=:6060

If you installed it from github, you will want to do this from the source directory:

godoc --http=:6060 --path=.

This will run in the foreground, so do it in a terminal without anything important in it. Then you can go to http://localhost:6060/ and navigate via the package directory to the documentation or the left-hand navigation, depending on if it was goinstalled or run from a git clone.

Documentation

Index

• Variables
• func Alternatives(names, vs []string, help string) *string
• func Expand(x string) string
• func Flag(yes []string, no []string, helpyes, helpno string) *bool
• func Int(names []string, def int, help string) *int
• func IntWithLabel(names []string, def int, label string, help string) *int
• func NoArg(names []string, help string, process func() error)
• func OptArg(names []string, def, help string, process func(string) error)
• func Parse(extraopts func() []string) bool
• func ReqArg(names []string, argname, help string, process func(string) error)
• func String(names []string, def string, help string) *string
• func StringWithLabel(names []string, def string, label string, help string) *string
• func Strings(names []string, def string, help string) *[]string
• func VisitAllNames(f func(string))

Variables

var Args = make([]string, 0, 4)

This is the list of non-flag arguments after processing

var Author = ""

Redefine this to change the author of your program (used in the default man page)

var Description = func() string {
	return `To add a description to your program, define goopt.Description.

If you want paragraphs, just use two newlines in a row, like latex.`
}

Set the description used in the man page for your program. If you want paragraphs, use two newlines in a row (e.g. LaTeX)

var Help = func() string {
	h0 := new(bytes.Buffer)
	h := tabwriter.NewWriter(h0, 0, 8, 2, ' ', 0)
	if len(opts) > 1 {
		fmt.Fprintln(h, "Options:")
	}
	for _, o := range opts {
		fmt.Fprint(h, "  ")
		if len(o.shortnames) > 0 {
			for _, sn := range o.shortnames[0 : len(o.shortnames)-1] {
				fmt.Fprintf(h, "-%c, ", sn)
			}
			fmt.Fprintf(h, "-%c", o.shortnames[len(o.shortnames)-1])
			if o.allowsArg != nil {
				fmt.Fprintf(h, " %s", *o.allowsArg)
			}
		}
		fmt.Fprintf(h, "\t")
		if len(o.names) > 0 {
			for _, n := range o.names[0 : len(o.names)-1] {
				fmt.Fprintf(h, "%s, ", n)
			}
			fmt.Fprint(h, o.names[len(o.names)-1])
			if o.allowsArg != nil {
				fmt.Fprintf(h, "=%s", *o.allowsArg)
			}
		}
		fmt.Fprintf(h, "\t%v\n", Expand(o.help))
	}
	h.Flush()
	return h0.String()
}

Override the way help is displayed (not recommended)

var Suite = ""

Redefine this to change the suite of your program (e.g. the application name) (used in the default manpage())

var Summary = ""

Redefine this to change the summary of your program (used in the default Usage() and man page)

var Synopsis = func() string {
	h := new(bytes.Buffer)
	for _, o := range opts {
		fmt.Fprint(h, " [")
		switch {
		case len(o.shortnames) == 0:
			for _, n := range o.names[0 : len(o.names)-1] {
				fmt.Fprintf(h, "\\-\\-%s|", n[2:])
			}
			fmt.Fprintf(h, "\\-\\-%s", o.names[len(o.names)-1][2:])
			if o.allowsArg != nil {
				fmt.Fprintf(h, " %s", *o.allowsArg)
			}
		case len(o.names) == 0:
			for _, c := range o.shortnames[0 : len(o.shortnames)-1] {
				fmt.Fprintf(h, "\\-%c|", c)
			}
			fmt.Fprintf(h, "\\-%c", o.shortnames[len(o.shortnames)-1])
			if o.allowsArg != nil {
				fmt.Fprintf(h, " %s", *o.allowsArg)
			}
		default:
			for _, c := range o.shortnames {
				fmt.Fprintf(h, "\\-%c|", c)
			}
			for _, n := range o.names[0 : len(o.names)-1] {
				fmt.Fprintf(h, "\\-\\-%s|", n[2:])
			}
			fmt.Fprintf(h, "\\-\\-%s", o.names[len(o.names)-1][2:])
			if o.allowsArg != nil {
				fmt.Fprintf(h, " %s", *o.allowsArg)
			}
		}
		fmt.Fprint(h, "]")
	}
	return h.String()
}

Override the shortened help for your program (not recommended)

var Usage = func() string {
	programName := os.Args[0][strings.LastIndex(os.Args[0], "/")+1:]
	if Summary != "" {
		return fmt.Sprintf("Usage of %s:\n\t", programName) +
			Summary + "\n" + Help()
	}
	return fmt.Sprintf("Usage of %s:\n%s", programName, Help())
}

Redefine this function to change the way usage is printed

var Vars = make(map[string]string)

Variables for expansion using Expand(), which is automatically called on help text for flags

var Version = ""

Redefine this to change the displayed version of your program (used in the default man page)

Functions

func Alternatives

func Alternatives(names, vs []string, help string) *string

Create a required-argument flag that only accepts the given set of values Parameters:

names []string            These are the names that are accepted on the command-line for this flag, e.g. -v --verbose
vs    []string            These are the allowable values for the argument
help    string            The help text (automatically Expand()ed) to display for this flag

Returns:

*string                   This points to a string whose value is updated as this flag is changed

func Expand

func Expand(x string) string

Expand all variables in Vars within the given string. This does not assume any prefix or suffix that sets off a variable from the rest of the text, so a var of A set to HI expanded into HAPPY will become HHIPPY.

func Flag

func Flag(yes []string, no []string, helpyes, helpno string) *bool

Create a no-argument flag that is set by either passing one of the "NO" flags or one of the "YES" flags. The default value is "false" (or "NO"). If you want another default value, you can swap the meaning of "NO" and "YES".

Parameters:

yes   []string            These flags set the boolean value to true (e.g. -i --install)
no    []string            These flags set the boolean value to false (e.g. -I --no-install)
helpyes string            The help text (automatically Expand()ed) to display for the "yes" flags
helpno  string            The help text (automatically Expand()ed) to display for the "no" flags

Returns:

*bool                     This points to a bool whose value is updated as this flag is changed

func Int

func Int(names []string, def int, help string) *int

Create a required-argument flag that accepts int values Parameters:

names []string            These are the names that are accepted on the command-line for this flag, e.g. -v --verbose
def     int               Default value for the flag and label in Help()
help    string            The help text (automatically Expand()ed) to display for this flag

Returns:

*int                      This points to an int whose value is updated as this flag is changed

func IntWithLabel

func IntWithLabel(names []string, def int, label string, help string) *int

Create a required-argument flag that accepts int values and has a Help() label Parameters:

names []string            These are the names that are accepted on the command-line for this flag, e.g. -v --verbose
def     int               Default value for the flag
label   string            Label for display in Help()
help    string            The help text (automatically Expand()ed) to display for this flag

Returns:

*int                      This points to an int whose value is updated as this flag is changed

func NoArg

func NoArg(names []string, help string, process func() error)

Add a new flag that does not allow arguments Parameters:

names []string            These are the names that are accepted on the command-line for this flag, e.g. -v --verbose
help    string            The help text (automatically Expand()ed) to display for this flag
process func() os.Error   The function to call when this flag is processed with no argument

func OptArg

func OptArg(names []string, def, help string, process func(string) error)

Add a new flag that may optionally have an argument Parameters:

names []string                 These are the names that are accepted on the command-line for this flag, e.g. -v --verbose
def     string                 The default of the argument in help, e.g. the "value" part of "--flag=value"
help    string                 The help text (automatically Expand()ed) to display for this flag
process func(string) os.Error  The function to call when this flag is processed with an argument

func Parse

func Parse(extraopts func() []string) bool

This parses the command-line arguments. It returns true if '--' was present. Special flags are:

--help               Display the generated help message (calls Help())
--create-manpage     Display a manpage generated by the goopt library (uses Author, Suite, etc)
--list-options       List all known flags

Arguments:

extraopts func() []string     This function is called by --list-options and returns extra options to display

func ReqArg

func ReqArg(names []string, argname, help string, process func(string) error)

Add a new flag that requires an argument Parameters:

names []string                  These are the names that are accepted on the command-line for this flag, e.g. -v --verbose
argname string                  The name of the argument in help, e.g. the "value" part of "--flag=value"
help    string                  The help text (automatically Expand()ed) to display for this flag
process func(string) os.Error   The function to call when this flag is processed

func String

func String(names []string, def string, help string) *string

Create a required-argument flag that accepts string values Parameters:

names []string            These are the names that are accepted on the command-line for this flag, e.g. -v --verbose
def     string            Default value for the string and label in Help()
help    string            The help text (automatically Expand()ed) to display for this flag

Returns:

*string                   This points to a string whose value is updated as this flag is changed

func StringWithLabel

func StringWithLabel(names []string, def string, label string, help string) *string

Create a required-argument flag that accepts string values and has a Help() label Parameters:

names []string            These are the names that are accepted on the command-line for this flag, e.g. -v --verbose
def     string            Default value for the string
label   string            Label for display in Help()
help    string            The help text (automatically Expand()ed) to display for this flag

Returns:

*string                   This points to a string whose value is updated as this flag is changed

func Strings

func Strings(names []string, def string, help string) *[]string

Create a required-argument flag that accepts string values but allows more than one to be specified Parameters:

names []string            These are the names that are accepted on the command-line for this flag, e.g. -v --verbose
def     string            The argument name of the strings that are appended (e.g. the val in --opt=val)
help    string            The help text (automatically Expand()ed) to display for this flag

Returns:

*[]string                 This points to a []string whose value will contain the strings passed as flags

func VisitAllNames

func VisitAllNames(f func(string))

Execute the given closure on the name of all known arguments