README
¶
subcommands
This is a simple package which allows you to write a CLI with distinct subcommands.
Overview
Using this library you can enable your command-line application to have a number of subcommands, allowing things like this to be executed:
$ application one
$ application two [args]
$ application help
In addition to allowing the user to specify a sub-command via the first argument it will also allow a default to be used if your binary has the same name as a sub-command.
For example if you had a binary named gobox you could create a symlink called ls:
$ ln -s gobox ls
$ ./ls
Here running ls is the same as running gobox ls, and argument parsing would work the same too:
$ gobox ls --foo
$ ./ls --foo
Bash Completion
All applications using this library will find it easy to generate a bash-completion script, via the following addition to their init-file:
$ source <(application bash-completion)
The generated completion-script will allow TAB-completion of the sub-commands, as well as their options.
Rationale
There are several frameworks for building a simple CLI application, such as Corba. But those are relatively heavyweight.
This is designed to implement the minimum required support:
- Allow an application to register sub-commands:
foo help- Show help
foo version- Show the version
foo server- Launch a HTTP-server
- etc.
- Allow flags to be defined on a per-subcommand basis.
- Allow the sub-commands to process any remaining arguments.
- Allow trivial bash-completion scripts to be generated.
Example
There is a simple example defined in _example/main.go.
Documentation
¶
Overview ¶
Package subcommands allows you to easily implement a simple CLI with well-defined and distinct subcommands.
The implementation is pretty naive, but it is sufficient to implement a simple command.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Register ¶
func Register(cmd Subcommand)
Register adds a new subcommand to those which are available.
Types ¶
type BashCompletion ¶ added in v0.8.0
type BashCompletion struct {
// We embed the NoFlags option, because we accept no
// command-line flags.
NoFlags
}
BashCompletion is a structure which implements the built-in "bash-completion" subcommand.
func (*BashCompletion) Execute ¶ added in v0.8.0
func (bc *BashCompletion) Execute(args []string) int
Execute the command.
func (*BashCompletion) Info ¶ added in v0.8.0
func (bc *BashCompletion) Info() (string, string)
Info returns the name of this subcommand, along with a one-line synopsis.
type CommandList ¶ added in v0.7.0
type CommandList struct {
// We embed the NoFlags option, because we accept no
// command-line flags.
NoFlags
}
CommandList is a structure which implements the built-in "commands" subcommand
func (*CommandList) Execute ¶ added in v0.7.0
func (c *CommandList) Execute(args []string) int
Execute the command.
func (*CommandList) Info ¶ added in v0.7.0
func (c *CommandList) Info() (string, string)
Info returns the name of this subcommand, along with a one-line synopsis.
type Help ¶
type Help struct {
// We embed the NoFlags option, because we accept no
// command-line flags.
NoFlags
}
Help is a structure which implements the built-in help subcommand
type NoFlags ¶
type NoFlags struct {
}
NoFlags is a helper method which allows you to define sub-commands which take no flags.
You still need to define `Info`, and `Execute()`, but this saves a little needless typing.
type Subcommand ¶
type Subcommand interface {
// Arguments sets up any required arguments.
Arguments(f *flag.FlagSet)
// Info is designed to returns the name, and brief
// description of the command.
Info() (string, string)
// The function is invoked if this subcommand is invoked.
//
// The arguments are any non-flag arguments passed to the
// subcommand, and the return value can be used as your
// exit-code.
Execute(args []string) int
}
Subcommand is the interface which subcommands must implement.
In brief a sub-command has a name, a function to invoke it, and the ability to define command-line flags which are specific to it.
Source Files
Directories