Features¶
Automatic Help¶
argue
parsers can automatically pretty-print help text, such as this:
==========
argue-demo
==========
version: 0.1.3-dev5
author : Josh Bialkowski <josh.bialkowski@gmail.com>
copyright: (C) 2018
argue-demo [-h/--help] [-v/--version] [-s/--sum] <N> [N..]
Flags:
------
-h --help print this help message
-v --version print version information and exit
-s --sum sum the integers (default: find the max)
Positionals:
------------
integer an integer for the accumulator
choices=[1, 2, 3, 4]
This action is automatically added to the parser with the flags -h/--help
if the add_help
metadata option is true
.
Machine Parseable Help¶
The help information can be printed in JSON format instead of pretty text. The
JSON can then be processed to generate documentation pages (man pages or HTML).
Just export ARGUE_HELP_FORMAT="json"
in the environment before using
--help
. If the program uses subparsers, you may also wish to export
ARGUE_HELP_RECURSE="1"
to include help contents for all subparsers
recursively.
The JSON help for the demo program is:
[
{
"metadata": {
"id": "0x7ffc11b0cb40",
"name": "argue-demo",
"author": "Josh Bialkowski <josh.bialkowski@gmail.com>",
"copyright": "(C) 2018",
"prolog": "",
"epilog": "",
"comamnd_prefix": "",
"subdepth": 0,
"usage": "argue-demo [-h/--help] [-v/--version] [-s/--sum] <N> [N..]\n"
},
"flags": [
{
"short_flag": "-h",
"long_flag": "--help",
"help": "print this help message"
},
{
"short_flag": "-v",
"long_flag": "--version",
"help": "print version information and exit"
},
{
"short_flag": "-s",
"long_flag": "--sum",
"help": "sum the integers (default: find the max)"
}
],
"positional": [
{
"name": "integer",
"help": "an integer for the accumulator\nchoices=[1, 2, 3, 4]"
}
],
"subcommands": [
]
}]
Subcommands / Subparsers¶
Argue supports arbitrary nesting of subcommands via
ArgumentParser::add_subparsers
. The API mirrors that of python’s
argparse
. See examples/subparser_example.cc
for an example. The help text
for this example is:
=================
subparser-example
=================
subparser-example [-h/--help] <command>
Flags:
------
-h --help print this help message
Positionals:
------------
command [bar, foo]
Subcommands:
------------
bar The bar command does bar
foo The foo command does foo
Automatic Bash Completion¶
Any program which uses argue
to parse it’s command line arguments will
automatically supports bash autocompletion. The completion script can be found
at bash_completion.d/argue-autocomplete
. Install this anywhere that bash
looks for completion scripts (e.g. /usr/share/bash-completion
or
~/.bash_completion.d
if the user is so configured). The script only needs to
be installed once, and completion will work for all argue
enabled programs.
The completion script will detect if a program uses argue
for it’s argument
parsing and, if it does, it will call the program with some additional
environment variables signallying the ArgumentParser
to work in
completion mode instead of regular mode.
Unique Prefix Matching for Long Flags¶
If the program user provides a long flag (e.g. --do-optional
) which does not
match any known long flags, but is a unique prefix of a known flag (e.g.
--do-optional-thing
), then argue
will match the known flag. The prefix must
be unique so --do
will not match if --do-optional-thing
and
--do-other-thing
are both known.