cli

Documentation

Index

• Constants
• func DumpGrammar(ctx *Context)
• func ShowHelp(c *Context)
• type Context
  • func (c *Context) Boolean(name string) bool
  • func (c *Context) FindGlobal() *Context
  • func (c *Context) GetParameter(i int) string
  • func (c *Context) GetParameterCount() int
  • func (c *Context) Integer(name string) (int, bool)
  • func (c *Context) Keyword(name string) (int, bool)
  • func (c *Context) Parse() error
  • func (c *Context) ResolveEnvironmentVariables() error
  • func (c *Context) String(name string) (string, bool)
  • func (c *Context) StringList(name string) ([]string, bool)
  • func (c *Context) WasFound(name string) bool
• type Error
  • func NewCLIError(msg string, args ...interface{}) Error
  • func (ce Error) Error() string
• type ExitError
  • func NewExitError(msg string, code int) ExitError
  • func (e ExitError) Error() string
  • func (e ExitError) Exit()
• type Option

Constants

const (
	ExitSuccess      = 0
	ExitGeneralError = 1
	ExitUsageError   = 2
)

Exit codes passed to the operating system.

const (
	CLIErrorPrefix            = "during command line processing"
	InvalidBooleanValueError  = "option --%s invalid boolean value: %s"
	InvalidIntegerError       = "option --%s invalid integer value: %s"
	InvalidKeywordError       = "option --%s has no such keyword: %s"
	RequiredNotFoundError     = "required option %s not found"
	TooManyParametersError    = "too many parameters on command line"
	UnexpectedParametersError = "unexpected parameters or invalid subcommand"
	UnknownOptionError        = "unknown option: %s"
	WrongParameterCountError  = "incorrect number of parameters"
)

CLI error message strings.

const (

	// StringType accepts a string (in quotes if it contains spaces or punctuation).
	StringType = 1

	// IntType accepts a signed integer value.
	IntType = 2

	// BooleanType is true if present, or false if not present.
	BooleanType = 3

	// BooleanValueType is representation of the boolean value (true/false).
	BooleanValueType = 4

	// Subcommand specifies that the LongName is a command name, and parsing continues with the SubGrammar.
	Subcommand = 6

	// StringListType is a string value or a list of string values, separated by commas and enclosed in quotes.
	StringListType = 7

	// ParameterType is a parameter from the command line. They should be declared in order.
	ParameterType = 8

	// UUIDType defines a value that must be a valid (parsable) UUID, though the value is stored
	// as a string datum.
	UUIDType = 9

	// KeywordType is a string that must be from an approved list of keyword values.
	KeywordType = 10
)

Functions

func DumpGrammar

func DumpGrammar(ctx *Context)

func ShowHelp

func ShowHelp(c *Context)

ShowHelp displays help text for the grammar, using a standardized format. The help shows subcommands as well as options, including value type cues. The output is automatically directed to the stdout console output.

This function uses the tables package to create uniform columns of output.

Types

type Context

type Context struct {
	AppName                string
	MainProgram            string
	Description            string
	Copyright              string
	Version                string
	Command                string
	ParameterDescription   string
	Grammar                []Option
	Args                   []string
	Parameters             []string
	Parent                 *Context
	Action                 func(c *Context) error
	ParameterCount         int
	ExpectedParameterCount int
}

Context is a simple array of Option types, and is used to express a grammar at a given level (root, subcommand, etc.).

func (*Context) Boolean

func (c *Context) Boolean(name string) bool

Boolean returns the value of a named boolean. If the boolean option was found during processing, this routine returns true. Otherwise it returns false.

func (*Context) FindGlobal

func (c *Context) FindGlobal() *Context

FindGlobal locates the top-most context structure in the chain of nested contexts. If our tree has no parent, we are the global grammar. Otherwise, ask our parent...

func (*Context) GetParameter

func (c *Context) GetParameter(i int) string

GetParameter returns the ith parameter string parsed, or an empty string if not found.

func (*Context) GetParameterCount

func (c *Context) GetParameterCount() int

GetParameterCount returns the number of parameters processed.

func (*Context) Integer

func (c *Context) Integer(name string) (int, bool)

Integer returns the value of a named integer from the parsed grammar, or a zero if not found. The boolean return value confirms if the value was specified on the command line.

func (*Context) Keyword

func (c *Context) Keyword(name string) (int, bool)

Keyword returns the value of a named string parameter from the parsed grammar. The result is the ordinal position (zero-based) on the keyword from the list. If the value is not in the list, it returns -1.

func (*Context) Parse

func (c *Context) Parse() error

Parse processes the grammar associated with the current context, using the []string array of arguments for that context.

Unrecognized options or subcommands, as well as invalid values are reported as an error. If there is an action routine associated with an option or a subcommand, that action is executed.

func (*Context) ResolveEnvironmentVariables

func (c *Context) ResolveEnvironmentVariables() error

ResolveEnvironmentVariables searches the grammar tree backwards looking for options that can be specified by an environment variable, and marking those found as needed. This is done after the command line options are processed, to provide defaults for un-specified options.

func (*Context) String

func (c *Context) String(name string) (string, bool)

String returns the value of a named string parameter from the parsed grammar, or an empty string if not found. The second return value indicates if the value was explicitly specified. This is used to differentiate between "not specified" and "specified as empty".

func (*Context) StringList

func (c *Context) StringList(name string) ([]string, bool)

StringList returns the array of strings that are the value of the named item. If the item is not found, an empty array is returned. The second value in the result indicates of the option was explicitly specified in the command line.

func (*Context) WasFound

func (c *Context) WasFound(name string) bool

WasFound reports if an entry in the grammar was found on the processed command line.

type Error

type Error struct {
	// contains filtered or unexported fields
}

Wrapper for CLI errors.

func NewCLIError

func NewCLIError(msg string, args ...interface{}) Error

NewCLIError generates a new CLIError object using the message string and optional values that are formatted using the message string.

func (Error) Error

func (ce Error) Error() string

Error returns a string representation of the CLIError.

type ExitError

type ExitError struct {
	ExitStatus int
	Message    string
}

ExitError is a wrapped error code structure used to return a message and a desired operating system exit value.

func NewExitError

func NewExitError(msg string, code int) ExitError

NewExitError constructs an ExitError.

func (ExitError) Error

func (e ExitError) Error() string

Error formats an ExitError into a text string for display.

func (ExitError) Exit

func (e ExitError) Exit()

Exit exits the program, returning the given exit status code to the operating system.

type Option

type Option struct {
	ShortName            string
	LongName             string
	Description          string
	ParameterDescription string
	EnvironmentVariable  string
	Aliases              []string
	Keywords             []string
	Value                interface{}
	Action               func(c *Context) error
	OptionType           int
	ParametersExpected   int
	Found                bool
	Required             bool
	Private              bool
}

Option defines the structure of each option that can be parsed.