Rivalry2

HTML Diff

0 added 0 removed

Original 2026-01-01

Modified 2026-02-26

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

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

3 <ul><li>определить интерфейс приложения командной строки</li>

4 <li>автоматически генерировать парсер для него</li>

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

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

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

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

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

10 <h2>Содержание</h2>

11 <ul><li><a>Шаблоны использования</a></li>

12 <li><a><argument> ARGUMENT</a></li>

13 <li><a>-o --option</a></li>

14 <li><a>command</a></li>

15 <li><a>[optional elements]</a></li>

16 <li><a>(required elements)</a></li>

17 <li><a>element|another</a></li>

18 <li><a>element...</a></li>

19 <li><a>[options]</a></li>

20 <li><a>[--]</a></li>

21 <li><a>[-]</a></li>

22 <li><a>Описание опций</a></li>

23 <li><a>Реализации</a></li>

24 </ul><h2>Шаблоны использования</h2>

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

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

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

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

29 <h2><argument> ARGUMENT</h2>

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

31 <h2>-o --option</h2>

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

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

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

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

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

37 <h2>command</h2>

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

39 <h2>[optional elements]</h2>

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

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

42 <h2>(required elements)</h2>

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

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

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

46 <h2>element|another</h2>

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

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

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

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

51 <h2>element...</h2>

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

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

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

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

56 <h2>[options]</h2>

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

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

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

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

61 <h2>[--]</h2>

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

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

64 <h2>[-]</h2>

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

66 <h2>Описание опций</h2>

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

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

69 <ul><li>что некоторые короткие и длинные варианты опций являются синонимами,</li>

70 <li>что у опции есть аргумент,</li>

71 <li>значение по умолчанию для аргумента опции.</li>

72 </ul>Правила следующие:

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

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

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

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

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

78 <h2>Реализации</h2>

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

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