.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "Perl::Critic::Policy::Compatibility::ConstantLeadingUnderscore 3pm" .TH Perl::Critic::Policy::Compatibility::ConstantLeadingUnderscore 3pm "2018-05-30" "perl v5.26.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Perl::Critic::Policy::Compatibility::ConstantLeadingUnderscore \- new enough "constant" module for leading underscores .SH "DESCRIPTION" .IX Header "DESCRIPTION" This policy is part of the \f(CW\*(C`Perl::Critic::Pulp\*(C'\fR add-on. It asks that if you have a constant with a leading underscore, .PP .Vb 1 \& use constant _FOO ... # leading underscore on name .Ve .PP then you explicitly declare \f(CW\*(C`use 5.6\*(C'\fR or \f(CW\*(C`use constant 1.02\*(C'\fR, or higher, since \f(CW\*(C`constant.pm\*(C'\fR before that did not allow leading underscores. .PP .Vb 1 \& use constant _FOO => 123; # bad \& \& use 5.006; \& use constant _FOO => 123; # ok \& \& use constant 1.02; \& use constant _FOO => 123; # ok \& \& use constant 1.02 _FOO => 123; # ok .Ve .PP The idea is to avoid trouble in code which might run on Perl 5.005, or might in principle still run there. On that basis this policy is under the \&\*(L"compatibility\*(R" theme (see \*(L"\s-1POLICY THEMES\*(R"\s0 in Perl::Critic). .PP Asking for the new enough module \f(CW\*(C`use constant 1.02\*(C'\fR is suggested, since it's the module feature which is required and the code might then still run on Perl 5.005 or earlier if the user has a suitable \f(CW\*(C`constant.pm\*(C'\fR from \&\s-1CPAN.\s0 .SS "Details" .IX Subsection "Details" A version declaration must be before the first leading underscore, so it's checked before the underscore is attempted (and gives an error). .PP .Vb 2 \& use constant _FOO => 123; # bad \& use 5.006; .Ve .PP A \f(CW\*(C`require\*(C'\fR for the Perl version is not enough since the \f(CW\*(C`use constant\*(C'\fR is at \f(CW\*(C`BEGIN\*(C'\fR time, before plain code. .PP .Vb 2 \& require 5.006; # doesn\*(Aqt run early enough \& use constant _FOO => 123; # bad .Ve .PP But a \f(CW\*(C`require\*(C'\fR within a \f(CW\*(C`BEGIN\*(C'\fR block is ok (an older style, still found occasionally). .PP .Vb 2 \& BEGIN { require 5.006 } \& use constant _FOO => 123; # ok \& \& BEGIN { \& require 5.006; \& and_other_setups ...; \& } \& use constant _FOO => 123; # ok .Ve .PP Currently ConstantLeadingUnderscore pays no attention to any conditionals within the \f(CW\*(C`BEGIN\*(C'\fR, it assumes any \f(CW\*(C`require\*(C'\fR there always runs. It might be tricked by obscure tests but hopefully anything like that is rare. .PP A quoted version number like .PP .Vb 1 \& use constant \*(Aq1.02\*(Aq; # no good .Ve .PP is no good, only a bare number is recognised by the \f(CW\*(C`use\*(C'\fR statement. A string like that in fact goes through to \f(CW\*(C`constant\*(C'\fR as a name to define (which it will reject). .PP Leading underscores in the multi-constant hash are not flagged, since if you've got multi-constants then you've got underscores. See Compatibility::ConstantPragmaHash for checking multi-constants. .PP .Vb 1 \& use constant { _FOO => 1 }; # not checked .Ve .PP Leading double-underscore is disallowed by all versions of \f(CW\*(C`constant.pm\*(C'\fR. That's not reported by this policy since the code won't run at all. .PP .Vb 1 \& use constant _\|_FOO = 123; # not allowed by any constant.pm .Ve .SS "Drawbacks" .IX Subsection "Drawbacks" Explicitly adding required version numbers in the code can be irritating, especially if other things you're using only run on 5.6 up anyway. But declaring what code needs is accurate, it allows maybe for backports of modules, and explicit versions can be grepped out to create or check \&\fIMakefile.PL\fR or \fIBuild.PL\fR prereqs. .PP As always if you don't care about this and in particular if you only ever use Perl 5.6 anyway then you can disable \f(CW\*(C`ConstantLeadingUnderscore\*(C'\fR from your \fI.perlcriticrc\fR in the usual way (see \&\*(L"\s-1CONFIGURATION\*(R"\s0 in Perl::Critic), .PP .Vb 1 \& [\-Compatibility::ConstantLeadingUnderscore] .Ve .SH "OTHER WAYS TO DO IT" .IX Header "OTHER WAYS TO DO IT" It's easy to write your own constant subr and it can have any name at all (anything acceptable to Perl), bypassing the sanity checks or restrictions in \f(CW\*(C`constant.pm\*(C'\fR. Only the \f(CW\*(C`()\*(C'\fR prototype is a bit obscure. .PP .Vb 1 \& sub _FOO () { return 123 } .Ve .PP The key benefit of subs like this, whether from \f(CW\*(C`constant.pm\*(C'\fR or explicitly, is that the value is inlined and can be constant-folded in an arithmetic expression etc (see \*(L"Constant Functions\*(R" in perlsub). .PP .Vb 1 \& print 2*_FOO; # folded to 246 at compile\-time .Ve .PP The purpose of a leading underscore is normally a hint that the sub is meant to be private to the module and/or its friends. If you don't need the constant folding then a \f(CW\*(C`my\*(C'\fR scalar is even more private, being invisible to anything outside the relevant scope, .PP .Vb 3 \& my $FOO = 123; # more private \& # ... \& do_something ($FOO); # nothing to constant\-fold anyway .Ve .PP The scalar from a constant sub is flagged read-only, which might prevent accidental when passed around. The \f(CW\*(C`Readonly\*(C'\fR module can have a similar effect on scalars. If you've got \f(CW\*(C`Readonly::XS\*(C'\fR then it's just a flag too (no performance penalty on using the value). .PP .Vb 2 \& use Readonly; \& Readonly::Scalar my $FOO => 123; .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" Perl::Critic::Pulp, Perl::Critic, Perl::Critic::Policy::Compatibility::ConstantPragmaHash, Perl::Critic::Policy::ValuesAndExpressions::ProhibitConstantPragma, Perl::Critic::Policy::Modules::RequirePerlVersion .PP \&\*(L"Constant Functions\*(R" in perlsub .SH "HOME PAGE" .IX Header "HOME PAGE" .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017 Kevin Ryde .PP Perl-Critic-Pulp is free software; you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version. .PP Perl-Critic-Pulp is distributed in the hope that it will be useful, but \&\s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See the \s-1GNU\s0 General Public License for more details. .PP You should have received a copy of the \s-1GNU\s0 General Public License along with Perl-Critic-Pulp. If not, see .