Bug #43838 for Getopt-Euclid: using an unconstrained repeated unflagged placeholder

Wed Mar 04 11:09:24 2009 harry [...] saltyshells.com - Ticket created

Subject:	using an unconstrained repeated unflagged placeholder
Date:	Wed, 4 Mar 2009 11:08:28 -0500
To:	bug-getopt-euclid [...] rt.cpan.org
From:	Harry Bennett <harry [...] saltyshells.com>

`my_script --usage` displays the following: "Usage: my_script <output_dir> <image_input>... [options]" Both <output_dir><image_input>... are required arguments as defined by Euclid. Since <output_dir> and <image input> are both required arguments, with the latter being an unconstrained repeated unflagged placeholder. Would it not be better to show the --usage as show below since the above showing would incline the user to place option switches at the end of the arguement list? "Usage: my_script [options] <output_dir> <image_input>... " For the record: I LOVE this module as it forces me to make docs :D

Thu Mar 05 20:05:29 2009 damian [...] conway.org - Correspondence added

Subject:	Re: [rt.cpan.org #43838] using an unconstrained repeated unflagged placeholder
Date:	Fri, 6 Mar 2009 12:05:17 +1100
To:	bug-Getopt-Euclid [...] rt.cpan.org
From:	Damian Conway <damian [...] conway.org>

Harry Bennett wrote: Show quoted text

> `my_script --usage` displays the following: > "Usage: my_script <output_dir> <image_input>... [options]" > > Both <output_dir><image_input>... are required arguments as defined by Euclid. > Since <output_dir> and <image input> are both required arguments, with the > latter being an unconstrained repeated unflagged placeholder. Would it not be > better to show the --usage as show below since the above showing would incline > the user to place option switches at the end of the arguement list?

Yes, it probably would. But I suspect the analysis required to detect when that's appropriate is too expensive for the derived benefit. Perhaps the next version should just always put "[options]" at the start (though the same problem can happen in reverse, of course, if any of the options take unconstrained repetitions). Hmmm. I'll certainly add this to the ToDo list. Thanks for the feedback! Damian

Thu Mar 05 20:05:30 2009 The RT System itself - Status changed from 'new' to 'open'

Fri Mar 06 10:58:19 2009 harry [...] saltyshells.com - Correspondence added

Subject:

using an unconstrained repeated unflagged placeholder | using an unconstrained repeated flagged placeholder

On Thu Mar 05 20:05:29 2009, damian@conway.org wrote: Show quoted text

> Harry Bennett wrote: >

> > `my_script --usage` displays the following: > > "Usage: my_script <output_dir> <image_input>... [options]" > > > > Both <output_dir><image_input>... are required arguments as defined

> by Euclid.

> > Since <output_dir> and <image input> are both required arguments,

> with the

> > latter being an unconstrained repeated unflagged placeholder. Would

> it not be

> > better to show the --usage as show below since the above showing

> would incline

> > the user to place option switches at the end of the arguement list?

> > Yes, it probably would. But I suspect the analysis required to detect > when that's appropriate is > too expensive for the derived benefit. Perhaps the next version should > just always put "[options]" > at the start (though the same problem can happen in reverse, of > course, if any of the options take > unconstrained repetitions). > > Hmmm. I'll certainly add this to the ToDo list. > > Thanks for the feedback! > > Damian

Damian, thanks for the reply. As I could not wrap my head around the 'unconstrained repeated unflagged placeholder' I decided to add a flag, which has gotten me a little further along with things. Sorry, I can no longer reproduce the issues I was having without the flag. I moved on without taking notes on it. In another matter regarding unconstrained repeated FLAGGED placeholder, the Euclid docs are telling me: "When an argument is marked repeatable the corresponding entry of %ARGV will not contain a hash reference, but rather an array of hash references, each of which records each repetition." However, when I dump it via Data::Dumper, it is showing it as an array reference of array references. More accurately, a single array reference within the expected array reference. What I am feeding that particular option is a simple list of filenames. Whether I list them individually or via globbing the behavior is the same. Is this the 'expected' behavior? As a point of curiosity why _would_ it be an array of hash references as opposed to a single array reference.. it is just a simple list, no? I do not understand the necessity/usefulness of the added depth. Any Idea when we could see an updated version? Thanks for your time!

Fri Mar 13 02:54:23 2009 damian [...] conway.org - Correspondence added

Subject:	Re: [rt.cpan.org #43838] using an unconstrained repeated unflagged placeholder \| using an unconstrained repeated flagged placeholder
Date:	Fri, 13 Mar 2009 17:54:06 +1100
To:	bug-Getopt-Euclid [...] rt.cpan.org
From:	Damian Conway <damian [...] conway.org>

Hi again Harry, Show quoted text

> In another matter regarding unconstrained repeated FLAGGED > placeholder, the Euclid docs are telling me: "When an argument is > marked repeatable the corresponding entry of %ARGV will not contain a > hash reference, but rather an array of hash references, each of which > records each repetition." However, when I dump it via Data::Dumper, it > is showing it as an array reference of array references. More > accurately, a single array reference within the expected array > reference. > > What I am feeding that particular option is a simple list of > filenames. Whether I list them individually or via globbing the > behavior is the same. > > Is this the 'expected' behavior?

Clearly not, since it wasn't what you'd expected. But it's the correct behaviour. ;-) (I believe the "array ref containing array ref" that you're seeing may be caused by the way you're calling Data::Dumper, but without seeing the actual code you're using, I can't be sure.) Show quoted text

> As a point of curiosity why _would_ it be an array of hash references > as opposed to a single array reference..it is just a simple list, no? > I do not understand the necessity/usefulness of the added depth.

Each flag can have more than one placeholder in it. For example: =item -size=<H>x<W> In such cases each entry for '-size' must be a hash (with the keys 'H' and 'W' to store the two components of the flag's value). Show quoted text

> Any Idea when we could see an updated version?

As you see, I haven't even enough time to reply promptly. As for module maintenance...that's only a fond wish just now, I'm sorry to say. :-( All the best, Damian

Sun Apr 19 08:44:22 2009 kgalinsky [...] gmail.com - Taken

Sun Apr 19 08:49:54 2009 kgalinsky [...] gmail.com - Correspondence added

Hi Harry and Damian, The documentation is a little wrong. As Damian mentions, I would venture that the current implementation is correct, but the documentation is confusing. For instance, consider the following example in the attached file: --single_vs_multi.pl ... =item [-]-s[ingle] <a> =for Euclid: repeatable =item [-]-m[ulti] <a>x<b> =for Euclid: repeatable ... --- The dump of \%ARGV contains: \%ARGV = { 'single' => [ '1', '2' ], 'multi' => [ { 'a' => '3', 'b' => '4' }, { 'a' => '5', 'b' => '6' } ] }; I will fix the documentation to make this clear.

#!/usr/bin/perl use Getopt::Euclid qw(:minimal_keys); use Data::Dumper; print Dumper \%ARGV; =head1 OPTIONS =over =item [-]-s[ingle] <a> =for Euclid: repeatable =item [-]-m[ulti] <a>x<b> =for Euclid: repeatable =back =cut

Mon Jun 01 06:28:19 2009 kgalinsky [...] gmail.com - Correspondence added

Documentation fixed in 0.2.1.

Mon Jun 01 06:28:21 2009 kgalinsky [...] gmail.com - Status changed from 'open' to 'resolved'