console

README

Console

Facilitates the process of creating complex command-line applications in Go.

Usage

You can see usage examples in the _examples/ folder in this repository.

Motivation

Command line applications provide an easy to use interface for interacting with your application. Go has great support for making these types of applications built into the standard library via the flags package, but it doesn't really facilitate the development of complex command line applications.

This library is designed to help make more complex, safe console applications, in a consistent, simple, and easy to use way. It's designed to be lightweight, but powerful and configurable. Another goal of this library is to make it so that commands are easily testable.

Todo List

There are still some things I'd like to get done with this library, as is reflected by the pre-v1.0 state. Here's a priority ordered todo list:

• Command groups.
• Documentation.
• Mutually exclusive options.
• More complete set of tests.
• More helpful Input type.
• Test helpers.
• Multiple environment variables per-option.

License

MIT

Contributions

Feel free to open a pull request, or file an issue on Github. I always welcome contributions as long as they're for the benefit of all (potential) users of this project.

If you're unsure about anything, feel free to ask about it in an issue before you get your heart set on fixing it yourself.

Documentation

Overview

Package console contains the core code that ties everything together. This includes the Application type that actually runs the commands and reacts to input, and also functions for parsing and mapping input that use other sub-packages.

Index

• func DescribeApplication(app *Application) string
• func DescribeCommand(app *Application, cmd *Command, path []string) string
• func DescribeCommands(commands []*Command) string
• func MapInput(definition *Definition, input *Input, env []string) error
• func MapInput2(definition *Definition, input Input, env []string) error
• type Application
  • func NewApplication(name string, version string) *Application
  • func (a *Application) AddCommand(command *Command)
  • func (a *Application) AddCommands(commands []*Command)
  • func (a *Application) AddGlobalOption(definition OptionDefinition)
  • func (a *Application) Commands() []*Command
  • func (a *Application) Run(argv []string, env []string) int
• type ArgumentDefinition
• type Command
  • func (c *Command) AddCommand(command *Command) *Command
  • func (c *Command) AddCommands(commands []*Command) *Command
  • func (c *Command) Commands() []*Command
• type CommandContainer
• type ConfigureFunc
• type Definition
  • func NewDefinition() *Definition
  • func (d *Definition) AddArgument(definition ArgumentDefinition)
  • func (d *Definition) AddOption(definition OptionDefinition)
  • func (d *Definition) Arguments() []parameters.Argument
  • func (d *Definition) Options() []parameters.Option
• type ExecuteFunc
• type Input
  • func ParseInput(params []string) *Input
  • func ParseInput2(definition *Definition, args []string) *Input
  • func (i *Input) GetOptionValue(names []string) string
  • func (i *Input) HasOption(names []string) bool
• type InputArgument
• type InputOption
• type OptionDefinition
• type Output
  • func NewOutput(writer io.Writer) *Output
  • func (o *Output) Print(a ...interface{}) (int, error)
  • func (o *Output) Printf(format string, a ...interface{}) (int, error)
  • func (o *Output) Println(a ...interface{}) (int, error)
  • func (o *Output) SetExitCode(code int)

Functions

func DescribeApplication

func DescribeApplication(app *Application) string

DescribeApplication describes an Application to provide usage information.

func DescribeCommand

func DescribeCommand(app *Application, cmd *Command, path []string) string

DescribeCommand describes a Command on an Application to provide usage information.

func DescribeCommands

func DescribeCommands(commands []*Command) string

DescribeCommands describes an array of Commands to provide usage information.

func MapInput

func MapInput(definition *Definition, input *Input, env []string) error

MapInput maps the values of input to their corresponding reference values.

func MapInput2

func MapInput2(definition *Definition, input Input, env []string) error

MapInput2 iterates over all defined possible input in the definition, and attempts to set the value defined in the input, or the environment. In the process of mapping, the input will also be validated (i.e. missing required params or values will be identified, and values of the wrong type in the input or env will be identified).

Types

type Application

type Application struct {
	// The name of the application.
	Name string
	// The name of the application printed in usage information, defaults to the binary's filename.
	UsageName string
	// The version of the application.
	Version string
	// Application logo, shown in help output
	Logo string
	// Help message for the application.
	Help string
	// Writer to write output to.
	Writer io.Writer
	// contains filtered or unexported fields
}

Application represents the heart of the console application. It is what orchestrates running commands, initiates input parsing, mapping, and validation; and will handle failure for each of those tasks.

func NewApplication

func NewApplication(name string, version string) *Application

NewApplication creates a new Application with some sane defaults.

func (*Application) AddCommand

func (a *Application) AddCommand(command *Command)

AddCommand adds a command to the application.

func (*Application) AddCommands

func (a *Application) AddCommands(commands []*Command)

AddCommands adds commands to the application.

func (*Application) AddGlobalOption

func (a *Application) AddGlobalOption(definition OptionDefinition)

func (*Application) Commands

func (a *Application) Commands() []*Command

Commands gets the sub-commands on an application.

func (*Application) Run

func (a *Application) Run(argv []string, env []string) int

