Docopt Reference Documents

docops.rst

Help message format

Help message consists of 2 parts:

• Usage pattern, e.g.:

  Usage: my_program.py [-hso FILE] [--quiet | --verbose] [INPUT ...]

• Option descriptions, e.g.:

  -h --help    show this
  -s --sorted  sorted output
  -o FILE      specify output file [default: ./test.txt]
  --quiet      print less text
  --verbose    print more text

Their format is described below; other text is ignored.

Usage pattern format

Usage pattern is a substring of doc that starts with usage: (case insensitive) and ends with a visibly empty line. Minimum example:

"""Usage: my_program.py

"""

The first word after usage: is interpreted as your program's name. You can specify your program's name several times to signify several exclusive patterns:

"""Usage: my_program.py FILE
          my_program.py COUNT FILE

"""

Each pattern can consist of the following elements:

• <arguments>, ARGUMENTS. Arguments are specified as either upper-case words, e.g. my_program.py CONTENT-PATH or words surrounded by angular brackets: my_program.py <content-path>.
• --options. Options are words started with dash (-), e.g. --output, -o. You can "stack" several of one-letter options, e.g. -oiv which will be the same as -o -i -v. The options can have arguments, e.g. --input=FILE or -i FILE or even -iFILE. However it is important that you specify option descriptions if you want your option to have an argument, a default value, or specify synonymous short/long versions of the option (see next section on option descriptions).
• commands are words that do not follow the described above conventions of --options or <arguments> or ARGUMENTS, plus two special commands: dash "-" and double dash "--" (see below).

Use the following constructs to specify patterns:

• [ ] (brackets) optional elements. e.g.: my_program.py [-hvqo FILE]
• ( ) (parens) required elements. All elements that are not put in [ ] are also required, e.g.: my_program.py --path=<path> <file>... is the same as my_program.py (--path=<path> <file>...). (Note, "required options" might be not a good idea for your users).
• | (pipe) mutually exclusive elements. Group them using ( ) if one of the mutually exclusive elements is required: my_program.py (--clockwise | --counter-clockwise) TIME. Group them using [ ] if none of the mutually-exclusive elements are required: my_program.py [--left | --right].
• ... (ellipsis) one or more elements. To specify that arbitrary number of repeating elements could be accepted, use ellipsis (...), e.g. my_program.py FILE ... means one or more FILE-s are accepted. If you want to accept zero or more elements, use brackets, e.g.: my_program.py [FILE ...]. Ellipsis works as a unary operator on the expression to the left.
• [options] (case sensitive) shortcut for any options. You can use it if you want to specify that the usage pattern could be provided with any options defined below in the option-descriptions and do not want to enumerate them all in usage-pattern.
• "[--]". Double dash "--" is used by convention to separate positional arguments that can be mistaken for options. In order to support this convention add "[--]" to your usage patterns.
• "[-]". Single dash "-" is used by convention to signify that stdin is used instead of a file. To support this add "[-]" to your usage patterns. "-" acts as a normal command.

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

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

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: my_program.py <file> <file> --path=<path>...

I.e. invoked with my_program.py file1 file2 --path=./here --path=./there the returned dict will contain args['<file>'] == ['file1', 'file2'] and args['--path'] == ['./here', './there'].

Option descriptions format

Option descriptions consist of a list of options that you put below your usage patterns.

It is necessary to list option descriptions in order to specify:

• synonymous short and long options,
• if an option has an argument,
• if option's argument has a default value.

The rules are as follows:

• Every line in doc that starts with - or -- (not counting spaces) is treated as an option description, e.g.:

  Options:
    --verbose   # GOOD
    -o FILE     # GOOD
  Other: --bad  # BAD, line does not start with dash "-"

• To specify that option has an argument, put a word describing that argument after space (or equals "=" sign) as shown below. Follow either <angular-brackets> or UPPER-CASE convention for options' arguments. You can use comma if you want to separate options. In the example below, both lines are valid, however you are recommended to stick to a single style.:

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

• Use two spaces to separate options with their informal description:

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

• If you want to set a default value for an option with an argument, put it into the option-description, in form [default: <my-default-value>]:

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

• If the option is not repeatable, the value inside [default: ...] will be interpreted as string. If it is repeatable, it will be splited into a list on whitespace:

  Usage: my_program.py [--repeatable=<arg> --repeatable=<arg>]
                       [--another-repeatable=<arg>]...
                       [--not-repeatable=<arg>]
  
  # will be ['./here', './there']
  --repeatable=<arg>          [default: ./here ./there]
  
  # will be ['./here']
  --another-repeatable=<arg>  [default: ./here]
  
  # will be './here ./there', because it is not repeatable
  --not-repeatable=<arg>      [default: ./here ./there]

docopts2.md

Command-line interface description language

<iframe width="800" height="450" src="http://www.youtube.com/embed/pXhcPJK5cMc?rel=0" frameborder="0" allowfullscreen></iframe>

docopt helps you:

• define interface for your command-line app, and
• automatically generate parser for it.

docopt is based on conventions that are used for decades in help messages and man pages for program interface description. Interface description in docopt is such a help message, but formalized. Here is an example:

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.

The example describes interface of executable naval_fate, which can be invoked with different combinations of commands (ship, new, move, etc.), options (-h, --help, --speed=<kn>, etc.) and positional arguments (<name>, <x>, <y>).

