cli

package module
v0.10.0 Latest Latest
Warning

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

Go to latest
Published: Oct 14, 2020 License: MIT Imports: 18 Imported by: 2

README

This is yet another library for structuring command-line interfaces. It aims to utilize the Go standard library as much as possible and provide a simpler API than other options.

Goals:

  • As lightweight as possible; should leverage the Go standard library for everything it can
  • Should enforce consistency. The framework should encourage developers to provide a good user experience, and conform to platform expectations.
  • Simple and easy to use. Developers should be able to pick it up with little or no documentation.

Features:

  • Easy to create nested subcommands
  • Enforced contextual help for every command, subcommand, and flag
  • Enforced use of Go contexts for traceability
  • Patterns for environment and flag parsing
  • Assertions for writing tests

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ExpectError

func ExpectError(t *testing.T, err error)

func ExpectErrorOutput

func ExpectErrorOutput(t *testing.T, stderr bytes.Buffer, err error)

func ExpectHelp

func ExpectHelp(t *testing.T, stderr bytes.Buffer, cmd Command)

func ExpectMatch

func ExpectMatch(t *testing.T, stdout bytes.Buffer, pattern string)

func ExpectOutput

func ExpectOutput(t *testing.T, stdout bytes.Buffer)

func ExpectSuccess

func ExpectSuccess(t *testing.T, err error)

func Main

func Main(ctx context.Context, mainCmd Command, sys System) (status int)

Main should be called from a CLI application's `main` function. It should be passed the Command that represents the root of the subcommand tree. Main will parse the command line, determine which subcommand is the intended target, create a FlagSet then execute that subcommand. If no suitable subcommand is found, or if flag parsing fails, it will call the Help method from the most-recently visited subcommand. Main returns the Unix status code which should be returned to the underlying OS

func NewTestSystem added in v0.8.0

func NewTestSystem(
	t *testing.T, arguments []string, environment map[string]string,
) (*TestSystem, *TestOutput)

Types

type Action

type Action interface {
	// Command is the method that actually performs the command.
	Command(context.Context, []string, System) error
}

Action is an interface for commands that do things other than display information

type BaseSystem added in v0.8.0

type BaseSystem struct {
	In          io.Reader
	Out         io.Writer
	Logger      *log.Logger
	Environment map[string]string
	Arguments   []string
}

func (*BaseSystem) Args added in v0.8.0

func (s *BaseSystem) Args() []string

func (*BaseSystem) Environ added in v0.8.0

func (s *BaseSystem) Environ() []string

func (*BaseSystem) Getenv added in v0.8.0

func (s *BaseSystem) Getenv(k string) string

func (*BaseSystem) Log added in v0.8.0

func (s *BaseSystem) Log(a ...interface{})

func (*BaseSystem) Logf added in v0.8.0

func (s *BaseSystem) Logf(format string, a ...interface{})

func (*BaseSystem) Print added in v0.8.0

func (s *BaseSystem) Print(a ...interface{}) (int, error)

func (*BaseSystem) Printf added in v0.8.0

func (s *BaseSystem) Printf(format string, a ...interface{}) (int, error)

func (*BaseSystem) Println added in v0.8.0

func (s *BaseSystem) Println(a ...interface{}) (int, error)

func (*BaseSystem) Scan added in v0.8.0

func (s *BaseSystem) Scan(a ...interface{}) (int, error)

func (*BaseSystem) Scanf added in v0.8.0

func (s *BaseSystem) Scanf(format string, a ...interface{}) (int, error)

func (*BaseSystem) Scanln added in v0.8.0

func (s *BaseSystem) Scanln(a ...interface{}) (int, error)

type CLI

type CLI map[string]Command

CLI is a map of names to Command implementations. It is used to represent a set of subcommands for a given Command

func (CLI) ListSubcommands

func (c CLI) ListSubcommands(prefix string) []string

type Command

type Command interface {
	// Help is called for a command if the command line fails to parse. It may
	// also be manually called in the `Command` method if appropriate.
	Help()
}

Command is an interface used to represent a CLI component. Both primary commands and subcommands implement Command

type ExitError added in v0.10.0

type ExitError struct {
	Status  int
	Message string
}

func (*ExitError) Error added in v0.10.0

func (e *ExitError) Error() string

type HasFlags

type HasFlags interface {
	// Flags is called before `Command` and is passed a pointer to a flag.FlagSet
	// where the Command may define flags to be automatically parsed
	Flags(*flag.FlagSet)
}

HasFlags is an interface for commands that use flags

type HasSubcommands

type HasSubcommands interface {
	// Subcommands should return a CLI if the command has subcommands
	Subcommands() CLI
}

HasSubcommands is an interface for commands that have subcommands

type NoOpCommand

type NoOpCommand struct{}

NoOpCommand is a command that does nothing.

func (NoOpCommand) Command

func (NoOpCommand) Command(c context.Context, args []string, s *System) error

func (NoOpCommand) Help

func (NoOpCommand) Help()

type System

type System interface {
	Environ() []string
	Getenv(string) string
	Args() []string

	Print(...interface{}) (int, error)
	Printf(string, ...interface{}) (int, error)
	Println(...interface{}) (int, error)

	Scan(...interface{}) (int, error)
	Scanf(string, ...interface{}) (int, error)

	Log(...interface{})
	Logf(string, ...interface{})

	ReadPassword() (string, error)
}

System is passed to commands as an argument when the command is run. It provides an IO interface for the command to use that can be easily attached to STDIN/STDOUT or to bytes.Buffer for testing

type TestOutput added in v0.8.2

type TestOutput struct {
	STDOUT *bytes.Buffer
	STDERR *bytes.Buffer
}

type TestSystem added in v0.8.0

type TestSystem struct {
	*BaseSystem
	Console *expect.Console
}

func (*TestSystem) ReadPassword added in v0.8.2

func (ts *TestSystem) ReadPassword() (string, error)

type UnixSystem added in v0.8.0

type UnixSystem struct {
	*BaseSystem
}

func NewUnixSystem added in v0.8.0

func NewUnixSystem() *UnixSystem

func (*UnixSystem) ReadPassword added in v0.8.2

func (s *UnixSystem) ReadPassword() (string, error)

Jump to

Keyboard shortcuts

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