Docoptz is slightly opinionated implementation of Docopt written using the
Dash shell. Like Docopt, it allows you to specify a program's command line
syntax by simply describing it in your --help
message.
Let's say we have the simple command merpstore
for saving/loading/listing
stuff in a key-value store. Its --help
look like this:
Usage: merpstore [OPTION]... [list|get KEY...|set (KEY VALUE)...]
Get, set, or (without args) list values in a merp key/value store.
Options:
-c,--color[=(yes|no|auto)] Colorize the output (default: 'yes')
(default without option is 'auto')
-f,--file=NAME File to read (default: ~/.merpstorerc)
-h,--help Display this help and exit
-V,--version Output version information and exit
The help message contains two parts: Usage patterns and option patterns.
The usage pattern begins with the Usage:
followed by or more (indented) lines
which starts with the command name (merpstore
) and possible arguments. There
may be followed by an (optional) unindented line with a short command
description.
The usage pattern could also be written as:
Usage:
merpstore [OPTION]... [list]
merpstore [OPTION]... get KEY...
merpstore [OPTION]... set (KEY VALUE)...
Get, set, or (without args) list values in a merp key/value store.
Or even:
Usage: merpstore [OPTION]... [ list |
get KEY... |
set (KEY VALUE)... ]
Get, set, or (without args) list values in a merp key/value store.
Options may be specified directly in the usage patterns or
separately. The option patterns begin with Options:
and all (optionally
indented) lines from that up until the first blank line, that also starts with
-
is taken to be an option pattern.
Options:
-c,--color[=(yes|no|auto)], Colorize the output (default: 'yes')
--colour[=(yes|no|auto)] (default without option is 'auto')
Aliases of the same option are separated by ,
and the comma can also be used
to continue an option pattern on the next line (as above). The description is
separated from the option by two or more spaces. Use default:
(in the
description) to specify a default value for an option argument.
When aliases are declared in an option pattern, then all aliases may be used wherever one of them is given in a usage pattern.
Usage: exampy --help
Example which REQUIRES either --help or -h to be specified.
Option:
-h,--help Display this help and exit
-
Positional arguments are written as
ARGUMENT
. They may only contain digits (0-9
), upper case letters (a-z
) and dashes (-
) and cannot start with a dash on number. -
Options are written as
--list
(-l
) or--dir=NAME
(-dNAME
). They may only contain digits (0-9
), lower case letters (a-z
) and dashes (-
) and can only start with one or two dashes. -
Subcommands are written as
command
and must (just like options) only contain digits (0-9
), lower case letters (a-z
) and dashes (-
) and cannot start with a dash or number.
To specify patterns you may use:
-
[
…]
indicates an optional grouping. E.g.[FILE]
could be used to indicate an optional filename. -
(
…)
indicates a required grouping. Not needed when repeating a single argument (FILE...
) but useful for alternatives ((FILE|URL)
) repeating multiple things ((KEY VALUE)...
). -
|
indicates logical 'or' in a grouping. For example(get|set)
requires eitherget
orset
. -
...
indicates a repetition. You could for example useFILE...
to indicate one or more files need to be specified ([FILE]...
for zero or more files). -
[OPTION]...
signifies zero or more options from theOptions:
section of your help message. -
--
used on the command line to signify end of options meaning that any arguments after--
on the command line are left as-is. (This could, for example, be used with therm
command to erase a file called-l
, like sorm -- -l
.) This behavior is always enabled in Docoptz and doesn't need to be included in your help message. -
-
is used to signify that instead of reading input from a file a command should read standard input. You can use-
in your help message, if you want to for example using(-|FILE)
to signify that either aFILE
or-
may be specified on the command line, but since-
is a perfectly valid value forFILE
you usually don't have to do that.
Docoptz differs from the original Docopt in the following ways:
-
Optional option arguments are supported, written
--color[=WHEN]
or even--color[=(yes|no|auto)]
. -
Spaces are never allowed between options and their arguments on the command line, so
--file abc
is always interpreted as option plus positional argument. To specify an option argument--file=abc
(or-fabc
) must be used. -
Positional arguments are written in capitals
ARGUMENT
. (The Docopt syntax<argument>
is not supported). -
A default argument is placed after the keyword
default:
, there's no need for brackets. (Docopt requires brackets[default: …]
.) -
Use
[OPTION]...
to specify 'any option'. This usage is familiar from the help pages ofgrep
,ls
etc. (The Docopt[options]
is not supported.) -
Long options (like
--almost-all
) cannot be abbreviated on the command line, and are not spell checked. This is by design: Long options are intended for clarity (e.g. in a script or code example). If you want brevity use it a short alias (-A
). -
--
and-
are always supported (no need to explicitly write them into the help message).
Docoptz uses the Dashtap test framework which is included as a Git submodule, so if you want to run the tests, you'll need to clone the submodules as well:
git clone --recurse-submodules [email protected]:zrajm/docoptz.git
The same goes for when you're pulling the latest changes:
git pull --recurse-submodules
NOTE: If a submodule is in a 'detach HEAD' state (using Git v2.34.1) when you
invoke git pull --recurse-submodules
, the submodule will remain in detached
HEAD state, but in the main repository git status
will report that the
submodule as unmodified. :(
The following command will output the names of all submodules that are in a detached HEAD state:
git submodule -q foreach 'git symbolic-ref -q HEAD || echo "$sm_path"'
The Docoptz test suite (found in the directory t/
) can be run using:
prove
Docoptz comes with a test suite written using the small Dashtap testing
framework. It is written using the Dash shell and uses the TAP (Test
Anything Protocol) output format. The small Dash shell file size and fast
execution format help deliver fast testing, while the TAP protocol allow you to
use any testing tool build for TAP (e.g. the prove
command used above that
comes with Perl).
All source code in this repository is licensed under GNU General Public License version 2.0 (GPL-2.0). – Except for any included external libraries and modules which use their own licenses.
Non-source code material is licensed under Creative Commons Attribution ShareAlike version 4.0 International (CC-BY-SA-4.0).