docopt详解

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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:”后出现的第一个单词被解释为程序的名字. 下面是一个最简单的示例,该示例没有任何命令行参数

1
#### Usage: my_program

程序可以使用用于描述模式的各种元素列出几个模式:
1
2
3
4
5
6
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) 必要元素

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

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

另一个用例是当您需要指定如果存在一个元素,则需要另外一个元素:
1
Usage: my_program [(<one-argument> <another-argument>)]

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

element|another

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

1
Usage: my_program go (--up | --down | --left | --right)

当需要相互排斥的情况之一时,使用括号“()”对元素进行分组. 当不需要相互排斥的情况时,使用括号“[]”分组元素:

Note, that specifying several patterns works exactly like pipe “|”, that is:

1
2
Usage: my_program run [--fast]
my_program jump [--high]

等价于
1
Usage: my_program (run [--fast] | jump [--high])

element…

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

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

您可以灵活地指定所需的参数数. 以下是需要零个或多个参数的3种(冗余)方法:
1
2
3
Usage: my_program [<file>...]
my_program [<file>]...
my_program [<file> [<file> ...]]

一个或多个参数

1
Usage: my_program <file>...

两个或多个参数
1
Usage: my_program <file> <file>...

[options]

“[options]”是一种快捷方式,可以避免在模式中列出所有选项(带有说明的选项列表). 例如:

1
2
3
4
5
Usage: my_program [options] <path>

--all List everything.
--long Long output.
--human-readable Display in human-readable format.

等价于
1
2
3
4
5
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:

1
2
3
4
5
Usage: my_program [-alh] <path>

-a, --all List everything.
-l, --long Long output.
-h, --human-readable Display in human-readable format.

[–]

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

1
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:
以“ - ”或“ – ”(不包括空格)开头的每一行都被视为一个选项描述,例如:

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

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

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

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

1
2
3
4
5
6
--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:].
1
2
3
--coefficient=K  The K coefficient [default: 2.95]
--output=FILE Output file [default: test.txt]
--directory=DIR Some directory [default: ./]

Powered by Hexo and Hexo-theme-hiker

Copyright © 2013 - 2022 Fan() All Rights Reserved.

访客数 : | 访问量 :