cli

Documentation

Index

• Constants
• type Args
• type CLI
  • func New(config *Config) *CLI
  • func (cli *CLI) Run(ctx context.Context, args []string) (int, error)
  • func (cli *CLI) WriteHelp(data string) (int, error)
• type Command
• type Config
  • func DefaultConfig() *Config
  • func (c *Config) Merge(b *Config) *Config
• type HelpFunc
  • func DefaultHelpFunc(app string) HelpFunc
  • func FilteredHelpFunc(include []string, f HelpFunc) HelpFunc
• type MockCommand
  • func (c *MockCommand) Help() string
  • func (c *MockCommand) Run(ctx context.Context, args []string) int
  • func (c *MockCommand) Synopsis() string
• type NamedCommand
• type Router
  • func NewRouter() *Router
  • func (r *Router) AddCommand(n string, cmd Command) error
  • func (r *Router) AddMissingParents(genCmd func() Command)
  • func (r *Router) GetCommand(n string) (Command, error)
  • func (r *Router) GetLongestPrefix(s string) (string, interface{}, bool)
  • func (r *Router) GetParent(n string) string
  • func (r *Router) GetSubcommands(prefix string) map[string]Command
• type SimpleUI
  • func (u *SimpleUI) Error(message string)
  • func (u *SimpleUI) Info(message string)
  • func (u *SimpleUI) Output(message string)
  • func (u *SimpleUI) Warn(message string)
• type UI

Constants

const (
	CommandReturnCodeHelp = -18511
)

Types

type Args

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

Args contains parsed input to the CLI

type CLI

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

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

CLI also supports nested subcommands, such as "cli foo bar". To use nested subcommands, the key in the Commands mapping below contains the full subcommand. In this example, it would be "foo bar".

If you use a CLI with nested subcommands, some semantics change due to ambiguities:

• We use longest prefix matching to find a matching subcommand. This means if you register "foo bar" and the user executes "cli foo qux", the "foo" command will be executed with the arg "qux". It is up to you to handle these args. One option is to just return the special help return code `RunResultHelp` to display help and exit.

• The help flag "-h" or "-help" will look at all args to determine the help function. For example: "otto apps list -h" will show the help for "apps list" but "otto apps -h" will show it for "apps". In the normal CLI, only the first subcommand is used.

• The help flag will list any subcommands that a command takes as well as the command's help itself. If there are no subcommands, it will note this. If the CLI itself has no subcommands, this entire section is omitted.

• Any parent commands that don't exist are automatically created as no-op commands that just show help for other subcommands. For example, if you only register "foo bar", then "foo" is automatically created.

func New

func New(config *Config) *CLI

New returns a new CLI instance with sensible defaults.

func (*CLI) Run

func (cli *CLI) Run(ctx context.Context, args []string) (int, error)

Run :

func (*CLI) WriteHelp

func (cli *CLI) WriteHelp(data string) (int, error)

WriteHelp :

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

	// Synopsis should return a one-line, short synopsis of the command.
	// This should be less than 50 characters ideally.
	Synopsis() 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(ctx context.Context, args []string) int
}

A Command is a runnable sub-command of a CLI

type Config

type Config struct {
	// Name defines the name of the CLI
	Name string

	// Version of the CLI
	Version string

	// Commands is a mapping of subcommand names to a 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.
	//
	// If the key has a space in it, this will create a nested subcommand.
	// For example, if the key is "foo bar", then to access it our CLI
	// must be accessed with "./cli foo bar".
	Commands map[string]Command

	// 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
	HelpFunc HelpFunc

	// HelpWriter is the Writer where the help text is outputted to. If
	// not specified, it will default to Stderr
	HelpWriter io.Writer
}

CLI configurations

func DefaultConfig

func DefaultConfig() *Config

Default CLI configurations

func (*Config) Merge

func (c *Config) Merge(b *Config) *Config

type HelpFunc

type HelpFunc func(map[string]Command) 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 DefaultHelpFunc

func DefaultHelpFunc(app string) HelpFunc

DefaultHelpFunc is the default function for generating help output

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 {
	HelpText      string
	SynopsisText  string
	RunReturnCode int
	// Set by the command
	RunCalled bool
	RunArgs   []string
}

MockCommand is an implementation of Command that can be used for testing. It is also used for automatically populating missing parent commands.

func (*MockCommand) Help

func (c *MockCommand) Help() string

func (*MockCommand) Run

func (c *MockCommand) Run(ctx context.Context, args []string) int

func (*MockCommand) Synopsis

func (c *MockCommand) Synopsis() string

type NamedCommand

type NamedCommand interface {
	Command
	Name() string
}

A NamedCommand is a runnable sub-command of a CLI with a name

type Router

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

Router ...

func NewRouter

func NewRouter() *Router

NewRouter creates a new router.

func (*Router) AddCommand

func (r *Router) AddCommand(n string, cmd Command) error

AddCommand ...

func (*Router) AddMissingParents

func (r *Router) AddMissingParents(genCmd func() Command)

AddMissingParents ensures that every registered command has a parent.

func (*Router) GetCommand

func (r *Router) GetCommand(n string) (Command, error)

GetCommand ...

func (*Router) GetLongestPrefix

func (r *Router) GetLongestPrefix(s string) (string, interface{}, bool)

GetLongestPrefix return the longest prefix match among all commands registered in the router, considering the query string passed as argument

func (*Router) GetParent

func (r *Router) GetParent(n string) string

GetParent returns the parent of this subcommand, if there is one. Otherwise, "" is returned.

func (*Router) GetSubcommands

func (r *Router) GetSubcommands(prefix string) map[string]Command

GetSubcommands returns a map containing all commands which are below a given prefix

type SimpleUI

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

BasicUI is an implementation of UI that outputs to the given writer.

func (*SimpleUI) Error

func (u *SimpleUI) Error(message string)

func (*SimpleUI) Info

func (u *SimpleUI) Info(message string)

func (*SimpleUI) Output

func (u *SimpleUI) Output(message string)

func (*SimpleUI) Warn

func (u *SimpleUI) Warn(message string)

type UI

type UI interface {

	// 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.