Documentation
¶
Overview ¶
Package completion provides shell script generation adapters for CONGA command line tools.
Index ¶
- func DetectHomebrew() bool
- func EnableInstructions(shell Shell, cmdName string, opts EnableOptions) string
- func Generate(shell Shell, opts DriverOptions) (string, error)
- func InferBashNeedsUpgrade(execPath string) (bool, bool)
- func NowSection(current CurrentShell, cmdName string, useFlag bool) string
- func SessionCommands(shell Shell, cmdName string, useFlag bool) []string
- func ShouldWarnBash(current CurrentShell) bool
- func Snippet(opts DriverOptions, shellName string) (string, error)
- func SupportedShells() []string
- type CurrentShell
- type DriverOptions
- type EnableOptions
- type EnvLookup
- type Session
- type Shell
- type ShellInfo
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 ¶
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) string
NowSection renders the "enable for your current shell now" block: the session commands for the detected shell, an upgrade warning when applicable, and a pointer to the per-shell help for persistence options. The useFlag parameter formats the output using either subcommand syntax or flag syntax.
func SessionCommands ¶
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 ¶
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 ¶
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 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 ¶
NewSession returns the invocation-scoped driver for targetShell.
func NewSessionWithEnv ¶
NewSessionWithEnv returns the invocation-scoped driver for targetShell using lookup to resolve environment variables.
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 ¶
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 ¶
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). |