cli

Documentation

Overview

Package cli provides tbd's command dispatcher: a small registry that commands join from their init() functions, plus the Context handed to each handler.

Index

• func Dispatch(ctx *Context) error
• func Register(c *Command)
• func Run(rawArgs []string) int
• type Args
  • func Parse(a []string) Args
• type Command
  • func Commands() []*Command
  • func Lookup(name string) (*Command, bool)
• type Context
  • func (c *Context) Colors() render.Colors
• type ExitError
  • func (e ExitError) Error() string

Functions

func Dispatch

func Dispatch(ctx *Context) error

Dispatch validates and runs the command named by ctx.Args.Command using the given Context, returning the command's error. Unlike Run it does not touch the process streams or exit code, so a command handler can invoke it to resume a previously interrupted operation (see tbd continue).

func Register

func Register(c *Command)

Register adds a command to the dispatch table. Commands call this from init().

func Run

func Run(rawArgs []string) int

Run parses argv, builds a Context, and dispatches to the matching command. It returns a process exit code.

Types

type Args

type Args = argv.Args

Args and Parse are re-exported from the argv parser library so existing callers keep working while the parsing/validation logic lives in one place.

func Parse

func Parse(a []string) Args

Parse splits a raw argument vector into a command and its arguments.

type Command

type Command struct {
	Name    string
	Summary string
	Usage   string
	Spec    argv.Spec
	Run     func(*Context) error
}

Command is a registered tbd subcommand. Spec declares the options it accepts; the dispatcher validates every invocation against it (merged with the global options), so unknown options get a helpful error instead of being ignored.

func Commands

func Commands() []*Command

Commands returns all registered commands sorted by name.

func Lookup

func Lookup(name string) (*Command, bool)

Lookup returns a registered command by name.

type Context

type Context struct {
	Args   Args
	Raw    []string // the raw argv tokens this command was invoked with
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer
	Dir    string
	IsTTY  bool
}

Context carries everything a command handler needs: the parsed arguments, output streams, and the directory from which tbd was invoked.

func (*Context) Colors

func (c *Context) Colors() render.Colors

Colors returns a colorizer honoring the color-mode argument and TTY status.

type ExitError

type ExitError struct{ Code int }

ExitError lets a command set the process exit code without the dispatcher printing an error message (the command has already reported its own output).

func (ExitError) Error

func (e ExitError) Error() string