argparse icon indicating copy to clipboard operation
argparse copied to clipboard

Rework/Enhance help and usage

Open ndevenish opened this issue 3 years ago • 1 comments

Generally reworked help output to be a little more like what I expect (or, at least, like python's argparse)

  • Added metavars. If set, then will be used in help for the value placeholder for options, or the placeholder alone for regular positional arguments.
  • Help option sections are indented by two spaces, and comma-separated. They now show metavar (this means that an option with value now shows as --option VALUE Description of Option instead of --option Description ....
  • Usage section now enumerates options, instead of just [options]. Added ArgumentParser::usage() to retreive this string alone (in case you wanted to, say, print usage if arguments incorrectly passed).
  • Not showing [default: ...] for implicit values. This seemed unusual. It might be better to rework the help system to recognise a placeholder (even python's %(default)s) rather than try to magically get this right.
  • I've refreshed the README with the updated strings from this approach.

I guess the biggest holes are:

  • Multiple argument support is a little underrepresented compared to the full semantics of python's argparse. I don't know how well the approach to multiple arguments in this package matches the semantics of the python package.
  • I haven't written tests for this because the help output doesn't seem to be tested. I'm not opposed to writing some.

Otherwise this... might not be how you want things. If you like these changes I'm happy to do some amount of reworking to get it up to scratch for merging - these changes work for my purposes, but it could be that you wanted all of this done some other way. I thought I'd at least try to polish them up if it was useful ;)


A slightly expanded version of the README second example:

  argparse::ArgumentParser program("main");
  program.add_argument("thing").help("Thing to use.").metavar("THING");
  program.add_argument("--member").help("The alias for the member to pass to.").metavar("ALIAS");
  program.add_argument("--verbose").default_value(false).implicit_value(true);
  program.add_description("Forward a thing to the next member.");
  program.add_epilog("Possible things include betingalw, chiz, and res.");

Gives:

% ./main --help
Usage: main [-h] [--member ALIAS] [--verbose] THING

Forward a thing to the next member.

Positional arguments:
  THING         	Thing to use.

Optional arguments:
  -h, --help    	shows help message and exits
  -v, --version 	prints version information and exits
  --member ALIAS	The alias for the member to pass to.
  --verbose

Possible things include betingalw, chiz, and res.

ndevenish avatar Jul 25 '22 18:07 ndevenish

Hi, just a note that I'm happy to make these changes and rework the README, I've just been a little busy and won't be able to get to it for a couple of weeks 😅

ndevenish avatar Aug 14 '22 11:08 ndevenish

Refactored and merged as part of https://github.com/p-ranav/argparse/pull/206, including changes requested by @skrobinson. Thanks to both of you!

p-ranav avatar Sep 22 '22 02:09 p-ranav