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.