[Docpie]

Fork me on GitHub

Usage格式


概述

"Usage"起始于"Usage:"(不区分大小写)。如果还有其他部分的帮助信息,一定要用一个空行隔开即可。

一个单行的Usage大致长这样:

Usage: my_program

自己试试 >>

或者一个帅气的多行Usage

Usage:
    my_program [options] command <argument> --option
    my_program [options] [optional-command] (REQIRED-ARGUMENT)
    my_program [options] (--either-this | --or-that)
    my_program [options] <repeatable-arg>...

自己试试 >>

你还可以将单个“Usage”分行,但分拆的行需要更多缩进以示区别。

Usage:
    prog [--long-option-1] [--long-option-2]
         [--long-option-3] [--long-option-4]  # Good
    prog [--long-option-1] [--long-option-2]
      [--long-option-3] [--long-option-4]     # Works but not so good
    prog [--long-option-1] [--long-option-2]
    [--long-option-3] [--long-option-4]       # Not work. Need to indent more.

各个元素通过空格、[]()|以及...彼此分开。不过长Option(用--开头)表示它比较喜欢用=来链接自己和它要求的Argument(像这样:--option=<value>)。各元素和分隔符的格式、意义和要求如下。

元素

<argument> ARGUMENT

Argument要么用<>裹起来,要么全大写。

Usage: my_program <input> <output>
       my_program INPUT OUTPUT

自己试试 >>

-o --option

Option同样有两个样子:单横线(-)配一个字母的是短Option(比如-h),双横线(--)配几个字母的是长Option(比如--help)。一些提示和注意:

  1. Option是唯一可以随意搅基的。-abc的意思是-a -b -c
  2. -a<arg>表示Option(-a)要求一个Argument(<arg>),因为两个黏在一起的。

    -a <arg>则只是表示一个Option(-a)和一个Argument(<arg>),俩货井水不犯河水。

  3. --long=<arg>表示Option(--long)要求一个Argument(<arg>),毕竟小手=将两货拉在了一起。

    --long <arg>则单纯地表示一个Option(--long)和一个Argument(<arg>)肩并肩纯洁地站在一起,并没有内在逻辑关系。

  4. 如果定义了“options”,那么-a <arg>--long <arg>的意义与“options”中定义保持一致

注:如果一个长Option要求一个Argument,强烈建议写成--long=<arg>而不是--long <arg>

command

所有不满足以上格式的单词都记为Command

Usage: get help pull

自己试试 >>

[可选元素]

所有在[](方括号)中的元素都为可选元素。在解析的时候,懒散的[]并不介意里面的元素是全部到齐了。也就是说,对于

Usage: my_program [command --option ARGUMENT]

自己试试 >>

Usage: my_program [command] [--option] [<argument>]

自己试试 >>

是一个意思。这样可以很方便地写option

Usage: my_program [-docpie]

自己试试 >>

如果你要求里面的元素要么全部到齐,要么全部缺席,请让一板一眼的()(圆括号)来帮忙(见下节)

(必选元素)

()(圆括号)里所有元素([]包裹元素除外)都必须出现。

Usage: my_program (--this [<arg>] | --that)

自己试试 >>

你可以将其嵌套在[]中,这样其中一个元素出现时,其它也必须出现。

Usage: my_program [(command --option ARGUMENT)]

自己试试 >>

要么这个 | 要么那个

|要求其分割的元素只匹配其中一个。

Usage: rank (--first | --second | --third)

自己试试 >>

你可以用它来组织重复元素,这些重复元素会在匹配时计数。

Usage: my_program [-v | -vv | -vvv]

自己试试 >>

重复元素...

...(省略号)意味着其左侧最近的元素/元素组可以重复。

Usage: cp <source>... <target> <logfile>

自己试试 >>

注意这货只粘左边最近的人,也就是说:

Usage: my_program -a<arg>...
       my_program --all=<arg>...

自己试试 >>

Option(-a)接受一个可重复的Argument(<arg>)Option(--all)也一样。这个情况下可以匹配-a 1 2 3。而

Usage: my_program (-a<arg>)...
       my_program (--all=<arg>)...

自己试试 >>

意味着Optional(-a)本身是可以重复的。这个情况可以匹配--all=1 --all=2 --all=3

[options]

[options]则是所有列在"Options"中选项的缩写。下面的这个写法

Usage:
  program [options] now

Options:
  --terminate  terminate the daemon process
  --reload     reload the config file
  --restart    restart the service

自己试试 >>

等同于

Usage: program [--terminate] [--reload] [--restart] now

自己试试 >>

--

单独的--(双横线)意味着Option的结束。不管后面参数如何,第一个--后面的元素,按照POSIX标准,都应当视为Positional Argument。详细请参看这里。你并不需要在"Usage"中声明--Docpie会自动处理--

Usage: cat [<file> ...]

自己试试 >>

对于-- -v --helpDocpie会将-v--help上缴给<file>,而不是当作Option来处理。

技巧

1. 你可以将多个短option写为一个,例如 -abc 等于 -a -b -c

from docpie import docpie
print(docpie('''Usage: prog -abc''', ['prog', '-a', '-bc']))
# {'--': False, '-a': True, '-b': True, '-c': True}

在线试试 >>

2. 你可以将短option的参数与option写在一起。

'''
Usage:
  prog [options]

Options:
  -a <value>  -a expects one value
'''
from docpie import docpie
print(docpie(__doc__, ['prog', '-abc']))
# {'--': False, '-a': 'bc'}

在线试试

3. 你可以指定某个元素允许多次出现:

Usage: my_program.py [-v | -vv | -vvv]

在线试试 >>

这样的话输入的 -v 会被计数。如果输入 my_program -vv ,则 -v 的解析结果为2。option/command均可以使用这个语法。

而对于argument和接受argumentoption,这个语法会触发收集,相同参数的值会被收集为一个列表:

Usage: program.py <file> <file> --path=<path>...

在线试试 >>

(建议定义“options”区指明 --path要求argument

如果输入 program.py file1 file2 --path ./here ./there 就会得到 {'<file>': ['file1', 'file2'], '--path': ['./here', './there']}

记住 ... 仅影响左边最近的 <path> 。下面的定义方法要求输入的格式不一样:

Usage: program.py <file> <file> (--path=<path>)...

在线试试>>

它可以匹配 program.py file1 file2 --path=./here --path=./there ,结果相同。


如果你喜欢这个项目,可以买我一杯啤酒,让我做的更好! | Flattr this

侧栏导航