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.

该示例描述了可执行的naval_fate的界面，可以使用命令(ship，new，move等)的不同组合，选项(-h，–help，–speed = 等)和 位置参数(，，).

示例使用方括号“[]”，圆括号“()”，管道“|” 和省略号“…”来描述可选的，必需的，相互排斥的和重复的元素. 一起，这些元素形成有效的使用模式，每个都以程序的名称naval_fate开头.

Below the usage patterns，有一个包含说明的选项列表. 它们描述一个选项是否具有短/长形式(-h，–help)，选项是否具有参数(-speed = )，以及该参数是否具有默认值([default:10]).

Usage模式

在Usage:(不区分大小写) 关键字 间出现,并且显示的空了一行的部分 被解释为 usage pattern
在”Usage:”后出现的第一个单词被解释为程序的名字. 下面是一个最简单的示例,该示例没有任何命令行参数

####Usage: my_program

程序可以使用用于描述模式的各种元素列出几个模式:

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

ARGUMENT

以”<”开始,”>”结尾 和 大写字母的被解释为 位置参数

-o –option

以一个或两个破折号开头的单词(除了“ - ”，“ - ”之外)分别被解释为短(一个字母)或长选项.

• 短选项可以“堆叠”，这意味着-abc等同于-a -b -c.
• 长选项可以在空格或等于“=”之后指定参数: –input = ARG相当于 - 输入ARG
• 短选项可以在可选空格之后指定参数:-f FILE等效于-fFILE

注意，写入 –input(与–input = ARG相比)是容易产生歧义的，这意味着不可能知道ARG是选项的参数还是位置参数. 在Usage:中，只有在提供该选项的description(如下所述)时，这个选项才会被解释为参数选项. 否则它将被解释为一个选项和单独的位置参数.
同样,使用-f FILE和-fFILE也可能产生歧义,后者可能是一组断选项的堆叠(就像之前的例子-abc是-a -b -c的堆叠),或者是一个带参数得选项.只有在提供了该选项的description时，这些符号才会被被解释为一个带参数的选项.

command

所有其他不符合–options或的约定的单词都被解释为(sub)command.

[optional elements] 可选元素

被方括号”[]”包围起来的元素(options, arguments, commands)被标记为可选项.
Usage: my_program [command --option <argument>]
等价于
Usage: my_program [command] [--option] [<argument>]

(required elements) 必要元素

默认情况下需要所有元素，如果不包括在括号“[]”中. 但是，有时候，必须使用“”()“来明确标记元素. 例如，当您需要组合相互排斥的元素(请参阅下一节):

Usage: my_program (--either-this <and-that> | <or-this>)

另一个用例是当您需要指定如果存在一个元素，则需要另外一个元素:

Usage: my_program [(<one-argument> <another-argument>)]

在这种情况下，有效的程序调用可以是无参数，也可以是2个参数.

element|another

相互排斥的元素可以用管道“|”分隔开 如下:

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…

使用省略号“…”来指定左侧的参数(或参数组)可以重复一次或多次:

Usage: my_program open <file>...
       my_program move (<from> <to>)...

您可以灵活地指定所需的参数数. 以下是需要零个或多个参数的3种(冗余)方法:

Usage: my_program [<file>...]
       my_program [<file>]...
       my_program [<file> [<file> ...]]

一个或多个参数

Usage: my_program <file>...

两个或多个参数

Usage: my_program <file> <file>...

[options]

“[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.

如果您有很多选项，并且所有选项都适用于其中一种模式，这将非常有用. 或者，如果您有短版本和长版本的选项(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.

[–]

双重破折号“ - ”，当不是选项的一部分时，通常用作分隔选项和位置参数的约定，以便处理例如文件名可能被误认为选项的情况. 为了支持这个约定，在位置参数之前添加“[ - ]”到你的模式中.

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 “[ ]”)

[-]

一个单独的破折号“ - ”，当不是选项的一部分时，常常被用来表示一个程序应该处理stdin而不是一个文件. 如果你想遵循这个惯例，在你的模式中添加“[ - ]”. “ - ”本身只是一个正常的命令，您可以使用任何意义.

Option descriptions

选项描述包含您放在使用模式下的选项列表.即使在usage pattern中没有产生歧义也可以指定他们
选项的描述允许指定:
- 互为同义词的短选项和长选项
- 带参数得选项
- 选项参数得默认值

The rules are as follows:
以“ - ”或“ – ”(不包括空格)开头的每一行都被视为一个选项描述，例如:

Options:
  --verbose   # GOOD
  -o FILE     # GOOD
Other: --bad  # BAD, line does not start with dash "-" 错误的示例,不是以'-'开头的行

要指定一个选项有一个参数，请在空格(或等于“=”符号)后面放置一个描述该参数的单词，如下所示. 遵循或UPPER-CASE约定的选项参数. 如果要分离选项，可以使用逗号. 在下面的示例中，两行均有效，但建议使用单一样式.

-o FILE --output=FILE       # without comma, with "=" sign
-i <file>, --input <file>   # with comma, without "=" sign

使用两个空格分隔选项和其描述信息

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

如果要为参数的选项设置默认值，请将其放入选项的描述中，格式为[default:].

--coefficient=K  The K coefficient [default: 2.95]
--output=FILE    Output file [default: test.txt]
--directory=DIR  Some directory [default: ./]