commander

README

commander

commander is a spin off of golang go tool infrastructure to provide commands and sub-commands.

A commander.Command has a Subcommands field holding []*commander.Command subcommands, referenced by name from the command line.

So a Command can have sub commands.

So you can have, e.g.:

$ mycmd action1 [options...]
$ mycmd subcmd1 action1 [options...]

Example provided by:

• hwaf
• examples/my-cmd

Documentation

Is available on godoc

Installation

Is performed with the usual:

$ go get github.com/gonuts/commander

Example

See the simple my-cmd example command for how this all hangs together there:

$ my-cmd cmd1
my-cmd-cmd1: hello from cmd1 (quiet=true)

$ my-cmd cmd1 -q
my-cmd-cmd1: hello from cmd1 (quiet=true)

$ my-cmd cmd1 -q=0
my-cmd-cmd1: hello from cmd1 (quiet=false)

$ my-cmd cmd2
my-cmd-cmd2: hello from cmd2 (quiet=true)

$ my-cmd subcmd1 cmd1
my-cmd-subcmd1-cmd1: hello from subcmd1-cmd1 (quiet=true)

$ my-cmd subcmd1 cmd2
my-cmd-subcmd1-cmd2: hello from subcmd1-cmd2 (quiet=true)

$ my-cmd subcmd2 cmd1
my-cmd-subcmd2-cmd1: hello from subcmd2-cmd1 (quiet=true)

$ my-cmd subcmd2 cmd2
my-cmd-subcmd2-cmd2: hello from subcmd2-cmd2 (quiet=true)

$ my-cmd help
Usage:

	my-cmd command [arguments]

The commands are:

    cmd1        runs cmd1 and exits
    cmd2        runs cmd2 and exits
    subcmd1     subcmd1 subcommand. does subcmd1 thingies
    subcmd2     subcmd2 subcommand. does subcmd2 thingies

Use "my-cmd help [command]" for more information about a command.

Additional help topics:


Use "my-cmd help [topic]" for more information about that topic.


$ my-cmd help subcmd1
Usage:

	subcmd1 command [arguments]

The commands are:

    cmd1        runs cmd1 and exits
    cmd2        runs cmd2 and exits


Use "subcmd1 help [command]" for more information about a command.

Additional help topics:


Use "subcmd1 help [topic]" for more information about that topic.

TODO

• automatically generate the bash/zsh/csh autocompletion lists
• automatically generate Readme examples text
• test cases

Documentation

Overview

commander helps creating command line programs whose arguments are flags, commands and subcommands.

Index

• Constants
• Variables
• func CompleterFrom(cmdr *Command) *complete.Command
• type Command
  • func (c *Command) ColFormat() string
  • func (c *Command) Context() context.Context
  • func (c *Command) Dispatch(ctx context.Context, args []string) error
  • func (c *Command) FlagOptions() string
  • func (c *Command) FullName() string
  • func (c *Command) FullSpacedName() string
  • func (c *Command) Lookup(name string) interface{}
  • func (c *Command) MaxLen() (res int)
  • func (c *Command) Name() string
  • func (c *Command) Runnable() bool
  • func (c *Command) SortCommands()
  • func (c *Command) SubcommandList(list Listing) []*Command
  • func (c *Command) Usage()
• type CommandSlice
  • func (c CommandSlice) Len() int
  • func (c CommandSlice) Less(i, j int) bool
  • func (c CommandSlice) Swap(i, j int)
• type Listing

Constants

const (
	CommandsList = iota
	HelpTopicsList
	Unlisted
)

Variables

