command

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Oct 14, 2026 License: MIT Imports: 16 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 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

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

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.

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