wire

package
v0.7.0 Latest Latest
Warning

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

Go to latest
Published: Nov 5, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package wire defines the shell-agnostic completion wire vocabulary shared by the native completion drivers: candidates, directives, per-shell quoting helpers, the RFC 8259 string escaper, and the CONGA_* sideband environment readers.

The types here are the fork-free contract between the completion engine (predict.Result) and the per-shell formatters (bash, zsh, fish, powershell, export). The framing each shell consumes is specified in docs/completion-wire-protocol.md.

Index

Constants

View Source
const (
	// EnvCompLine is the bash-native current command line.
	EnvCompLine = "COMP_LINE"
	// EnvCompPoint is the bash-native cursor offset (bytes) into EnvCompLine.
	EnvCompPoint = "COMP_POINT"
	// EnvCompType is the bash-native readline completion type.
	EnvCompType = "COMP_TYPE"
	// EnvCompWordbreaks is the bash-native word-break character set.
	EnvCompWordbreaks = "COMP_WORDBREAKS"

	// CompletionAliasesSuffix is appended to the application prefix to form the
	// alias-suppression variable name (TASK_COMPLETION_ALIASES for a task app).
	CompletionAliasesSuffix = "COMPLETION_ALIASES"
	// CompletionBareSpaceFlagsSuffix is appended to the application prefix to
	// form the bare-space flag-restoration variable name
	// (TASK_COMPLETION_BARE_SPACE_FLAGS for a task app).
	CompletionBareSpaceFlagsSuffix = "COMPLETION_BARE_SPACE_FLAGS"
	// CompletionDescriptionsSuffix is appended to the application prefix to form
	// the description-suppression variable name.
	CompletionDescriptionsSuffix = "COMPLETION_DESCRIPTIONS"

	// EnvColor forces color styling on ("1") or off ("0").
	EnvColor = "CONGA_COLOR"
	// EnvDescriptionLength limits the maximum description length in runes.
	EnvDescriptionLength = "CONGA_DESCRIPTION_LENGTH"
	// EnvMergeFlags merges the "shorthand flags" and "longhand flags" tags
	// into "flags" (zsh grouping).
	EnvMergeFlags = "CONGA_MERGE_FLAGS"
	// EnvShell forces the target shell, overriding detection.
	EnvShell = "CONGA_SHELL"
	// EnvTooltip enables tooltip-style description rendering (powershell).
	EnvTooltip = "CONGA_TOOLTIP"
	// EnvZshListSeparator overrides the separator zsh renders between a match
	// and its description (the user's list-separator style).
	EnvZshListSeparator = "CONGA_ZSH_LIST_SEPARATOR"
	// EnvZshStyleLimit caps the number of candidates inline-styled in zsh.
	EnvZshStyleLimit = "CONGA_ZSH_STYLE_LIMIT"

	// EnvCLIColor is the standard CLICOLOR variable; "0" disables color.
	EnvCLIColor = "CLICOLOR"
	// EnvNoColor is the standard NO_COLOR variable; presence disables color.
	EnvNoColor = "NO_COLOR"
)

Environment variable names of the shell completion protocol: the bash-native variables and the CONGA_* sideband, plus the standard color variables.

Variables

This section is empty.

Functions

func AliasesEnabled added in v0.3.0

func AliasesEnabled(prefix string) bool

AliasesEnabled reports whether alias candidates are shown: the application-prefixed variable (prefix + CompletionAliasesSuffix) parsed as a boolean. Unset or unparseable keeps the default (shown). An empty prefix has no application namespace to match, so it always keeps the default.

func AppendJSONString

func AppendJSONString(dst []byte, input string) []byte

AppendJSONString appends the RFC 8259 JSON string literal for input (including the surrounding quotes) to dst and returns the extended buffer.

It delegates to jsonwire.AppendString so the completion wire protocol and the version report share one escaper without importing encoding/json (ADR 005 dependency boundaries).

func BareSpaceFlagsEnabled added in v0.4.0

func BareSpaceFlagsEnabled(prefix string) bool

BareSpaceFlagsEnabled reports whether flag candidates are restored at a bare space: the application-prefixed variable (prefix + CompletionBareSpaceFlagsSuffix) parsed as a boolean. Unset or unparseable keeps the default (suppressed); an empty prefix has no application namespace to match, so it also keeps the default.

func ClampDescription

func ClampDescription(description string, maxLength int) string

