argo

README

Argo

A minimalist Go library for parsing command line arguments.

Features

• Long-form boolean flags with single-character shortcuts: --flag, -f.

• Long-form string, integer, and floating-point options with single-character shortcuts: --option <arg>, -o <arg>.

• Condensed short-form options: -abc <arg> <arg>.

• Automatic --help and --version flags.

• Support for multivalued options.

• Support for git-style command interfaces with arbitrarily-nested commands.

Installation

Install the argo package:

    go get github.com/dmulholl/argo/v4

Import the argo package:

    import "github.com/dmulholl/argo/v4"

Links

• Documentation
• Simple Example
• Command Example
• API Documentation

License

Zero-Clause BSD (0BSD).

Documentation

Overview

Package argo is a library for parsing command line arguments.

Index

• type ArgParser
  • func NewParser() *ArgParser
  • func (parser *ArgParser) ArgsAsFloats() ([]float64, error)
  • func (parser *ArgParser) ArgsAsInts() ([]int, error)
  • func (parser *ArgParser) Count(name string) int
  • func (parser *ArgParser) FloatValue(name string) float64
  • func (parser *ArgParser) FloatValues(name string) []float64
  • func (parser *ArgParser) Found(name string) bool
  • func (parser *ArgParser) IntValue(name string) int
  • func (parser *ArgParser) IntValues(name string) []int
  • func (parser *ArgParser) NewCommand(name string) *ArgParser
  • func (parser *ArgParser) NewFlag(name string)
  • func (parser *ArgParser) NewFloatOption(name string, fallback float64)
  • func (parser *ArgParser) NewIntOption(name string, fallback int)
  • func (parser *ArgParser) NewStringOption(name string, fallback string)
  • func (parser *ArgParser) Parse(args []string) error
  • func (parser *ArgParser) ParseOsArgs() error
  • func (parser *ArgParser) String() string
  • func (parser *ArgParser) StringValue(name string) string
  • func (parser *ArgParser) StringValues(name string) []string

Types

type ArgParser

type ArgParser struct {
	// The parser's helptext string.
	//
	// Specifying a helptext string for a parser activates an automatic --help flag that prints the
	// parser's helptext and exits. (Also activates an automatic -h shortcut unless registered by
	// another flag/option.)
	Helptext string

	// The parser's version string.
	//
	// Specifying a version string for a parser activates an automatic --version flag that prints the
	// parser's version and exits. (Also activates an automatic -v shortcut unless registered
	// by another flag/option.)
	Version string

	// The parser's callback function.
	//
	// This field is only valid for command subparsers. If the command subparser's registered
	// command is found by the parent parser, and if this field is not nil, the specified callback
	// function will be called automatically. It will be passed the command name and the command's
	// ArgParser instance as arguments.
	Callback func(string, *ArgParser) error

	// If true, enables an automatic 'help' command that prints helptext for subcommands.
	//
	// Defaults to false but gets toggled automatically to true whenever a command is registered.
	// Set this value to false to disable the automatic 'help' command.
	EnableHelpCommand bool

	// After parsing, stores the parser's positional arguments.
	Args []string

	// After parsing, if the parser has found a command, stores the command's name.
	FoundCommandName string

	// After parsing, if the parser has found a command, stores the command's ArgParser instance.
	FoundCommandParser *ArgParser
	// contains filtered or unexported fields
}

An ArgParser instance stores registered options and commands.

func NewParser

func NewParser() *ArgParser

NewParser initializes a new ArgParser instance.

func (*ArgParser) ArgsAsFloats

func (parser *ArgParser) ArgsAsFloats() ([]float64, error)

ArgsAsFloats attempts to return the parser's positional arguments as a slice of floats. Returns an error if any of the arguments cannot be parsed as a float.

func (*ArgParser) ArgsAsInts

func (parser *ArgParser) ArgsAsInts() ([]int, error)

ArgsAsInts attempts to return the parser's positional arguments as a slice of integers. Returns an error if any of the arguments cannot be parsed as an integer.

func (*ArgParser) Count

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

Count returns the number of times the specified flag or option was found. Any of the flag/option's registered aliases or shortcuts can be used as the name parameter.

Panics if name is not a registered flag or option name.

func (*ArgParser) FloatValue

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

FloatValue returns the value of the specified float-valued option. Any of the option's registered aliases or shortcuts can be used as the name parameter.

Panics if name is not a registered flag or option name.

func (*ArgParser) FloatValues

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

FloatValues returns the specified float-valued option's list of values. Any of the option's registered aliases or shortcuts can be used as the name parameter.

Panics if name is not a registered flag or option name.

func (*ArgParser) Found

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

Found returns true if the specified flag or option was found. Any of the flag/option's registered aliases or shortcuts can be used as the name parameter.

Panics if name is not a registered flag or option name.

func (*ArgParser) IntValue

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

IntValue returns the value of the specified integer-valued option. Any of the option's registered aliases or shortcuts can be used as the name parameter.

Panics if name is not a registered flag or option name.

func (*ArgParser) IntValues

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

IntValues returns the specified integer-valued option's list of values. Any of the option's registered aliases or shortcuts can be used as the name parameter.

Panics if name is not a registered flag or option name.

func (*ArgParser) NewCommand

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

NewCommand registers a new command. The name parameter accepts an unlimited number of space- separated aliases for the command. Returns the new command's ArgParser instance.

func (*ArgParser) NewFlag

func (parser *ArgParser) NewFlag(name string)

NewFlag registers a new flag, i.e. a valueless option that is either present (found) or absent (not found). You can check for the presence of a flag using the parser's Found() or Count() methods.

The name parameter accepts an unlimited number of space-separated aliases and single-character shortcuts.

func (*ArgParser) NewFloatOption

func (parser *ArgParser) NewFloatOption(name string, fallback float64)

NewFloatOption registers a new float-valued option, i.e. the option's value will be parsed as a float64.

The name parameter accepts an unlimited number of space-separated aliases and single-character shortcuts. The fallback parameter specifies the option's default value.

func (*ArgParser) NewIntOption

func (parser *ArgParser) NewIntOption(name string, fallback int)

NewIntOption registers a new integer-valued option, i.e. the option's value will be parsed as an int.

The name parameter accepts an unlimited number of space-separated aliases and single-character shortcuts. The fallback parameter specifies the option's default value.

func (*ArgParser) NewStringOption

func (parser *ArgParser) NewStringOption(name string, fallback string)

NewStringOption registers a new string-valued option.

The name parameter accepts an unlimited number of space-separated aliases and single-character shortcuts. The fallback parameter specifies the option's default value.

func (*ArgParser) Parse

func (parser *ArgParser) Parse(args []string) error

Parse parses a slice of string arguments. The arguments will be treated as if they came directly from os.Args, i.e. the first argument will be treated as the application's path and will be ignored.

func (*ArgParser) ParseOsArgs

func (parser *ArgParser) ParseOsArgs() error

ParseOsArgs parses the application's command line arguments. This is a shortcut for calling Parse(os.Args).

func (*ArgParser) String

func (parser *ArgParser) String() string

String returns a string representation of the parser instance for debugging.

func (*ArgParser) StringValue

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

StringValue returns the value of the specified string-valued option. Any of the option's registered aliases or shortcuts can be used as the name parameter.

Panics if name is not a registered flag or option name.

func (*ArgParser) StringValues

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

StringValues returns the specified string-valued option's list of values. Any of the option's registered aliases or shortcuts can be used as the name parameter.

Panics if name is not a registered flag or option name.