completion

package
v0.6.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: 18 Imported by: 0

Documentation

Overview

Package completion provides shell script generation adapters for CONGA command line tools.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DetectHomebrew

func DetectHomebrew() bool

DetectHomebrew reports whether the current binary was installed via Homebrew on macOS, detected by resolving the executable path and looking for a Homebrew layout. Returns false on all other platforms.

func EnableInstructions

func EnableInstructions(shell Shell, cmdName string, opts EnableOptions) string

EnableInstructions renders the full enable block for one shell: session and persistent commands, plus platform-specific notes, in prose with tab-indented commands to copy-paste.

func Generate

func Generate(shell Shell, opts DriverOptions) (string, error)

Generate renders the completion driver script for the specified shell and options. All shells render their registration snippet natively (docs/adr/003-native-completion-driver.md).

func InferBashNeedsUpgrade

func InferBashNeedsUpgrade(execPath string) (bool, bool)

InferBashNeedsUpgrade inspects the executable path of a detected bash shell to infer whether it predates the features the generated bash script requires (bash 4.4+). The bundled macOS bash lives at /bin/bash and is still 3.2.57; a Homebrew-installed bash is modern. known is false when the version cannot be determined from the path alone, so callers warn only on positive evidence.

func NowSection

func NowSection(current CurrentShell, cmdName string, useFlag bool, helpAvailable bool) string

NowSection renders the "enable for your current shell now" block: the session commands for the detected shell, an upgrade warning when applicable, and, when helpAvailable is true, a pointer to the per-shell help for persistence options. The useFlag parameter formats the output using either subcommand syntax or flag syntax. When the completion command's help flag is disabled, the pointer is omitted because the referenced invocation is a usage error.

func SessionCommands

func SessionCommands(shell Shell, cmdName string, useFlag bool) []string

SessionCommands returns the one-time commands that enable completions, formatted for either subcommand syntax or flag syntax.

func ShouldWarnBash

func ShouldWarnBash(current CurrentShell) bool

ShouldWarnBash reports whether the enable hints should call out an outdated bash. This only ever applies on macOS, where the bundled bash is 3.2.57.

func Snippet

func Snippet(opts DriverOptions, shellName string) (string, error)

