Documentation
¶
Overview ¶
Package commands provides functions for registering and executing administrative commands.
To create a new command, start by writing its function. Command functions take the same form as requests handlers e.g.:
func MyCommand(ctx *app.Context)
Then register it using Register() or MustRegister().
func init() {
commands.MustRegister(MyCommand, nil)
}
This will create a command named my-comand. To specify additional command options, like its name or the flags it might accept, set the Options parameter. See the documentation on Options on this page for information on each field or, alternatively, check the example down this page.
If you're using gnd.la/app.App.ListenAndServe or gnd.la/app.App.MustListenAndServe, then you don't need to do anything else, since those functions will check if a command was provided, run it and exit. Alternatively, you can also call commands.Execute with a gnd.la/app.App instance manually if you're not using the functions previously mentioned or, if for some reason, you want to check for commands sooner. e.g.
func main() {
// Set up ORM, config etc...
config.MustParse()
a := app.New()
// Set up context processors and finalizers, etc... on a
// Now check if there's a command and run it
if !commands.Execute(a) {
// No command supplied. Set up your handlers and
// start listening.
something := anExpensiveCalculationWhichTakesALotOfTime()
a.Handle("^/hello/$", HelloHandler)
a.MustListenAndServe(-1)
}
// Command was executed. Now just exit.
}
Commands might use the context methods ParamValue() to access flags values. Methods built on top of ParamValue(), like ParseParamValue(), are also supported. Any additional non-flag arguments are passed to the command handler and might be accessed using IndexValue() (0 represents the first non-flag argument). ParseIndexValue() and related methods are also supported.
commands.MustRegister(FlagsCommand, &commands.Options{
Help: "This command does nothing interesting",
Flags: commands.Flags(commands.IntFlag("foo", 0, "Help for foo flag"), commands.BoolFlag("bar", false, "Help for bar flag")),
})
func FlagCommand(ctx *app.Context) {
var foo int
var bar bool
ctx.ParseParamValue(&foo, "foo")
ctx.ParseParamValue(&bar, "bar")
// foo and bar now contain the parameters received in the command line
}
Finally, to invoke the command, pass it to your app binary e.g.
./myapp my-command
Keep in mind that any flags parsed by your application or the Gondola config package must come before the command name.
./myapp -config=conf/production.conf my-command -mycommandflag=7
To list all the available commands together with their respective help, use the help command:
./myapp help
NOTE: These examples assume a UNIX environment. If you're using Windows type "myapp.exe" rather than "./myapp".
Index ¶
- func Error(args ...interface{})
- func Errorf(format string, args ...interface{})
- func Execute(a *app.App) (bool, error)
- func MustRegister(f app.Handler, o *Options)
- func Register(f app.Handler, o *Options) error
- func Remove(name string)
- func UsageError(args ...interface{})
- func UsageErrorf(format string, args ...interface{})
- type Flag
- type Options
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Errorf ¶
func Errorf(format string, args ...interface{})
Errorf works like Error, but accepts a format parameter.
func Execute ¶
Execute tries to run a command reading the parameters from the command line. It returs true if a command was executed and false if it wasn't. Note that most users won't need to call this function directly, since gndl.la/app.App will automatically call it before listening (and exit after executing the command if it was provided).
func MustRegister ¶
MustRegister works like Register, but panics if there's an error
func Register ¶
Register registers a new command with the given function and options (which might be nil).
func UsageError ¶
func UsageError(args ...interface{})
UsageError stops the command and prints the given error followed by the command usage.
func UsageErrorf ¶
func UsageErrorf(format string, args ...interface{})
UsageErrorf works like UsageError, but accepts a format parameter.
Types ¶
type Flag ¶
type Flag struct {
// contains filtered or unexported fields
}
Flag is a opaque type used to represent a flag for a command. Use the BoolFlag(), IntFlag() and StringFlag() functions to create a Flag. You can also use the convenience function Flags() to create a slice with several flags.
type Options ¶
type Options struct {
// The name of the command. If no name is provided,
// it will be obtained from the function name, transforming
// its name from camel case to words separated by a '-'
Name string
// The help string that will be printed for this command.
Help string
// Usage is printed just after the Help, prepending the command to it.
Usage string
// Any flags this command might accept. Use the convenience
// functions to define them.
Flags []*Flag
}
Options is used to specify the command options when registering it.
Source Files