README
Documentation
¶
Overview ¶
Package hadfield implements a basic subcommand system to complement the flag package.
Example ¶
package main
import (
"fmt"
"os"
"hawx.me/code/hadfield"
)
var cmdGreet = &hadfield.Command{
Usage: "greet [options]",
Short: "displays a greeting",
Long: `
Greet displays a formatted greeting to a person in the language specified.
--person <name> # Name of person to greet
--lang <en|fr> # Language to use, English or French
`,
}
func runGreet(cmd *hadfield.Command, args []string) {
switch greetLang {
case "en":
fmt.Println("Hello", greetPerson)
case "fr":
fmt.Println("Bonjour", greetPerson)
default:
os.Exit(2)
}
}
var greetPerson, greetLang string
func init() {
cmdGreet.Run = runGreet
cmdGreet.Flag.StringVar(&greetPerson, "person", "someone?", "")
cmdGreet.Flag.StringVar(&greetLang, "lang", "en", "")
}
var templates = hadfield.Templates{
Help: `usage: example [command] [arguments]
This is an example.
Commands: {{range .}}
{{.Name | printf "%-15s"}} # {{.Short}}{{end}}
`,
Command: `usage: example {{.Usage}}
{{.Long}}
`,
}
var commands = hadfield.Commands{
cmdGreet,
}
func main() {
hadfield.Run(commands, templates)
}
Output:
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var Exit = os.Exit
Customisable Exit function. This is used for exiting in various places throughout and can be overriden for testing purposes or to perform other tasks.
Functions ¶
func CommandUsage ¶
CommandUsage writes a help message for the subcommand to Stdout.
Types ¶
type Command ¶
type Command struct {
// Run runs the command. It is passed the list of args that came after the
// command name.
Run func(cmd *Command, args []string)
// Usage returns the one-line usage string. The first word on the line is
// taken to be the command name.
Usage string
// Short is a single line description used in the help listing.
Short string
// Long is the detailed and formatted message shown in the full help for the
// command.
Long string
Flag flag.FlagSet
CustomFlags bool
}
func (*Command) Call ¶
Call parses the flags if CustomFlags is not set, then calls the function defined by Run, and finally exits.
func (*Command) Category ¶
Category returns "Command" if Run is defined, and otherwise "Documentation".
type Interface ¶
type Interface interface {
// Name is the word used to call the subcommand.
Name() string
// Data is used when rendering help and usage templates. Values that should be
// expected are:
//
// Callable:
// i.e. Callable()
// Category:
// i.e. Category().
// Usage:
// The string starting with the commands name.
// Short:
// A short, one-line, description.
// Long:
// A long description.
// Name:
// i.e. Name().
Data() interface{}
// Category is the type of subcommand, it can be anything and can be used to
// group subcommands together.
Category() string
// Callable is true if the Call() method actually does something.
Callable() bool
// Call runs the subcommand.
Call(cmd Interface, templates Templates, args []string)
}
Interface defines the common behaviour of subcommands. The default implementation is Command, but it is possible to mix these with other types of subcommand such as those dynamically discovered when used.
type Templates ¶
type Templates struct {
// Help is the template rendered to display the help for the executable, that
// is the one shown when "$0 help", "$0 -h" or "$0 --help" are called.
Help Template
// Command is the template rendered to display help for a particular
// subcommand, it is shown when "$0 help [subcommand]", "$0 [subcommand] -h"
// or "$0 [subcommand] --help" are called.
Command Template
}
Templates defines how the help screens are displayed given in the text/template format.
Source Files