subcommands: github.com/google/subcommands Index | Files

package subcommands

import "github.com/google/subcommands"

Package subcommands implements a simple way for a single command to have many subcommands, each of which takes arguments and so forth.

Index

Package Files

subcommands.go

func ImportantFlag Uses

func ImportantFlag(name string)

ImportantFlag marks a top-level flag as important, which means it will be printed out as part of the output of an ordinary "help" subcommand. (All flags, important or not, are printed by the "flags" subcommand.) It is a wrapper around DefaultCommander.ImportantFlag.

func Register Uses

func Register(cmd Command, group string)

Register adds a subcommand to the supported subcommands in the specified group. (Help output is sorted and arranged by group name.) The empty string is an acceptable group name; such subcommands are explained first before named groups. It is a wrapper around DefaultCommander.Register.

type Command Uses

type Command interface {
    // Name returns the name of the command.
    Name() string

    // Synopsis returns a short string (less than one line) describing the command.
    Synopsis() string

    // Usage returns a long string explaining the command and giving usage
    // information.
    Usage() string

    // SetFlags adds the flags for this command to the specified set.
    SetFlags(*flag.FlagSet)

    // Execute executes the command and returns an ExitStatus.
    Execute(ctx context.Context, f *flag.FlagSet, args ...interface{}) ExitStatus
}

A Command represents a single command.

func Alias Uses

func Alias(alias string, cmd Command) Command

Alias returns a Command alias which implements a "commands" subcommand.

func CommandsCommand Uses

func CommandsCommand() Command

CommandsCommand returns Command which implements a "commands" subcommand.

func FlagsCommand Uses

func FlagsCommand() Command

FlagsCommand returns a Command which implements "flags" for the DefaultCommander. Use Register(FlagsCommand(), <group>) for it to be recognized.

func HelpCommand Uses

func HelpCommand() Command

HelpCommand returns a Command which implements "help" for the DefaultCommander. Use Register(HelpCommand(), <group>) for it to be recognized.

type CommandGroup Uses

type CommandGroup struct {
    // contains filtered or unexported fields
}

A CommandGroup represents a set of commands about a common topic.

func (CommandGroup) Len Uses

func (g CommandGroup) Len() int

Sorting of the commands within a group.

func (CommandGroup) Less Uses

func (g CommandGroup) Less(i, j int) bool

func (*CommandGroup) Name Uses

func (g *CommandGroup) Name() string

Name returns the group name

func (CommandGroup) Swap Uses

func (g CommandGroup) Swap(i, j int)

type Commander Uses

type Commander struct {
    Explain        func(io.Writer)                // A function to print a top level usage explanation. Can be overridden.
    ExplainGroup   func(io.Writer, *CommandGroup) // A function to print a command group's usage explanation. Can be overridden.
    ExplainCommand func(io.Writer, Command)       // A function to print a command usage explanation. Can be overridden.

    Output io.Writer // Output specifies where the commander should write its output (default: os.Stdout).
    Error  io.Writer // Error specifies where the commander should write its error (default: os.Stderr).
    // contains filtered or unexported fields
}

A Commander represents a set of commands.

var DefaultCommander *Commander

DefaultCommander is the default commander using flag.CommandLine for flags and os.Args[0] for the command name.

func NewCommander Uses

func NewCommander(topLevelFlags *flag.FlagSet, name string) *Commander

NewCommander returns a new commander with the specified top-level flags and command name. The Usage function for the topLevelFlags will be set as well.

func (*Commander) CommandsCommand Uses

func (cdr *Commander) CommandsCommand() Command

CommandsCommand returns Command which implements a "commands" subcommand.

func (*Commander) Execute Uses

func (cdr *Commander) Execute(ctx context.Context, args ...interface{}) ExitStatus

Execute should be called once the top-level-flags on a Commander have been initialized. It finds the correct subcommand and executes it, and returns an ExitStatus with the result. On a usage error, an appropriate message is printed to os.Stderr, and ExitUsageError is returned. The additional args are provided as-is to the Execute method of the selected Command.

func (*Commander) FlagsCommand Uses

func (cdr *Commander) FlagsCommand() Command

FlagsCommand returns a Command which implements a "flags" subcommand.

func (*Commander) HelpCommand Uses

func (cdr *Commander) HelpCommand() Command

HelpCommand returns a Command which implements a "help" subcommand.

func (*Commander) ImportantFlag Uses

func (cdr *Commander) ImportantFlag(name string)

ImportantFlag marks a top-level flag as important, which means it will be printed out as part of the output of an ordinary "help" subcommand. (All flags, important or not, are printed by the "flags" subcommand.)

func (*Commander) Name Uses

func (cdr *Commander) Name() string

Name returns the commander's name

func (*Commander) Register Uses

func (cdr *Commander) Register(cmd Command, group string)

Register adds a subcommand to the supported subcommands in the specified group. (Help output is sorted and arranged by group name.) The empty string is an acceptable group name; such subcommands are explained first before named groups.

func (*Commander) VisitAll Uses

func (cdr *Commander) VisitAll(fn func(*flag.Flag))

VisitAll visits the top level flags in lexicographical order, calling fn for each. It visits all flags, even those not set.

func (*Commander) VisitAllImportant Uses

func (cdr *Commander) VisitAllImportant(fn func(*flag.Flag))

VisitAllImportant visits the important top level flags in lexicographical order, calling fn for each. It visits all flags, even those not set.

func (*Commander) VisitCommands Uses

func (cdr *Commander) VisitCommands(fn func(*CommandGroup, Command))

VisitCommands visits each command in registered order grouped by command group in lexicographical order, calling fn for each.

func (*Commander) VisitGroups Uses

func (cdr *Commander) VisitGroups(fn func(*CommandGroup))

VisitGroups visits each command group in lexicographical order, calling fn for each.

type ExitStatus Uses

type ExitStatus int

An ExitStatus represents a Posix exit status that a subcommand expects to be returned to the shell.

const (
    ExitSuccess ExitStatus = iota
    ExitFailure
    ExitUsageError
)

func Execute Uses

func Execute(ctx context.Context, args ...interface{}) ExitStatus

Execute should be called once the default flags have been initialized by flag.Parse. It finds the correct subcommand and executes it, and returns an ExitStatus with the result. On a usage error, an appropriate message is printed to os.Stderr, and ExitUsageError is returned. The additional args are provided as-is to the Execute method of the selected Command. It is a wrapper around DefaultCommander.Execute.

Package subcommands imports 8 packages (graph) and is imported by 176 packages. Updated 2019-11-04. Refresh now. Tools for package owners.