cli

README

cli

Opinionated utility for command line applications with options for commands or sub-commands.

Golang Version

This package requires Go version 1.8 or higher because it uses the updates testing package.

Status

Documentation and Usage

Full documentation and usage examples can be found at

Documentation

Overview

Package cli provides some functions that make dealing with the flag package easier as well as some formatting functions for cli output.

Cli is intended to be used by the command and subcommand subpackages that implement their specific use cases.

See the command subpackage for writing CLI's that only do "one" thing. And see the subcommand subpackage for writing CLI's with multiple subcommands.

Index

• Constants
• Variables
• func CountFlags(f *flag.FlagSet) int
• func FormatArgument(name string, optional, many bool) string
• func FormatParameter(p *Parameter) string
• func FormatParameterName(name string) string
• func FormatParameters(params []*Parameter, format func(p *Parameter) string) string
• func GetFlagSetDefaults(f *flag.FlagSet) string
• func GetJoinedNameSortedAliases(name string, aliases []string) string
• func NewFlagSet(name string, fs FlagSetter) *flag.FlagSet
• func ParseArgumentsInterspersed(f *flag.FlagSet, args []string) (params []string, err error)
• type ExitStatusError
  • func (e *ExitStatusError) Error() string
• type FlagSetter
• type Parameter
• type ParameterSetter
• type RequiredParameterNotSetError
  • func (e *RequiredParameterNotSetError) Error() string

Constants

const (
	Usage = "usage:"

	ParameterName  = "parameter"
	ParametersName = "parameters"

	ArgumentSeparator = " | "
)

Output values that affect error and help output.

const DoubleMinus = "--"

DoubleMinus is the argument to determine if the flag package has stopped parsing after seeing this argument.

Variables

var ErrInvalidParameters = errors.New("invalid parameters")

ErrInvalidParameters is a generic error for invalid parameters being set. Note that this error message will not be printed to output, it is simply a sentinel value.

var ErrTooManyParameters = fmt.Errorf("too many parameters")

ErrTooManyParameters is an error value that clients can use to signal that too many parameters were provided to a ParameterSetter.

Functions

func CountFlags

func CountFlags(f *flag.FlagSet) int

CountFlags returns the total number of flags (set or unset) in f.

func FormatArgument

func FormatArgument(name string, optional, many bool) string

FormatArgument formats an argument's name given whether or not it is optional or multiple values are allowed.

func FormatParameter

func FormatParameter(p *Parameter) string

FormatParameter returns a string representation of p appropriate for help and error output.

func FormatParameterName

func FormatParameterName(name string) string

FormatParameterName returns a string representation of a Parameter name appropriate for help and error output. It returns the result of strings.ToUpper(name).

func FormatParameters

func FormatParameters(params []*Parameter, format func(p *Parameter) string) string

FormatParameters calls format() for each Parameter in params and returns the result joined by " ".

func GetFlagSetDefaults

func GetFlagSetDefaults(f *flag.FlagSet) string

GetFlagSetDefaults returns the result of f.PrintDefaults() with the optionally trailing "\n" removed.

func GetJoinedNameSortedAliases

func GetJoinedNameSortedAliases(name string, aliases []string) string

GetJoinedNameSortedAliases returns name followed by the cloned and sorted aliases all joined by ", ".

GetJoinedNameSortedAliases("c", []string{"b", "a"}) // "c, a, b"

func NewFlagSet

func NewFlagSet(name string, fs FlagSetter) *flag.FlagSet

NewFlagSet creates a new flag.FlagSet with name and flag.ContinueOnError and calls fs with it if fs is not nil. If fs is nil, then a new, empty flag.FlagSet is returned.

func ParseArgumentsInterspersed

func ParseArgumentsInterspersed(f *flag.FlagSet, args []string) (params []string, err error)

ParseArgumentsInterspersed allows argument parsing to be more flexible than what is provided natively in the flag package. In the flag package, all flag options must be specified before any other arguments. Parsing stop when the first non-flag argument is reached. ParseArgumentsInterspersed allows non-flag arguments to be parsed within the normal listing of flag arguemtns.

For example, with f having the -value and -count flags set, the following command arguments would set -value and -count on f and return "one" and "two" as the return variable params.

[]string{"one" "-count" "22" "two" "-value" "foobar"}

Essentially, the order of the arguments do not matter when parsing. And non-flag arguments are returned in params. Err will be any error returned from flag.FlagSet.Parse().

Types

type ExitStatusError

type ExitStatusError struct {
	//Code is the desired exit status.
	Code int

	//Err is the wrapped error.
	Err error
}

ExitStatusError allows wrapping together an exit status with an error providing that exit code.

func (*ExitStatusError) Error

func (e *ExitStatusError) Error() string

Error is the error implementation for e. It returns e.Err.Error()

type FlagSetter

type FlagSetter interface {
	SetFlags(f *flag.FlagSet)
}

FlagSetter allows implementations to receive values from flag.FlagSets while argument parsing occurs. Implementations should not retain references to f.

type Parameter

type Parameter struct {
	//Name is the name of the Parameter as it will appear in help and error output.
	Name string

	//Optional denotes whether or not the parameter's presence in command line
	//arguments is optional. False for required.
	Optional bool

	//Many denotes whether or not this Parameter can have a variable number of
	//command line arguments for input.
	Many bool
}

Parameter is a value struct for a parameter in the command line arguments.

type ParameterSetter

type ParameterSetter interface {
	//ParameterUsage returns the Parameters used and a possible usage string to
	//describe parameters in more detail.
	//These values are used in help and error output.
	ParameterUsage() (params []*Parameter, usage string)

	//SetParameters allows implementations to receive parameter arguments during
	//argument parsing.
	//An error should be returned if values cannot be correctly parsed as parameters
	//expected by the implementation.
	//Implementations should not retain references to values.
	SetParameters(values []string) error
}

ParameterSetter provides the interface for a cli working with command line parameters.

type RequiredParameterNotSetError

type RequiredParameterNotSetError struct {
	//Name is the name of the Parameter.
	Name string

	//Many is the Many option of the Parameter.
	Many bool

	//Formatted may be provided to override output of Error().
	Formatted string
}

RequiredParameterNotSetError is an error that denotes a parameter was not supplied in the arguments but is required to be present. If Formatted is not empty, then it is used in Error(). Otherwise, Name is used. It is up to client code to set Formatted if that output is desired.

func (*RequiredParameterNotSetError) Error

func (e *RequiredParameterNotSetError) Error() string

Error provides the error implementation. It returns fmt.Sprintf("required %s %s not set", ParameterName, <value>) where <value> is e.Formatted if not empty or e.Name otherwise.