[Docpie]

Fork me on GitHub

Usage Format


Summary

Usage section starts with "Usage:" (case-insensitive), ends with a visibly empty line. Each usage pattern should starts with your program's name. You can write more than one usage pattern in "Usage" section. The help message must has & only has one "Usage" section.

A one usage pattern example may look like:

Usage: my_program

try it >>

A multi usage patterns example may look like:

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

try it >>

When one usage pattern goes too long you can separate into several lines, but the following lines need to indent more:

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.

Each Command/Option/Argument is separated by white space or [, ], (, ), |, .... long Option & its expecting argument can be separated by =. The format rules are as follow.

Element Rules

<argument> ARGUMENT

Argument is the word which is surrounded by a pair of <> or the letters are all in upper-case.

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

try it >>

-o --option

Option has two forms: word starts with one dash ("-") followed by one letter is short option, two dashes ("--") followed by serveral letters is long option. Note:

  1. You can write several short options together, e.g. -abc will be interpreted as -a -b -c.
  2. -a<arg> means Option(-a) excepts one Argument(<arg>),

    -a <arg> means a Option(-a) (with no argument) and a positional Argument(<arg>).

  3. --long=<arg> means Option(--long) excepts one Argument(<arg>).

    --long <arg> means a Option(--long) (with no argument) and a positional Argument(<arg>).

  4. If you define “options”, then the meaning of -a <arg> and --long <arg> will keep the same as what “options” announces.

command

Any other words that do not in the format of Argument & Option are interpreted as Command.

Usage: get help pull

try it >>

[Optional Element(s)]

Elements inside [] (square brackets) are optional elements. It does not matter if the elements are in the same pair of brackets or not.

Usage: my_program [command --option ARGUMENT]

try it >>

is equal to

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

try it >>

If you need all elements appear or be omitted, use () (see below).

Then writing options can be easy & human-readable

Usage: my_program [-docpie]

try it >>

(Required Elements)

Any element inside ()(parentheses) is required except those which are nested in []

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

try it >>

You can nest () in a [] so when one element appears, others must appear together.

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

try it >>

this | or | that

| (pipe) separates elements into several exclusive matching cases. To group them, use () if one case must match or [] if any case is optional.

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

try it >>

You can also group duplicated elements, they'll be counted when matching.

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

try it >>

element...

... (ellipsis) means the closest one element/group at left is repeatable.

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

try it >>

Note ... only effect the one left element/group. Which means

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

try it >>

indicates that Option(-a) expects repeatable Argument(<arg>). So does Option(--all). It can match -a 1 2 3. But

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

try it >>

means that Option(-a) & Option(--all) themselve are repeatable. It can match --all=1 --all=2 --all=3

[options]

[options] is a shortcut for all options listed in "Options" section. You can simply consider it as all optional options. More details are in the next section.

Usage:
  program [options] now

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

try it >>

is equal to

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

try it >>

--

-- (double dashes) usually means the end of the options. Anything after the first -- will be considered as positional argument no matter how it looks like. For more information please check here. You do not need to declare it in your "Usage", docpie will handle it for you.

Usage: cat [<file> ...]

try it >>

Then for -- -v --help, docpie will give -v & --help to <file> instead of handling them as Option.

Tips

1. you can write several short options into one. -abc can mean -a -b -c.

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

try it now >>

2. You can also write short option and its value together

'''
Usage:
  prog [options]

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

try it now >>

3. If your pattern allows to match argument-less option (a flag) several times:

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

try it now >>

then number of occurrences of the option will be counted. I.e. args['-v'] will be 2 if program was invoked as my_program -vv. Same works for commands.

If your usage patterns allows to match same-named option with argument or positional argument several times, the matched arguments will be collected into a list:

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

try it now >>

(It's strongly suggested to specify it in "Options")

Then program.py file1 file2 --path ./here ./there will give you {'<file>': ['file1', 'file2'], '--path': ['./here', './there']}

Also note that the ... only has effect to <path>. You can also write in this way:

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

try it now >>

Then it can match program.py file1 file2 --path=./here --path=./there with the same result.


If you like this project, you can buy me a beer to help me make it better! | Flattr this

侧栏导航