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:

tree := cmd.NewTree("root")
file := cmd.NewTree("file")

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

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

And here is how you might query the command tree:

func (a *app) processCommand(s string) error {
    sel, err := tree.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) DisplayDescription(w io.Writer)
  • func (c *Command) DisplayHelp(w io.Writer)
  • func (c *Command) DisplayShortcuts(w io.Writer)
  • func (c *Command) DisplayUsage(w io.Writer)
  • func (c *Command) Parent() *Tree
  • func (c *Command) Shortcuts() []string
• type CommandDescriptor
• type Node
• type Tree
  • func NewTree(d TreeDescriptor) *Tree
  • func (t *Tree) AddCommand(d CommandDescriptor) *Command
  • func (t *Tree) AddShortcut(shortcut, target string) error
  • func (t *Tree) AddSubtree(d TreeDescriptor) *Tree
  • func (t *Tree) Autocomplete(line string) []string
  • func (t *Tree) Commands() []*Command
  • func (t *Tree) DisplayHelp(w io.Writer)
  • func (t *Tree) DisplayUsage(w io.Writer)
  • func (t *Tree) GetHelp(w io.Writer, args []string) error
  • func (t *Tree) Lookup(line string) (n Node, args []string, err error)
  • func (t *Tree) LookupCommand(line string) (cmd *Command, args []string, err error)
  • func (t *Tree) LookupSubtree(line string) (subtree *Tree, args []string, err error)
  • func (t *Tree) Parent() *Tree
  • func (t *Tree) Subtrees() []*Tree
• type TreeDescriptor

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 {
	CommandDescriptor
	// contains filtered or unexported fields
}

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

func (*Command) DisplayDescription

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

DisplayDescription outputs the command's description text. If the command has no description, the commands 'brief' text is output instead.

func (*Command) DisplayHelp

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

DisplayHelp outputs the help text associated with the command, including its usage, description, and shortcuts.

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.

func (*Command) Parent

func (c *Command) Parent() *Tree

Parent returns the parent tree containing this command.

func (*Command) Shortcuts

func (c *Command) Shortcuts() []string

Shortcuts returns the shortcut strings associated with the command.

type CommandDescriptor

type CommandDescriptor struct {
	Name        string // command name
	Brief       string // brief description shown in a command list
	Description string // long description shown with command help
	Usage       string // usage hint text
	Data        any    // user-defined data
}

A CommandDescriptor describes a single command within a command tree.

type Node

type Node interface {
	DisplayHelp(w io.Writer)
	Parent() *Tree
	// contains filtered or unexported methods
}

A Node may be a Tree or a Command.

type Tree

type Tree struct {
	TreeDescriptor
	// 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(d TreeDescriptor) *Tree

NewTree creates a new command tree with the given title.

func (*Tree) AddCommand

func (t *Tree) AddCommand(d CommandDescriptor) *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) AddSubtree

func (t *Tree) AddSubtree(d TreeDescriptor) *Tree

AddSubtree adds a child command tree to an existing command tree.

func (*Tree) Autocomplete

func (t *Tree) Autocomplete(line string) []string

Autocomplete builds a list of auto-completion candidates for the provided line of text.

func (*Tree) Commands

func (t *Tree) Commands() []*Command

Commands returns the tree's commands.

func (*Tree) DisplayHelp

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

DisplayHelp displays a sorted list of commands (and subtrees) available at the tree's top level.

func (*Tree) DisplayUsage

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

DisplayUsage outputs the tree's usage string.

func (*Tree) GetHelp

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

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

func (*Tree) Lookup

func (t *Tree) Lookup(line string) (n Node, args []string, err error)

Lookup performs a search on a command tree for a command or subtree node matching the line input. If found, it returns the matching node and the remaining unmatched line arguments.

func (*Tree) LookupCommand

func (t *Tree) LookupCommand(line string) (cmd *Command, args []string, err error)

LookupCommand performs a search on a command tree for a command matching the line input. If found, it returns the matching command and the remaining unmatched line arguments.

func (*Tree) LookupSubtree

func (t *Tree) LookupSubtree(line string) (subtree *Tree, args []string, err error)

LookupSubtree performs a search on a command tree for a subtree matching the line input. If found, it returns the matching subtree and the remaining unmatched line arguments.

func (*Tree) Parent

func (t *Tree) Parent() *Tree

Parent returns the tree's parent tree, or nil if the tree is the root of the command tree.

func (*Tree) Subtrees

func (t *Tree) Subtrees() []*Tree

Subtrees returns the tree's subtrees.

type TreeDescriptor

type TreeDescriptor struct {
	Name        string // tree name
	Brief       string // brief description shown in a command list
	Description string // long description shown with command help
	Usage       string // usage hint text
	Data        any    // user-defined data
}

A TreeDescriptor describes a command tree.