ClampDescription truncates description to maxLength runes, appending "..." when text was dropped. The cut is hard (without ellipsis) when maxLength is 3 or fewer runes.

func ColorDisabled

func ColorDisabled() bool

ColorDisabled reports whether styled output is disabled: CONGA_COLOR is honored first ("0" disables, any other non-empty value forces color), then the NO_COLOR standard (present and non-empty disables), then CLICOLOR=0.

func DescriptionLength

func DescriptionLength() int

DescriptionLength returns the maximum description length in runes: CONGA_DESCRIPTION_LENGTH when set to a positive integer, 80 otherwise.

func DescriptionsEnabled added in v0.3.0

func DescriptionsEnabled(prefix string) bool

DescriptionsEnabled reports whether candidate descriptions are shown: the application-prefixed variable (prefix + CompletionDescriptionsSuffix) parsed as a boolean. Unset or unparseable keeps the default (shown). An empty prefix has no application namespace to match, so it always keeps the default.

func ExecTarget

func ExecTarget(name string) string

ExecTarget returns name when set, and otherwise resolves the base name of the running executable so generated snippets can reference the binary.

func FromResult

func FromResult(envPrefix string, result predict.Result) ([]Candidate, Directives)

FromResult translates an engine result into the wire vocabulary: candidates in engine order with the display defaulting to the value, and directives derived from the engine's directive bits. envPrefix is the application's normalized completion environment prefix (TASK_ for an app named task): alias candidates are dropped when the prefixed alias variable disables them, and descriptions are blanked when the prefixed description variable disables them, so every framing observes the same suppressed stream. The result's file-completion fallback list is engine-internal and is not carried onto the wire.

func MergeFlags

func MergeFlags() (bool, bool)

MergeFlags reports whether flag tag merging is requested (first return) and whether CONGA_MERGE_FLAGS was explicitly set to a parseable boolean (second return). Shells apply their own default when the variable is unset or unparseable.

func QuoteElvish

func QuoteElvish(s string) string

QuoteElvish quotes s for safe evaluation in elvish: single quotes preserve every character except the single quote itself, which is doubled.

func QuoteFish

func QuoteFish(s string) string

QuoteFish quotes s for safe evaluation in fish: single quotes preserve every character except backslashes and single quotes, which are escaped with a backslash.

func QuoteIfUnsafe

func QuoteIfUnsafe(s string, unsafe string, quote func(string) string) string

QuoteIfUnsafe quotes s through quote when s contains any rune in unsafe, and returns it unchanged otherwise. It is the shared quote-only-when-needed skeleton for shell bareword emission.

func QuotePOSIX

func QuotePOSIX(s string) string

QuotePOSIX quotes s for safe evaluation in POSIX-compatible shells (bash, zsh): the string is enclosed in single quotes, in which every character is literal, with embedded single quotes escaped.

func QuotePowerShell

func QuotePowerShell(s string) string

QuotePowerShell quotes s as a PowerShell single-quoted string literal, in which embedded single quotes are doubled.

func QuoteTargetPOSIX

func QuoteTargetPOSIX(target string) string

QuoteTargetPOSIX quotes target for use as a word in a POSIX shell script unless it consists only of characters that are literal in an unquoted word (alphanumerics and the common path/punctuation set "-_/.:,@"), where it is returned unchanged. Quoting is otherwise unconditional: POSIX single quotes make every character literal.

func ReplaceControlWithSpace

func ReplaceControlWithSpace(input, cutset string) string

ReplaceControlWithSpace replaces all occurrences of any character in cutset from input with an ASCII space. It returns input unchanged if input contains no cutset characters.

func SanitizeIdentifier

func SanitizeIdentifier(s string) string

SanitizeIdentifier maps a command name onto a conservative identifier for generated shell scripts (function, variable, and `let` names): alphanumeric and underscore runes are kept, everything else becomes an underscore, and an empty result falls back to a single underscore.

func Shell

func Shell() string

Shell returns the CONGA_SHELL override, which forces the target shell and takes precedence over detection.

func StripControl

func StripControl(input, cutset string) string

StripControl removes all occurrences of any character in cutset from input. It returns input unchanged if input contains no cutset characters.

func Tooltip

func Tooltip() bool

Tooltip reports whether tooltip-style description rendering is requested (powershell): CONGA_TOOLTIP set to a truthy value.

func ZshListSeparator added in v0.3.0

