add bash-comp-tut (ru)

2025-04-24 23:37:19 +00:00 · 2014-07-18 00:05:48 +04:00 · 2014-07-18 00:05:48 +04:00 · b2904998b8
commit b2904998b8
parent 79059122a0
2 changed files with 146 additions and 7 deletions
--- a/ru/_posts/2014-07-17-writting-own-completions-p1.html
+++ b/ru/_posts/2014-07-17-writting-own-completions-p1.html
@ -17,7 +17,7 @@ description: В данных статьях описываются некото
 <p>Рассмотрим на примере моего же приложения, часть справки к которому выглядит таким образом:</p>
 {% highlight bash %}
 netctl-gui [ -h | --help ] [ -e ESSID | --essid ESSID ] [ -с FILE | --config FILE ]
-           [ -o PROFILE | --open PROFILE ] [ -t NUM | --tab NUM ] [ --set-opts OPTIONS ]           
+           [ -o PROFILE | --open PROFILE ] [ -t NUM | --tab NUM ] [ --set-opts OPTIONS ]
 {% endhighlight %}

 <p>Список флагов:
@ -35,7 +35,7 @@ netctl-gui [ -h | --help ] [ -e ESSID | --essid ESSID ] [ -с FILE | --config FI
 <p>В заголовке должно быть обязательно указано, что это файл дополнений и для каких приложений он служит (можно строкой, если в файле будет содержаться дополнение для нескольких команд):

 {% highlight bash %}
-#compdef netctl-gui          
+#compdef netctl-gui
 {% endhighlight %}

 Дальше идет описание флагов, вспомогательные функции и переменные. Замечу, что функции и переменные, которые будут использоваться для дополнения <b>должны возвращать массивы</b>, а не строки. В моем случае схема выглядит примерно так (все функции и переменные в этой главе умышленно оставлены пустыми):
@ -45,14 +45,14 @@ netctl-gui [ -h | --help ] [ -e ESSID | --essid ESSID ] [ -с FILE | --config FI
 _netctl_gui_arglist=()
 _netctl_gui_settings=()
 _netctl_gui_tabs=()
-_netctl_profiles() {}       
+_netctl_profiles() {}
 {% endhighlight %}

 Затем идут основные функции, которые будут вызываться для дополнения для определенной команды. В моем случае команда одна, и функция одна:

 {% highlight bash %}
 # work block
-_netctl-gui() {}       
+_netctl-gui() {}
 {% endhighlight %}

 Далее <b>без выделения в отдельную функцию</b> идет небольшое шаманство, связанное с соотнесением приложения, которое было декларировано в первой строке, с функцией в теле скрипта:
@ -62,7 +62,7 @@ case "$service" in
    netctl-gui)
        _netctl-gui "$@" && return 0
        ;;
-esac      
+esac
 {% endhighlight %}
 </p>

@ -79,7 +79,7 @@ _netctl_gui_arglist=(
    {'(--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 %}
 </p>

@ -141,6 +141,6 @@ _netctl-gui() {
 </p>

 <h2><a name="conclusion" class="anchor" href="#conclusion"><span class="octicon octicon-link"></span></a>Заключение</h2>
-<p>Файл хранится в директории <code>/usr/share/zsh/site-functions</code> с произвольным в общем-то именем с префиксом <code>_</code>. Файл примера полностью может быть найден <a href="https://raw.githubusercontent.com/arcan1s/netctl-gui/master/sources/gui/zsh-completions">в моем репозитории</a>.</p>
+<p>Файл хранится в директории <code>/usr/share/zsh/site-functions/</code> с произвольным, в общем-то, именем с префиксом <code>_</code>. Файл примера полностью может быть найден <a href="https://raw.githubusercontent.com/arcan1s/netctl-gui/master/sources/gui/zsh-completions">в моем репозитории</a>.</p>

 <p>Дополнительная информация может быть найдена в репозитории <a href="https://github.com/zsh-users/zsh-completions">zsh-completions</a>. Например, там есть такой <a href="https://github.com/zsh-users/zsh-completions/blob/master/zsh-completions-howto.org">How-To</a>. А еще там есть много примеров.</p>
--- a/ru/_posts/2014-07-17-writting-own-completions-p2.html
+++ b/ru/_posts/2014-07-17-writting-own-completions-p2.html
@ -0,0 +1,139 @@
+---
+category: ru
+type: paper
+hasTr: true
+layout: paper
+tags: linux, разработка
+title: Написание собственных дополнений для Shell. Bash
+short: writting-own-completions-p2
+description: В данных статьях описываются некоторые основы создания файлов автодополнений для собственной программы.
+---
+<h2><a name="preamble" class="anchor" href="#preamble"><span class="octicon octicon-link"></span></a>Преамбула</h2>
+<p>В процессе разработки <a href="/ru/projects/netctl-gui">одного своего проекта</a> возникло желание добавить также файлы автодополнений (только не спрашивайте зачем). Благо я как-то уже брался за написание подобных вещей, но читать что-либо тогда мне было лень, и так и не осилил.</p>
+
+<h2><a name="introduction" class="anchor" href="#introduction"><span class="octicon octicon-link"></span></a>Введение</h2>
+<p>Bash, в <a href="/ru/2014/07/17/writting-own-completions-p1">отличие от zsh</a>, требует к себе некоторого велосипедостроения в отношении дополнений. Бегло погуглив, я не нашел более-менее нормальных туториалов, потому за основу были взяты имеющиеся в системе файлы дополнений для <code>pacman</code>.</p>
+
+<p>Рассмотрим на примере все того же моего приложения. Я напомню, что часть справки к которому выглядит таким образом:</p>
+{% 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 %}
+
+<p>Список флагов:
+<ul>
+  <li>флаги <code>-h</code> и <code>--help</code> не требуют аргументов;</li>
+  <li>флаги <code>-e</code> и <code>--essid</code> требуют аргумента в виде строки, без дополнения;</li>
+  <li>флаги <code>-c</code> и <code>--config</code> требуют аргумента в виде строки, файл с произвольной локацией;</li>
+  <li>флаги <code>-o</code> и <code>--open</code> требуют аргумента в виде строки, дополнение по файлам из определенной директории;</li>
+  <li>флаги <code>-t</code> и <code>--tab</code> требуют аргумента в виде строки, дополнение из указанного массива;</li>
+  <li>флаг <code>--set-opts</code> требует аргумента в виде строки, дополнение из указанного массива, разделены запятыми;</li>
+</ul>
+</p>
+
+<h2><a name="file" class="anchor" href="#file"><span class="octicon octicon-link"></span></a>Структура файла</h2>
+<p>Здесь <b>все</b> переменные должны возвращать массив. Каких-либо особых форматов тут уже нет. Сначала опишем флаги, потом уже все остальные переменные. Я напомню (так как ниже я уже не буду приводить функции более подробно), что <code>_netctl_profiles()</code>, в отличие от других переменных, должна возвращать актуальный на данный момент массив:
+
+{% highlight bash %}
+# variables
+_netctl_gui_arglist=()
+_netctl_gui_settings=()
+_netctl_gui_tabs=()
+_netctl_profiles() {}       
+{% endhighlight %}
+
+Затем идут основные функции, которые будут вызываться для дополнения для определенной команды. В моем случае команда одна, и функция одна:
+
+{% highlight bash %}
+# work block
+_netctl-gui() {}       
+{% endhighlight %}
+
+Далее, опять, <b>без выделения в отдельную функцию</b> делаем соответствие функция-команда:
+
+{% highlight bash %}
+complete -F _netctl_gui netctl-gui  
+{% endhighlight %}
+</p>
+
+<h2><a name="variables" class="anchor" href="#variables"><span class="octicon octicon-link"></span></a>Массивы переменных</h2>
+<p>Приведу только функцию, которая в zsh выглядела таким образом:
+
+{% highlight bash %}
+_netctl_profiles() {
+    print $(find /etc/netctl -maxdepth 1 -type f -printf "%f\n")
+}
+{% endhighlight %}
+
+В bash так не получится, пришлось чуть-чуть изменить:
+
+{% highlight bash %}
+_netctl_profiles() {
+    echo $(find /etc/netctl -maxdepth 1 -type f -printf "%f\n")
+}
+{% endhighlight %}
+</p>
+
+<h2><a name="flags" class="anchor" href="#flags"><span class="octicon octicon-link"></span></a>Флаги</h2>
+<p>Как было сказано выше, особого формата тут нет, доступные флаги располагаются просто массивом:
+
+{% highlight bash %}
+_netctl_gui_arglist=(
+    '-h'
+    '--help'
+    '-e'
+    '--essid'
+    '-c'
+    '--config'
+    '-o'
+    '--open'
+    '-t'
+    '--tab'
+    '--set-opts'
+)
+{% endhighlight %}
+</p>
+
+<h2><a name="body" class="anchor" href="#body"><span class="octicon octicon-link"></span></a>Тело функции</h2>
+<p>За дополнение в bash отвечает переменная <code>COMPREPLY</code>. Для отслеживания текущего состояния нужно вызвать функцию <code>_get_comp_words_by_ref</code> с параметрами <code>cur</code> (текущая опция) и <code>prev</code> (предыдущая, собственно состояние). Ну и нужно несколько точек, на которых сворачивать в определенную часть case (переменные <code>want*</code>). Для генерации дополнения используется <code>compgen</code>. После флага <code>-W</code> ему подается список слов. (Есть еще флаг <code>-F</code>, который вызывает функцию, но у меня он помимо этого еще и ворнинг выдает.) Последним аргументом идет текущая строка, к которой и нужно генерировать дополнение.</p>
+
+<p>Таким образом, наша функция выглядит так:
+
+{% highlight bash %}
+_netctl_gui() {
+    COMPREPLY=()
+    wantfiles='-@(c|-config)'
+    wantprofiles='-@(o|-open|s|-select)'
+    wantsettings='-@(-set-opts)'
+    
+    wanttabs='-@(t|-tab)'
+    _get_comp_words_by_ref cur prev
+
+    if [[ $prev = $wantstring ]]; then
+        # не делать дополнения, ждать введенной строки
+        COMPREPLY=()
+    elif [[ $prev = $wantfiles ]]; then
+        # дополнение по существующим файлам
+        _filedir
+    elif [[ $prev = $wantprofiles ]]; then
+        # дополнение из функции
+        COMPREPLY=($(compgen -W '${_netctl_profiles[@]}' -- "$cur"))
+    elif [[ $prev = $wanttabs ]]; then
+        # дополнение из массива
+        COMPREPLY=($(compgen -W '${_netctl_gui_tabs[@]}' -- "$cur"))
+    elif [[ $prev = $wantsettings ]]; then
+        # дополнение из массива
+        # -S вставит запятую после, но вот мультивыбор не включил =(
+        COMPREPLY=($(compgen -S ',' -W '${_netctl_gui_settings[@]}' -- "$cur"))
+    else
+        # вывести доступные аргументы
+        COMPREPLY=($(compgen -W '${_netctl_gui_arglist[@]}' -- "$cur"))
+    fi
+
+    true
+}
+{% endhighlight %}
+</p>
+
+<h2><a name="conclusion" class="anchor" href="#conclusion"><span class="octicon octicon-link"></span></a>Заключение</h2>
+<p>Файл хранится в директории <code>/usr/share/bash-completion/completions/</code> с произвольным именем. Файл примера полностью может быть найден <a href="https://raw.githubusercontent.com/arcan1s/netctl-gui/master/sources/gui/bash-completions">в моем репозитории</a>.</p>