cmd

README

cmd

The cmd package is a lightweight, hierarchical command processor. It's handy when you have a number of text commands you wish to organize into a hierarchy.

For example, suppose you have written an application that uses the following command hierarchy:

• file
  • open
  • close
  • read
  • write
• status
• quit

With each of these commands you have associated a callback function that is called with user-supplied arguments whenever the command is matched.

Now consider what would happen if the application user types the following command into the application:

file open foo.txt rw

This command string would be fed into a command tree's Lookup function, which would return the callback associated with the file/open command as well as a slice of string arguments []string{"foo.txt", "rw"}.

The cmd package supports shortest unambiguous prefix matches, so the following command would return the same results:

f o foo.txt rw

Code examples

This code shows how the command tree used in the example above might be created:

root := cmd.NewTree("Root")

file := cmd.NewTree("File")
root.AddCommand(cmd.Command{Name: "file", Subtree: file})
file.AddCommand(cmd.Command{Name: "open", Brief: "Open file", Data: (*app).onOpen})
file.AddCommand(cmd.Command{Name: "close", Brief: "Close file", Data: (*app).onClose})
file.AddCommand(cmd.Command{Name: "read", Brief: "Read file", Data: (*app).onRead})
file.AddCommand(cmd.Command{Name: "write", Brief: "Write file", Data: (*app).onWrite})

root.AddCommand(cmd.Command{Name: "status", Brief: "Show status", Data: (*app).onStatus})
root.AddCommand(cmd.Command{Name: "quit", Brief: "Quit application", Data: (*app).onQuit})

And here is how you might query the command tree:

func (a *app) processCommand(s string) error {
    sel, err := commands.Lookup(s)
    switch {
        case err == cmd.ErrAmbiguous:
            fmt.Printf("Command '%s' is ambiguous.\n", s)
            return err
        case err == cmd.ErrNotFound:
            fmt.Printf("Command '%s' not found.\n", s)
            return err
        default:
            handler := sel.Command.Param.(func(a *app, args []string) error)
            return handler(a, sel.Args)
    }
}

Documentation

Index

• Variables
• type Command
  • func (c *Command) DisplayShortcuts(w io.Writer)
  • func (c *Command) DisplayUsage(w io.Writer)
• type Selection
• type Tree
  • func NewTree(title string) *Tree
  • func (t *Tree) AddCommand(c Command) *Command
  • func (t *Tree) AddShortcut(shortcut, target string) error
  • func (t *Tree) DisplayCommands(w io.Writer)
  • func (t *Tree) DisplayHelp(w io.Writer, args []string) error
  • func (t *Tree) Lookup(line string) (Selection, error)

Variables

var (
	ErrAmbiguous = errors.New("Command is ambiguous")
	ErrNotFound  = errors.New("Command not found")
)

Errors returned by the cmd package.

Types

type Command

type Command struct {
	Name        string      // command string
	Brief       string      // brief description shown in a command list
	Description string      // long description shown with command help
	Usage       string      // usage hint text
	Shortcuts   []string    // command shortcuts
	Subtree     *Tree       // the command's subtree of commands
	Data        interface{} // user-defined data for this command
}

A Command represents either a single named command or the root of a subtree of commands.

func (*Command) DisplayShortcuts

func (c *Command) DisplayShortcuts(w io.Writer)

DisplayShortcuts displays all shortcuts associated with the command.

func (*Command) DisplayUsage

func (c *Command) DisplayUsage(w io.Writer)

DisplayUsage outputs the command's usage string.

type Selection

type Selection struct {
	Command *Command // the selected command
	Args    []string // the command's white-space delimited arguments
}

A Selection represents the result of looking up a command in a command tree. It includes the whitespace-delimited arguments following the discovered command.

type Tree

type Tree struct {
	Title    string     // description of all commands in tree
	Commands []*Command // all commands in the tree
	// contains filtered or unexported fields
}

A Tree contains one or more commands which are grouped together and may be looked up by a shortest unambiguous prefix match.

func NewTree

func NewTree(title string) *Tree

NewTree creates a new command tree with the given title.

func (*Tree) AddCommand

func (t *Tree) AddCommand(c Command) *Command

AddCommand adds a command to a command tree.

func (*Tree) AddShortcut

func (t *Tree) AddShortcut(shortcut, target string) error

AddShortcut adds a shortcut to a command in the tree.

func (*Tree) DisplayCommands

func (t *Tree) DisplayCommands(w io.Writer)

DisplayCommands displays the commands available at the tree's top level.

func (*Tree) DisplayHelp

func (t *Tree) DisplayHelp(w io.Writer, args []string) error

DisplayHelp parses the 'help' command's arguments string and displays an appropriate help response.

func (*Tree) Lookup

func (t *Tree) Lookup(line string) (Selection, error)

Lookup performs a search on a command tree for a matching command. If found, it returns the command and the command arguments.