Documentation
¶
Overview ¶
Package complete provides imperative and composable shell completion.
Completing a command line consists of returning a set of propositions to shell by writing in stdout one proposition per line. The target features of this package includes:
- Composable and imperative API.
- Inline documentation of propositions.
- Hide proposition by prefix until user type prefix. e.g hidden filename.
- Non intrusive configuration, easy for packaging.
- Propose --opt=false booleans.
- Exclude --help if other flag are set. Exclude flags when --help is set.
Shells processes propositions differently:
- Bash accepts proposition as full command line completion.
- Zsh and fish accept proposition as single argument completion.
- Fish accept a description after a tab.
Also, shells have different handling of multiple propositions:
- Bash simply list, user needs to type a letter to further complete.
- Zsh and fish allow to loop propositions.
POSIX flags accepts setting a value to a flag either with an equal sign or space. Shells behave differently on this matter.
- Bash treat value after equal sign as a single command line argument.
- Zsh and Fish wants completion of value to include the flag.
i.e. to complete --section=, Zsh and fish expect proposition `--section=data` while bash expects `data`.
The limitations of this package:
- no completion for short options.
- no quoting/escaping of path.
- ignores command line after point.
- ignores COMP_TYPE.
Index ¶
- Variables
- func Any(v ...proposer) []string
- func Complete(c Completer, shell Formatter)
- func DirOnly() pathoption
- func Enum(flag string, propositions ...string) enum
- func PFlagValue(pflags *pflag.FlagSet, args []string, valuers ...Valuer) ([]string, bool)
- func PFlags(pflags *pflag.FlagSet) ([]string, bool)
- func ParsePFlags(f *pflag.FlagSet, args []string)
- func Path(flag string, options ...pathoption) path
- func Proposition(arg string, full bool, help string) string
- func Trace(msg string, args ...any)
- func WithRoot(r string) pathoption
- func WithStdIO() pathoption
- type Completer
- type Formatter
- type PropositionsFunc
- type Valuer
Constants ¶
This section is empty.
Variables ¶
var Hidden string = "._-"
Hidden lists first chars of hidden propositions.
- . for dot files.
- _ for hidden commands.
- - for flags.
If [proposer] produces only hidden propositions, complete shows them, even if user didn't type first character. This is the only cas where both propositions starting with ., _ or - are presented to user.
Functions ¶
func Any ¶
func Any(v ...proposer) []string
Any tries several proposers until one returns completions
func Complete ¶
Complete sends command line argument propositions to shell.
Reads command line and point from COMP_ env vars. Parses line and ask completer to produce propositions. Filters propositions to match last argument prefix. Format proposition help.
Exits process.
func PFlagValue ¶
PFlagValue proposes value for current flag.
Accepts a set of proposer for some flags in flagset. Check args to determine which flag is being completed. Returns corresponding values.
See Enum and [Dir] to define values for a flag.
func PFlags ¶
PFlags generates completion from sp13/pflag flagset
Flagset should have command line arguments parsed. Proposes only unset flags.
func ParsePFlags ¶
ParsePFlags parses completion args
Ensures current placeholder is not parsed. Accepts errors and unknown flags (e.g. partial flags).
func Path ¶
func Path(flag string, options ...pathoption) path
Path complete file-system path
Use WithRoot, DirOnly, [FileOnly] and WithStdIO to configure the propositions.
Ignores hidden dirs unless user types dot.
func Proposition ¶
Proposition formats an argument for completion
func Trace ¶
Trace logs if PGM_TRACE is defined
Unlike internal/logging, levelTrace is unusable when completing since slog is not configured.
Types ¶
type Completer ¶
type Completer interface {
// Complete returns the list of command line continuation
//
// args is the list of command line token **so far**.
// arguments after cursor are not accessible.
// If user begins a new argument,
// an empty string terminates args list.
//
// Returns a list of propositions as strings.
//
// A proposition is a string with specific trails:
//
// - a space to acknowledge a full proposition.
// - a tab and a help text.
//
// e.g.: "--section=" without space to let user set value right after equal.
// e.g.: "--verbose " with space to move on next flag.
// e.g.: "convert \tsub-command help" tab and help message.
//
// Use [Proposition] to format a proposition.
// Use [Formatter] to present proposition.
Complete(args []string) []string
}
Completer defines an object producing propositions from arguments.
type Formatter ¶
type Formatter interface {
// Generates configuration for the shell to interpret proposition.
Configuration(command, completer string) string
// Format a proposition for specific shell.
Format(flag, proposition string, unique bool) string
}
Formatter render proposition for a specific shell
The formatting of proposition is tightly coupled with configuration. For example, zsh configuration is a shell function processing propositions as formatted by go completer.
type PropositionsFunc ¶
PropositionsFunc implements [proposer] with a func.
func (PropositionsFunc) Propose ¶
func (f PropositionsFunc) Propose() ([]string, bool)
func (PropositionsFunc) String ¶
func (f PropositionsFunc) String() string
type Valuer ¶
type Valuer interface {
// Name of the flag for which values are produced.
String() string
// Propose values for command line argument.
//
// Each values is a regular [Proposition].
Propose(current string) []string
}
Valuer generates propositions for a flag.
func PFlagBools ¶
PFlagBools generates proposers for boolean flags
Source Files