That’s it! No Template Haskell, no unreadable syntax, no learning yet another finicky API. Write the usage patterns you support, and docopt builds the appropriate option parser for you (internally using parsec). If your user invokes your program correctly, you query for the arguments they provided. If the arguments provided do not match a supported usage pattern, you guessed it: docopt automatically prints the help text and exits!

Usage Patterns

<argument> or ARGUMENT

--flag or --option=<arg>

Options are typically optional (though this is up to you), and can be either boolean (present/absent), as in --flag, or expect a trailing argument, as in --option=<arg> or --option=ARG. Arguments can be separated from the option name by an = or a single space, and can be specified as <arg> or ARG (consistency of style is recommended, but it is not enforced).

Short-style options, as in -f or -f ARG or -f=<arg>, are also allowed. Synonyms between different spellings of the same option (e.g. -v and --verbose) can be established in the option descriptions (see below). Short-style options can also be stacked, as in -rfA. When options are stacked, -rfA is effectively equivalent to (-r | -f | -A)... to the argument parser.

You can match a long-style option --option or --option=<arg> with longOption "option", and a short-style option -for -f=<arg> with shortOption 'f'. Note that neither --option=<arg> nor -f=<arg> would be matched by argument "arg".

command

Anything not recognized as a positional argument or a short or long option is treated as a command (or subcommand, same thing to docopt). A command named pull can be matched with command "pull".

[] (brackets) e.g. command [--option]

Patterns inside brackets are optional.

() (parens)

Patterns inside parens are required (the same as patterns not in () are required). Parens are useful if you need to group some elements, either for use with | or ....

| (pipe) e.g. command [--quiet | --verbose]

A pipe | separates mutually exclusive elements in a group. A group could be elements inside [], (), or the whole usage line.

When elements are separated by a pipe, the elements are tried from left to right until one succeeds. At least one of the elements are required unless in an eplicitly optional group surrounded by [].

... (ellipsis) e.g. command <file>...

An ellipsis can trail any element or group to make it repeatable. Repeatable elements will be accumulated into a list of occurrences.

[options] (case sensitive)

The string [options] is a shortcut to match any options specified in your option descriptions.

[-] and [--]

Single hyphen - is used by convention to specify using stdin as input instead of reading a file. Double hyphen -- is typically used to manually separate leading options from trailing positional arguments. Both of these are treated as commands, and so are perfectly legal in usage patterns. They are typically optional elements, but can be required if you drop the []. These are treated as commands and can be matched with command "-" or command "--", whether they’re wrapped [-] or not.

Option descriptions

Option descriptions establish:

which short and long options are synonymous

whether an option expects an argument or is a simple flag

if an option’s argument has a default value

Rules:

Any line after the usage patterns whose first non-space character is a - is treated as an option description. (Options: prefix line not required).

Options: --help # invalid: line does not start with '-'
--verbose # good

Options on the same line will be treated by the parser as synonyms (everywhere interchangeable). Synonymous options are separated by a space (with optional comma):

Here, in the arguments myprog analyze --verbose ./file1.txt would be invalid, because -vand its synonyms expect an argument, so ./file1.txt is captured as the argument of --verbose, not as the positional argument <file>. Be careful!

Options can be separated from arguments with a single space or a =, and arguments can have the form <arg> or ARG. Just be sure to separate synonyms and arguments from the beginning of the description by at least 2 spaces.

Differences from reference python implementation:

does not automatically exclude from the [options] shortcut options that are already used elsewhere in the usage pattern (e.g. usage: prog [options] -a will try to parse -a twice).

does not automatically resolve partially-specified arguments, e.g. --verb does not match where --verbose is expected. This is planned to be deprecated in future versions of docopt, and will likely not be implemented in docopt.hs

is not insensitive to the ordering of adjacent options, e.g. usage: prog -a -b does not allow prog -b -a (reference implementation currently does).

Changes

0.7.0.5

Fix an issue where in some cases pattern lines were matched out of order [#16]