Shell completion - Miller

<div> Quick links:   <a class="quicklink" href="../reference-main-flag-list/index.html">Flags</a>   <a class="quicklink" href="../reference-verbs/index.html">Verbs</a>   <a class="quicklink" href="../reference-dsl-builtin-functions/index.html">Functions</a>   <a class="quicklink" href="../glossary/index.html">Glossary</a>   <a class="quicklink" href="../release-docs/index.html">Release docs</a> </div> # 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:

<pre class="pre-non-highlight-non-pair"> mlr {main flags} verb1 {verb1 flags} then verb2 {verb2 flags} {filenames} </pre>

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:

<pre class="pre-non-highlight-non-pair"> eval "$(mlr completion bash)" </pre>

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

<pre class="pre-non-highlight-non-pair"> mlr completion bash > /etc/bash_completion.d/mlr </pre>

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:

<pre class="pre-non-highlight-non-pair"> eval "$(mlr completion zsh)" </pre>

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

<pre class="pre-non-highlight-non-pair"> mlr completion zsh > "${fpath[1]}/_mlr" </pre>

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:

<pre class="pre-non-highlight-non-pair"> mlr TAB altkv cat completion count ... help version </pre>

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

<pre class="pre-non-highlight-non-pair"> mlr --vTAB --value-color --version --vflatsep </pre>

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

<pre class="pre-non-highlight-non-pair"> mlr help TAB flags list-verbs verb function keyword ... mlr help verb TAB altkv bar cat count cut ... mlr help function strlTAB strlen </pre>

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

<pre class="pre-non-highlight-non-pair"> mlr --cTAB --c2b --c2c --c2d --c2j --c2p ... --csv --csvlite </pre>

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

<pre class="pre-non-highlight-non-pair"> mlr cat -TAB -n -N -g --filename --filenum </pre>

After then, TAB offers verb names again:

<pre class="pre-non-highlight-non-pair"> mlr --icsv cat -n then head -n 10 then TAB altkv cat count cut ... </pre>

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

<pre class="pre-non-highlight-non-pair"> mlr -i TAB csv csvlite dcf dkvp dkvpx gen json markdown nidx pprint tsv xtab yaml </pre>

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

<pre class="pre-non-highlight-non-pair"> mlr --ifs TAB comma pipe semicolon space tab ... </pre>

Generating the scripts

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

<pre class="pre-highlight-in-pair"> mlr completion --help </pre> <pre class="pre-non-highlight-in-pair"> 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. </pre>

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.