subcommands: Index | Files | Directories

package subcommands

import ""

Package subcommands permits a Go application to implement subcommands support similar to what is supported by the 'go' tool.

The library is designed so that the test cases can run concurrently. Using global flags variables is discouraged to keep your program testable conccurently.


Package Files

logger.go subcommands.go


var CmdHelp = &Command{
    UsageLine: "help [<command>|-advanced]",
    ShortDesc: "prints help about a command",
    LongDesc:  "" /* 129 byte string literal not displayed */,
    CommandRun: func() CommandRun {
        ret := &helpRun{}
        ret.Flags.BoolVar(&ret.advanced, "advanced", false, "show advanced commands")
        return ret

CmdHelp defines the help command. It should be included in your application's Commands list.

It is not added automatically but it will be run automatically if added.

func KillStdLog Uses

func KillStdLog()

KillStdLog sets an output that will panic if used. This permits trapping any log.*() calls that would inhibit efficient use of t.Parallel().

func Run Uses

func Run(a Application, args []string) int

Run runs the application, scheduling the subcommand. This is the main entry point of the library.

func VoidStdLog Uses

func VoidStdLog()

VoidStdLog sets an output that will be ignored. This permits ignoring any log.*() calls that would inhibit efficient use of t.Parallel().

type Application Uses

type Application interface {
    // GetName returns the 'name' of the application.
    GetName() string

    // GetTitle returns a one-line title explaining the purpose of the tool.
    GetTitle() string

    // GetCommands returns the list of the subcommands that are supported.
    GetCommands() []*Command

    // GetOut is used for testing to allow parallel test case execution, should
    // be normally os.Stdout.
    GetOut() io.Writer

    // GetOut is used for testing to allow parallel test case execution, should
    // be normally os.Stderr.
    GetErr() io.Writer

    // GetEnvVars returns the map of EnvVarName -> EnvVarDefinition that this
    // Application responds to.
    GetEnvVars() map[string]EnvVarDefinition

Application describes an application with subcommand support.

type Command Uses

type Command struct {
    UsageLine  string
    ShortDesc  string
    LongDesc   string
    Advanced   bool
    CommandRun func() CommandRun
    // contains filtered or unexported fields

Command describes a subcommand. It has one generator to generate a command object which is executable. The purpose of this design is to enable safe parallel execution of test cases.

func FindCommand Uses

func FindCommand(a Application, name string) *Command

FindCommand finds a Command by name and returns it if found.

func FindNearestCommand Uses

func FindNearestCommand(a Application, name string) *Command

FindNearestCommand heuristically finds a Command the user wanted to type but failed to type correctly.

func Section Uses

func Section(name string) *Command

Section returns an un-runnable command that can act as a nice section heading for other commands.

func (*Command) Name Uses

func (c *Command) Name() string

Name returns the command's name: the first word in the usage line.

type CommandRun Uses

type CommandRun interface {
    // Run execute the actual command. When this function is called by
    // command_support.Run(), the flags have already been parsed.
    Run(a Application, args []string, env Env) int

    // GetFlags returns the flags for this specific command.
    GetFlags() *flag.FlagSet

CommandRun is an initialized object representing a subcommand that is ready to be executed.

type CommandRunBase Uses

type CommandRunBase struct {
    Flags flag.FlagSet

CommandRunBase implements GetFlags of CommandRun. It should be embedded in another struct that implements Run().

func (*CommandRunBase) GetFlags Uses

func (c *CommandRunBase) GetFlags() *flag.FlagSet

GetFlags implements CommandRun.

type DefaultApplication Uses

type DefaultApplication struct {
    Name     string
    Title    string
    Commands []*Command
    EnvVars  map[string]EnvVarDefinition

DefaultApplication implements all of Application interface's methods. An application should usually have a global instance of DefaultApplication and route main() to command_support.Run(app).

func (*DefaultApplication) GetCommands Uses

func (a *DefaultApplication) GetCommands() []*Command

GetCommands implements interface Application.

func (*DefaultApplication) GetEnvVars Uses

func (a *DefaultApplication) GetEnvVars() map[string]EnvVarDefinition

GetEnvVars implements interface Application.

func (*DefaultApplication) GetErr Uses

func (a *DefaultApplication) GetErr() io.Writer

GetErr implements interface Application.

func (*DefaultApplication) GetName Uses

func (a *DefaultApplication) GetName() string

GetName implements interface Application.

func (*DefaultApplication) GetOut Uses

func (a *DefaultApplication) GetOut() io.Writer

GetOut implements interface Application.

func (*DefaultApplication) GetTitle Uses

func (a *DefaultApplication) GetTitle() string

GetTitle implements interface Application.

type Env Uses

type Env map[string]EnvVar

Env is the mapping of resolved environment variables passed to CommandRun.Run.

type EnvVar Uses

type EnvVar struct {
    Value  string
    Exists bool

EnvVar will document the value and existance of a given environment variable, as defined by Application.GetEnvVars. Value will be the value from the environment, or the Default value if it didn't exist. Exists will be true iff the value was present in the environment.

type EnvVarDefinition Uses

type EnvVarDefinition struct {
    Advanced  bool
    ShortDesc string
    Default   string

EnvVarDefinition describes an environment variable that this application responds to.

type PanicWriter Uses

type PanicWriter struct {

PanicWriter is an io.Writer that will panic if used.

func (PanicWriter) Write Uses

func (p PanicWriter) Write(b []byte) (n int, err error)

Write implements io.Writer.


sample-complexsample - Sample app to demonstrate example usage of package subcommand.
sample-simplesample-simple - Sample app to demonstrate a very basic example usage of package subcommand.
subcommandstestIncludes tools to help with concurrent testing.

Package subcommands imports 10 packages (graph) and is imported by 57 packages. Updated 2018-12-26. Refresh now. Tools for package owners.