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

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

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

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

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

Пример описывает интерфейс исполняемого файла 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: интерпретируется как имя программы.

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

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

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

<argument> ARGUMENT

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

-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]

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

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

(required elements)

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

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

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

element|another

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

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

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

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

element...

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

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

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

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

[options]

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

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

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

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

[--]

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

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

[-]

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

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

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

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

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

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

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

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

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

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

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

Реализации

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

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