cli

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 13, 2015 License: MPL-2.0, MPL-2.0 Imports: 12 Imported by: 0

README

Go CLI Library GoDoc

cli is a library for implementing powerful command-line interfaces in Go. cli is the library that powers the CLI for Packer, Serf, and Consul.

Features

  • Easy sub-command based CLIs: cli foo, cli bar, etc.

  • Optional support for default subcommands so cli does something other than error.

  • Automatic help generation for listing subcommands

  • Automatic help flag recognition of -h, --help, etc.

  • Automatic version flag recognition of -v, --version.

  • Helpers for interacting with the terminal, such as outputting information, asking for input, etc. These are optional, you can always interact with the terminal however you choose.

  • Use of Go interfaces/types makes augmenting various parts of the library a piece of cake.

Example

Below is a simple example of creating and running a CLI

package main

import (
	"log"
	"os"

	"github.com/mitchellh/cli"
)

func main() {
	c := cli.NewCLI("app", "1.0.0")
	c.Args = os.Args[1:]
	c.Commands = map[string]cli.CommandFactory{
		"foo": fooCommandFactory,
		"bar": barCommandFactory,
	}

	exitStatus, err := c.Run()
	if err != nil {
		log.Println(err)
	}

	os.Exit(exitStatus)
}

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	UiColorNone    UiColor = UiColor{-1, false}
	UiColorRed             = UiColor{31, false}
	UiColorGreen           = UiColor{32, false}
	UiColorYellow          = UiColor{33, false}
	UiColorBlue            = UiColor{34, false}
	UiColorMagenta         = UiColor{35, false}
	UiColorCyan            = UiColor{36, false}
)

A list of colors that are useful. These are all non-bolded by default.

Functions

This section is empty.

Types

type BasicUi

type BasicUi struct {
	Reader      io.Reader
	Writer      io.Writer
	ErrorWriter io.Writer
}

BasicUi is an implementation of Ui that just outputs to the given writer. This UI is not threadsafe by default, but you can wrap it in a ConcurrentUi to make it safe.

func (*BasicUi) Ask

func (u *BasicUi) Ask(query string) (string, error)

func (*BasicUi) AskSecret added in v0.1.2

func (u *BasicUi) AskSecret(query string) (string, error)

func (*BasicUi) Error

func (u *BasicUi) Error(message string)

func (*BasicUi) Info

func (u *BasicUi) Info(message string)

func (*BasicUi) Output

func (u *BasicUi) Output(message string)

func (*BasicUi) Warn

func (u *BasicUi) Warn(message string)

type CLI

type CLI struct {
	// Args is the list of command-line arguments received excluding
	// the name of the app. For example, if the command "./cli foo bar"
	// was invoked, then Args should be []string{"foo", "bar"}.
	Args []string

	// Commands is a mapping of subcommand names to a factory function
	// for creating that Command implementation. If there is a command
	// with a blank string "", then it will be used as the default command
	// if no subcommand is specified.
	Commands map[string]CommandFactory

	// Name defines the name of the CLI.
	Name string

	// Version of the CLI.
	Version string

	// HelpFunc and HelpWriter are used to output help information, if
	// requested.
	//
	// HelpFunc is the function called to generate the generic help
	// text that is shown if help must be shown for the CLI that doesn't
	// pertain to a specific command.
	//
	// HelpWriter is the Writer where the help text is outputted to. If
	// not specified, it will default to Stderr.
	HelpFunc   HelpFunc
	HelpWriter io.Writer
	// contains filtered or unexported fields
}

CLI contains the state necessary to run subcommands and parse the command line arguments.

func NewCLI

func NewCLI(app, version string) *CLI

NewClI returns a new CLI instance with sensible defaults.

func (*CLI) IsHelp

func (c *CLI) IsHelp() bool

IsHelp returns whether or not the help flag is present within the arguments.

func (*CLI) IsVersion

func (c *CLI) IsVersion() bool

IsVersion returns whether or not the version flag is present within the arguments.

func (*CLI) Run

func (c *CLI) Run() (int, error)

Run runs the actual CLI based on the arguments given.

func (*CLI) Subcommand

func (c *CLI) Subcommand() string

Subcommand returns the subcommand that the CLI would execute. For example, a CLI from "--version version --help" would return a Subcommand of "version"

func (*CLI) SubcommandArgs

func (c *CLI) SubcommandArgs() []string

SubcommandArgs returns the arguments that will be passed to the subcommand.

type ColoredUi

type ColoredUi struct {
	OutputColor UiColor
	InfoColor   UiColor
	ErrorColor  UiColor
	WarnColor   UiColor
	Ui          Ui
}

ColoredUi is a Ui implementation that colors its output according to the given color schemes for the given type of output.

func (*ColoredUi) Ask

func (u *ColoredUi) Ask(query string) (string, error)

func (*ColoredUi) AskSecret added in v0.1.2

func (u *ColoredUi) AskSecret(query string) (string, error)

func (*ColoredUi) Error

func (u *ColoredUi) Error(message string)

func (*ColoredUi) Info

func (u *ColoredUi) Info(message string)

func (*ColoredUi) Output

func (u *ColoredUi) Output(message string)

func (*ColoredUi) Warn

func (u *ColoredUi) Warn(message string)

type Command

