README
¶
Comandante
Simple command line interfaces.
What is Comandante
Many command line tools are structured to accept subcommands. Like the go tool. When you run the go command you are presented with help text listing the available subcommands. Each subcommand has its own command line flags and documentation. Comandante makes creating binaries with subcommands easy.
So what does Comandante look like? Let's say that you are creating a program called "coolbinary" with two subcommands: "sayhi" and "demo". If you were to run coolbinary without a subcommand
$ coolbinary
you would get this output:
Do cool things from the commandline
Usage:
coolbinary command [arguments]
Available commands:
demo run a demo
help get more information about a command
sayhi say hello
Use "coolbinary help [command]" for more information about a command.
And the (over)simplified code that handles the subcommands:
bin := comandante.New("coolbinary", "Do cool things from the commandline")
bin.IncludeHelp() // comandante can create a "help" command for you
greetCmd := comandante.NewCommand("sayhi", "say hello", helloFunction)
greetCmd.Documentation = "This is longer form documentation for the sayhi command"
bin.RegisterCommand(greetCmd)
demoCmd := comandante.NewCommand("demo", "Run a demo", DemoFunction)
demoCmd.Documentation = "longer form documentation of the demo command"
bin.RegisterCommand(demoCmd)
// run the command
if err := bin.Run(); err != nil {
fmt.Fprintln(os.Stderr, err)
}
If you were to invoke the sayhi subcommand
$ coolbinary sayhi
helloFunction would be called
Installation
Install to your GOPATH with
$ go get github.com/robmerrell/comandante
Usage
First step is to generate a new comandante with the name of your program and a short description:
bin := comandante.New("coolbinary", "Do cool things from the commandline")
We also want to include the autogenerated help command:
bin.IncludeHelp()
Now we add subcommands to that comandante instance. Creating a new subcommand takes a name and a short description.
greetCmd := comandante.NewCommand("sayhi", "say hello", helloFunction)
bin.RegisterCommand(greetCmd)
We also should give that subcommand a longer description for the autogenerated help:
greetCmd.Documentation = `
This is longer form documentation that describes this command in much greater detail.
`
Now register the subcommand with comandante:
bin.RegisterCommand(greetCmd)
Command line options
Subcommands can also handle their own command line options via FlagInit. These command line options are automatically displayed in the command's help text.
var testFlag string
greeterCmd.FlagInit = func(fs *flag.FlagSet) {
fs.StringVar(&testFlag, "testing", "", "This is the usage")
}
License
The MIT License (MIT)
Copyright (c) 2013 Rob Merrell
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Comandante ¶
type Comandante struct {
// contains filtered or unexported fields
}
func (*Comandante) IncludeHelp ¶
func (c *Comandante) IncludeHelp()
IncludeHelp adds the built in help command.
func (*Comandante) RegisterCommand ¶
func (c *Comandante) RegisterCommand(cmd *Command) error
RegisterCommand tells Comandante about a command so that it can be used.
func (*Comandante) Run ¶
func (c *Comandante) Run() error
Run finds a command based on the command line argument and invokes the command in the case that one is found.
type Command ¶
type Command struct {
// Name is used for invoking the command. If Name is "sayhello" the command is
// invoked with: your-binary sayhello
Name string
// ShortDescription is a one line description of the command that is displayed in
// the default list of commands
ShortDescription string
// Documentation is a longer form of help text that is displayed when help
// information is queried about a specific command.
Documentation string
// Action is the function called when the command is invoked
Action actionFunc
// FlagInit is the function called to handle delaing with flags sent to the command
FlagInit flagInitFunc
// FlagPostParse is the function called after the flagset has been parsed
FlagPostParse flagPostParseFunc
// contains filtered or unexported fields
}
Command details a command that can be run from the command line
func NewCommand ¶
NewCommand creates a new command with a name, a short description and an action that runs when the command is invoked.
type PrintableCommandsByName ¶
type PrintableCommandsByName struct {
// contains filtered or unexported fields
}
func (PrintableCommandsByName) Less ¶
func (s PrintableCommandsByName) Less(i, j int) bool
Source Files