develooper Front page | perl.perl5.porters | Postings from January 2018

Re: [perl #132732] use if - behaviour does not match documentation

Thread Previous | Thread Next
From:
Dan Book
Date:
January 24, 2018 00:09
Subject:
Re: [perl #132732] use if - behaviour does not match documentation
Message ID:
CABMkAVUkZtEvQAB=voGu2rDcwDRva0Ve8Y_mskogq97j2jwv0Q@mail.gmail.com
On Tue, Jan 23, 2018 at 6:38 PM, <sisyphus1@optusnet.com.au> wrote:

>
>
> -----Original Message----- From: James E Keenan via RT
> Sent: Wednesday, January 24, 2018 2:45 AM
> To: OtherRecipients of perl Ticket #132732:
> Cc: perl5-porters@perl.org
> Subject: [perl #132732] use if - behaviour does not match documentation
>
> On Wed, 17 Jan 2018 02:57:55 GMT, sisyphus wrote:
>>
>>> Hi,
>>>
>>> The documentation states:
>>>
>>> <quote>
>>> The use of => above provides necessary quoting of MODULE . If you don't
>>> use
>>> the fat comma (eg you don't have any ARGUMENTS), then you'll need to
>>> quote
>>> the MODULE.
>>> </quote>
>>>
>>> But the "use of => above provides necessary quoting of MODULE" only if:
>>> 1) strictures are not enabled
>>> &&
>>> 2) MODULE does not contain any occurrences of "::".
>>>
>>
> ....
>
> 3. The problem appears to be specific to 'use strict "subs";'.  The
>> following DWIM:
>> #####
>> use strict;
>> no strict "subs";
>> use if 1, POSIX => qw(:errno_h :fcntl_h);
>> use if 1, Digest::SHA => qw(sha1);
>> use if 1, Non::Existent, qw(foo);
>> #####
>> use strict;
>> no strict "subs";
>> use if 1, POSIX, qw(:errno_h :fcntl_h);
>> use if 1, Digest::SHA, qw(sha1);
>> use if 1, Non::Existent, qw(foo);
>> #####
>>
>> So the problem is not specific to use of the fat arrow.  Indeed, the use
>> of '=>' in the module's SYNOPSIS and DESCRIPTION is misleading.  So if we
>> revise the documentation, we should use commas rather than fat arrows.
>>
>
> Yes, that's a better appraisal.
> It seems the only time the fat arrow helps is when strict "subs" is
> enabled - as it then allows 'use if 1, POSIX => qw(:errno_h :fcntl_h);' to
> work.
>
> So maybe the docs could just not mention the fat comma option, and specify
> that the module name needs to be placed in quotes if strict "subs" is
> enabled.
> And then we just wait for someone to point out that you don't actually need
> to quote the module name when strict subs are enabled, so long as you use
> the fat comma && the module name doesn't contain "::" ;-)
>
> But perhaps we need more than just doc fixes.
>>
>
> Perhaps - though I'd personally be quite happy with just a doc fix.
>
> Cheers,
> Rob


I think it would be better to have the docs show the module name in quotes
every time. Use of the fat comma vs a regular comma is then just a
stylistic choice, and we are showing strict-safe examples as we should.

-Dan

Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About