Example uses brackets "[ ]", parens "( )", pipes "|" and ellipsis "..." to describe optional, required, mutually exclusive, and repeating elements. Together, these elements form valid usage patterns, each starting with program's name naval_fate.

Below the usage patterns, there is a list of options with descriptions. They describe whether an option has short/long forms (-h, --help), whether an option has an argument (--speed=<kn>), and whether that argument has a default value ([default: 10]).

docopt implementation will extract all that information and generate a command-line arguments parser, with text of the example above being the help message, which is shown to a user when the program is invoked with -h or --help options.

Usage patterns

Text occuring between keyword usage: (case-insensitive) and a visibly empty line is interpreted as list of usage patterns. First word after usage: is interpreted as program's name. Here is a minimum example for program that takes no command-line arguments:

Usage: my_program

Program can have several patterns listed with various elements used to describe the pattern:

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

Each of the elements and constructs is described below. We will use the word "word" to describe a sequence of characters delimited by either whitespace, one of "[]()|" characters, or "...".

<argument> ARGUMENT

Words starting with "<", ending with ">" or upper-case words are interpreted as positional arguments.

Usage: my_program <host> <port>

-o --option

Words starting with one or two dashes (with exception of "-", "--" by themselves) are interpreted as short (one-letter) or long options, respectively.

• Short options can be "stacked" meaning that -abc is equivalent to -a -b -c.
• Long options can have arguments specified after space or equal "=" sign:
  --input=ARG is equivalent to --input ARG.
• Short options can have arguments specified after optional space:
  -f FILE is equivalent to -fFILE.

Note, writing --input ARG (opposed to --input=ARG) is ambiguous, meaning it is not possible to tell whether ARG is option's argument or positional argument. In usage patterns this will be interpreted as option with argument only if option's description (covered below) for that option is provided. Otherwise it will be interpreted as separate option and positional argument.

Same ambiguity is with -f FILE and -fFILE notation. Although in the latter case it is not possible to tell whether it is a number of stacked short options, or an option with argument. These notations will be interpreted as option with argument only if option's description is provided.

command

All other words that do not follow the above conventions of --options or <arguments> are interpreted as (sub)commands.

[optional elements]

Elements (options, arguments, commands) enclosed with square brackets "[ ]" are marked to be optional. It does not matter if elements are enclosed in same or different brackets, for example:

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

is equivalent to:

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

(required elements)

All elements are required by default, if not included in brackets "[ ]". However, sometimes it is necessary to mark elements as required explicitly with parens "( )". For example, when you need to group mutually-exclusive elements (see next section):

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

Another use-case, is when you need to specify that if one element is present, then another one is required, which you can achieve as:

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

In this case, a valid program invocation could be with either no arguments, or with 2 arguments.

element|another

Mutually exclusive elements can be separated with pipe "|" as follows:

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

Use parens "( )" to group elements when one of the mutually exclusive cases is required. Use brackets "[ ]" to group elements when none of the mutually exclusive cases is required:

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]

is equivalent to:

Usage: my_program (run [--fast] | jump [--high])

element...

Use ellipsis "..." to specify that argument (or group of arguments) to the left could be repeated one or more times:

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

You can flexibly specify number of arguments that are required. Here are 3 (redundant) ways of requiring zero or more arguments:

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

One or more arguments:

Usage: my_program <file>...

Two or more arguments (and so on):

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

[options]

"[options]" is a shortcut that allows to avoid listing all options (from list of options with descriptions) in a pattern. For example:

Usage: my_program [options] <path>

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

is equivalent to:

Usage: my_program [--all --long --human-readable] <path>

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

This can be useful, if you have many options, and all of them are applicable to one of patterns. Alternatively, if you have both short and long versions of options (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.

More details on how to write options' descriptions will follow below.

[--]

Double dash "--", when not part of an option, is often used by convention to separate options and positional arguments, in order to handle cases when e.g. file names could be mistaken for options. In order to support this convention, add "[--]" into your patterns before positional arguments.

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 "[ ]")

[-]

Single dash "-", when not part of an option, is often used by convention to signify that a program should process stdin, as opposed to a file. If you want to follow this convention add "[-]" to your pattern. "-" by itself is just a normal command, which you can use with any meaning.

Option descriptions

Option descriptions consist of a list of options that you put below your usage patterns. It is optional to specify them if there is no ambiguity in usage patterns (described in --option section above).

Option's description allows to specify:

• that a short and a long options are synonymous,
• that an option has an argument,
• default value for option's argument.

The rules are as follows:

Every line that starts with "-" or "--" (not counting spaces) is treated as an option description, e.g.:

Options:
  --verbose   # GOOD
  -o FILE     # GOOD
Other: --bad  # BAD, line does not start with dash "-"

To specify that option has an argument, put a word describing that argument after space (or equals "=" sign) as shown below. Follow either <angular-brackets> or UPPER-CASE convention for options' arguments. You can use comma if you want to separate options. In the example below, both lines are valid, however you are recommended to stick to a single style.

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

Use two spaces to separate options with their informal description.

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

If you want to set a default value for an option with an argument, put it into the option's description, in form [default: <the-default-value>].

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

Try docopt in your browser

Implementations

docopt is available in numerous programming languages. Official implementations are listed at docopt organization on GitHub.