pythonic参数分析器,它会让你微笑
docopt_plus的Python项目详细描述
fork information
==
``docopt_plus``是'docopt<;https://github.com/docopt/docopt>;``的一个fork。
这个fork添加了一些不是gnu/posix标准的特性,
可能没有被广泛认可。
/>
-模式组
请参见原始的"docopt<;https://github.com/docopt/docopt>;""项目
以获得更稳定、更受支持的包。如果不需要"docopt_plus"添加到docopt的任何功能,我建议您使用原始项目。
但是,我没有承诺。
因此,当前的``docopt_plus`
版本是``0.6.3-alpha-1``
l docopt_plus
用法
----
::
``除此之外,python导入应该从``from docopt import docopt``
更改为``from docopt_plus import docopt```。
``docopt``创建*beautiful*命令行接口
=t**:`pycon uk 2012:create*beautiful*
使用python命令行界面<;http://youtu.be/pxhcpjk5cmc>;`
0.6.1版中的新功能:
-修复问题` 85<;https://github.com/docopt/docopt/issues/85>;`
这导致对` `[选项]` `短的处理不当剪切
如果它多次出现。
0.6.0版中的新功能:
-新参数"options\u first",不允许插入选项
和参数。如果将"options_first=true"提供给
``docopt``,则它将在第一个位置参数之后将所有参数解释为位置参数。
-如果带参数的选项可以重复,则其默认值
将解释为空格分隔列表。例如,with
``[默认值:./here./there]``将被解释为
``['./here','./there']```.
中断更改:
`[选项]``快捷方式的含义略有更改。以前它的意思是"任何已知的选项"。现在它的意思是*"任何不在
使用模式中的选项"*。这避免了在无意中重复选项时出现的情况。
-``argv``默认为``none`,而不是``sys.argv[1:```.
这允许``docopt``在导入期间始终使用*latest*``sys.argv`,
not``sys.argv`.
"optparse"和"argparse"如何根据代码生成帮助消息真是太棒了?!
*不!*你知道什么很棒吗?当选项解析器*根据您自己编写的漂亮的帮助消息生成时!
这样,您就不需要编写这个愚蠢的可重复解析器代码,
而只需要编写帮助消息--*您想要的方式*
**docopt**帮助您创建最漂亮的命令行界面
*很容易*:
……代码::python
"naval fate."
用法:
naval fate.py ship new<;name>;…
naval fate.py ship<;name>;move<;x>;<;y>;[--speed=<;kn>;]
naval fate.py ship shoot<;x>;<;y>;
naval fate.py mine(set remove)<;x>;<;y>;[--系泊--漂流]
海上脂肪e.py(-h--help)
naval_fate.py--version
选项:
-h--帮助显示此屏幕。
--version显示version。
--speed=<;kn>;speed in knots[默认值:10]。
--系泊(锚定)矿井。
--漂移最小值e.
"
从docopt导入docopt
选项解析器是根据传递给"docopt"函数的
上面的docstring生成的。`` docopt``解析用法
模式(``"用法:…"```)和选项描述(以短划线"``-``"开头的行),并确保程序调用与
用法模式匹配;它基于
解析选项、参数和命令。基本思想是,*一个好的帮助消息包含所有必要的
信息,以便生成解析器*
另外,`pep 257<;http://www.python.org/dev/peps/pep-0257/>;``建议
将帮助消息放入模块docstrings。
t;http://pip installer.org>;``或者简单安装::
=======
您可以使用以下命令运行单元测试:
===
……代码::来自docopt import docopt的python
…代码::python
docopt(doc,argv=none,help=true,version=none,options-first=false)
``docopt``接受1个必需参数和4个可选参数:
-``doc``可以是一个模块doc string(``````doc``)或其他包含**帮助消息**的
字符串,将对其进行解析创建选项解析器。关于如何编写这样的
帮助消息的简单规则将在下一节中给出。下面是这样一个字符串的快速示例:
…代码::python
"用法:my_program.py[-h s o file][--quiet--verbose][input…]
-h--帮助显示此项
-s--排序输出
-o文件指定输出文件[默认值:./test.txt]
--安静打印较少文本
--详细打印更多text
"
-``argv``是一个可选的参数向量;默认情况下,``docopt``使用
传递给程序的参数向量(``sys.argv[1:```).
或者,您可以提供一个字符串列表,如`['--verbose'、
'-o'、`hai.txt']```.
-``help``,由default``true`,指定当遇到`-h``或`--help``选项时,解析器是否应
自动打印帮助消息(作为``doc```提供)和
终止
(选项应存在于使用模式中,更多信息见下文)。如果
要手动处理`-h``或`--help``选项(与其他
选项一样),请设置``help=false``。
-``version``默认情况下,``none``是一个可选参数,它指定程序的版本。如果提供,那么(假设用法模式中提到了
`--version``选项)当解析器
遇到``--version``选项时,它将打印提供的
版本并终止。`` version``可以是任何可打印的对象,
,但很可能是一个字符串,例如``"2.1.0rc1``.
注意,当``docopt``设置为自动处理`-h`、
`--help`和``--version``选项时,您仍然需要在使用模式中提到它们才能工作。同时,让您的用户
了解他们。
-``选项优先``,默认情况下为'false`。如果设置为"true",则不允许混合选项和位置参数。即,在第一个
位置参数之后,即使看起来像是选择。这可以用于与posix的严格兼容,或者如果您想将参数分派给其他程序,
**返回**值是一个简单的字典,其中包含选项、参数和命令作为键,其拼写与帮助消息中的完全相同。long
选项的版本优先。例如,如果调用
顶部示例::
naval_fate.py ship guardian move 100 150--speed=15
,返回字典将是:
。代码::python
{--漂移:false,'mine':false,
'--help':false,'move':true,
'--moored':false,'new':false,
'--speed':'15','remove':false,
'--version':false,'set':false,
'<;name>;':['guardian','ship':true,
'<;x>;':'100,'shoot':false,
'<;y>;':'150'}
…]
-选项说明,例如::
-h--帮助显示此项
-s--排序输出
-o文件指定输出文件[默认值:./test.txt]
--安静打印较少文本
--详细打印更多文本
-组说明(可选,``doc选项加``only),例如::
group 1:
<;arg1>;--opt1[--opt2=arg2]
group2:command2 command3
>其格式如下所述;其他文本将被忽略。
usage pattern format
----
**usage pattern**是``doc``以
``用法:```(不区分大小写*)开头,以*可见*空行结尾。
最小示例:
代码::python
"用法:my_program.py
"
``用法:`'后面的第一个字被解释为程序的名称。
您可以多次指定程序的名称来表示多个
独占模式:
。代码::python
"用法:my_program.py file
my_program.py count file
>每个模式可以由以下元素组成:
-**<;arguments>;**,**arguments**。参数指定为
大写单词,例如"my_program.py content-path"或由尖括号括起的单词
:"`my_program.py<;content path>;"`"。
-**--选项**。选项是以破折号(`-``)开头的单词,例如
`--output``,`-o``。您可以"堆叠"一个字母中的几个选项,例如`-o i v``与`-o-i-v``相同。
选项可以有参数,例如`--input=file``或`-i file``或
甚至是`-ifile``。但是,如果希望选项具有参数、默认值或指定同义的短/长版本选项(请参见关于选项描述的下一节),请指定选项
描述,这一点很重要。
-**命令**是不*遵循描述的单词上述
`--options``或`<;arguments>;``或`` arguments``的约定,
加上两个特殊命令:破折号"`-``"和双破折号"`--`"
(见下文)。
-**-组-**。组是以破折号(`-``)开头和结尾的单词,例如
``-my-u group-`。在使用模式中定义的每个组都必须在其自己的部分中进行描述。请参阅下面的"组描述格式"。
使用以下结构指定模式:
-**[**(括号)**可选**元素。例如:``my_program.py
[-hvqo file]``
-**()**(parens)**必需的**元素。所有*未*
放入**[]**的元素也都是必需的,例如:``my_program.py
--path=<;path>;<;file>;…``与``my_program.py
(-path=<;path>;<;file>;…``相同。(注意,"必需选项"可能不是您的用户)。如果需要互斥元素之一,请使用**(
)**将它们分组:
``my_program.py(--顺时针--逆时针)time``。如果不需要互斥元素,则使用**[]**将其分组:``my_program.py[--left--right]``.
-**…**(省略号)**一个或多个**元素。要指定
可以接受任意数量的重复元素,请使用省略号(``…`),例如``my_program.py file…``表示接受一个或多个``file``。如果要接受零个或多个
元素,请使用方括号,例如:``my_program.py[file…]```。省略号
用作左侧表达式上的一元运算符。
-**[选项]**(区分大小写)任何选项的快捷方式。如果要指定使用模式可以与下面在选项描述中定义的任何选项一起提供,并且不想在使用模式中枚举它们,则可以使用它。按照惯例,双破折号"`--`"用于分隔可能被误认为选项的
位置参数。为了支持此约定,请在您的使用模式中添加"`[--]``"。
-"`[-]``"。按照惯例,单破折号"`-`"表示使用
``stdin``而不是文件。要支持此功能,请将"``[-]``"
添加到您的使用模式中。``-``"充当普通命令。
也就是说,如果程序作为"我的程序"调用,那么
``args['-v']``将是``2```。同样适用于命令。
=./这里
--path=./那里``返回的dict将包含``args['<;file>;']===
['file1','file2']``和``args['--path']==['./这里,'./那里']``.
option descriptions format
----
**option descriptions**包含一个选项列表,您将这些选项放在使用模式下面。
必须列出选项描述才能指定:
-同义的短选项和长选项,
-如果选项有参数,
-如果选项的参数有默认值,
规则如下:
-以`-``或`--```开头的``doc`中的每一行(不包括
空格)都被视为选项des描述,例如::
options:
--verbose\good
-o file\good
other:--bad\bad,line不以破折号开头"-"
-若要指定该选项有参数,请在空格(或等于"``=```"符号)后添加一个描述该参数的单词,如下所示。对于选项"
参数,请遵循
角括号或大写约定。如果要分隔选项,可以使用逗号。在
下面的示例中,这两行都是有效的,但是建议您使用
以保持单一样式。:
-o file--output=file不带逗号,带"="符号
-i<;file>;,--input<;file>;带逗号,不带"="sing
-使用两个空格将选项与其非正式描述分开::
--详细说明更多文本。#不正确,将被视为verbose选项有
参数"more",因此使用2个空格代替
-q quit。#良好的
-o文件输出文件。#好的
--标准输出使用标准输出。#很好,两个空格
-如果要为带参数的选项设置默认值,请将其放入选项根据说明,格式为``[默认值:
<;我的默认值>;``::
--coefficient=k k系数[默认值:2.95]
--output=file output file[默认值:test.txt]
--directory=dir some directory[默认值:./]
-如果该选项不可重复,则值为"`[默认值:…]``
中的e将被解释为字符串。如果*是*可重复的,则将
拆分为空白列表::
用法:my_program.py[--repeatable=<;arg>;--repeatable=<;arg>;]
[--另一个repeatable=<;arg>;]…
[--not repeatable=<;arg>;]
#将是['./这里,'./那里]
--repeatable=<;arg>;[默认值:./这里/那里]
t;[默认值:./here./there]
group descriptions format(``dopcopt_plus`` only)
——在引擎盖下,docopt将用它们各自的模式替换组元素(例如
```-my_group-````)。
**组描述**必须定义参数、选项和
命令元素的模式。不允许具有组的组元素。
::
我的组:--一个"u"选项(-另一个"u"选项命令)[-o<;arg>;]
组名的大小写不相关。在查找组描述时,
组元素中的下划线(`````)将转换为空格。
可以在多行上跨越模式定义。这个
定义相当于前面的示例::
我的组:
--一个"u"选项
(另一个"u"选项命令)
[-o<;arg>;]
arenthesis等
这些都是使用组的有效使用模式:
usage:prog[-v]-input-[-out_file-(out_db-[-create])]
input:<;in_file>;
out file:<;out_file>;
out db:
<;db_name>;
[-u usernAME[-p password]]
[<;host>;]
选项:
…
缩进在所有级别上都是完全可选的,与查找定义无关。但是,它确实使用法说明更易于阅读,因此受到鼓励。
ine,
至少间隔两个空格。与选项不同,不支持在单独的行上添加注释::
out db:
<;db懔name>;database name懔good,2个空格
[-u username[-p password]
database credentials懔bad,将被误认为模式!
[<;host>;]本地或远程主机名不正确,只有1个空间!
还必须描述在使用模式中定义的每个组(例如``-我的组-```')。
r/>
我们有一个广泛的"示例"列表
<;https://github.com/docopt/docopt/tree/master/examples>;`,涵盖了**docopt**功能的各个方面。尝试一下,如果有疑问,请阅读
源代码。
多级帮助(每个子命令都有单独的帮助屏幕),
要与不使用**docopt**的现有脚本交互,或者
要构建下一个"git",您将需要新的"options\u first"参数(如上文api部分所述)。为了让您快速开始
,我们实现了git命令行界面的一个子集作为示例:
`examples/git
<;https://github.com/docopt/docopt/tree/master/examples/git>;`
元素进入
命令行界面。但是它不会验证输入数据。
另一方面,有些库如"python schema
<;https://github.com/halst/schema>;``使验证数据变得轻而易举。看一看"validation\u example.py
<;https://github.com/docopt/docopt/tree/master/examples/validation\u example.py>;`\u
,它使用**schema**验证数据并向
用户报告错误。
配置文件用于提供默认值,这些值可以被命令行参数覆盖。由于**docopt**
返回一个简单的字典,因此很容易与以json、yaml或ini格式编写的配置文件集成。
`config_file_example.py<;examples/config_file_example.py>;```提供了
和如何将**docopt**与json或ini配置文件一起使用的示例。
开发
==
您还可以直接将一行代码放到
<;vladimir@keleshev.com>;
所有其他语言的官方docopt端口都可以在github上的"docopt organization page"lt;http://github.com/docopt>;下找到。
我们鼓励您使用python版本作为
参考实现。与语言无关的测试套件与"python实现"捆绑在一起,lt;http://github.com/docopt/docopt>;` `.
移植讨论位于"问题"页
<;http://github.com/docopt/docopt/issues>;` ` `.
==
**docopt**遵循"语义版本控制"<;http://semver.org>;`。带有稳定api的第一个版本将是1.0.0(很快)。在此之前,我们鼓励您在依赖项
工具中明确指定版本,例如::
-0.6.1错误修复版本。
-0.6.0``options_first``参数。
**中断更改**:更正了````[options]``含义。
``argv``defa"none"的结果。
-0.5.0重复的选项/命令被计数或累积到
列表中。
-0.4.2错误修复版本。
-0.4.0选项描述变为可选,
支持"``--`"和"``-```"命令。
-0.3.0支持(sub)命令,如"git remote add"。
introduce```[options]``任何选项的快捷方式。
**中断更改**:``docopt``返回字典。
-0.2.0使用模式匹配。基于
使用模式的位置参数解析。
**中断更改**:``docopt``返回命名空间(用于参数),
不列出。使用模式已正式化。
-0.1.0初始版本。仅分析选项(基于选项
描述)。
==
``docopt_plus``是'docopt<;https://github.com/docopt/docopt>;``的一个fork。
这个fork添加了一些不是gnu/posix标准的特性,
可能没有被广泛认可。
/>
-模式组
请参见原始的"docopt<;https://github.com/docopt/docopt>;""项目
以获得更稳定、更受支持的包。如果不需要"docopt_plus"添加到docopt的任何功能,我建议您使用原始项目。
但是,我没有承诺。
因此,当前的``docopt_plus`
版本是``0.6.3-alpha-1``
l docopt_plus
用法
----
::
``除此之外,python导入应该从``from docopt import docopt``
更改为``from docopt_plus import docopt```。
``docopt``创建*beautiful*命令行接口
=t**:`pycon uk 2012:create*beautiful*
使用python命令行界面<;http://youtu.be/pxhcpjk5cmc>;`
0.6.1版中的新功能:
-修复问题` 85<;https://github.com/docopt/docopt/issues/85>;`
这导致对` `[选项]` `短的处理不当剪切
如果它多次出现。
0.6.0版中的新功能:
-新参数"options\u first",不允许插入选项
和参数。如果将"options_first=true"提供给
``docopt``,则它将在第一个位置参数之后将所有参数解释为位置参数。
-如果带参数的选项可以重复,则其默认值
将解释为空格分隔列表。例如,with
``[默认值:./here./there]``将被解释为
``['./here','./there']```.
中断更改:
`[选项]``快捷方式的含义略有更改。以前它的意思是"任何已知的选项"。现在它的意思是*"任何不在
使用模式中的选项"*。这避免了在无意中重复选项时出现的情况。
-``argv``默认为``none`,而不是``sys.argv[1:```.
这允许``docopt``在导入期间始终使用*latest*``sys.argv`,
not``sys.argv`.
"optparse"和"argparse"如何根据代码生成帮助消息真是太棒了?!
*不!*你知道什么很棒吗?当选项解析器*根据您自己编写的漂亮的帮助消息生成时!
这样,您就不需要编写这个愚蠢的可重复解析器代码,
而只需要编写帮助消息--*您想要的方式*
**docopt**帮助您创建最漂亮的命令行界面
*很容易*:
……代码::python
"naval fate."
用法:
naval fate.py ship new<;name>;…
naval fate.py ship<;name>;move<;x>;<;y>;[--speed=<;kn>;]
naval fate.py ship shoot<;x>;<;y>;
naval fate.py mine(set remove)<;x>;<;y>;[--系泊--漂流]
海上脂肪e.py(-h--help)
naval_fate.py--version
选项:
-h--帮助显示此屏幕。
--version显示version。
--speed=<;kn>;speed in knots[默认值:10]。
--系泊(锚定)矿井。
--漂移最小值e.
"
从docopt导入docopt
选项解析器是根据传递给"docopt"函数的
上面的docstring生成的。`` docopt``解析用法
模式(``"用法:…"```)和选项描述(以短划线"``-``"开头的行),并确保程序调用与
用法模式匹配;它基于
解析选项、参数和命令。基本思想是,*一个好的帮助消息包含所有必要的
信息,以便生成解析器*
另外,`pep 257<;http://www.python.org/dev/peps/pep-0257/>;``建议
将帮助消息放入模块docstrings。
t;http://pip installer.org>;``或者简单安装::
=======
您可以使用以下命令运行单元测试:
……代码::来自docopt import docopt的python
…代码::python
docopt(doc,argv=none,help=true,version=none,options-first=false)
``docopt``接受1个必需参数和4个可选参数:
-``doc``可以是一个模块doc string(``````doc``)或其他包含**帮助消息**的
字符串,将对其进行解析创建选项解析器。关于如何编写这样的
帮助消息的简单规则将在下一节中给出。下面是这样一个字符串的快速示例:
…代码::python
"用法:my_program.py[-h s o file][--quiet--verbose][input…]
-h--帮助显示此项
-s--排序输出
-o文件指定输出文件[默认值:./test.txt]
--安静打印较少文本
--详细打印更多text
"
-``argv``是一个可选的参数向量;默认情况下,``docopt``使用
传递给程序的参数向量(``sys.argv[1:```).
或者,您可以提供一个字符串列表,如`['--verbose'、
'-o'、`hai.txt']```.
-``help``,由default``true`,指定当遇到`-h``或`--help``选项时,解析器是否应
自动打印帮助消息(作为``doc```提供)和
终止
(选项应存在于使用模式中,更多信息见下文)。如果
要手动处理`-h``或`--help``选项(与其他
选项一样),请设置``help=false``。
-``version``默认情况下,``none``是一个可选参数,它指定程序的版本。如果提供,那么(假设用法模式中提到了
`--version``选项)当解析器
遇到``--version``选项时,它将打印提供的
版本并终止。`` version``可以是任何可打印的对象,
,但很可能是一个字符串,例如``"2.1.0rc1``.
注意,当``docopt``设置为自动处理`-h`、
`--help`和``--version``选项时,您仍然需要在使用模式中提到它们才能工作。同时,让您的用户
了解他们。
-``选项优先``,默认情况下为'false`。如果设置为"true",则不允许混合选项和位置参数。即,在第一个
位置参数之后,即使看起来像是选择。这可以用于与posix的严格兼容,或者如果您想将参数分派给其他程序,
**返回**值是一个简单的字典,其中包含选项、参数和命令作为键,其拼写与帮助消息中的完全相同。long
选项的版本优先。例如,如果调用
顶部示例::
naval_fate.py ship guardian move 100 150--speed=15
,返回字典将是:
。代码::python
{--漂移:false,'mine':false,
'--help':false,'move':true,
'--moored':false,'new':false,
'--speed':'15','remove':false,
'--version':false,'set':false,
'<;name>;':['guardian','ship':true,
'<;x>;':'100,'shoot':false,
'<;y>;':'150'}
…]
-选项说明,例如::
-h--帮助显示此项
-s--排序输出
-o文件指定输出文件[默认值:./test.txt]
--安静打印较少文本
--详细打印更多文本
-组说明(可选,``doc选项加``only),例如::
group 1:
<;arg1>;--opt1[--opt2=arg2]
group2:command2 command3
>其格式如下所述;其他文本将被忽略。
usage pattern format
----
**usage pattern**是``doc``以
``用法:```(不区分大小写*)开头,以*可见*空行结尾。
最小示例:
代码::python
"用法:my_program.py
"
``用法:`'后面的第一个字被解释为程序的名称。
您可以多次指定程序的名称来表示多个
独占模式:
。代码::python
"用法:my_program.py file
my_program.py count file
>每个模式可以由以下元素组成:
-**<;arguments>;**,**arguments**。参数指定为
大写单词,例如"my_program.py content-path"或由尖括号括起的单词
:"`my_program.py<;content path>;"`"。
-**--选项**。选项是以破折号(`-``)开头的单词,例如
`--output``,`-o``。您可以"堆叠"一个字母中的几个选项,例如`-o i v``与`-o-i-v``相同。
选项可以有参数,例如`--input=file``或`-i file``或
甚至是`-ifile``。但是,如果希望选项具有参数、默认值或指定同义的短/长版本选项(请参见关于选项描述的下一节),请指定选项
描述,这一点很重要。
-**命令**是不*遵循描述的单词上述
`--options``或`<;arguments>;``或`` arguments``的约定,
加上两个特殊命令:破折号"`-``"和双破折号"`--`"
(见下文)。
-**-组-**。组是以破折号(`-``)开头和结尾的单词,例如
``-my-u group-`。在使用模式中定义的每个组都必须在其自己的部分中进行描述。请参阅下面的"组描述格式"。
使用以下结构指定模式:
-**[**(括号)**可选**元素。例如:``my_program.py
[-hvqo file]``
-**()**(parens)**必需的**元素。所有*未*
放入**[]**的元素也都是必需的,例如:``my_program.py
--path=<;path>;<;file>;…``与``my_program.py
(-path=<;path>;<;file>;…``相同。(注意,"必需选项"可能不是您的用户)。如果需要互斥元素之一,请使用**(
)**将它们分组:
``my_program.py(--顺时针--逆时针)time``。如果不需要互斥元素,则使用**[]**将其分组:``my_program.py[--left--right]``.
-**…**(省略号)**一个或多个**元素。要指定
可以接受任意数量的重复元素,请使用省略号(``…`),例如``my_program.py file…``表示接受一个或多个``file``。如果要接受零个或多个
元素,请使用方括号,例如:``my_program.py[file…]```。省略号
用作左侧表达式上的一元运算符。
-**[选项]**(区分大小写)任何选项的快捷方式。如果要指定使用模式可以与下面在选项描述中定义的任何选项一起提供,并且不想在使用模式中枚举它们,则可以使用它。按照惯例,双破折号"`--`"用于分隔可能被误认为选项的
位置参数。为了支持此约定,请在您的使用模式中添加"`[--]``"。
-"`[-]``"。按照惯例,单破折号"`-`"表示使用
``stdin``而不是文件。要支持此功能,请将"``[-]``"
添加到您的使用模式中。``-``"充当普通命令。
也就是说,如果程序作为"我的程序"调用,那么
``args['-v']``将是``2```。同样适用于命令。
=./这里
--path=./那里``返回的dict将包含``args['<;file>;']===
['file1','file2']``和``args['--path']==['./这里,'./那里']``.
option descriptions format
----
**option descriptions**包含一个选项列表,您将这些选项放在使用模式下面。
必须列出选项描述才能指定:
-同义的短选项和长选项,
-如果选项有参数,
-如果选项的参数有默认值,
规则如下:
-以`-``或`--```开头的``doc`中的每一行(不包括
空格)都被视为选项des描述,例如::
options:
--verbose\good
-o file\good
other:--bad\bad,line不以破折号开头"-"
-若要指定该选项有参数,请在空格(或等于"``=```"符号)后添加一个描述该参数的单词,如下所示。对于选项"
参数,请遵循
角括号或大写约定。如果要分隔选项,可以使用逗号。在
下面的示例中,这两行都是有效的,但是建议您使用
以保持单一样式。:
-o file--output=file不带逗号,带"="符号
-i<;file>;,--input<;file>;带逗号,不带"="sing
-使用两个空格将选项与其非正式描述分开::
--详细说明更多文本。#不正确,将被视为verbose选项有
参数"more",因此使用2个空格代替
-q quit。#良好的
-o文件输出文件。#好的
--标准输出使用标准输出。#很好,两个空格
-如果要为带参数的选项设置默认值,请将其放入选项根据说明,格式为``[默认值:
<;我的默认值>;``::
--coefficient=k k系数[默认值:2.95]
--output=file output file[默认值:test.txt]
--directory=dir some directory[默认值:./]
-如果该选项不可重复,则值为"`[默认值:…]``
中的e将被解释为字符串。如果*是*可重复的,则将
拆分为空白列表::
用法:my_program.py[--repeatable=<;arg>;--repeatable=<;arg>;]
[--另一个repeatable=<;arg>;]…
[--not repeatable=<;arg>;]
#将是['./这里,'./那里]
--repeatable=<;arg>;[默认值:./这里/那里]
t;[默认值:./here./there]
group descriptions format(``dopcopt_plus`` only)
——在引擎盖下,docopt将用它们各自的模式替换组元素(例如
```-my_group-````)。
**组描述**必须定义参数、选项和
命令元素的模式。不允许具有组的组元素。
::
我的组:--一个"u"选项(-另一个"u"选项命令)[-o<;arg>;]
组名的大小写不相关。在查找组描述时,
组元素中的下划线(`````)将转换为空格。
可以在多行上跨越模式定义。这个
定义相当于前面的示例::
我的组:
--一个"u"选项
(另一个"u"选项命令)
[-o<;arg>;]
arenthesis等
这些都是使用组的有效使用模式:
usage:prog[-v]-input-[-out_file-(out_db-[-create])]
input:<;in_file>;
out file:<;out_file>;
out db:
<;db_name>;
[-u usernAME[-p password]]
[<;host>;]
选项:
…
缩进在所有级别上都是完全可选的,与查找定义无关。但是,它确实使用法说明更易于阅读,因此受到鼓励。
ine,
至少间隔两个空格。与选项不同,不支持在单独的行上添加注释::
out db:
<;db懔name>;database name懔good,2个空格
[-u username[-p password]
database credentials懔bad,将被误认为模式!
[<;host>;]本地或远程主机名不正确,只有1个空间!
还必须描述在使用模式中定义的每个组(例如``-我的组-```')。
r/>
我们有一个广泛的"示例"列表
<;https://github.com/docopt/docopt/tree/master/examples>;`,涵盖了**docopt**功能的各个方面。尝试一下,如果有疑问,请阅读
源代码。
多级帮助(每个子命令都有单独的帮助屏幕),
要与不使用**docopt**的现有脚本交互,或者
要构建下一个"git",您将需要新的"options\u first"参数(如上文api部分所述)。为了让您快速开始
,我们实现了git命令行界面的一个子集作为示例:
`examples/git
<;https://github.com/docopt/docopt/tree/master/examples/git>;`
元素进入
命令行界面。但是它不会验证输入数据。
另一方面,有些库如"python schema
<;https://github.com/halst/schema>;``使验证数据变得轻而易举。看一看"validation\u example.py
<;https://github.com/docopt/docopt/tree/master/examples/validation\u example.py>;`\u
,它使用**schema**验证数据并向
用户报告错误。
配置文件用于提供默认值,这些值可以被命令行参数覆盖。由于**docopt**
返回一个简单的字典,因此很容易与以json、yaml或ini格式编写的配置文件集成。
`config_file_example.py<;examples/config_file_example.py>;```提供了
和如何将**docopt**与json或ini配置文件一起使用的示例。
开发
==
您还可以直接将一行代码放到
<;vladimir@keleshev.com>;
所有其他语言的官方docopt端口都可以在github上的"docopt organization page"lt;http://github.com/docopt>;下找到。
我们鼓励您使用python版本作为
参考实现。与语言无关的测试套件与"python实现"捆绑在一起,lt;http://github.com/docopt/docopt>;` `.
移植讨论位于"问题"页
<;http://github.com/docopt/docopt/issues>;` ` `.
**docopt**遵循"语义版本控制"<;http://semver.org>;`。带有稳定api的第一个版本将是1.0.0(很快)。在此之前,我们鼓励您在依赖项
工具中明确指定版本,例如::
-0.6.1错误修复版本。
-0.6.0``options_first``参数。
**中断更改**:更正了````[options]``含义。
``argv``defa"none"的结果。
-0.5.0重复的选项/命令被计数或累积到
列表中。
-0.4.2错误修复版本。
-0.4.0选项描述变为可选,
支持"``--`"和"``-```"命令。
-0.3.0支持(sub)命令,如"git remote add"。
introduce```[options]``任何选项的快捷方式。
**中断更改**:``docopt``返回字典。
-0.2.0使用模式匹配。基于
使用模式的位置参数解析。
**中断更改**:``docopt``返回命名空间(用于参数),
不列出。使用模式已正式化。
-0.1.0初始版本。仅分析选项(基于选项
描述)。