command

package
v0.23.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 30, 2026 License: MIT Imports: 21 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddGlobalFlags

func AddGlobalFlags(root *cobra.Command, p *i18n.Printer)

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

func ConfigValues() config.Values

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

func Duration(value string) (time.Duration, bool)

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

func FlagValues(flag *pflag.Flag) []string

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 FormKeys added in v0.18.0

func FormKeys(p *i18n.Printer) tui.Keys

FormKeys returns the help of a form's keys in the language of p.

func HelpFunc

func HelpFunc(p *i18n.Printer, noColor bool) func(*cobra.Command, []string)

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 HelpUsage added in v0.18.0

func HelpUsage(c *cobra.Command, message string) contract.Problem

HelpUsage reports USAGE_INVALID with the help of c as its hint.

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

func Quote(word string) string

Quote returns a word as a POSIX shell reads it back: as is when it needs no quotes, and between single quotes otherwise.

func Refused added in v0.23.3

func Refused(p *i18n.Printer, line Line) *contract.Problem

Refused returns USAGE_INVALID for the first value that Global flags or Configuration in contract.md refuses, or nil. It checks the NCLY_ variable of each switch that the line leaves to it, which must hold 1, 0, or nothing. NO_COLOR follows no-color.org instead. It then checks --lang or NCLY_LANG, whichever sets the language.

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

func Summarizer(p *i18n.Printer) func(contract.Code) contract.Problem

Summarizer returns the leading error of an outcome that no single failure explains, in the language of p, as Registry.Finish asks.

func UnknownCommand

func UnknownCommand(p *i18n.Printer, c *cobra.Command, word string) contract.Problem

UnknownCommand reports a word that names no command under c. When a command of c is close to the word, it suggests that command, whose help is the hint, as Usage in contract.md defines.

func Usage added in v0.18.0

func Usage(message, hint string) contract.Problem

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.

func WithForm added in v0.18.0

func WithForm(ctx context.Context, f *Form) context.Context

WithForm returns ctx with f, which each command that Build makes asks its missing values in. A nil f makes a missing value fail.

func WriteFailure

func WriteFailure(p *i18n.Printer) contract.Outcome

WriteFailure is the outcome of an answer that could not be written.

Types

type Failure

type Failure struct{ Outcome contract.Outcome }

Failure carries the outcome of a command that failed or that a signal stopped, as the error that the command returns.

func Fail

func Fail(problems ...contract.Problem) *Failure

Fail returns the failure of a command whose errors are problems.

func (*Failure) Error

func (f *Failure) Error() string

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

func NewForm(p *i18n.Printer, g Globals, stdin, stdout *os.File, stderr io.Writer) *Form

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

func (f *Form) PrintNext(code int) error

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.

func Resolve

func Resolve(line Line) Globals

Resolve applies the precedence of contract.md. It reads the config only when neither --lang nor NCLY_LANG sets the language.

func (Globals) Vars

func (g Globals) Vars() map[string]string

Vars returns the variables that carry the resolved global flags to a program, as Global flags in contract.md names them. An empty value means that the variable is unset.

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

func Scan(cmd *cobra.Command, args []string) Line

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) Help

func (line Line) Help() bool

Help reports whether the line asks for help.

func (Line) Switch added in v0.18.0

func (line Line) Switch(name string) (on, given bool)

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.

func (Line) Version

func (line Line) Version() bool

Version reports whether the line asks for the version.

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.

func NewOutput

func NewOutput(file *os.File) *Output

NewOutput wraps a file, such as stdout.

func (*Output) Err

func (o *Output) Err() error

Err returns the first write error, or nil.

func (*Output) Fd

func (o *Output) Fd() uintptr

func (*Output) File

func (o *Output) File() *os.File

File returns the file, for a program that the runner starts, which then sees a terminal when the file is one. The program reports its own failed writes through its exit code.

func (*Output) Write

func (o *Output) Write(b []byte) (int, error)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL