optionparser

README

optionparser

Mature command line arguments processor for Go.

Inspired by Ruby's (OptionParser) command line arguments processor.

Installation

go get github.com/speedata/optionparser

Usage

op := optionparser.NewOptionParser()
op.On(arguments ...interface{})
...
err := op.Parse()

where arguments is one of:

• "-a": a short argument
• "--argument": a long argument
• "--argument [FOO]" a long argument with an optional parameter
• "--argument FOO" a long argument with a mandatory parameter
• "Some text": The description text for the command line parameter
• &aboolean: Set the given boolean to true if the argument is given, set to false if parameter is prefixed with no-, such as --no-foo.
• &astring: Set the string to the value of the given parameter
• function: Call the function. The function must have the signature func().
• map[string]string: Set an entry of the map to the value of the given parameter and the key of the argument.
• []string Set the slice values to a comma separated list.

Help usage

The options -h and --help are included by default. Starting with v1.1.0, calling op.Parse() or op.ParseFrom() with --help no longer exits the program automatically. Instead, Parse() prints the help text to standard output and returns the sentinel error optionparser.ErrHelp. This makes the package safer and easier to integrate in larger applications or libraries.

To emulate the previous behavior (exit after printing help), you can simply do:

if errors.Is(err, optionparser.ErrHelp) {
    os.Exit(0)
}

The example below shows the help output that appears when running cmd -h:

 Usage: [awesome-options] <awesome-command>
 -h, --help                   Show this help
 -a, --func                   call myfunc
     --bstring=FOO            set string to FOO
 -c                           set boolean option (try -no-c)
 -d, --dlong=VAL              set option
 -e, --elong[=VAL]            set option with optional parameter
 -f                           boolean option

 Commands
       y                      Run command y
       z                      Run command z

 For more information or to contribute, visit https://github.com/speedata/optionparser.

Settings

After calling op := optionparser.NewOptionParser() you can set op.Banner and op.Coda. op.Banner customizes the first line of the help output. The default value is "Usage: [parameter] command". By default, op.Coda is an empty string. Set a value for op.Coda if you want to add text at the end of the help output.

To control the first and last column of the help output, set op.Start and op.Stop. The default values are 30 and 79.

Example usage

package main

import (
	"errors"
	"fmt"
	"log"
	"os"

	"github.com/speedata/optionparser"
)

func myfunc() {
	fmt.Println("myfunc called")
}

func main() {
	var somestring string
	var truefalse bool
	options := make(map[string]string)
	stringslice := []string{}

	op := optionparser.NewOptionParser()
	op.On("-a", "--func", "call myfunc", myfunc)
	op.On("--bstring FOO", "set string to FOO", &somestring)
	op.On("-c", "set boolean option (try -no-c)", options)
	op.On("-d", "--dlong VAL", "set option", options)
	op.On("-e", "--elong [VAL]", "set option with optional parameter", options)
	op.On("-f", "boolean option", &truefalse)
	op.On("-g VALUES", "give multiple values", &stringslice)

	op.Command("y", "Run command y")
	op.Command("z", "Run command z")

	op.Banner = "Usage: [awesome-options] <awesome-command>"
	op.Coda = "\nFor more information or to contribute, visit https://github.com/speedata/optionparser."

	err := op.Parse()
	if errors.Is(err, optionparser.ErrHelp) {
		// Exit cleanly after showing help
		os.Exit(0)
	}
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("string `somestring' is now %q\n", somestring)
	fmt.Printf("options %v\n", options)
	fmt.Printf("-f %v\n", truefalse)
	fmt.Printf("-g %v\n", stringslice)
	fmt.Printf("Extra: %#v\n", op.Extra)
}

The output of go run main.go -a --bstring foo -c -d somevalue -e x -f -g a,b,c y z is:

