Writting own Shell completions. Zsh

Some basics of creating a completion files for own application are described in these articles.

Preamble

While developing one of my projects I have wanted to add completion files. I have already tried to create these files, but I was too lazy to read some manuals about it.

Introduction

There are some possible ways to create zsh completion file. In this article I will describe only one of them, which provides a lot of opportunities, but does not require a lot of costs (such as regular expressions).

Lets consider the example of my application, which has a part of help message that looks like this:

netctl-gui [ -h | --help ] [ -e ESSID | --essid ESSID ] [ -с FILE | --config FILE ]
           [ -o PROFILE | --open PROFILE ] [ -t NUM | --tab NUM ] [ --set-opts OPTIONS ]

Here is a flag list:

• flags -h and --help do not require any arguments;
• flags -e and --essid require a string argument without completion;
• flags -c and --config require a string argument, which is a file;
• flags -o and --open require a string argument, there is a completion from files in the specified directory;
• flags -t and --tab require a string argument, there is a completion from the specified array;
• flag --set-opts requires a string argument, there is a completion from the specified array comma separated;

The file pattern

It must be specified in the header that it is a completion file and application for which it will complete (may be string if this file provides completions for several applications):

#compdef netctl-gui

Next there is flags, additional functions and variables declarations. It should be noted that all functions and variables, which will be used for completions, should return arrays. In my case this scheme looks like this (I left empty these functions in this chapter):

# variables
_netctl_gui_arglist=()
_netctl_gui_settings=()
_netctl_gui_tabs=()
_netctl_profiles() {}

Then there are main functions, which will be called for completion of specific application. In my case this there is only one applications, so there is only one function:

# work block
_netctl-gui() {}

And finally without isolation in a separate function there is a small shamanism, which declares a dependence “application-function”:

case "$service" in
    netctl-gui)
        _netctl-gui "$@" && return 0
        ;;
esac

Flags

As it was said above, there are some different ways to create these files. In particular they differ in the flag declaration and their further processing. In my case I will use _arguments command, which require a specific format of variables: FLAG[description]:MESSAGE:ACTION. The last two fields are not required and, as you will see below, are not needed in some cases. If you want to add two flags for an action (short and long format), then the format is a little bit complicated: {(FLAG_2)FLAG_1,(FLAG_1)FLAG_2}[description]:MESSAGE:ACTION. It should be noted that if you want to create completions for two flags but some flags have not a second format. you will should to add following line: {FLAG,FLAG}[description]:MESSAGE:ACTION. MESSAGE is a message which will be shown, ACTION is an action which will be performed after this flag. In this tutorial ACTION will be following: ->STATE.

So, according to our requirements, flags declaration will be following:

_netctl_gui_arglist=(
    {'(--help)-h','(-h)--help'}'[show help and exit]'
    {'(--essid)-e','(-e)--essid'}'[select ESSID]:type ESSID:->essid'
    {'(--config)-c','(-c)--config'}'[read configuration from this file]:select file:->files'
    {'(--open)-o','(-o)--open'}'[open profile]:select profile:->profiles'
    {'(--tab)-t','(-t)--tab'}'[open a tab with specified number]:select tab:->tab'
    {'--set-opts','--set-opts'}'[set options for this run, comma separated]:comma separated:->settings'
)

Arrays of variables

In my case there are two static arrays (which will not be changed):

_netctl_gui_settings=(
    'CTRL_DIR'
    'CTRL_GROUP'
)

_netctl_gui_tabs=(
    '1'
    '2'
)

And there is a dynamic array, which should be generated each time. In my case it is a list of files in the specified directory (by the way it may be done by means of zsh):

_netctl_profiles() {
    print $(find /etc/netctl -maxdepth 1 -type f -printf "%f\n")
}

Function

Remember, there was something about a state above? It is stored in the variable $state and in this function we will check what it is to choose the appropriate action. At the beginning of the function we should call _arguments with our flags.

_netctl-gui() {
    _arguments $_netctl_gui_arglist
    case "$state" in
        essid)
            # do not completion, wait for string
            ;;
        files)
            # completion from files in this directory
            _files
            ;;
        profiles)
            # completion from function
            # first variable is a description
            # second variable is a completion array
            _values 'profiles' $(_netctl_profiles)
            ;;
        tab)
            # completion from array
            _values 'tab' $_netctl_gui_tabs
            ;;
        settings)
            # completion from array
            # flag -s sets separator and enables multi-selection
            _values -s ',' 'settings' $_netctl_gui_settings
            ;;
    esac
}

Conclusion

File should be places to /usr/share/zsh/site-functions/ with any name (it is recommended to set prefix to _). You may found the example in my repository.

The additional information may be found in zsh-completions repository. For example there is this How-To. And also there are a lot of examples.