More stuff: Add: public function: `more_from_described()` -- [DISCUSS]

tabulon commented 5 years ago

Requesting feedback.

SYNOPSIS

Add a public function that might be named more_from_described(), as explained below.

The WHY

Current GLD users should be able to try GLM out with existing code, without having to put much effort, and vice versa.

Besides, some may simply prefer the array API currently offered by GLD. Allow them to cherish "more stuff", to their liking.

The WHAT

Introduce a new public function, dubbed here as more_from_described(), that simply performs an API translation (GLD => GLM) for the "described" options it recieves as input parameters.

Naturally, this would be useful and meaningful only after #16 is complete, i.e. when GLM reaches Feature parity with GLD (Getopt::Long::Descriptive).

Note that more_from_described() should ONLY concetrate on doing an API translation (GLD => GLM).

Nothing more, nothing less...

In particular, more_from_described() should NOT assume that it knows or drives the "whole picture" concerning the list of options, in any way.

In other words, the kind of mixing and matching shown in EXAMPLE-2 below, should be fully supported.

EXAMPLE-1 given just below, on the other hand, demonstrates a simple / straight-forward scenario.

EXAMPLE-1


# DISCUSS: which one of the below 'use' statements sound better?
use Getopt::Long::More qw(more_from_descibed);    # a) either this way? EXPORT_OK
use Getopt::Long::More::Descriptive;              # b) or this way?     EXPORT

# more_from_described(...) will enable GLM to grok some options given via the GLD API.

my $res = GetOptions( more_from_described (

  'my-program %o <some-arg>',
  [ 'server|s=s', "the server to connect to", { required => 1  } ],
  [ 'port|p=i',   "the port to connect to",   { default  => 79 } ],
  [],
  [ 'verbose|v',  "print extra stuff"            ],
  [ 'help',       "print usage message and exit", { shortcircuit => 1 } ],
));

EXAMPLE-2

Here is a slighty hairier example that demonstrates the general case.


# more_from_described(...) will enable GLM to grok some options given via the GLD API.
my $res = GetOptions(
  cmdinfo (
    summary => "Awesome garbage grinder"
  ),

  'foo=s',
  'bar=s',  optpsec(
    required => 1,
    summary => 'Bla, bla...'
  ),

  more_from_described (
    'my-program %o <some-arg>',
    [ 'server|s=s', "the server to connect to", { required => 1  } ],
    [ 'port|p=i',   "the port to connect to",   { default  => 79 } ],
    [],
    [ 'verbose|v',  "print extra stuff"            ],
    [ 'help',       "print usage message and exit", { shortcircuit => 1 } ],
  ),

  'baz=s', optspec (

  ),
  'gaz!,
);

SIDE NOTE 1

Whether or not the stuff demonstrated by EXAMPLE-2 above reflects "best-practises" is another subject altogether. Imho, GLM should not be in the business of dictating best practises; We may at best suggest what those might be.

Also, let's not forget that kind of thing (which may arguably look "ugly" to some) might just be a temporary state of code, while someone is just trying things out.

SIDE NOTE 2

The careful reader is probably wondering what is happening in EXAMPLE-2 above with that cmdinfo() call along with the $usage_desc (my-program %o <some-arg>) passed in à la GLD to more_from_described().

Here, the $usage_desc provided to more_from_described() would behave as if there were another cmdinfo( usage_desc => 'my-program %o <some-arg>') at that point in the parameter list, and it would not be forbidden to have multiple cmdinfo(...). Their contents would just get merged in the end, any latter program attribute value winning over the former(s).

DISCUSSION

Which of the use statements below strike as being more intuitive (for the module user)?
How about from a code layout (and load performance) perspective?
other angles ...?


# DISCUSS: which one of the below 'use' statements sound better?
use Getopt::Long::More qw(more_from_descibed);    # a) either this way? EXPORT_OK
use Getopt::Long::More::Descriptive;              # b) or this way?     with an automatic EXPORT of descriptive.

RELATED ISSUES

dependsOn: #16 -- Feature parity with GLD Getopt::Long::Descriptive.

...

perlancar commented 5 years ago

That's nice to have, I guess, but this feature would be low on my priority list. I slightly prefer putting more_from_described() in a separate module to keep GLM lean and startup-friendly. The functionality is not essential/core anyway.

tabulon commented 5 years ago

I agree on all points raised. Though naturally low at this point, once GLM reaches feature parity with GLD, the priority could perhaps go higher.

perlancar / perl-Getopt-Long-More