bash

package
v0.11.0 Latest Latest
Warning

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

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

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). The Session Patch pass re-lexes the bash-native COMP_LINE environment through internal/completion/lex to reject redirect targets, isolate the current pipeline segment, and expose the COMP_WORDBREAKS prefix that the session's Format pass strips from candidate values.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Snippet

func Snippet(name string, aliases []string, _ string) string

Snippet renders the bash registration script for the given command name and aliases (docs/completion-wire-protocol.md): one completer function per name that exports the bash-native completion environment, splits the cursor-truncated COMP_LINE with xargs (the appended-quote retry chain closes unclosed quotes mid-word and keeps the input non-empty so xargs always runs, preserving the trailing empty word), and feeds the resolved words — excluding the program name — to the binary's __complete entry point. The invocation target is "${cmd}", the first word of the truncated line — the command the user actually typed (local ./path, PATH lookup, alias, etc.) — so the callback always re-invokes the exact binary rather than a generation-time name. The D/M/C lines parse back into COMPREPLY without echoing anything: bash has no message widget, so M lines are dropped, and the function must produce zero terminal leakage. In successive-tab mode (COMP_TYPE=63) the payload carries display/value/description triplets, rendered as "display (description)" for readline's listing. The completer function name derives from the command name via wire.SanitizeIdentifier; registration lines keep the raw name, quoted via wire.QuoteTargetPOSIX.

Types

type EnvLookup

type EnvLookup func(key string) (string, bool)

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

type Session

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

Session carries one bash completion invocation's presentation state: the inputs Patch derives from the bash-native environment and Format consumes when framing candidates. A fresh Session per invocation keeps concurrent completions independent — this package holds no per-invocation mutable state.

func NewSession

func NewSession() *Session

NewSession returns an inactive session for one completion invocation: Format derives its inputs from toComplete and the environment until Patch runs.

func NewSessionWithEnv

func NewSessionWithEnv(lookup EnvLookup) *Session

NewSessionWithEnv returns an inactive session using lookup to resolve environment variables (falling back to os.LookupEnv when lookup is nil).

func (*Session) Format

func (s *Session) Format(toComplete string, directives wire.Directives, candidates []wire.Candidate) string

Format renders candidates in bash's line-oriented framing: a directive header line ("D"), optional message lines ("M", discarded by the snippet to keep the terminal clean), and one candidate line ("C") per candidate.

Normal mode carries the insertion value with the COMP_WORDBREAKS prefix (e.g. `--env=`) stripped and quoted for the word's state: backslash-escaped when unquoted, continued (and closed when complete) inside a quote the user opened; successive-tab mode (COMP_TYPE=63 with multiple candidates) carries tab-delimited display/value/description triplets that the snippet renders as "display (description)". Multiple candidates sharing a non-flag common value prefix collapse to that prefix with the nospace directive so the first tab inserts the shared stem.

func (*Session) Patch

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

Patch rewrites the completion arguments for the engine: with COMP_LINE and COMP_POINT present it re-lexes the cursor-truncated line, rejects redirect positions, isolates the current pipeline segment, drops redirect operators with their targets, and preserves the trailing empty word. Without the bash-native environment (direct API invocations) the arguments pass through unchanged. Patch only reads the environment; it never mutates process state.

Jump to

Keyboard shortcuts

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