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, helpAvailable 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, 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 ¶
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). |