How to Add Terminal Completion to Your Command Line Apps

Automatic completion is a great way to make your own tools more accessible. Find out how to take the first steps by building a simple bash and zsh automatic script.

How the completion of the tab works

Semi -automatic entry – has passed everywhere, text messaging applications to IDE – may seem a fairly modern innovation, but it has been present in various forms of UNIX since the early 1980s, if not earlier. Linux shells like Bash and Zsh support a more powerful completion ecosystem that you can expect.

You probably use the completion most often with commands and file names. The completion of the control tab works by inspecting the path environment variable to identify the available commands starting with the letters you have hit. The completion of the file name will provide the rest of a file path (absolute or relative) and will help you refine your options, resolving the ambiguities as you go. Both will save you a lot of time and manual strike.

But there is a third type of completion, perhaps less popular, but even more powerful, perhaps, than the most common types. The automatic plate argument applies to everything after the order name, such as options or sub-communs:

How to add the completion to your own scripts

I will explain how you can first add a personalized completion for ZSH, then describe a bash equivalent.

An order example

I will demonstrate the end of the personalized control argument with a trivial script that I use to manage my task list. The complete script is not very complicated, but this extract focuses on the most relevant parts:

        #!/usr/bin/env zsh
FILE="$HOME/.local/state/todos/data"
if [ "$#" -eq "1" ] && [ "$1" = "edit" ] ; then
    "${EDITOR:-vi}" "$FILE"
elif [ "$#" -eq "1" ] && [ "$1" = "help" ] ; then
    echo "Usage: $(basename $0) [ edit | help ]"
else
    <"$FILE" grep -v ^~
fi

    

I have this script saved in a file called Todos, so the following commands now run on my system:

• todos: output content of the data file, ignoring the lines starting ~
• Todos helps: Display use
• Todos modify: Open the data file in the editor

It is really a convenience command, although the complete script does an additional work to maintain a separate JSON file on the modifications. I do not have a men’s page for such a simple script, and the help sub-command is practical, but I would like to add the completion of the arguments so that I can discover the edition subcommanding or other sub-comments that I could add to the future.

A personalized completion script

Your complete complete script must do two things: configure the completion system for your order using integrated scaffolding and generate possible supplements.

In ZSH, the most basic completion is very simple:

        _complete_todos() {
    compadd help edit
}
autoload -Uz compinit
compinit
compdef _complete_todos todos

    

The _Complete_Todos function is a manager who calls Compad to specify suggestions. The Compadd function belongs to the compinit module of Zsh. Each word you pass as a argument to Compad represents a possible completion. For a script as simple as this example, it is perfectly good to cocoded them with a static call to Compadd.

With the defined function, the charting script and then performs the compinit module before calling Compdef to connect the _complete_todos function with the command, todos.

You can put the above script in your .zshrc file, or another file it gets. You can also use the ZSH FPATH system to store it in a file starting with an underlint, in an appropriate directory.

For development and tests, you can simply run the code above directly on the command line. Once you have done it, try to type todos And experiment with the behavior of semi-automatic seizure.

Bash differences

Bash is very different with regard to completion. In particular, he will not hold his hand as much as Zsh. While Zsh manages the complete suggestions herself, Bash expects that you are appropriate what suggestions are appropriate, depending on what has been typed and where the tab has been in a hurry.

Consider a naive equivalent of the ZSH script above:

        _complete_todos_bash() {
    COMPREPLY=(help edit)
}
complete -F _complete_todos_bash todos

    

Bash provides a complete order instead of ZSH’s function approach, so it is not necessary to load or initialize anything. The completion manager establishes a known – complex – variable – instead of echo suggestions. This variable is a bash table.

If you test this bash script, you will see that it lists all the suggestions of sub-command as you expect:

        $ todos 
help edit

    

The problem is that BASH will always trust your manager to provide all the relevant suggestions, without applying any more logic. These results are therefore not always useful:

        $ todos he
help edit

    

It is your responsibility to tell Bash that “he” should only suggest “help” as a possible completion. You can do this by inspecting certain useful variables that Bash provides when the tab is driven:

• Comp_words is a table containing the complete command line divided into individual words.

• Comp_cword is an index in Comp_Words referring to the word that the cursor is currently inside.

Using this data, you can determine which word is finished and provide contextual suggestions. Although there are ways to do so manually, Bash provides another useful, compgen order. This can generate many types of suggestions based on things such as available functions or orders, and the word typed so far. The -W option will look for a list of static words:

        $ compgen -W "one two three" o
one
$ compgen -W "one two three" t
two
three

    

Thus, you can make a call to Compgen in the suggestion manager and take advantage of appropriate and context -specific suggestions with a very minimal script:

        _complete_todos_bash() {
    COMPREPLY=( $( compgen -W "edit help" -- "${COMP_WORDS[$COMP_CWORD]}" ) )
}
complete -F _complete_todos_bash todos

    

Gather everything

For your personal scripts, you probably run in a known environment: that is to say Bash or Zsh. But for more portable scripts, which you may want to share with others or use on several systems, you must summarize part of this code.

Here is a full version of the completion script that works in ZSH or Bash, detecting the Shell in which he runs and executing the relevant code.

        SUBCOMMANDS=(help edit halt)
_complete_todos_zsh() {
    compadd $SUBCOMMANDS
}
_complete_todos_bash() {
    COMPREPLY=( $( compgen -W "${SUBCOMMANDS[*]}" -- "${COMP_WORDS[$COMP_CWORD]}" ) )
}
if [ -n "${ZSH_VERSION:-}" ]; then
    autoload -Uz compinit
    compinit
    compdef _complete_todos_zsh todos
elif [ -n "${BASH_VERSION:-}" ]; then
    complete -F _complete_todos_bash todos
fi

    

The environment variables ZSH_Version and Bash_version announce in which Shell we are currently executing. Remember that the shell in which your order works is unimportant, it is the shell that invokes the completion system, in which the user pressed the tab, which counts here.

This script stores its suggestions in a variable of sub-communs to which the two functions have access. They each use it to define the supplements supported, ZSH by calling the Compadd function and based by defining the inclusion variable. Note that Bash must do a lot of syntactically heavy massage of the types to be converted between the tables and the channels.

You can save the above script in a single file – EG Completion.sh – Then enter this file from your .bashrc and / or .zshrc like this:

        . /path/to/completion.sh

    

Following steps

We barely scratched the surface of the personalized supplements of the shell. Using this simple script, you can add supplements for a fixed set of simple sub-communs, but there is much more to perform programs on the command line that you may want to take into account.

A robust completion script must take into account the complete command line, as other arguments may affect the one you are trying to finish.