API Reference
- Basic Usage
- Register Options
- Retrieve A Single Value
- Retrieve Multiple Values
- Retrieve Positional Arguments
- Commands
Install directly from Github:
$ go get github.com/dmulholl/janus/v2
Import the janus
package:
import "github.com/dmulholl/janus/v2"
Alternatively, you can incorporate the single, public-domain janus.go
file directly into your application. The library has no external dependencies.
Basic Usage
Initialize an argument parser, optionally specifying the application's help text and version string:
parser := janus.NewParser() parser.Helptext = "Usage: foobar..." parser.Version = "1.0"
Specifying help text activates an automatic --help
flag; specifying a version string activates an automatic --version
flag. (Automatic -h
and -v
shortcuts are also activated unless registered by other options.)
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:
parser.Parse()
Parsed option values can be retrieved from the parser instance itself.
Register Options
Janus 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) NewFlag(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) NewFloat(name string, fallback float64 = 0.0)
-
Register a floating-point option, optionally specifying a custom fallback value. (The default fallback value is
0
.) -
func (parser *ArgParser) NewInt(name string, fallback int = 0)
-
Register an integer option, optionally specifying a custom fallback value. (The default fallback value is
0
.) -
func (parser *ArgParser) NewString(name string, fallback string = "")
-
Register a string option, optionally specifying a custom fallback value. (The default fallback value is the empty string.)
Retrieve A Single Value
An option's value can be retrieved from the parser instance using any of its registered aliases.
Each option maintains an internal array of values — the value of the option is the final value in the array or the fallback value if the array is empty.
-
func (parser *ArgParser) Count(name string) int
-
Returns the number of times the specified option was found.
-
func (parser *ArgParser) Found(name string) bool
-
Returns true if the specified option was found.
-
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) GetString(name string) string
-
Returns the value of the specified string option.
Retrieve Multiple Values
An option's internal array of values can be retrieved from the parser instance using any of its registered aliases.
-
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) GetStringList(name string) []string
-
Returns the specified option's list of values.
Retrieve Positional Arguments
Options can be preceded, followed, or interspaced with positional arguments.
-
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) NumArgs() int
-
Returns the number of positional arguments.
Commands
Janus supports git-style command interfaces with arbitrarily-nested commands. Register a command on a parser instance using the NewCmd()
method:
func (parser *ArgParser) NewCmd(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.)
-
Like options, commands can have an unlimited number of aliases specified via the
name
string. -
Commands support an automatic
--help
flag and an automatichelp <name>
command using the specified help text. -
The specified callback function will be called if the command is found. The callback should accept the command's
ArgParser
instance as its sole argument and should have no return value.
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.