How Bash completion works, Hacker News

Published October 6, 2019 byChris Patuzzo

This is the first of two parts on Bash completion. Part two ishere.

Over the years I ‘ve developed a command-line tool I use for routine tasks such as provisioning my machine, generating project templates and managing secrets. The tool is written in Ruby and I invoke it with theZZcommand.

Most ofwhatit does is Fairly straightforward. The clever bits are usually delegated to something else. For example,zz provisionis really just a wrapper that installs and runs Chef, while passing various options to it.

Recently, I added Bash completion to my tool. I’ve wanted this for a while, but decided to add it now in preparation forsecrets management.For example, I want to be able to typezz secret --readamazand have it complete tozz secret --read amazon /. Perhaps hittingagain will list all secrets under this path, eg username, password, access_key, etc.

The mechanics

InBash, completion is handled through thecomplete‘built-in’:

$typecompletecomplete is a shellbuiltin

This command allows you to register a method of completion for a command. For example, anrgbcommand might register its known colors:

$ complete -W"red green blue yellow purple pink orange"color

You could then complete color names:

($ color(TAB)>TAB>blue green orange pink p urple red yellow$ color pTAB>TAB>pink purple)$ color piTAB>

The- Wswitch configures a static list of completions that are printed in alphabetical order. It’s just one of the many methods ofcompletion.

Listing completion methods

To see which commands have completion methods, runcompletewithout arguments:

$ completecomplete -W'red green blue yellow purple pink orange'colorcomplete -F _nodenv nodenvcomplete -F _rbenv rbenv

Here you can seeNodenvandrbenvsupport completion. They use the- Fswitch to specify functions to handle their completion,namely_ nodenvand_ rbenv. When you complete one of these commands, their output is context-aware:

$ rbenvinstall2.(5) *********TAB>TAB>**********2.5.02.5.0-rc12.5.1**2.5.22.5.3

That’s helpful!rbenvhas kindly listed which Ruby (2.5.x) versions are available to install. We could find this out fromrbenv install --listbut that’s inefficient because we’d have to clear our current command then re-type it.

How completionfunctionswork

When a function is registered as the method of completion with the- Fswitch, it must comply with an ‘interface’ of sorts. When the function is called, Bash sets some environment variables to be used by the completion function.

Theytellit the contents of the command-line, the cursor position, etc. For example,$ COMP_LINEcontains the full line that was typed,$ COMP_WORDSis that same line broken into an array of words and$ COMP_POINTis the cursor’s index position.

In return, the completion function should set$ COMPREPLYto specify which completions to print for the command.

An example

Everybody loves FizzBuzz, right? Let’s demonstrate Bash completion with a custom function thatmagicallycompletes the next term in the sequence:

function_ fizzbuzz(){length=$ {#COMP_WORDS[@]}number=$ ((length-1))**********if!***((number) %15));thenCOMPREPLY=(fizzbuzz)***elif!((number%3));then)COMPREPLY=(fizz)ELIF!(()number%(5)));)thenCOMPREPLY=(buzz)elseCOMPREPLY=($ number) )fi}complete -F _fizzbuzz fizzbuzz

Ourcommandis calledfizzbuzzso we name our completion function_ fizzbuzz, as per the convention . We first set thelengthvariable to the number of words on the command-line and(number)to one less, since ‘fizzbuzz‘itself counts as a word.

We’ve probably all seen FizzBuzz before so let’s skip the modulo logic. The important part is to set$ COMPREPLY– in this case, to an array of the next term in the sequence.

Now, if we typefizzbuzz, Bash completion kicks in and as if bymagicthe next term is appended to the current command-line. Ourfizzbuzzcommand doesn’t actually exist but that doesn’t seem to matter!

As you can see, there’s plenty of fun to be had! Inpart twowe’ll implement Bash completion for my automation tool and see how it works in practice.