type Command interface {
	// Help should return long-form help text that includes the command-line
	// usage, a brief few sentences explaining the function of the command,
	// and the complete list of flags the command accepts.
	Help() string

	// Run should run the actual command with the given CLI instance and
	// command-line arguments. It should return the exit status when it is
	// finished.
	Run(args []string) int

	// Synopsis should return a one-line, short synopsis of the command.
	// This should be less than 50 characters ideally.
	Synopsis() string
}

A command is a runnable sub-command of a CLI.

type CommandFactory

type CommandFactory func() (Command, error)

CommandFactory is a type of function that is a factory for commands. We need a factory because we may need to setup some state on the struct that implements the command itself.

type ConcurrentUi

type ConcurrentUi struct {
	Ui Ui
	// contains filtered or unexported fields
}

ConcurrentUi is a wrapper around a Ui interface (and implements that interface) making the underlying Ui concurrency safe.

func (*ConcurrentUi) Ask

func (u *ConcurrentUi) Ask(query string) (string, error)

func (*ConcurrentUi) AskSecret added in v0.1.2

func (u *ConcurrentUi) AskSecret(query string) (string, error)

func (*ConcurrentUi) Error

func (u *ConcurrentUi) Error(message string)

func (*ConcurrentUi) Info

func (u *ConcurrentUi) Info(message string)

func (*ConcurrentUi) Output

func (u *ConcurrentUi) Output(message string)

func (*ConcurrentUi) Warn

func (u *ConcurrentUi) Warn(message string)

type HelpFunc

type HelpFunc func(map[string]CommandFactory) string

HelpFunc is the type of the function that is responsible for generating the help output when the CLI must show the general help text.

func BasicHelpFunc

func BasicHelpFunc(app string) HelpFunc

BasicHelpFunc generates some basic help output that is usually good enough for most CLI applications.

func FilteredHelpFunc

func FilteredHelpFunc(include []string, f HelpFunc) HelpFunc

FilteredHelpFunc will filter the commands to only include the keys in the include parameter.

type MockCommand

type MockCommand struct {
	// Settable
	HelpText     string
	RunResult    int
	SynopsisText string

	// Set by the command
	RunCalled bool
	RunArgs   []string
}

MockCommand is an implementation of Command that can be used for tests. It is publicly exported from this package in case you want to use it externally.

func (*MockCommand) Help

func (c *MockCommand) Help() string

func (*MockCommand) Run

func (c *MockCommand) Run(args []string) int

func (*MockCommand) Synopsis

func (c *MockCommand) Synopsis() string

type MockUi

type MockUi struct {
	InputReader  io.Reader
	ErrorWriter  *bytes.Buffer
	OutputWriter *bytes.Buffer
	// contains filtered or unexported fields
}

MockUi is a mock UI that is used for tests and is exported publicly for use in external tests if needed as well.

func (*MockUi) Ask

func (u *MockUi) Ask(query string) (string, error)

func (*MockUi) AskSecret added in v0.1.2

func (u *MockUi) AskSecret(query string) (string, error)

func (*MockUi) Error

func (u *MockUi) Error(message string)

func (*MockUi) Info

func (u *MockUi) Info(message string)

func (*MockUi) Output

func (u *MockUi) Output(message string)

func (*MockUi) Warn

func (u *MockUi) Warn(message string)

type PrefixedUi

type PrefixedUi struct {
	AskPrefix       string
	AskSecretPrefix string
	OutputPrefix    string
	InfoPrefix      string
	ErrorPrefix     string
	WarnPrefix      string
	Ui              Ui
}

PrefixedUi is an implementation of Ui that prefixes messages.

func (*PrefixedUi) Ask

func (u *PrefixedUi) Ask(query string) (string, error)

func (*PrefixedUi) AskSecret added in v0.1.2

func (u *PrefixedUi) AskSecret(query string) (string, error)

func (*PrefixedUi) Error

func (u *PrefixedUi) Error(message string)

func (*PrefixedUi) Info

func (u *PrefixedUi) Info(message string)

func (*PrefixedUi) Output

func (u *PrefixedUi) Output(message string)

func (*PrefixedUi) Warn

func (u *PrefixedUi) Warn(message string)

type Ui

type Ui interface {
	// Ask asks the user for input using the given query. The response is
	// returned as the given string, or an error.
	Ask(string) (string, error)

	// AskSecret asks the user for input using the given query, but does not echo
	// the keystrokes to the terminal.
	AskSecret(string) (string, error)

	// Output is called for normal standard output.
	Output(string)

	// Info is called for information related to the previous output.
	// In general this may be the exact same as Output, but this gives
	// Ui implementors some flexibility with output formats.
	Info(string)

	// Error is used for any error messages that might appear on standard
	// error.
	Error(string)

	// Warn is used for any warning messages that might appear on standard
	// error.
	Warn(string)
}

Ui is an interface for interacting with the terminal, or "interface" of a CLI. This abstraction doesn't have to be used, but helps provide a simple, layerable way to manage user interactions.

type UiColor

type UiColor struct {
	Code int
	Bold bool
}

UiColor is a posix shell color code to use.

type UiWriter

type UiWriter struct {
	Ui Ui
}

UiWriter is an io.Writer implementation that can be used with loggers that writes every line of log output data to a Ui at the Info level.

func (*UiWriter) Write

func (w *UiWriter) Write(p []byte) (n int, err error)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL