miller/docs/src/shell-completion.md

Quick links:   Flags   Verbs   Functions   Glossary   Release docs

# Shell completion

Miller can generate tab-completion scripts for bash and zsh. Once installed, pressing TAB completes Miller's main flags, verb names, subcommands like help and version, each verb's own flags, the then keyword, and filenames -- and it does so in a way that understands Miller's then-chains.

Why this is more than the usual flag completion

Most command-line tools have a single set of flags: prog --flag1 --flag2 file.

Miller's command line, by contrast, is instead a sequence of contexts:

mlr {main flags} verb1 {verb1 flags} then verb2 {verb2 flags} {filenames}

So the same word can mean different things depending on where it sits. Miller's completion walks the command line left-to-right and offers candidates appropriate to the cursor's position:

• Before the first verb: main flags (e.g. --icsv), verb names (e.g. cat), and subcommands (e.g. help, version, repl).
• Inside a verb: that verb's own flags, plus then and filenames.
• Right after then: verb names.
• As the argument to a flag that takes one (e.g. mlr --ifs): the flag's values where these are a known set, otherwise filenames.

Installing for bash

Add this to your ~/.bashrc:

eval "$(mlr completion bash)"

Or install it system-wide (loaded by the bash-completion package):

mlr completion bash > /etc/bash_completion.d/mlr

Prefer eval "$(mlr completion bash)" over source <(mlr completion bash). The latter silently does nothing on the bash 3.2 that ships with macOS, where sourcing from a process-substitution file descriptor can read no data.

Installing for zsh

Add this to your ~/.zshrc:

eval "$(mlr completion zsh)"

Or place the script on your $fpath so zsh autoloads it:

mlr completion zsh > "${fpath[1]}/_mlr"

The generated script initializes zsh's completion system (compinit) if your startup files have not already done so, so it works even with a minimal ~/.zshrc.

What completion looks like

Before the first verb, TAB offers verb names along with subcommands like help and version:

mlr TAB
altkv      cat        completion     count      ...      help      version

The top-level help and version flags are offered too:

mlr --vTAB
--value-color   --version   --vflatsep

The help subcommand completes its topics, and topics that take a name argument complete that too:

mlr help TAB
flags   list-verbs   verb   function   keyword   ...

mlr help verb TAB
altkv   bar   cat   count   cut   ...

mlr help function strlTAB
strlen

A leading dash offers main flags, including the format-conversion keystroke-savers (--c2j, --x2y, and so on):

mlr --cTAB
--c2b   --c2c   --c2d   --c2j   --c2p   ...   --csv   --csvlite

Inside a verb, TAB offers that verb's flags:

mlr cat -TAB
-n   -N   -g   --filename   --filenum

After then, TAB offers verb names again:

mlr --icsv cat -n then head -n 10 then TAB
altkv      cat        count          cut        ...

For flags whose argument is a known set of values, TAB offers those values. Format flags (-i, -o, --io) offer file-format names:

mlr -i TAB
csv   csvlite   dcf   dkvp   dkvpx   gen   json   markdown   nidx   pprint   tsv   xtab   yaml

and separator flags (--ifs, --ofs, --ips, and so on) offer the named separator aliases:

mlr --ifs TAB
comma   pipe   semicolon   space   tab   ...

Generating the scripts

The mlr completion command prints the scripts, and mlr completion --help describes the options:

mlr completion --help

Usage: mlr completion {bash|zsh}
Generates a shell tab-completion script for Miller.

Bash:
  Add to your ~/.bashrc:
    eval "$(mlr completion bash)"
  Or install system-wide:
    mlr completion bash > /etc/bash_completion.d/mlr
  Note: prefer 'eval' over 'source <(mlr completion bash)'. The latter
  silently fails on the bash 3.2 that ships with macOS, where sourcing from a
  process-substitution FIFO can read nothing.

Zsh:
  Add to your ~/.zshrc:
    eval "$(mlr completion zsh)"
  Or place the output on your $fpath, e.g.:
    mlr completion zsh > "${fpath[1]}/_mlr"
  The script initializes zsh's completion system (compinit) if your startup
  files have not done so already.

Completion is context-aware across Miller's then-chains: it offers main flags
and verb names before the first verb, the current verb's flags inside a verb,
verb names after 'then', and filenames where appropriate.

Notes

• Completion candidates are produced by Miller itself: the shell scripts simply forward the current command-line words to mlr and render what it returns. This means completion stays in sync with Miller's flags and verbs automatically -- there is no separate list to maintain.

• Value completion is offered for flags with a known set of values (file formats for -i/-o/--io, separator aliases for --ifs and friends). Other arg-taking flags fall back to filename completion; per-verb argument values (such as field names) are not yet completed.

• The mlr completion complete ... subcommand is an internal interface used by the generated scripts; it is not intended to be run directly.