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

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

Thread Previous
From:
James E Keenan via RT
Date:
January 24, 2018 03:39
Subject:
[perl #132732] use if - behaviour does not match documentation
Message ID:
rt-4.0.24-1461-1516765141-535.132732-15-0@perl.org
On Wed, 24 Jan 2018 00:09:26 GMT, grinnz@gmail.com wrote:
> 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

Sounds good.  I'll prepare a patch tomorrow.

-- 
James E Keenan (jkeenan@cpan.org)

---
via perlbug:  queue: perl5 status: open
https://rt.perl.org/Ticket/Display.html?id=132732

Thread Previous


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