Go API

Install:

go get github.com/dmulholland/clio/go/clio

Import:

import "github.com/dmulholland/clio/go/clio"

Usage

Initialize an argument parser, optionally specifying the application's help text and version:

func NewParser(helptext string, version string) *ArgParser

Supplying help text activates an automatic --help flag; supplying a version string activates an automatic --version flag. An empty string "" can be passed for either parameter.

You can now register your application's options and commands on the parser using the registration functions described below. Once the required options and commands have been registered, call the parser's Parse() method to process the application's command line arguments:

func (parser *ArgParser) Parse()

Parsed option values can be retrieved from the parser instance itself.

Register Options

Clio supports long-form options, --foo, with single-character shortcuts, -f.

An option can have an unlimited number of long and short-form aliases. Aliases are specified via the name parameter which accepts a string of space-separated alternatives, e.g. "foo f".

Option values can be separated on the command line by either a space, --foo 123, or an equals symbol, --foo=123.

func (parser *ArgParser) AddFlag(name string)

Register a flag (a boolean option) with a default value of false. Flag options take no arguments but are either present (true) or absent (false).

func (parser *ArgParser) AddFloat(name string, value float64)

Register a floating-point option with a default value.

func (parser *ArgParser) AddInt(name string, value int)

Register an integer option with a default value.

func (parser *ArgParser) AddStr(name string, value string)

Register a string option with a default value.

Register List Options

List options store multiple values. Greedy list options attempt to parse multiple consecutive arguments.

Like single-valued options, list options can have an unlimited number of long and short-form aliases specified via the name parameter.

func (parser *ArgParser) AddFlagList(name string)

Register a boolean list option.

func (parser *ArgParser) AddFloatList(name string, greedy bool)

Register a floating-point list option.

func (parser *ArgParser) AddIntList(name string, greedy bool)

Register an integer list option.

func (parser *ArgParser) AddStrList(name string, greedy bool)

Register a string list option.

Retrieve Option Values

An option's value can be retrieved from the parser instance using any of its registered aliases.

func (parser *ArgParser) Found(name string) bool

Returns true if the specified option was found while parsing.

func (parser *ArgParser) GetFlag(name string) bool

Returns the value of the specified boolean option.

func (parser *ArgParser) GetFloat(name string) float64

Returns the value of the specified floating-point option.

func (parser *ArgParser) GetInt(name string) int

Returns the value of the specified integer option.

func (parser *ArgParser) GetStr(name string) string

Returns the value of the specified string option.

Retrieve List Values

A list-option's values can be retrieved from the parser instance using any of its registered aliases.

func (parser *ArgParser) GetFlagList(name string) []bool

Returns the specified option's list of values.

func (parser *ArgParser) GetFloatList(name string) []float64

Returns the specified option's list of values.

func (parser *ArgParser) GetIntList(name string) []int

Returns the specified option's list of values.

func (parser *ArgParser) GetStrList(name string) []string

Returns the specified option's list of values.

func (parser *ArgParser) LenList(name string) int

Returns the length of the specified option's list of values.

Set Option Values

The methods below can be used to set option values manually.

Note that, internally, all options are list-options. An option's 'value' is simply the last value in its internal list.

func (parser *ArgParser) ClearList(name string)

Clear the specified option's internal list of values.

func (parser *ArgParser) SetFlag(name string, value bool)

Append a boolean value to the specified option's internal list.

func (parser *ArgParser) SetFloat(name string, value float64)

Append a floating-point value to the specified option's internal list.

func (parser *ArgParser) SetInt(name string, value int)

Append an integer value to the specified option's internal list.

func (parser *ArgParser) SetStr(name string, value string)

Append a string value to the specified option's internal list.

Positional Arguments

The methods below provide access to positional arguments identified by the parser.

func (parser *ArgParser) GetArg(index int) string

Returns the positional argument at the specified index.

func (parser *ArgParser) GetArgs() []string

Returns the positional arguments as a slice of strings.

func (parser *ArgParser) GetArgsAsFloats() []float64

Attempts to parse and return the positional arguments as a slice of floats. Exits with an error message on failure.

func (parser *ArgParser) GetArgsAsInts() []int

Attempts to parse and return the positional arguments as a slice of integers. Exits with an error message on failure.

func (parser *ArgParser) HasArgs() bool

Returns true if at least one positional argument has been found.

func (parser *ArgParser) LenArgs() int

Returns the length of the positional argument list.

Commands

Clio supports git-style command interfaces with arbitrarily-nested commands. Register a command on a parser instance using the AddCmd() method:

func (parser *ArgParser) AddCmd(name, helptext string, callback func(*ArgParser)) *ArgParser

This method returns a new ArgParser instance associated with the command. You can register the command's flags and options on this sub-parser using the standard methods listed above. (Note that you never need to call Parse() on a command parser - if a command is found, its arguments are parsed automatically.)

The following ArgParser methods are also available for processing commands manually:

func (parser *ArgParser) GetCmdName() string

Returns the command name, if the parser has found a command.

func (parser *ArgParser) GetCmdParser() *ArgParser

Returns the command's parser instance, if the parser has found a command.

func (parser *ArgParser) GetParent() *ArgParser

Returns a command parser's parent parser.

func (parser *ArgParser) HasCmd() bool

Returns true if the parser has found a command.