Introduction

I like to use Go to write small command line programs, so I need to parse command line options. The Go standard library comes with the flag package, but infortunately it uses the uncommon format -option instead of the usual short (-o) and long (--option) formats.

I used github.com/pborman/getopt for some time, and it did the job. However I often use subcommands, and getopt does not support them. So I ended up writing my own library.

github.com/galdor/go-cmdline is a small and simple package; it supports short and long options, parses arguments and commands, and display nice usage strings.

Usage

The simplest application only supports -h and --help:

cmdline := cmdline.New()
cmdline.Parse(os.Args)

cmdline.Parse() will print the usage string and exit if a help option is provided.

Options

We can then add flags and options, optionally with default values:

cmdline := cmdline.New()

cmdline.AddFlag("v", "verbose", "log more information")
cmdline.AddOption("o", "output", "file", "the output file")
cmdline.SetOptionDefault("output", "-")

cmdline.Parse(os.Args)

Our fictional application now supports a flag, -v or --verbose, and an option to specify the output file with a default value.

The value associated with each option can be retrieved with cmdline.OptionValue(name). cmdline.IsOptionSet(name) indicates whether the option was set or not.

The resulting usage string displays all options:

Usage: ./example OPTIONS

OPTIONS

-h, --help           print help and exit
-o, --output <file>  the output file (default: -)
-v, --verbose        log more information

Arguments

Let’s add an input file:

cmdline.AddArgument("input", "the input file")

The application will now require a single argument after options. Its value can be read using cmdline.ArgumentValue("input").

And the usage string now includes the argument:

Usage: ./example OPTIONS <input>

OPTIONS

-h, --help           print help and exit
-o, --output <file>  the output file (default: -)
-v, --verbose        log more information

ARGUMENTS

input                the input file

Trailing arguments

cmdline supports trailing arguments. In our example we may want to have multiple input files:

cmdline.AddTrailingArguments("input", "an input file")

These arguments can be retrieved as a slice of strings using cmdline.TrailingArgumentsValues()

Commands

It is also easy to add commands:

cmdline.AddCommand("foo", "subcommand 1")
cmdline.AddCommand("bar", "subcommand 2")

After parsing the command line, the command selected is available using cmdline.CommandName(), and the arguments passed after the command name are available as a slice of strings with cmdline.CommandArgumentsValues().

Of course the usage string takes commands into account:

Usage: ./example OPTIONS <command>

OPTIONS

-h, --help  print help and exit

COMMANDS

foo         subcommand 1
bar         subcommand 2

Examples

The examples directory contains examples for the various features of cmdline. You can run them with go run. Feel free to copy and use these examples in your own application.