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:
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
- 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 ¶ added in v0.3.0
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 ¶
ColFormat returns the column header size format for printing in the template
func (*Command) Dispatch ¶
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 ¶
FlagOptions returns the flag's options as a string
func (*Command) FullName ¶
FullName returns the full name of the command, prefixed with parent commands
func (*Command) FullSpacedName ¶
FullSpacedName returns the full name of the command, with ' ' instead of '-'
func (*Command) Runnable ¶
Runnable reports whether the command can be run; otherwise it is a documentation pseudo-command such as importpath.
func (*Command) SubcommandList ¶
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)
Source Files
Directories