var Defaults = Command{
	UsageTemplate: `{{if .Runnable}}Usage: {{if .Parent}}{{.Parent.FullSpacedName}}{{end}} {{.UsageLine}}

{{end}}{{.FullSpacedName}} - {{.Short}}

{{if commandList}}Commands:
{{range commandList}}
    {{.Name | printf (colfmt)}} {{.Short}}{{end}}

Use "{{.Name}} help <command>" for more information about a command.

{{end}}{{.FlagOptions}}{{if helpList}}
Additional help topics:
{{range helpList}}
    {{.Name | printf (colfmt)}} {{.Short}}{{end}}

Use "{{.Name}} help <topic>" for more information about that topic.

{{end}}`,

	HelpTemplate: `{{if .Runnable}}Usage: {{if .Parent}}{{.Parent.FullSpacedName}}{{end}} {{.UsageLine}}

{{end}}{{.Long | trim}}
{{.FlagOptions}}
`,
}

Functions

func CompleterFrom

func CompleterFrom(cmdr *Command) *complete.Command

CompleterFrom creates a new tab-completer from the provided command.

Types

type Command

type Command struct {

	// UsageLine is the short usage message.
	// The first word in the line is taken to be the command name.
	UsageLine string

	// Short is the short description line shown in command lists.
	Short string

	// Long is the long description shown in the 'help <this-command>' output.
	Long string

	// List reports which list to show this command in Usage and Help.
	// Choose between {CommandsList (default), HelpTopicsList, Unlisted}
	List Listing

	// Run runs the command.
	// The args are the arguments after the command name.
	Run func(cmd *Command, args []string) error

	// Flag is a set of flags specific to this command.
	Flag flag.FlagSet

	// CustomFlags indicates that the command will do its own
	// flag parsing.
	CustomFlags bool

	// Subcommands are dispatched from this command
	Subcommands []*Command

	// Parent command, nil for root.
	Parent *Command

	// UsageTemplate formats the usage (short) information displayed to the user
	// (leave empty for default)
	UsageTemplate string

	// HelpTemplate formats the help (long) information displayed to the user
	// (leave empty for default)
	HelpTemplate string

	// Stdout and Stderr by default are os.Stdout and os.Stderr, but you can
	// point them at any io.Writer
	Stdout io.Writer
	Stderr io.Writer

	// Complete provides command completion.
	// If Complete is nil, a default one will be generated.
	Complete *complete.Command
	// contains filtered or unexported fields
}

A Command is an implementation of a subcommand.

func (*Command) ColFormat

func (c *Command) ColFormat() string

ColFormat returns the column header size format for printing in the template

func (*Command) Context

func (c *Command) Context() context.Context

func (*Command) Dispatch

func (c *Command) Dispatch(ctx context.Context, args []string) error

Dispatch executes the command using the provided arguments. If a subcommand exists matching the first argument, it is dispatched. Otherwise, the command's Run function is called.

func (*Command) FlagOptions

func (c *Command) FlagOptions() string

FlagOptions returns the flag's options as a string

func (*Command) FullName

func (c *Command) FullName() string

FullName returns the full name of the command, prefixed with parent commands

func (*Command) FullSpacedName

func (c *Command) FullSpacedName() string

FullSpacedName returns the full name of the command, with ' ' instead of '-'

func (*Command) Lookup

func (c *Command) Lookup(name string) interface{}

Lookup returns the named flag value or nil if none exists.

func (*Command) MaxLen

func (c *Command) MaxLen() (res int)

func (*Command) Name

func (c *Command) Name() string

Name returns the command's name: the first word in the usage line.

func (*Command) Runnable

func (c *Command) Runnable() bool

Runnable reports whether the command can be run; otherwise it is a documentation pseudo-command such as importpath.

func (*Command) SortCommands

func (c *Command) SortCommands()

Sort the commands

func (*Command) SubcommandList

func (c *Command) SubcommandList(list Listing) []*Command

func (*Command) Usage

func (c *Command) Usage()

Usage prints the usage details to the standard error output.

type CommandSlice

type CommandSlice []*Command

Type to allow us to use sort.Sort on a slice of Commands

func (CommandSlice) Len

func (c CommandSlice) Len() int

func (CommandSlice) Less

func (c CommandSlice) Less(i, j int) bool

func (CommandSlice) Swap

func (c CommandSlice) Swap(i, j int)

type Listing

type Listing int

UsageSection differentiates between sections in the usage text.