Все статьи | Дневник студента

[ docopt ] Описаниe языка интерфейса командной строки

[ docopt ] Описаниe языка интерфейса командной строки главное изображение

Ознакомьтесь с видеороликом https://youtu.be/pXhcPJK5cMc

docopt поможет вам:

  • определить интерфейс приложения командной строки
  • автоматически генерировать парсер для него

docopt основан на соглашениях, которые десятилетиями использовались в справочных сообщениях и страницах помощи для описания интерфейса программ. Описание интерфейса в docopt - это формализованное справочное сообщение. Например:

enter image description here

Пример описывает интерфейс исполняемого файла naval_fate, который может быть вызван различными комбинациями команд (ship, new, move и др.).), параметры (-h, --help, --speed=<kn> и др.) и позиционные аргументы (<name>, <x>, <y>).

Пример использует квадратные скобки "[ ]", круглые скобки "( )", знак вертикальной черты "|" и многоточие "..." для описания соответственно необязательных, обязательных, взаимоисключающих и повторяющихся элементов. Вместе эти элементы образуют допустимые шаблоны использования, каждый из которых начинается с имени программы naval_fate.

Ниже шаблонов помещен список опций с описаниями. Они описывают, имеет ли опция короткую/длинную форму (-h, --help), имеет ли опция аргумент (--speed=<kn>), и имеет ли этот аргумент значение по умолчанию ([default: 10]).

Реализация docopt извлекает всю эту информацию и генерирует синтаксический анализатор аргументов командной строки с текстом описания интерфейса в качестве справочного сообщения, которое выводится при вызове программы с параметрами -h или --help.

Шаблоны использования

Текст, находящийся между ключевым словом usage: (без учета регистра) и явной (видимой) пустой строкой, интерпретируется как список шаблонов использования (usage patterns). Первое слово после usage: интерпретируется как имя программы.

Это минимальный пример программы, которая не принимает аргументы командной строки:

enter image description here

Программа может иметь несколько шаблонов, перечисленных с различными элементами, используемыми для описания шаблона:

enter image description here

Все элементы и конструкции описаны ниже. Мы будем использовать слово "слово" для описания последовательности символов, разделенных или пробелами, или одним из символов из списка" | ", или "...".

<argument> ARGUMENT

Слова, начинающиеся с "<", и заканчивающиеся ">" и находящиеся в верхнем регистре, интерпретируются как позиционные аргументы.

enter image description here

-o --option

Слова, начинающиеся с одного или двух тире (за исключением самих-по-себе "-", "--") интерпретируются как соответственно короткие (one-letter) или длинные опции.

Короткие опции могут быть "сложены" ("stacked"), что означает, что -abc эквивалентно -a-b-c. Длинные опции могут иметь аргументы, указанные после пробела или равные знаку "=", например: --input=ARG эквивалентно --input ARG.

Короткие параметры могут иметь аргументы, указанные после необязательного пробела: -f FILE эквивалентно -fFILE.

Обратите внимание, что запись --input ARG (в отличие от --input=ARG) неоднозначна, то есть невозможно определить, является ли ARG аргументом опции или позиционным аргументом. В применяемых шаблонах это будет интерпретироваться как параметр с аргументом только в том случае, если приведено описание (приведенное ниже) для этого параметра. В противном случае он будет интерпретироваться как опция и отдельный позиционный аргумент.

Существует такая же двусмысленность с нотацией -f FILE и -fFILE. В последнем случае невозможно сказать, является ли это ряд сложенных (stacked) коротких вариантов или вариант с аргументом. Эти обозначения будут интерпретироваться как параметр с аргументом только в том случае, если будет предоставлено описание для параметра.

command

Все другие слова, которые не следуют вышеуказанным соглашениям --options или <arguments>, интерпретируются как (под)команды.

[optional elements]

Элементы (параметры (опции), аргументы, команды), заключенные в квадратные скобки "[ ]", помечаются как необязательные. Не имеет значения, заключены ли элементы в одну или несколько пар скобок, например:

enter image description here

Эквивалентно

enter image description here

(required elements)

Все элементы обязательны по умолчанию, если они не заключены в скобки "[ ]". Однако, иногда необходимо пометить элементы как обязательные явно с помощью круглых скобок "()". Например, когда необходимо сгруппировать взаимоисключающие элементы (см. Следующий раздел):

enter image description here

Другой случай использования - когда вам нужно указать, что если один элемент присутствует, то и другой является обязательным, и это вы можете сделать следующим образом:

enter image description here

В этом случае, допустимый вызов программы может быть либо без аргументов, либо с двумя аргументами.

element|another

Взаимоисключающие элементы могут быть разделены вертикальной чертой (pipe) "|" как ниже:

enter image description here

