命令行程序接口描述语言[译]
docopt
Command-line interface description language
命令行程序接口描述语言
docopt helps you:
define interface for your command-line app, and
定义命令行程序接口
automatically generate parser for it.
自动为接口创建解析器
docopt is based on conventions that are used for decades in help messages and man pages for program interface description. Interface description in docopt is such a help message, but formalized. Here is an example:
docopt 是一种有特定格式的帮助信息，用于描述命令行接口，基于几十年来命令行应用程序的帮助信息和使用手册的对程序接口描述的惯用格式开发。下面是一个示例：
Naval Fate. Usage: naval_fate ship new <name>... naval_fate ship <name> move <x> <y> [--speed=<kn>] naval_fate ship shoot <x> <y> naval_fate mine (set|remove) <x> <y> [--moored|--drifting] naval_fate -h | --help naval_fate --version Options: -h --help Show this screen. --version Show version. --speed=<kn> Speed in knots [default: 10]. --moored Moored (anchored) mine. --drifting Drifting mine.
The example describes interface of executable naval_fate, which can be invoked with different combinations of commands (ship, new, move, etc.), options (-h, --help, --speed=<kn>, etc.) and positional arguments (<name>, <x>, <y>).
该示例描述了可执行程序naval_fate的接口，它可以调用不同的组合命令（ship, new, move等），选项（-h, --help, --speed=<kn>等），还有占位参数（<name>, <x>, <y>）。
Example uses brackets "[ ]", parens "( )", pipes "|" and ellipsis "..." to describe optional, required, mutually exclusive, and repeating elements. Together, these elements form valid usage patterns, each starting with program's name naval_fate.
示例使用方括号 "[ ]"、括号"( )"、竖线 "|"以及省略号"..."来描述可选、必要、相互排斥以及重复元素。这些元素构成了合法的使用模式，每个模式以程序名称naval_fate开头。
Below the usage patterns, there is a list of options with descriptions. They describe whether an option has short/long forms (-h, --help), whether an option has an argument (--speed=<kn>), and whether that argument has a default value ([default: 10]).
在使用模式的下面，是一列选项描述。描述了选项是否有长、短两种形式（-h, --help），选择是否有参数(--speed=<kn>)以及参数是否有默认值 ([default: 10])。
docopt implementation will extract all that information and generate a command-line arguments parser, with text of the example above being the help message, which is shown to a user when the program is invoked with-h or --help options.
docopt的会提取所有信息并创建一个命令行参数解析器，把上面的描述信息作为程序的帮助消息，在用户使用-h或--help时回显给客户。
Usage patterns 使用模式
Text occuring between keyword usage: (case-insensitive) and a visibly empty line is interpreted as list of usage patterns. First word after usage: is interpreted as program's name. Here is a minimum example for program that takes no command-line arguments:
关键词 usage:（大小写都可以）和一个明显的空行之间的所有文本会被当作使用模式解析。usage:之后的第一个词会被解析为程序名。以下是一个最小的示例，该程序不接受任何参数：
Usage: my_program
Program can have several patterns listed with various elements used to describe the pattern:
程序可以有多个使用模式，每个使用模式可以用多个元素来描述：
Usage: my_program command --option <argument> my_program [<optional-argument>] my_program --another-option=<with-argument> my_program (--either-that-option | <or-this-argument>) my_program <repeating-argument> <repeating-argument>...
Each of the elements and constructs is described below. We will use the word "word" to describe a sequence of characters delimited by either whitespace, one of "[]()|" characters, or "...".
元素和结构的描述如下。在接下来的描述中“词”这个词代表空白[]()|之间的所有字符，或者代表“...”。
<argument> ARGUMENT 占位参数
Words starting with "<", ending with ">" or upper-case words are interpreted as positional arguments.
被"<"、">"包围的词或者全大写的词表示占位参数。
Usage: my_program <host> <port>
-o --option 选项
Words starting with one or two dashes (with exception of "-", "--" by themselves) are interpreted as short (one-letter) or long options, respectively.
以"-"或"--"开头的词分别表示短选项（一个字符的）或长选项：
Short options can be "stacked" meaning that
-abcis equivalent to-a -b -c.短选项可以被压缩，-abc等价于 -a -b -c。
Long options can have arguments specified after space or equal "
=" sign:长选项可以有参数，参数与选项之间可以是空格也可以是等号“=”：
--input=ARG等价于--input ARG.Short options can have arguments specified after optional space:
短选项也可以有参数，参数与选项之间可以有空格也可以没有：
-f FILE 等价于-fFILE.
Note, writing --input ARG (opposed to --input=ARG) is ambiguous, meaning it is not possible to tell whether ARG is option's argument or positional argument. In usage patterns this will be interpreted as option with argument only if option's description (covered below) for that option is provided. Otherwise it will be interpreted as separate option and positional argument.
注意：写成 --input ARG（相对于 --input=ARG）会有歧义，前者不能说明ARG是选项的参数还是一个占位参数。在使用模式中会把ARG解析为一个占位参数，除非选项描述中有该选项的描述，那么在使用模式中ARG会被解析成该选项的参数。
Same ambiguity is with -f FILE and -fFILE notation. Although in the latter case it is not possible to tell whether it is a number of stacked short options, or an option with argument. These notations will be interpreted as option with argument only if option's description is provided.
同样的歧义还发生在短命令上，如-f FILE 和 -fFILE，在后一种定法中，FILE即可以理解为选项的一个参数，也可以理解为多个选项的压缩。所以在docopt中，这种写法会被解析为多个选项的压缩，除非在选项描述中有特别说明。
command 命令
All other words that do not follow the above conventions of --options or<arguments> are interpreted as (sub)commands.
所有其它不是--options也不是<arguments>的词表示（子）命令。
[optional elements] 可选元素
Elements (options, arguments, commands) enclosed with square brackets "[ ]" are marked to be optional. It does not matter if elements are enclosed in same or different brackets, for example:
包含在“[]”内的元素（选项、参数、命令）表示是可选的。所有元素写在不在一个方括号内都是一样的。
Usage: my_program [command --option <argument>]
等价于：
Usage: my_program [command] [--option] [<argument>]
(required elements) 必要元素
All elements are required by default, if not included in brackets "[ ]". However, sometimes it is necessary to mark elements as required explicitly with parens "( )". For example, when you need to group mutually-exclusive elements (see next section):
不在方括号"[]"内的所有元素默认都是必须要元素。但有时需要使用圆括号“（）”来表示互斥元素（请看下节）：
Usage: my_program (--either-this <and-that> | <or-this>)
Another use-case, is when you need to specify that if one element is present, then another one is required, which you can achieve as:
另一种情况，可以用如下方式表示如果一个元素出现，另一个元素必须出现：
Usage: my_program [(<one-argument> <another-argument>)]
In this case, a valid program invocation could be with either no arguments, or with 2 arguments.
在上面的示例中，程序的正确调用方法是要么没有参数，要么有两个参数。
element|another
Mutually exclusive elements can be separated with pipe "|" as follows:
互斥的元素可以用竖线“|”分隔：
Usage: my_program go (--up | --down | --left | --right)
Use parens "( )" to group elements when one of the mutually exclusive cases is required. Use brackets "[ ]" to group elements when none of the mutually exclusive cases is required:
用圆括号“（）”包围互斥元素表示必须要一个，但只能要一个，即有且仅有一个。用方括号“[]”包围互斥元素表示可以不要，如果要，只能要一个，即至多一个：
Usage: my_program go [--up | --down | --left | --right]
Note, that specifying several patterns works exactly like pipe "|", that is:
注：定义多个使用模式等同于使用竖线“|”：
Usage: my_program run [--fast] my_program jump [--high]
等价于：
Usage: my_program (run [--fast] | jump [--high])
element...
Use ellipsis "..." to specify that argument (or group of arguments) to the left could be repeated one or more times:
置于元素右边的“...”表示元素或者参数组可以被重复一次或多次：
Usage: my_program open <file>... my_program move (<from> <to>)...
You can flexibly specify number of arguments that are required. Here are 3 (redundant) ways of requiring zero or more arguments:
还可以定义需要零个或多个参数，以下这些都表示需要零个或多个参数，很灵活：
Usage: my_program [<file>...] my_program [<file>]... my_program [<file> [<file> ...]]
一个或多个参数：
Usage: my_program <file>...
两个或多个参数：
Usage: my_program <file> <file>...
[options] 选项
"[options]" is a shortcut that allows to avoid listing all options (from list of options with descriptions) in a pattern. For example:
"[options]"这个特殊的词可以用来代表所有可用的选项，避免在使用模式中列出所有选项。如：
Usage: my_program [options] <path> --all List everything. --long Long output. --human-readable Display in human-readable format.
等价于：
Usage: my_program [--all --long --human-readable] <path> --all List everything. --long Long output. --human-readable Display in human-readable format.
This can be useful, if you have many options, and all of them are applicable to one of patterns. Alternatively, if you have both short and long versions of options (specified in option description part), you can list either of them in a pattern:
这在你有很多选项，这些选项可以用在一个模式中的时候很有用。另外，如果你有长选项和短选项，在模式中可以只列出一个。
Usage: my_program [-alh] <path> -a, --all List everything. -l, --long Long output. -h, --human-readable Display in human-readable format.
More details on how to write options' descriptions will follow below.
更多细节请看下面选项描述的格式。
[--]
Double dash "--", when not part of an option, is often used by convention to separate options and positional arguments, in order to handle cases when e.g. file names could be mistaken for options. In order to support this convention, add "[--]" into your patterns before positional arguments.
双短横线“--”，在不作为选项的一部分时，可以用来做选项与占位参数的分隔，如此一来可以消除一些歧义。如下面的<file>可能会被误以为是选项的参数，为了消除这种歧义，可以在占位参数前加上一个可选的"[--]"。
Usage: my_program [options] [--] <file>...
Apart from this special meaning, "--" is just a normal command, so you can apply any previously-described operations, for example, make it required (by dropping brackets "[ ]")
除这层意思外，“--”可以只是一个普通的命令，可以不要[]而让其变成必要项。
[-]
Single dash "-", when not part of an option, is often used by convention to signify that a program should process stdin, as opposed to a file. If you want to follow this convention add "[-]" to your pattern. "-" by itself is just a normal command, which you can use with any meaning.
“-”如果不做为选项的一部分，通常表示程序可以处理stdin。如果你想遵从这个习惯，可以使用[-]，除此之外，-就是一个普通命令，你可以做任意使用。
Option descriptions 选项描述格式
Option descriptions consist of a list of options that you put below your usage patterns. It is optional to specify them if there is no ambiguity in usage patterns (described in --option section above).
Option's description allows to specify:
选项描述由使用模式以下的一系列选项描述组成。可以用来消除上面提到的歧义问题。
选项描述可以定义：
that a short and a long options are synonymous,
长、短选项是同义词，
that an option has an argument,
不个选项是否有参数，
default value for option's argument.
选项参数的默认值。
The rules are as follows:
规则如下：
Every line that starts with "-" or "--" (not counting spaces) is treated as an option description, e.g.:
以“-”或“--”开头的行都会被当作一个选项描述，比如：
Options: --verbose # GOOD -o FILE # GOOD Other: --bad # BAD, line does not start with dash "-"
To specify that option has an argument, put a word describing that argument after space (or equals "=" sign) as shown below. Follow either <angular-brackets> or UPPER-CASE convention for options' arguments. You can use comma if you want to separate options. In the example below, both lines are valid, however you are recommended to stick to a single style.
如果要表示一个选项有一个参数，在其后面添加一个词，中间可以用空格或者等号，如下。可以用大写的词或者是包围在"<>"中的词。同义词选项之间可以用逗号分隔，也可以不用，你最好保持统一的风格。
-o FILE --output=FILE # without comma, with "=" sign -i <file>, --input <file> # with comma, without "=" sign
Use two spaces to separate options with their informal description.
用两个空格来分格选项和它的描述信息。
--verbose MORE text. # BAD, will be treated as if verbose # option had an argument MORE, so use # 2 spaces instead -q Quit. # GOOD -o FILE Output file. # GOOD --stdout Use stdout. # GOOD, 2 spaces
If you want to set a default value for an option with an argument, put it into the option's description, in form [default: <the-default-value>].
如果你想为一个选项设置一个默认值，请以[default:<值>]的格式写在描述信息中。
--coefficient=K The K coefficient [default: 2.95] --output=FILE Output file [default: test.txt] --directory=DIR Some directory [default: ./]
Try docopt in your browser
Implementations
docopt is available in numerous programming languages. Official implementations are listed at docopt organization on GitHub.