goopt

package module
v0.0.0-...-48d6390 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 17, 2022 License: BSD-2-Clause Imports: 9 Imported by: 212

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

Constants

This section is empty.

Variables

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

This is the list of non-flag arguments after processing

View Source 
var Author = ""

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

View Source 
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)

View Source 
var ExtraUsage = ""

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

View Source 
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 && len(o.names) == 0 {
				fmt.Fprintf(h, " %s", *o.allowsArg)
			}
		}
		if len(o.names) > 0 {
			if len(o.shortnames) > 0 {
				fmt.Fprint(h, ", ")
			}
			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)

View Source 
var RequireOrder = false

Redefine this to force flags to come before all options or be treated as if they were options

View Source 
var Suite = ""

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

View Source 
var Summary = ""

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

View Source 
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)

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

Redefine this function to change the way usage is printed

View Source 
var Vars = make(map[string]string)

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

View Source 
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 AlternativesWithLabel 

func AlternativesWithLabel(names, vs []string, label string, help string) *string

Create a required-argument flag that only accepts the given set of valuesand 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
vs    []string            These are the allowable values for the argument
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 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

Types

This section is empty.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.