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 ConfigValues() config.Values
- func Duration(value string) (time.Duration, bool)
- func Finish(p *i18n.Printer, g Globals, codes contract.Registry, out *Output, err error, ...) int
- func FlagValues(flag *pflag.Flag) []string
- func FormKeys(p *i18n.Printer) tui.Keys
- func HelpFunc(p *i18n.Printer, noColor bool) func(*cobra.Command, []string)
- func HelpUsage(c *cobra.Command, message string) contract.Problem
- func ModuleVersion() string
- func Quote(word string) 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 Usage(message, hint string) contract.Problem
- func WithForm(ctx context.Context, f *Form) context.Context
- func WriteFailure(p *i18n.Printer) contract.Outcome
- type Failure
- type Form
- 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 extension root. 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 ConfigValues ¶ added in v0.18.0
ConfigValues reads the values of the config files. A load error gives none, so the help still works with the defaults.
func Duration ¶ added in v0.18.0
Duration reads the value of a --timeout under the common duration rules of Global flags in contract.md: a duration such as 30s, 5m, or 2h, or a number of seconds, above 0. It reports false for any other value.
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 FlagValues ¶ added in v0.18.0
FlagValues returns the values of a flag that the caller set: each value of a variadic flag in the caller's order, or the last value of any other.
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 Quote ¶ added in v0.18.0
Quote returns a word as a POSIX shell reads it back: as is when it needs no quotes, and between single quotes otherwise.
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.
func Usage ¶ added in v0.18.0
Usage reports USAGE_INVALID whose hint is a command that runs as is, so the same command is its next, as Output in contract.md asks.
Types ¶
type Failure ¶
Failure carries the outcome of a command that failed or that a signal stopped, as the error that the command returns.
type Form ¶ added in v0.18.0
type Form struct {
// contains filtered or unexported fields
}
Form is the form for missing values of Modes in contract.md: in interactive mode, it asks for the values that a call lacks before the command runs, then keeps the command that the call became, which PrintNext shows once the command has run. Core and every Go extension share it through Build.
func NewForm ¶ added in v0.18.0
NewForm returns the form of a command line that reads stdin and draws on stderr, or nil outside interactive mode, where a missing value fails.
func (*Form) PrintNext ¶ added in v0.18.0
PrintNext prints, after a run that the form completed, the line Next time: and the equivalent command, unless a signal stopped the run, which code tells. It returns the error of a write that fails, which fails the run, as Output in contract.md asks of lost output.
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.
func Scan ¶
Scan reads args with the flags of cmd and the same rules as the parser: a flag that takes a value takes the next argument even when it starts with "-". An unknown flag counts as a switch, and scanning goes on after it, so help and machine mode hold wherever the parser would stop.
func (Line) Switch ¶ added in v0.18.0
Switch returns the last valid value of a switch, by long name, and whether the line sets it at all. An invalid value, such as --json=bad, is the parser's to report, and never cancels an earlier one. The test kit reads the switches of each call of a scenario with it, so it sees what ncly sees.
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.