cli

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

• func ExpectError(t *testing.T, err error)
• func ExpectErrorOutput(t *testing.T, stderr bytes.Buffer, err error)
• func ExpectHelp(t *testing.T, stderr bytes.Buffer, cmd Command)
• func ExpectMatch(t *testing.T, stdout bytes.Buffer, pattern string)
• func ExpectOutput(t *testing.T, stdout bytes.Buffer)
• func ExpectSuccess(t *testing.T, err error)
• func Main(mainCmd Command, sys *System) int
• type Action
• type CLI
  • func (c CLI) ListSubcommands(prefix string) []string
• type Command
• type HasFlags
• type HasSubcommands
• type NoOpCommand
  • func (NoOpCommand) Command(c context.Context, args []string, s *System) int
  • func (NoOpCommand) Help()
• type System
  • func (s System) Fatal(v ...interface{})
  • func (s System) Fatalf(format string, v ...interface{})
  • func (s System) Fatalln(v ...interface{})
  • func (s System) Log(a ...interface{})
  • func (s System) Logf(format string, a ...interface{})
  • func (s System) Print(a ...interface{}) (int, error)
  • func (s System) Printf(format string, a ...interface{}) (int, error)
  • func (s System) Println(a ...interface{}) (int, error)
  • func (s System) Scan(a ...interface{}) (int, error)
  • func (s System) Scanf(format string, a ...interface{}) (int, error)
  • func (s System) Scanln(a ...interface{}) (int, error)

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(mainCmd Command, sys *System) 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

Types

type Action

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

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

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 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) int

func (NoOpCommand) Help

func (NoOpCommand) Help()

type System

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

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

func (System) Fatal

func (s System) Fatal(v ...interface{})

func (System) Fatalf

func (s System) Fatalf(format string, v ...interface{})

func (System) Fatalln

func (s System) Fatalln(v ...interface{})

func (System) Log

func (s System) Log(a ...interface{})

func (System) Logf

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

func (System) Print

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

func (System) Printf

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

func (System) Println

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

func (System) Scan

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

func (System) Scanf

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

func (System) Scanln

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