Bash-completion: как сделать удобно в CLI18.04.2024 14:15

Так получилось что в рамках моей основной деятельности пришла пора сделать сервис для манипуляции с ресурсами СХД для виртуальных машин (ВМ). Они подаются в SAN в виде «LUN» («Logical Unit Number»). Пока речь шла о десятках … первых сотнях LUN, хватало моего старого решения (оно изначально про телефонию и блок-схемы, но на самом деле всё равно подо что делать очередной модуль). А потом он рос, рос, и…

9c847d5eafdf3e4789bb010936626c46.jpgВ общем, взял я в руки python.

(Как удобный для прототипирования/«склейки» инструмент. И при этом в моём отделе примерно все могут, как минимум, прочитать написанное).
И наваял обёртку «lun» и пачку модулей в соседней папочке «lun.d». (Догадываюсь что на питоне принято раскладывать в другое место, но здесь — сервис местного значения.)

И вот теперь — главное. Эргономика рабочего места.

Структура вызова запроектирована в CLI таким образом (откидывая ненужные подробности): 

# lun edit dc 60:0a:09:80:00:01:02:03:00:00:02:7d:5a:3a:e3:b9 [--extra-keys]
# lun attach dc machine-name --lun=lun_name

Ровно один «фактор», и он не должен выламывать пальцы инженеру ТП!
WWN ("60:0a:09:80:00:01:02:03:00:00:02:7d:5a:3a:e3:b9") копипастится с консольки СХД или из задачи. Остальное должно заезжать «магически», примерно всё «интересное».

К делу

Чтобы не плеваться от UI, нужно автодополнять:

  • Имя модуля (список модулей покажет ls в подкаталоге).

  • Аббревиатуру датацентра («dc» в примере выше, спросить можно »lun get list-dc»).

  • Третий позиционный аргумент (больше низзя!), или »--ключ».

  • Прочие »--ключи», по необходимости.

И в этом месте начался реальный трэш. По итогам которого я дал себе обещание написать «хавтушку» для других желающих «как лучше».

  • Хабро-перевод я просмотрел одним из первых. Но, «фактуры маловато».

  • Что можно найти в «man bash», читатель, я полагаю, в курсе. Я не настолько фанат bash (но в этот раз таки немного пришлось и там поползать).

  • Подход к подобному классу задач обычно состоит в том чтобы взять чей-нибудь код для затравки. И порыться в интернетах на предмет приличной статьи на тему. И тут — нате вам. Гугл принялся выдавать репосты одного и того же chatGPTбреда про автодополнение из bash_history. А подручные «дополнялки» (модули bash-completion от используемого софта) демонстрируют откровенно слабое владение мат.частью.

  • В какой-то момент повезло, наконец, наткнуться на devmanual.gentoo.org. Сразу дам ссылки: Ключевые понятия, Подробности про «compgen», Подробности про «complete». Все 3 статьи достаточно компактные, но позволяют начать разбираться в вопросе.

Дальше показываю «как», на своём примере.

«Рыба»: 

_lun() {
  local cur="$2"
  local prev="$3"
  local obj cmd base keys key val
  local LIST=""
  local WWID=""
  local LUN=""
  local cmd="${COMP_WORDS[1]}"
  local DC="${COMP_WORDS[2]}"
…
} && complete -F _lun lun

  • complete -F вызывает функцию _lun(), когда дополняет команду lun.

  • Для простых манипуляций достаточно трёх аргументов вызываемой функции (подробнее). Какую команду дополняем ($1), что дополняем ($2) и что было перед этим ($3).

  • Ключевое слово local призвано подстраховать переменные внутри функции от «протекания» наружу. Вообще, всё автодополнение в bash свалено в одну кучу, и безграмотными действиями легко сломать работу чужого кода.

  • Для более сложных манипуляций доступны массив COMP_WORDS[] и указатель на его последний элемент COMP_CWORD. Выше видно, как я достаю из него пару «позиционных» аргументов.

  • Для «высшего пилотажа» оставлен доступ к COMP_LINE и COMP_POINT (вся дополняемая строка и текущее положение курсора).