Run runs the configured application, with the given input.

type ArgumentDefinition

type ArgumentDefinition struct {
	// The value to reference.
	Value parameters.Value
	// The specification of the argument.
	Spec string
	// The description of the argument.
	Desc string
}

ArgumentDefinition is a struct that represents the entire configuration of a CLI argument.

type Command

type Command struct {
	// The name of the command.
	Name string
	// An optional alias for the name, usually a shortened name.
	Alias string
	// The description of the command.
	Description string
	// Help message for the command.
	Help string
	// Function to configure command-level parameters.
	Configure ConfigureFunc
	// Function to execute when this command is requested.
	Execute ExecuteFunc
	// contains filtered or unexported fields
}

Command represents a command to run in an application.

func (*Command) AddCommand

func (c *Command) AddCommand(command *Command) *Command

AddCommand adds a sub-command to the command.

func (*Command) AddCommands

func (c *Command) AddCommands(commands []*Command) *Command

AddCommands adds sub-commands to the command.

func (*Command) Commands

func (c *Command) Commands() []*Command

Commands gets the sub-commands on a command.

type CommandContainer

type CommandContainer interface {
	// Commands gets commands from an object.
	Commands() []*Command
}

CommandContainer is the interface that provides a method to get commands on an object.

type ConfigureFunc

type ConfigureFunc func(*Definition)

ConfigureFunc is a function to mutate the input definition to add arguments and options.

type Definition

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

Definition represents the collected and configured input parameters of an application.

func NewDefinition

func NewDefinition() *Definition

NewDefinition creates a new Definition with sensible defaults.

func (*Definition) AddArgument

func (d *Definition) AddArgument(definition ArgumentDefinition)

AddArgument creates a parameters.Argument and adds it to the Definition. Duplicate argument names will result in an error.

func (*Definition) AddOption

func (d *Definition) AddOption(definition OptionDefinition)

AddOption creates a parameters.Option and adds it to the Definition. Duplicate option names will result in an error.

func (*Definition) Arguments

func (d *Definition) Arguments() []parameters.Argument

Arguments gets all of the arguments in this Definition.

func (*Definition) Options

func (d *Definition) Options() []parameters.Option

Options gets all of the options in this Definition.

type ExecuteFunc

type ExecuteFunc func(input *Input, output *Output) error

ExecuteFunc is a function to perform whatever task this command does.

type Input

type Input struct {
	Arguments []InputArgument
	Options   []InputOption
}

Input represents the raw application input, in a slightly more organised way, and provides helpers for retrieving that information. This allows commands to get application-wide input, instead of only the command-specific input.

func ParseInput

func ParseInput(params []string) *Input

ParseInput takes an array of strings (typically arguments to the application), and parses them into the raw Input type.

func ParseInput2

func ParseInput2(definition *Definition, args []string) *Input

ParseInput2 takes the raw input, and regardless of what is actually defined in the definition, categorising the input as either arguments or options. In other words, the raw input is iterated over, not the definition's parameters. The definition is used so that we can identify options that should have values and consume the next argument as it's value.

func (*Input) GetOptionValue

func (i *Input) GetOptionValue(names []string) string

GetOptionValue gets the an option with one of the given names' value./

func (*Input) HasOption

func (i *Input) HasOption(names []string) bool

HasOption checks to see if the given option exists by one of it's names.

type InputArgument

type InputArgument struct {
	Value string
}

InputArgument represents the raw data parsed as arguments, really this is just the value.

type InputOption

type InputOption struct {
	Name  string
	Value string
}

InputOption represents the raw data parsed as options. This includes it's name and it's value. The value can be "" if no value is given (i.e. if the option is a flag).

type OptionDefinition

type OptionDefinition struct {
	// The value to reference.
	Value parameters.Value
	// The specification of the option.
	Spec string
	// The description of the option.
	Desc string
	// The name of an environment variable to read an option value from.
	EnvVar string
}

OptionDefinition is a struct that represents the entire configuration of a CLI option.

type Output

type Output struct {
	Writer io.Writer
	// contains filtered or unexported fields
}

Output abstracts application output. This is mainly useful for testing, as a different writer can be passed to capture output in an easy to test manner.

func NewOutput

func NewOutput(writer io.Writer) *Output

NewOutput creates a new Output.

func (*Output) Print

func (o *Output) Print(a ...interface{}) (int, error)

Print uses the fmt package's Print with a pre-set writer. Spaces are always added between operands. It returns the number of bytes written and any write error encountered.

func (*Output) Printf

func (o *Output) Printf(format string, a ...interface{}) (int, error)

Printf uses the fmt package's Printf with a pre-set writer. It returns the number of bytes written and any write error encountered.

func (*Output) Println

func (o *Output) Println(a ...interface{}) (int, error)

Println uses the fmt package's Println with a pre-set writer. Spaces are always added between operands and a newline is appended. It returns the number of bytes written and any write error encountered.

func (*Output) SetExitCode

func (o *Output) SetExitCode(code int)

SetExitCode sets the exit code to a specific int. By default, the exit code is set to 0.