myfunc called
string `somestring' is now "foo"
options map[c:true dlong:somevalue elong:x]
-f true
-g [a b c]
Extra: []string{"y", "z"}

State: Actively maintained, and used in production. Without warranty, of course.
Maturity level: 5/5 (works well in all tested repositories, no breaking API changes expected)
License: Free software (MIT License)
Installation: Just run go get github.com/speedata/optionparser
API documentation: https://pkg.go.dev/github.com/speedata/optionparser
Contact: gundlach@speedata.de, @speedata@typo.social
Repository: https://github.com/speedata/optionparser
Dependencies: None
Contribution: We like to get any kind of feedback (success stories, bug reports, merge requests, ...)

Documentation

Overview

Package optionparser is a library for defining and parsing command line options. It aims to provide a natural language interface for defining short and long parameters and mandatory and optional arguments. It provides the user with nice output formatting on the built-in method '--help'.

Index

• Variables
• type OptionParser
  • func NewOptionParser() *OptionParser
  • func (op *OptionParser) Command(cmd string, helptext string)
  • func (op *OptionParser) Help()
  • func (op *OptionParser) On(a ...interface{})
  • func (op *OptionParser) Parse() error
  • func (op *OptionParser) ParseFrom(args []string) error

Examples

• OptionParser.Help

Variables

var ErrHelp = errors.New("help requested")

ErrHelp is returned by Parse/ParseFrom when the user requested help. Callers can check for this sentinel error and decide whether to os.Exit(0).

Types

type OptionParser

type OptionParser struct {
	Extra  []string
	Banner string
	Coda   string
	Start  int
	Stop   int

	// Out is the writer Help() and related formatting functions write to.
	// Defaults to os.Stdout.
	Out io.Writer
	// contains filtered or unexported fields
}

OptionParser contains the methods to parse options and the settings to influence the output of --help. Set the Banner and Coda for usage info, set Start and Stop for output of the long description text.

func NewOptionParser

func NewOptionParser() *OptionParser

NewOptionParser initializes the OptionParser struct with sane settings for Banner, Start and Stop and adds a "-h", "--help" option for convenience.

func (*OptionParser) Command

func (op *OptionParser) Command(cmd string, helptext string)

Command defines optional arguments to the command line. These are written in a separate section called 'Commands' on --help.

func (*OptionParser) Help

func (op *OptionParser) Help()

Help prints help text generated from the "On" commands to op.Out.

Example

op := NewOptionParser()
var str string
var options = make(map[string]string)
var truefalse bool
var stringslice []string
myfunc := func() { return }
op.On("-a", "--func", "call myfunc", myfunc)
op.On("--bstring FOO", "set string to FOO", &str)
op.On("-c", "set boolean option (try -no-c)", options)
op.On("-d", "--dlong VAL", "set option", options)
op.On("-e", "--elong [VAL]", "set option with optional parameter", options)
op.On("-f", "boolean option", &truefalse)
op.On("-g VALUES", "give multiple values", &stringslice)
op.Help()

Output:

Usage: [parameter] command
-h, --help                   Show this help
-a, --func                   call myfunc
    --bstring=FOO            set string to FOO
-c                           set boolean option (try -no-c)
-d, --dlong=VAL              set option
-e, --elong[=VAL]            set option with optional parameter
-f                           boolean option
-g=VALUES                    give multiple values

func (*OptionParser) On

func (op *OptionParser) On(a ...interface{})

On defines arguments and parameters. Each argument is one of:

• a short option, such as "-x",
• a long option, such as "--extra",
• a long option with an argument such as "--extra FOO" (or "--extra=FOO") for a mandatory argument,
• a long option with an argument in brackets, e.g. "--extra [FOO]" for a parameter with optional argument,
• a string (not starting with "-") used for the parameter description, e.g. "This parameter does this and that",
• a string variable in the form of &str that is used for saving the result of the argument,
• a variable of type map[string]string which is used to store the result (the parameter name is the key, the value is either the string true or the argument given on the command line)
• a variable of type *[]string which gets a comma separated list of values,
• a bool variable (in the form &bool) to hold a boolean value, or
• a function in the form of func() or in the form of func(string) which gets called if the command line parameter is found.

On panics if the user supplies a type in its argument other than the ones given above.

op := optionparser.NewOptionParser()
op.On("-a", "--func", "call myfunc", myfunc)
op.On("--bstring FOO", "set string to FOO", &somestring)
op.On("-c", "set boolean option (try --no-c)", options)
op.On("-d", "--dlong VAL", "set option", options)
op.On("-e", "--elong [VAL]", "set option with optional parameter", options)
op.On("-f", "boolean option", &truefalse)
op.On("-g VALUES", "give multiple values", &stringslice)

and running the program with --help gives the following output:

go run main.go --help
Usage: [parameter] command
   -h, --help                   Show this help
   -a, --func                   call myfunc
       --bstring=FOO            set string to FOO
   -c                           set boolean option (try --no-c)
   -d, --dlong=VAL              set option
   -e, --elong[=VAL]            set option with optional parameter
   -f                           boolean option
   -g=VALUES                    give multiple values

func (*OptionParser) Parse

func (op *OptionParser) Parse() error

Parse takes the command line arguments as found in os.Args and interprets them. If it finds an unknown option or a missing mandatory argument, it returns an error.

func (*OptionParser) ParseFrom

func (op *OptionParser) ParseFrom(args []string) error

ParseFrom takes a slice of string arguments and interprets them. If it finds an unknown option or a missing mandatory argument, it returns an error. Note: this function expects args like os.Args (program name at index 0) and starts parsing at index 1.