Первый аргумент: 

  if [ "${COMP_CWORD}" = "1" ]
  then
    # first level -> base objects
    base="/usr/local/sbin/lun.d"
    obj=$(cd ${base} && ls -1 *.py | cut -f 1 -d "." | sort -u)
    COMPREPLY=( $(compgen -W "help ${obj}" -- "${cur}") )

  • Башисты в этом месте должны стукнуть мне по рукам за cd. Потому что есть пара pushd/popd.

  • Берём список всех модулей *.py, добавляем ещё одно ключевое слово help (вывести хинт к обёртке lun) и формируем из этого набор «слов» для compgen -W. В COMPREPLY возвращается bash-массив (то что внутри круглых скобок »(…)»).

  • В конце вызова compgen нужно обязательно ставить дополняемое (${cur}). »--«подсказывают GNU’тым утилитам, что дальше -ключей не будет.

Второй аргумент: 

  elif [ "${COMP_CWORD}" = "2" ]
  then
    # second level -> commands
    DC=$(sudo lun get list-dc)
    if [ "${cmd}" = "get" ]; then
      COMPREPLY=( $(compgen -W "help ${DC} list-dc" -- "${cur}") )
    else
      COMPREPLY=( $(compgen -W "help ${DC}" -- "${cur}") )
    fi

  • Применение sudo здесь реально важно. Пользователь имеет доступ к неким привилегированным командам, но не sudo -i для всех подряд же!

  • Вызов sudo lun поломает работу автодополнения. Потому что дополнение будет для sudo, а мнение писавших sudo не всегда совпадает с моим. Чтобы у пользователя всё работало, нужен альяс (где-нибудь в ~/.bashrc): alias lun="sudo lun"

