search

perlancar / perl-Getopt-Long-More

1 stars 1 forks source link

more stuff: Add support for `usage_desc` and `program_name()` #17

Open tabulon opened 5 years ago

tabulon commented 5 years ago

SYNOPSIS

Add support for usage_desc and program_name()

The WHY

See #16 - Feature parity with GLD (Getopt::Long::Descriptive).

The WHAT

GLD offers an means for optionally specifying a usage_desc which, if present, makes its way to the generated HelpText.

GLM should offer an equivalent optional usage_desc feature that is similar, if not identical, (in terms of semantics) to its existing counterpart in GLD.

Obviously, this should come via a mechanism suitable to its own API,

Below is a quote from the GLD docs where usage_desc is described:

$usage_desc

The $usage_desc parameter to describe_options is a sprintf-like string that is used in generating the first line of the usage message. It's a one-line summary of how the command is to be invoked. A typical usage description might be:

$usage_desc = "%c %o ";

%c will be replaced with what Getopt::Long::Descriptive thinks is the program name (it's computed from $0, see "prog_name").

%o will be replaced with a list of the short options, as well as the text "[long options...]" if any have been defined.

The rest of the usage description can be used to summarize what arguments are expected to follow the program's options, and is entirely free-form.

Literal % characters will need to be written as %%, just like with sprintf.

and prog_name() is described as:

prog_name

This routine, exported on demand, returns the basename of $0, grabbed at compile-time. You can override this guess by calling prog_name($string) yourself.

The API MECHANISM - [TBD]

One possible API mechanism to achieve this kind of thing (and more) could be to employ a trick similiar to GLM's optspec() function; but with a function scoped around the entire 'command/program' rather than just one option.

This will be discussed under another thread/issue; because it could cater to more than just usage_desc mentioned here.