Используйте круглые скобки "()" для группировки элементов, когда требуется один из взаимоисключающих случаев. Используйте квадратные скобки "[ ]" для группировки элементов, когда ни один из взаимоисключающих случаев не требуется:

enter image description here

Обратите внимание, что указание нескольких шаблонов работает точно так же, как вертикальная черта "|", то есть:

enter image description here

Эквивалентно

enter image description here

element...

Используйте многоточие "..." чтобы указать, что аргумент (или группа аргументов) слева может быть продублирован один или несколько раз:

enter image description here

Вы можете гибко указать количество необходимых аргументов. Например, ниже приведено три разных способа указать, что требуется от ноля аргументов и более:

enter image description here

Один или больше аргументов

enter image description here

Два или больше аргументов (и т.д.)

enter image description here

[options]

"[options]" - это ярлык, который позволяет избежать перечисления всех опций (из списка опций с описаниями) в шаблоне. Например:

enter image description here

Эквивалентно:

enter image description here

Это может быть полезно, если у вас много вариантов, и все они применимы к одному из шаблонов. Кроме того, если у вас есть как короткие, так и длинные версии опций (указанные в описании опций), вы можете любую из них использовать в шаблоне:

enter image description here

Более подробная информация о том, как делать описания опций, будет приведена ниже.

[--]

В тех случаях когда не является частью опции, двойное тире "--" часто используется по соглашению для разделения опций и позиционных аргументов, чтобы обрабатывать случаи, когда, например, имена файлов могут быть ошибочно приняты за опции. Чтобы поддержать это соглашение, добавьте "[--]" в свои шаблоны перед позиционными аргументами.

enter image description here

Помимо этого особого значения, "--" - это просто обычная команда, поэтому вы можете применить любые ранее описанные операции, например, сделать ее необходимой (отбросив скобки "[ ]")

[-]

Одиночное тире "-", в тех случаях когда не является частью опции, часто используется по соглашению для обозначения того, что программа должна обрабатывать stdin, а не файл. Если вы хотите следовать этому соглашению, добавьте "[-]" в свой шаблон. "-" сама по себе это просто обычная команда, которую можно использовать с любым смыслом.

Описание опций

Описания опций состоят из списка опций, которые вы помещаете под своими шаблонами использования (usage patterns). Необязательно указывать их, если нет двусмысленности в шаблонах использования (описанных в разделе --option выше).

Описание опции позволяет указать:

  • что некоторые короткие и длинные варианты опций являются синонимами,
  • что у опции есть аргумент,
  • значение по умолчанию для аргумента опции.

Правила следующие:

Каждая строка, которая начинается с "-" или "--" (не считая пробелов), рассматривается как описание опции, например:

enter image description here

Чтобы указать, что параметр (опция) имеет аргумент, поместите слово, описывающее этот аргумент, после пробела (или знака равно "=") как показано ниже. Для обозначения аргументов опций используйте либо <угловые скобки>, либо соглашение верхнего регистра (UPPER-CASE). Вы можете использовать запятую, если хотите разделить параметры. В приведенном ниже примере обе строки допустимы, однако рекомендуется придерживаться одного стиля.

enter image description here

Используйте два пробела для отделения параметров от неформального описания.

enter image description here

Если вы хотите установить значение по умолчанию для параметра с аргументом, поместите его в описание параметра в форме [default: <the-default-value>].

enter image description here

Поупражняйтесь с docopt в браузере http://try.docopt.org/

Реализации

docopt доступен на многих языках программирования. Официальные реализации перечислены в аккаунте организации docopt на GitHub.

Адаптированный перевод материала с сайта docopt.org, подготовил Константин Жаринов.

Аватар пользователя Konstantin Zharinov
Konstantin Zharinov 01 октября 2019
Рекомендуемые программы

С нуля до разработчика. Возвращаем деньги, если не удалось найти работу.

Иконка программы Фронтенд-разработчик
Профессия
Разработка фронтенд-компонентов веб-приложений
30 июня 10 месяцев
Иконка программы Python-разработчик
Профессия
Разработка веб-приложений на Django
30 июня 10 месяцев
Иконка программы PHP-разработчик
Профессия
Разработка веб-приложений на Laravel
30 июня 10 месяцев
Иконка программы Node.js-разработчик
Профессия
Разработка бэкенд-компонентов веб-приложений
30 июня 10 месяцев
Иконка программы Fullstack-разработчик
Профессия
Новый
Разработка фронтенд и бэкенд компонентов веб-приложений
30 июня 16 месяцев
Иконка программы Верстальщик
Профессия
Вёрстка с использованием последних стандартов CSS
в любое время 5 месяцев
Иконка программы Java-разработчик
Профессия
Разработка приложений на языке Java
30 июня 10 месяцев
Иконка программы Разработчик на Ruby on Rails
Профессия
Создает веб-приложения со скоростью света
30 июня 5 месяцев