Третий аргумент: 

  elif [ "${COMP_CWORD}" = "3" ]
  then
    # third level -> keys
    keys=`sudo lun ${cmd} args`
    if [[ "${cmd}" =~ get|add|edit ]]; then
      if [ "${DC}" = "list-dc" ]; then
        return
      fi
      WWID=$(sudo lun get ${DC} --fields=wwid --compact | cut -d ']' -f 1 | cut -d ' ' -f 2 | tail -n 5)
      COMPREPLY=( $(compgen -W "${keys} ${WWID}" -- "${cur}" | awk '{ if ($0 !~ "^-") {print "'\''"$0"'\''"} else print $0 }') )
    elif [[ "${cmd}" == vm || "${cmd}" == attach || "${cmd}" == resize ]]; then
#      compopt -o nospace
      LIST=`sudo lun vm ${DC} list "${cur}" --cached`
      COMPREPLY=( $(compgen -W "${LIST}" -- "${cur}" ) )
    else
      COMPREPLY=( $(compgen -W "${keys}" -- "${cur}" | awk '{ if ($0 !~ "^-") {print "'\''"$0"'\''"} else print $0 }') )
    fi

  • Про nospace будет ниже.

  • Каждый модуль обучен выводить список принимаемых аргументов по ключу args. Его и показываем, в общем случае.

  • list-dc вместо аббревиатуры датацентра выводит список известных ДЦ. Нечего дальше дополнять, return.

  • Для команд get|add|edit дополнительно показываем список из пяти последних добавленных LUN. Не супер удачное решение, т.к. в процессе вытаскивает листинг всех LUN в ДЦ. Правильнее было бы не-юниксвейно протащить ограничение в lun get.

  • Вот этот фокус с кавычками для WWN (кому не ясно что тут написано, гуглит «bash escape quotes»): {print "'''"$0"'''"}. Он для того чтобы автодополнялось разделённое »:». Т.к.»:» входит в список разделителей слов по умолчанию. Глубже копать в этом месте я поленился.

  • Для команд vm, attach, resize дополняем имя ВМ из закэшированного в локальной БД списка. Выше сравнение было через »=~», а здесь вот так. Просто потому что сначала команда была одна.

  • Автодополнять ну очень желательно откуда-то из «быстрого» кэша. Не уподобляйтесь писателям yum/dnf и иже с ним. Долгие запросы через ssh, так и вовсе отваливаются по таймауту. Я не нашёл этого места в bash-completion, но не сильно и старался.

  • Для всех прочих команд, выводим только список ключей.

Остальные аргументы: 

  else
    # other level -> options
    if [ "${COMP_WORDS[COMP_CWORD]}" = "=" ]; then
      key=$((COMP_CWORD - 1))
    elif [ "${COMP_WORDS[COMP_CWORD-1]}" = "=" ]; then
      key=$((COMP_CWORD - 2))
    fi

Для не-булевых аргументов, ключи вида --key=value, без пробелов. С пробелами я ниасилил. Будем считать это «домашним заданием», для лучшего овладения материалом.

Поехали дополнять: 

    if [ ! -z "${key}" ]; then
      if [ "${COMP_WORDS[$key]}" = "--fields" ]; then
        val="alias host vm scsi blkdeviotune ,"
        local list=$(echo "${cur}" | egrep -o '([a-z]+,)+')
        cur="${cur/[[:alpha:]]*,/}"
        COMPREPLY=( "${list}"$(compgen -W "${val}" -- "${cur}") )
        compopt -o nospace
      elif [ "${COMP_WORDS[$key]}" = "--file" ]; then # [ "${cmd}" = "edit" ]
        compopt -o filenames
        COMPREPLY=( $(compgen -f -- "${cur}") )
      elif [ "${COMP_WORDS[$key]}" = "--vm" ]; then # [ "${cmd}" = "get" ]
        LUN=`sudo lun vm ${DC} list --cached`
        COMPREPLY=( $(compgen -W "${LUN}" -- "${cur}" ) )
      elif [ "${COMP_WORDS[$key]}" = "--lun" ]; then # [ "${cmd}" = "attach"|"resize" ]
        local vm="${COMP_WORDS[3]}"
        LUN=`sudo lun vm ${DC} ${vm} --cached --luns --json | jq -r ".luns[]"`
        COMPREPLY=( $(compgen -W "${LUN}" -- "${cur}" ) )
      else
        val="<`echo ${COMP_WORDS[$key]} | tr -d '=-'`>"
        COMPREPLY=( $(compgen -W "${val}" -- "${cur}") )
        compopt -o nospace
      fi
    else
      keys=`sudo lun "${COMP_WORDS[1]}" args`
      COMPREPLY=( $(compgen -W "${keys}" -- "${cur}") )
    fi

  • Если ключ не начали вводить, показываем список ключей для модуля (нижний блок else). Правильно было бы исключить уже́ задействованные ключи из списка. Внутри — питоновский «argparse», он тупо возьмёт последний попавшийся.

  • Ключ --fields принимает на вход список полей через »,». Такое решение опять-таки поперёк дефолтных настроек разделителей для libreadline, поэтому дальше — фокус: cur="${cur/[[:alpha:]]*,/}". Срезаем всё до последней «запятой». Я вообще в баш-портянках стараюсь ограничиваться средствами баша. Потому что самому потом грозит (в случае чего) разматывать логи аудита.

  • В этом месте также следовало бы исключать все ранее перечисленные через »,» поля из автодополнения.

  • Для --file нужно автодополнять имена файлов из текущего каталога. Для этого заказываем compopt -o filenames, иначе не даст «проваливаться» в подкаталоги. Где-то написано что это можно вставлять прямо в вызов compgen -f. Но так (у меня, bash 4.4.20 из Oracle Linux 8) не работает.

  • Для --lun берём список LUN, относящихся к указанной ВМ. Запрос jq -r ".luns[]" достаёт значения (имена LUN) из отданного в json словаря. JSON и «jq» — вообще довольно удобно при парсинге отдаваемого в CLI. Для тех утилит, которые умеют в JSON.

  • Всё остальное (после else) — не знаем как дополнять. По «табулятору» выводим название ключа в угловых скобках (--key=).

Чтобы автодополнялось после »=», просим не добавлять пробел: 

  if [[ "${COMPREPLY[@]}" =~ =$ ]]; then
    # Add space, if there is not a '=' in suggestions
    compopt -o nospace
  fi

Всё. Как смог, рассказал. Удачи в улучшении UI/UX для инструментов командной строки!

  • Это мой первый опыт написания (а не подачи в виде лекции) обучающего материала для взрослых тётей и дядей. Буду крайне признателен за конструктивную критику. И, по мере поступления таковой,  постараюсь доработать эту статью для улучшения читаемости.

© Habrahabr.ru