func ZshListSeparator() string

ZshListSeparator returns the separator to embed in zsh list-colors patterns: CONGA_ZSH_LIST_SEPARATOR when it is a usable literal, "--" otherwise. A value that is empty, longer than 32 bytes, or contains a colon or control character falls back to the default: a colon would corrupt the colon-joined specification and control characters would corrupt the pattern.

func ZshStyleLimit

func ZshStyleLimit() int

ZshStyleLimit returns the maximum number of candidates to inline-style in zsh: CONGA_ZSH_STYLE_LIMIT when parseable, 300 otherwise.

Types

type Candidate

type Candidate struct {
	// Value is the string inserted into the command line.
	Value string
	// Display is the menu label, resolved to Value when the engine leaves it empty.
	Display string
	// Description is the optional help text shown next to the candidate.
	Description string
	// Style is the optional style token string from the internal/style vocabulary.
	Style string
	// Tag is the optional grouping tag (e.g. "commands", "longhand flags").
	Tag string
	// Alias reports that the candidate is an alternative spelling of another
	// candidate (a subcommand/flag alias or a predictor-supplied domain alias).
	Alias bool
}

Candidate is a single completion candidate on the wire.

func (Candidate) TrimmedDescription

func (c Candidate) TrimmedDescription() string

TrimmedDescription returns the description clamped for shells with a single-line description channel: only the first line is kept (trimmed) and truncated to the configured maximum length with "..." appended. The cut is hard (without ellipsis) when the limit is 3 or fewer runes.

type Directives

type Directives struct {
	// NoSpace holds the runes after which no space is appended while the
	// nospace directive is active ("*" matches every value).
	NoSpace SuffixSet
	// NoPrefix holds the runes the shell must not re-insert from the current
	// word when candidates are complete word replacements ("*" matches every
	// value).
	NoPrefix PrefixSet
	// KeepOrder requests that the shell preserves the engine candidate order.
	KeepOrder bool
	// Messages are diagnostics for shells with a message channel (zsh).
	Messages []string
	// Usage is the raw usage string accompanying an error result.
	Usage string
	// SuppressDescriptions reports that the application-prefixed sideband
	// disabled candidate descriptions, so framings that style a description
	// column (zsh list-colors) can omit patterns that would never match. It is
	// framing metadata, not a wire token; the zero value keeps the default
	// (descriptions shown).
	SuppressDescriptions bool
}

Directives carries the shell-agnostic instructions accompanying a candidate stream.

func (Directives) NoSpaceFor

func (d Directives) NoSpaceFor(value string) bool

NoSpaceFor reports whether inserting value must suppress the trailing space: either the nospace directive is active, or the value ends with "=" or "/".

func (Directives) Tokens

func (d Directives) Tokens() []string

Tokens returns the directive vocabulary tokens in effect, in fixed order (keeporder, noprefix, nospace), for rendering into shell framing headers.

type PrefixSet

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

PrefixSet is a set of runes matched against the first rune of a word, with "*" as the match-any wildcard.

func (*PrefixSet) Add

func (s *PrefixSet) Add(runes ...rune)

Add inserts runes into the set, deduplicating and sorting them; adding "*" collapses the set to the wildcard.

func (*PrefixSet) IsEmpty

func (s *PrefixSet) IsEmpty() bool

IsEmpty reports whether the set holds no runes.

func (*PrefixSet) Matches

func (s *PrefixSet) Matches(value string) bool

Matches reports whether the first rune of value is in the set. The empty string never matches.

func (*PrefixSet) String

func (s *PrefixSet) String() string

String returns the set's runes as a sorted string ("*" for the wildcard).

type SuffixSet

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

SuffixSet is a set of runes matched against the last rune of a word, with "*" as the match-any wildcard.

func (*SuffixSet) Add

func (s *SuffixSet) Add(runes ...rune)

Add inserts runes into the set, deduplicating and sorting them; adding "*" collapses the set to the wildcard.

func (*SuffixSet) IsEmpty

func (s *SuffixSet) IsEmpty() bool

IsEmpty reports whether the set holds no runes.

func (*SuffixSet) Matches

func (s *SuffixSet) Matches(value string) bool

Matches reports whether the last rune of value is in the set. The empty string never matches.

func (*SuffixSet) String

func (s *SuffixSet) String() string

String returns the set's runes as a sorted string ("*" for the wildcard).

Jump to

Keyboard shortcuts

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