miller/pkg/terminals/completion/scripts.go
John Kerl 299636038c
Shell tab-completion for bash and zsh (#2096)
* initial attempt

* fix bash

* fix zsh

* Add shell-completion docs page

Documents the new 'mlr completion {bash,zsh}' feature: the then-chain
context model, install instructions for bash and zsh (including the macOS
bash-3.2 'eval' caveat and zsh compinit self-init), and examples of
context-aware completion. Added to the nav under "Miller in more detail".

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Add enum value completion for format and separator flags

Completes the argument value for arg-taking main flags whose values are a
known set: file-format names for -i/-o/--io, separator aliases for
--ifs/--ofs/--ips/etc., and regex-separator aliases for --ifs-regex/--ips-regex.
Other arg-taking flags continue to fall back to filename completion.

Candidate sets come from new cli getters (GetFileFormatNames,
GetSeparatorAliasNames, GetSeparatorRegexAliasNames) that read the same maps
Miller uses at runtime, so there is no separate list to keep in sync. The
command-line walk now records which flag a value position belongs to.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Include format-conversion keystroke-savers in bare-dash completion

Reverts the suppression of --c2j/--x2y-style flags from 'mlr -<TAB>'. The full
set of main flags (297) is now offered, matching what is valid on the command
line. GetFlagNames no longer takes an includeSuppressed argument.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Complete terminal subcommands and top-level help/version flags

'mlr <TAB>' now offers subcommand names (help, version, repl, regtest, script,
completion, terminal-list) alongside verb names, and 'mlr -<TAB>' offers the
top-level terminal flags (-h, --help, --version, --bare-version, and the help
shorthands -g/-l/-L/-f/-F/-k/-K). Subcommand names are offered only as the
first non-flag token, where they are valid.

To let the completion engine know these names without an import cycle
(pkg/terminals imports pkg/terminals/completion), the canonical terminal names
and version-flag spellings are factored into a new leaf package
pkg/terminals/registry, imported by pkg/terminals, pkg/climain, and completion.
The help-flag spellings come from a new help.GetTerminalFlagNames derived from
the existing shorthand table, so nothing drifts.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Complete 'mlr help' topics and topic arguments

'mlr help <TAB>' now completes help topics (flags, verb, function, keyword,
list-verbs, ...), and topics that take a name argument complete it too:
'mlr help verb <TAB>' -> verb names, 'mlr help function <TAB>' -> function
names, 'mlr help keyword <TAB>' -> keyword names, 'mlr help flag <TAB>' ->
flag names. 'mlr completion <TAB>' completes bash/zsh.

A terminal subcommand consumes the rest of the command line, so the walk now
returns a ctxTerminalArgs context carrying the terminal name and the words
typed after it. New getters supply the candidate names without drift:
help.GetTopicNames, help.GetFunctionNames/GetKeywordNames (wrapping new
cst.BuiltinFunctionManager.GetBuiltinFunctionNames and cst.GetKeywordNames).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs-neaten

* Move flag-value-candidate logic into pkg/cli; fix verb-flag collision

The mapping of which flags take a format/separator/regex-separator argument is
flag metadata, so it now lives with the flags in pkg/cli as
cli.FlagValueCandidates, alongside the existing GetFileFormatNames /
GetSeparatorAliasNames getters, replacing the maps that were in
pkg/terminals/completion/value_completion.go (now removed).

This also fixes a bug: value completion now applies only to main flags, not to
identically-spelled verb flags. Previously 'mlr uniq -o <TAB>' offered file
formats because uniq's -o (an output field name) collided with the main -o
format flag; it now correctly falls back to filename completion.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-21 12:47:54 -04:00

77 lines
2.4 KiB
Go

package completion
// bashScript is the bash completion shim emitted by `mlr completion bash`. It
// holds no knowledge of Miller's grammar: it forwards the current words to
// `mlr completion complete`, which returns a one-line directive followed by
// candidate words.
const bashScript = `# bash completion for mlr -- generated by 'mlr completion bash'
_mlr_complete() {
local cur response directive rest
cur="${COMP_WORDS[COMP_CWORD]}"
response=$("${COMP_WORDS[0]}" completion complete "$COMP_CWORD" "${COMP_WORDS[@]}" 2>/dev/null)
# The first line is a directive; the remaining lines are candidate words.
# We split with parameter expansion rather than array slicing
# (${arr[@]:1}), which is broken in the bash 3.2 that ships with macOS.
directive=${response%%$'\n'*}
if [[ "$response" == *$'\n'* ]]; then
rest=${response#*$'\n'}
else
rest=""
fi
# compgen -f rather than 'compopt -o default' for file completion, since
# compopt does not exist in bash 3.2.
local IFS=$'\n'
COMPREPLY=()
case "$directive" in
files)
COMPREPLY=( $(compgen -f -- "$cur") )
compopt -o filenames 2>/dev/null
;;
default)
COMPREPLY=( $rest $(compgen -f -- "$cur") )
compopt -o filenames 2>/dev/null
;;
*)
COMPREPLY=( $rest )
;;
esac
}
complete -F _mlr_complete mlr
`
// zshScript is the zsh completion shim emitted by `mlr completion zsh`.
const zshScript = `#compdef mlr
# zsh completion for mlr -- generated by 'mlr completion zsh'
# Initialize the completion system if it has not been already; this provides
# 'compdef' and makes 'source <(mlr completion zsh)' work even when the user's
# zsh startup files do not run compinit themselves.
if ! (( $+functions[compdef] )); then
autoload -Uz compinit && compinit
fi
_mlr() {
local -a response candidates
local directive
response=("${(@f)$(${words[1]} completion complete $((CURRENT-1)) "${words[@]}" 2>/dev/null)}")
directive=${response[1]}
candidates=(${response[2,-1]})
case $directive in
files)
_files
;;
default)
(( ${#candidates} )) && compadd -- ${candidates}
_files
;;
*)
compadd -- ${candidates}
;;
esac
}
compdef _mlr mlr
`