Documentation
¶
Overview ¶
Package command turns command declarations into a command line: the commands and their flags, the global flags, help pages, and printed answers. Core and every Go extension build their command line with it, so every command parses, helps, and fails alike.
Index ¶
- func AddGlobalFlags(root *cobra.Command, p *i18n.Printer)
- func AddManifest(root *cobra.Command, p, text *i18n.Printer, m contract.Manifest, ...) *cobra.Command
- func Build(p, text *i18n.Printer, d contract.Command, ...) *cobra.Command
- func Finish(p *i18n.Printer, g Globals, codes contract.Registry, out *Output, err error, ...) int
- func HelpFunc(p *i18n.Printer, noColor bool) func(*cobra.Command, []string)
- func ModuleVersion() string
- func Report(p *i18n.Printer, g Globals, codes contract.Registry, o contract.Outcome, ...) int
- func Summarizer(p *i18n.Printer) func(contract.Code) contract.Problem
- func UnknownCommand(p *i18n.Printer, c *cobra.Command, word string) contract.Problem
- func WriteFailure(p *i18n.Printer) contract.Outcome
- type Failure
- type Globals
- type Line
- type Output
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddGlobalFlags ¶
AddGlobalFlags gives a root command the global flags of the contract, and turns every parser error into USAGE_INVALID.
func AddManifest ¶
func AddManifest(root *cobra.Command, p, text *i18n.Printer, m contract.Manifest, run func(contract.Command) func(*cobra.Command, []string) error) *cobra.Command
AddManifest adds the commands that a manifest declares under root, each parent before its children, and returns the command of its domain. text renders the manifest's catalog IDs. run returns what each command that runs does with its call, and a command for which it returns nil prints its help.
func Build ¶
func Build(p, text *i18n.Printer, d contract.Command, run func(*cobra.Command, []string) error) *cobra.Command
Build makes the command that a declaration describes. text renders the catalog IDs of the declaration, from the catalogs of its owner, and p renders the SDK's own text, such as usage errors. A nil run makes a command that groups others: alone it prints its help, and an unknown word after it is a usage error.
func Finish ¶
func Finish(p *i18n.Printer, g Globals, codes contract.Registry, out *Output, err error, hint string, stdout, stderr io.Writer) int
Finish returns the exit code of a command line whose run ended with err, after printing its failure: RUNTIME when out lost a write, the failure that err carries, or USAGE_INVALID with hint for any other error of the parser.
func HelpFunc ¶
HelpFunc prints the help page of a command from its declaration, in the active language. The commands of a group, such as the extensions under core's root, get a section of their own, titled by the group.
func ModuleVersion ¶
func ModuleVersion() string
ModuleVersion returns the version that Go stamped from the module or the VCS of the build, or a development marker.
func Report ¶
func Report(p *i18n.Printer, g Globals, codes contract.Registry, o contract.Outcome, stdout, stderr io.Writer) int
Report prints an outcome and returns its exit code. An answer that cannot be written is a runtime failure, whatever the verdict: when stderr itself refuses it, the exit code is all that remains to tell.
func Summarizer ¶
Summarizer returns the leading error of an outcome that no single failure explains, in the language of p, as Registry.Finish asks.
func UnknownCommand ¶
UnknownCommand reports a word that names no command under c.
Types ¶
type Failure ¶
Failure carries the outcome of a command that failed, as the error that the command returns.
type Globals ¶
type Globals struct {
JSON bool
NoInput bool
NoColor bool
Verbose bool
// Lang is the language setting before matching, such as fr_CA.UTF-8.
Lang string
}
Globals holds the resolved global flags. A flag wins over its variable.
type Line ¶
type Line struct {
// Words holds the positional words before "--", in order.
Words []string
// Operands holds the words after "--", which are never flags or commands.
Operands []string
// contains filtered or unexported fields
}
Line is what the parser will find in the arguments of one command.
type Output ¶
type Output struct {
// contains filtered or unexported fields
}
Output records the first failed write to a file, so lost output never reports success. Beyond Write, it keeps Fd, for terminal detection, and File, for a program that writes to the file itself. Write and Err are safe for concurrent use, because a handler that outlives its time may still write while the extension answers.