New Issue: How should ArgumentParser metadata be provided?

Notifications Issues
1

18648, "arezaii", "How should ArgumentParser metadata be provided?", "2021-10-28T22:34:59Z"

Continuing work on the ArgumentParser library, we would like to improve our generated help message output by including additional fields, such as a program's name, description, author, version, and usage text.

Python's argparse library allows a user to define some of these values during the instantiation of the ArgumentParser by using parameters such as:

  • prog - to set the name of the program (defaults to sys.argv[0])
  • usage - string describing program usage (defaults to string generated from the arguments added)
  • description - text to display before the help message (default none)
  • epilog - text to display after the help message (default none)

Similarly, Rust's clap crate defines an expanded list of methods on the App struct:

  • name - program name (typically set when new'ing up an App struct)
  • about - a string describing what the program does
  • author - program author
  • version - that one explains itself
  • before_help - adds additional help information to be displayed in before the auto-generated help
  • help_message - sets the help text for the auto-generated help flag
  • after_help - adds additional help information to be displayed in after the auto-generated help
  • usage - a custom usage string to override the auto-generated usage string
  • bin_name - overrides the system-determined binary name

Swift's ArgumentParser defines a multi-purpose CommandConfiguration struct that contains some of this information as well (here Command may be interpreted as program), such as:

  • commandName - the name of the command to use on the command line
  • abstract - a one-line description of the command
  • discussion - a longer description of the command
  • version - version number for the command
  • helpNames - overrides default flags for help (-h/--help)

I would propose adding parameters with similar names to Rust's clap to the init method of our argumentParser record to capture this metadata.

An implementation might look like:

proc init(<previously defined parameters>, name="", 
                author="", version="", beforeHelp="", afterHelp="",
                usage="", helpFlags=["-h","--help"], helpMessage="Prints help information")

where additional fields that are defaulted to the empty string indicate they are not applicable or should be auto-generated as in the case of name and usage.

Rust's clap defines many separate values for help message outputs that are displayed differently depending on whether the long version (--help) or short version (-h) of the help flag was detected, but I am not proposing that we add similar functionality at this time.