subcom

README

Subcommander

Somewhat easy subcommand-runner

Documentation

Overview

Package subcom is a somewhat easy subcommand runner.

Index

• Variables
• func AddSpecs[T any](c *Cdr[T], specs []Spec[T])
• type Cdr
  • func New[T any](specs []Spec[T]) *Cdr[T]
  • func (c *Cdr[T]) Add(name, argHelp, description string, handler Handler[T])
  • func (c *Cdr[T]) Call(ctx T, parents []string, args []string) error
  • func (c *Cdr[T]) Specs() map[string]Spec[T]
  • func (c *Cdr[T]) Table() string
• type Handler
• type Spec

Variables

var (
	// ErrEmptyArgs is returned if an empty args slice was passed to
	// Cdr.Call.
	ErrEmptyArgs = errors.New("empty args")

	// ErrNotFound is returned by Cdr.Call if args[0] didn't have a
	// registered Handler.
	ErrNotFound = errors.New("command not found")
)

Functions

func AddSpecs

func AddSpecs[T any](c *Cdr[T], specs []Spec[T])

AddSpecs adds the given commands handlers to s, possibly overwriting existing handlers. specs may be nil.

Types

type Cdr

type Cdr[T any] struct {
	// contains filtered or unexported fields
}

Cdr holds and calls (sub)commands. Cdr's methods are safe for concurrent use by multiple goroutines.

func New

func New[T any](specs []Spec[T]) *Cdr[T]

New returns a new Subcommander, ready for use. If any Specs are provided the new Cdr will contain them. specs may be nil.

func (*Cdr[T]) Add

func (c *Cdr[T]) Add(name, argHelp, description string, handler Handler[T])

Add adds a single Handler to c. If handler is nil and c has a Handler with the given name, the Handler will be deleted.

func (*Cdr[T]) Call

func (c *Cdr[T]) Call(ctx T, parents []string, args []string) error

Call calls a command registered with the Subcommander. The command name is assumed to be args[0]; the name will be appended to parents and removed from he args passed to the CommandHandler. If the comand wasn't found, ErrNotFound is returned. Parents will not be modified by Call, at the cost of an allocation and copy. A subslice of args will be passed to the CommandHandler; it will never be nil.

func (*Cdr[T]) Specs

func (c *Cdr[T]) Specs() map[string]Spec[T]

Specs returns the Specs added to c. The caller owns the returned slice.

func (*Cdr[T]) Table

func (c *Cdr[T]) Table() string

Table returns a formatted table of commands and descriptions, suitable for use in Usage statements. The table will not end in a newline. If c has no commands, an empty string is returned.

type Handler

type Handler[T any] func(ctx T, name, args []string) error

Handler is what's called when a cammand is executed.

type Spec

type Spec[T any] struct {
	Name        string     /* Command's callable name. */
	ArgHelp     string     /* Argument help. */
	Description string     /* One-line description. */
	Handler     Handler[T] /* Nil to delete a handler. */
}

Spec is used to add a command to a handler.