В процессе разработки одного своего проекта возникло желание добавить также файлы автодополнений (только не спрашивайте зачем). Благо я как-то уже брался за написание подобных вещей, но читать что-либо тогда мне было лень, и так и не осилил.
- -Существует несколько возможных вариантов написания файла автодополнения для zsh. В случае данной статьи я остановлюсь только на одном из них, который предоставляет большие возможности и не требует больших затрат (например, работы с регулярными выражениями).
- -Рассмотрим на примере моего же приложения, часть справки к которому выглядит таким образом:
-{% highlight bash %} -netctl-gui [ -h | --help ] [ -e ESSID | --essid ESSID ] [ -с FILE | --config FILE ] - [ -o PROFILE | --open PROFILE ] [ -t NUM | --tab NUM ] [ --set-opts OPTIONS ] -{% endhighlight %} - -Список флагов: -
-h и --help не требуют аргументов;-e и --essid требуют аргумента в виде строки, без дополнения;-c и --config требуют аргумента в виде строки, файл с произвольной локацией;-o и --open требуют аргумента в виде строки, дополнение по файлам из определенной директории;-t и --tab требуют аргумента в виде строки, дополнение из указанного массива;--set-opts требует аргумента в виде строки, дополнение из указанного массива, разделены запятыми;В заголовке должно быть обязательно указано, что это файл дополнений и для каких приложений он служит (можно строкой, если в файле будет содержаться дополнение для нескольких команд): - -{% highlight bash %} -#compdef netctl-gui -{% endhighlight %} - -Дальше идет описание флагов, вспомогательные функции и переменные. Замечу, что функции и переменные, которые будут использоваться для дополнения должны возвращать массивы, а не строки. В моем случае схема выглядит примерно так (все функции и переменные в этой главе умышленно оставлены пустыми): - -{% highlight bash %} -# variables -_netctl_gui_arglist=() -_netctl_gui_settings=() -_netctl_gui_tabs=() -_netctl_profiles() {} -{% endhighlight %} - -Затем идут основные функции, которые будут вызываться для дополнения для определенной команды. В моем случае команда одна, и функция одна: - -{% highlight bash %} -# work block -_netctl-gui() {} -{% endhighlight %} - -Далее без выделения в отдельную функцию идет небольшое шаманство, связанное с соотнесением приложения, которое было декларировано в первой строке, с функцией в теле скрипта: - -{% highlight bash %} -case "$service" in - netctl-gui) - _netctl-gui "$@" && return 0 - ;; -esac -{% endhighlight %} -
- -Как я и говорил во введении, существует несколько способов создания подобных файлов. В частности, они различаются декларацией флагов и их дальнейшей обработкой. В данном случае я буду использовать команду _arguments, которая требует специфичный формат переменных. Выглядит он таким образом ФЛАГ[описание]:СООБЩЕНИЕ:ДЕЙСТВИЕ. Последние два поля не обязательны и, как Вы увидите чуть ниже, вовсе и не нужны в некоторых местах. Если Вы предусматриваете два флага (короткий и длинный формат) на одно действие, то формат чуть-чуть усложняется: {(ФЛАГ_2)ФЛАГ_1,(ФЛАГ_1)ФЛАГ_2}[описание]:СООБЩЕНИЕ:ДЕЙСТВИЕ. Замечу, что, если Вы хотите сделать дополнения для двух типов флагов, но некоторые флаги не имеют второй записи, то Вам необходимо продублировать его таким образом: {ФЛАГ,ФЛАГ}[описание]:СООБЩЕНИЕ:ДЕЙСТВИЕ. СООБЩЕНИЕ - сообщение, которое будет показано, ДЕЙСТВИЕ - действие, которое будет выполнено после этого флага. В случае данного туториала, ДЕЙСТВИЕ будет иметь вид ->СОСТОЯНИЕ.
Итак, согласно нашим требованиям, получается такое объявление аргументов: - -{% highlight bash %} -_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' -) -{% endhighlight %} -
- -В нашем случае есть два статических массива (не изменятся ни сейчас, ни через пять минут) (массивы умышленно уменьшены): -{% highlight bash %} -_netctl_gui_settings=( - 'CTRL_DIR' - 'CTRL_GROUP' -) - -_netctl_gui_tabs=( - '1' - '2' -) -{% endhighlight %} - -И есть динамический массив, который должен каждый раз генерироваться. Он содержит, в данном случае, файлы в указанной директории (это можно сделать и средствами zsh, кстати): - -{% highlight bash %} -_netctl_profiles() { - print $(find /etc/netctl -maxdepth 1 -type f -printf "%f\n") -} -{% endhighlight %} -
- -Помните, там выше было что-то про состояние? Оно хранится в переменной $state, и в теле функции делается проверка на то, чему оно равно, чтобы подобрать соответствующие действия. В начале также нужно не забыть вызвать _arguments с нашими флагами.
-
-{% highlight bash %}
-_netctl-gui() {
- _arguments $_netctl_gui_arglist
- case "$state" in
- essid)
- # не делать дополнения, ждать введенной строки
- ;;
- files)
- # дополнение по существующим файлам
- _files
- ;;
- profiles)
- # дополнение из функции
- # первая переменная описание
- # вторая массив для дополнения
- _values 'profiles' $(_netctl_profiles)
- ;;
- tab)
- # дополнение из массива
- _values 'tab' $_netctl_gui_tabs
- ;;
- settings)
- # дополнение из массива
- # флаг -s устанавливает разделитель и включает мультивыбор
- _values -s ',' 'settings' $_netctl_gui_settings
- ;;
- esac
-}
-{% endhighlight %}
-
Файл хранится в директории /usr/share/zsh/site-functions с произвольным в общем-то именем с префиксом _. Файл примера полностью может быть найден в моем репозитории.
Дополнительная информация может быть найдена в репозитории zsh-completions. Например, там есть такой How-To. А еще там есть много примеров.