Snippet renders the registration snippet for shellName ("" auto-detects the caller's shell). Only the protocol shells have registration snippets; any other identifier — including the export framing, which is a machine- readable entry-point target without a script — is rejected.

func SupportedShells

func SupportedShells() []string

SupportedShells returns the shells of the wire protocol (docs/adr/003-native-completion-driver.md). The export framing is an internal entry-point target and is not listed.

Types

type CurrentShell

type CurrentShell struct {
	Shell    Shell
	ExecPath string
}

CurrentShell reports the detected caller shell and the executable path used to identify it, so callers can tailor hints to the actual running shell (e.g. macOS's bundled bash versus a Homebrew bash).

func DetectCurrentShell

func DetectCurrentShell() (CurrentShell, bool)

DetectCurrentShell identifies the caller's shell by walking the parent process ancestry and matching executable names against the supported shells. It does not rely on $SHELL (which reflects the login shell, not the shell running the command) and honours no environment overrides.

type DriverOptions

type DriverOptions struct {
	CommandName string
	Aliases     []string
	// EnvPrefix is the application's normalized completion environment prefix
	// (for example TASK_), used by drivers whose generated script forwards
	// description and alias suppression to the binary.
	EnvPrefix string
}

DriverOptions configures template rendering parameters for shell script generation.

type EnableOptions

type EnableOptions struct {
	// Homebrew is true when the command was installed via Homebrew on macOS,
	// tailoring the zsh lazy-load target to Homebrew's zsh site-functions dir.
	Homebrew bool

	// BashNeedsUpgrade is true when the caller's shell is macOS's bundled bash
	// (3.2.57), which lacks the builtins the generated bash script requires.
	BashNeedsUpgrade bool

	// UseFlag is true when instructions should be formatted using the
	// --completion flag syntax rather than the completion subcommand.
	UseFlag bool
}

EnableOptions tailors the enable-instructions block to the caller's setup.

type EnvLookup

type EnvLookup = bash.EnvLookup

EnvLookup returns the value of an environment variable and whether it was set.

type Session

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

Session is one completion invocation's driver: Patch derives the shell's presentation inputs and Format consumes them, so concurrent completions never share state. Unknown identifiers — and the empty auto-detect form — render in the export framing.

func NewSession

func NewSession(targetShell string) *Session

NewSession returns the invocation-scoped driver for targetShell.

func NewSessionWithEnv

func NewSessionWithEnv(targetShell string, lookup EnvLookup, envPrefix string) *Session

NewSessionWithEnv returns the invocation-scoped driver for targetShell using lookup to resolve shell environment variables and envPrefix to name the application-prefixed description and alias sideband toggles.

func (*Session) Format

func (s *Session) Format(toComplete string, result predict.Result) string

Format renders a completion result in the framing of the session's shell. The protocol shells render natively; an unknown, removed, or empty identifier falls back to the export framing.

func (*Session) Patch

func (s *Session) Patch(args []string) ([]string, error)

Patch applies shell-specific completion argument patching: bash's redirect rejection and wordbreak trimming, and nushell's raw-span dequoting. Every other shell passes the arguments through unchanged.

type Shell

type Shell string

Shell represents a supported target shell environment for completion scripts.

const (
	// ShellBash represents the GNU Bash shell.
	ShellBash Shell = "bash"

	// ShellElvish represents the Elvish shell.
	ShellElvish Shell = "elvish"

	// ShellFish represents the Friendly Interactive Shell.
	ShellFish Shell = "fish"

	// ShellNushell represents the Nushell shell.
	ShellNushell Shell = "nushell"

	// ShellPowerShell represents Microsoft PowerShell (5.1 & Core 7+).
	ShellPowerShell Shell = "powershell"

	// ShellZsh represents the Z Shell.
	ShellZsh Shell = "zsh"
)

func ParseShell

func ParseShell(name string) (Shell, error)

ParseShell parses a shell name string into a validated Shell enum. Only the canonically supported shells are accepted; experimental and alias names are rejected. Matching is case-insensitive and trims surrounding whitespace.

type ShellInfo

type ShellInfo struct {
	Name        string
	Description string
}

ShellInfo pairs a supported shell identifier with a short human description.

func ShellDescriptions

func ShellDescriptions() []ShellInfo

ShellDescriptions returns the canonically supported shells with a short description for each, used by the completion predictor and help screens.

Directories

Path Synopsis
Package bash renders completion results in bash's line-oriented framing and generates the bash registration snippet for the wire protocol (docs/completion-wire-protocol.md).
Package bash renders completion results in bash's line-oriented framing and generates the bash registration snippet for the wire protocol (docs/completion-wire-protocol.md).
Package elvish renders completion results as a single-line JSON object for elvish's edit:complex-candidate consumption and generates the elvish registration snippet for the wire protocol (docs/completion-wire-protocol.md).
Package elvish renders completion results as a single-line JSON object for elvish's edit:complex-candidate consumption and generates the elvish registration snippet for the wire protocol (docs/completion-wire-protocol.md).
Package export renders completion results as single-line JSON: the machine-readable test surface and unknown-shell fallback framing of the wire protocol (docs/completion-wire-protocol.md).
Package export renders completion results as single-line JSON: the machine-readable test surface and unknown-shell fallback framing of the wire protocol (docs/completion-wire-protocol.md).
Package fish renders completion results in fish's native completion feed and generates the fish registration snippet for the wire protocol (docs/completion-wire-protocol.md).
Package fish renders completion results in fish's native completion feed and generates the fish registration snippet for the wire protocol (docs/completion-wire-protocol.md).
Package lex implements a clean-room lexer for bash COMP_LINE command lines (docs/completion-wire-protocol.md).
Package lex implements a clean-room lexer for bash COMP_LINE command lines (docs/completion-wire-protocol.md).
Package nushell renders completion results as a bare JSON array of records for nushell's external completer and generates the nushell registration snippet for the wire protocol (docs/completion-wire-protocol.md).
Package nushell renders completion results as a bare JSON array of records for nushell's external completer and generates the nushell registration snippet for the wire protocol (docs/completion-wire-protocol.md).
Package powershell renders completion results as the JSON payload consumed by the generated registration snippet and generates the Register-ArgumentCompleter snippets for the wire protocol (docs/completion-wire-protocol.md).
Package powershell renders completion results as the JSON payload consumed by the generated registration snippet and generates the Register-ArgumentCompleter snippets for the wire protocol (docs/completion-wire-protocol.md).
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.
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.
Package zsh renders completion results as the record stream consumed by the generated registration snippet and generates the #compdef registration snippets for the wire protocol (docs/completion-wire-protocol.md).
Package zsh renders completion results as the record stream consumed by the generated registration snippet and generates the #compdef registration snippets for the wire protocol (docs/completion-wire-protocol.md).

Jump to

Keyboard shortcuts

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