Bug #120231 for Getopt-Long: Documentation: Must names and aliases be spelled in diminishing-length order?

Mon Feb 13 13:05:36 2017 jkeenan [...] cpan.org - Ticket created

CC:	ANDK [...] cpan.org, gbhull [...] gmail.com
Subject:	Documentation: Must names and aliases be spelled in diminishing-length order?

Please see discussion in this bug ticket: https://rt.perl.org/Ticket/Display.html?id=130764 In comment https://rt.perl.org/Ticket/Display.html?id=130764#txn-1448515, Andreas Koenig suggests that there is a documentation error in Getopt::Long. The relevant section (in v2.48 found in perl-5.24.1) is: ##### Options with multiple names Often it is user friendly to supply alternate mnemonic names for options. For example "--height" could be an alternate name for "--length". Alternate names can be included in the option specification, separated by vertical bar "|" characters. To implement the above example: GetOptions ('length|height=f' => \$length); The first name is called the primary name, the other names are called aliases. When using a hash to store options, the key will always be the primary name. Multiple alternate names are possible. ##### Andreas suggests that the primary name and its aliases should be arranged left-to-right in diminishing length order. My experimentation confirms that this would resolve the problem cited by the original poster in perl:130764. Can the Getopt::Long documentation be adjusted? Thank you very much. Jim Keenan

Mon Feb 13 13:06:18 2017 jkeenan [...] cpan.org - Reference to perl ticket #130764 added

Tue Feb 14 04:32:43 2017 jv [...] cpan.org - Correspondence added

RT-Send-CC:

ANDK [...] cpan.org

The order of alternatives is not really important. The first name specified is the primary name. This name is use to return option values when an option hash is used. GetOptions( \%opt, "foo|bar" ) will set $opt{foo} when --bar is set on the command line. Also, it goes without saying that all option names must be unique, even -- and this is the problem described in ticket 130764 -- when case insensitive matching is selected. Specifying option names "P" and "p" while ignore_case is in effect is a bad idea.

Tue Feb 14 04:32:43 2017 The RT System itself - Status changed from 'new' to 'open'

Tue Feb 14 05:54:23 2017 andreas.koenig.7os6VVqR [...] franz.ak.mind.de - Correspondence added

CC:	ANDK [...] cpan.org
Subject:	Re: [rt.cpan.org #120231] Documentation: Must names and aliases be spelled in diminishing-length order?
Date:	Tue, 14 Feb 2017 11:53:58 +0100
To:	"Johan Vromans via RT" <bug-Getopt-Long [...] rt.cpan.org>
From:	Andreas Koenig <andreas.koenig.7os6VVqR [...] franz.ak.mind.de>

Show quoted text

>>>>> On Tue, 14 Feb 2017 04:32:43 -0500, "Johan Vromans via RT" <bug-Getopt-Long@rt.cpan.org> said:

Show quoted text

> <URL: https://rt.cpan.org/Ticket/Display.html?id=120231 > > The order of alternatives is not really important. The first name specified > is the primary name. This name is use to return option values when an > option hash is used.

Show quoted text

> GetOptions( \%opt, "foo|bar" )

Show quoted text

> will set $opt{foo} when --bar is set on the command line.

Show quoted text

> Also, it goes without saying that all option names must be unique, even -- > and this is the problem described in ticket 130764 -- when case insensitive > matching is selected. Specifying option names "P" and "p" while ignore_case > is in effect is a bad idea.

I fear I must play advocate for the OP. The documentation talks about two kinds of ignoring case: 1) When configured for bundling, single-character options are matched case sensitive while long options are matched case insensitive 2) Without additional configuration, GetOptions() will ignore the case of option names So the OP thought, since he enables bundling, he can treat "p" and "P" as two different options. In fact he can do so, as I pointed out, as long as the single-letter-options are just aliases. But he cannot use them as primaries, which I cannot say where that would be documented. Do you see what I mean? I mean, I agree that the OP chose a configuration I would not recommend, but I belief he acted in accordance with the documentation. -- andreas

Tue Feb 14 07:43:06 2017 jv [...] cpan.org - Correspondence added

Show quoted text

> So the OP thought, since he enables bundling, he can treat "p" and "P" > as two different options.

If ignore_case is left out, the default case, single character options are be treated case sensistive due to the bundling. There is a small bug in the code which takes the wrong branch when there are single-character, case differing primary names. I'll address that bug (it's a trivial fix) in due time but I do not consider it urgent, given that it took 15 years or so for the bug to emerge :). Enabling no_ignore_case makes everything work as OP expected. And it makes clear what the intentions are.

Tue Feb 14 07:57:15 2017 jv [...] cpan.org - Correspondence added

Fixed in git, commit 94c6915..5416cda.

Tue Feb 14 07:57:16 2017 jv [...] cpan.org - Status changed from 'open' to 'patched'

Tue Feb 14 08:29:25 2017 andreas.koenig.7os6VVqR [...] franz.ak.mind.de - Correspondence added

Subject:	Re: [rt.cpan.org #120231] Documentation: Must names and aliases be spelled in diminishing-length order?
Date:	Tue, 14 Feb 2017 14:29:05 +0100
To:	bug-Getopt-Long [...] rt.cpan.org
From:	Andreas Koenig <andreas.koenig.7os6VVqR [...] franz.ak.mind.de>

Thanks Johan, all the best! -- andreas

Tue Feb 14 14:44:33 2017 gbhull [...] gmail.com - Correspondence added

CC:	jkeenan [...] cpan.org, ANDK [...] cpan.org
Subject:	Re: [rt.cpan.org #120231] Documentation: Must names and aliases be spelled in diminishing-length order?
Date:	Wed, 15 Feb 2017 08:44:14 +1300
To:	bug-Getopt-Long [...] rt.cpan.org
From:	Geoff Hull <gbhull [...] gmail.com>

Thank you from me also. -- Geoff On 15 February 2017 at 02:29, (Andreas J. Koenig) via RT < bug-Getopt-Long@rt.cpan.org> wrote: Show quoted text

> <URL: https://rt.cpan.org/Ticket/Display.html?id=120231 > > > Thanks Johan, all the best! > -- > andreas > >

Tue Aug 18 08:00:56 2020 jv [...] cpan.org - Status changed from 'patched' to 'resolved'

Tue Aug 18 08:00:56 2020 jv [...] cpan.org - Taken

Tue Aug 18 08:00:57 2020 jv [...] cpan.org - Broken in 2.50 added

Tue Aug 18 08:00:57 2020 jv [...] cpan.org - Broken in 2.47 deleted