.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Perl::Critic::Policy::Compatibility::PerlMinimumVersionAndWhy 3pm"
.TH Perl::Critic::Policy::Compatibility::PerlMinimumVersionAndWhy 3pm "2021-02-28" "perl v5.32.1" "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::PerlMinimumVersionAndWhy \- explicit Perl version for features used
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This policy is part of the \f(CW\*(C`Perl::Critic::Pulp\*(C'\fR
add-on.  It requires that you have an explicit \f(CW\*(C`use 5.XXX\*(C'\fR etc for the Perl
syntax features you use, as determined by
\&\f(CW\*(C`Perl::MinimumVersion\*(C'\fR.
.PP
.Vb 2
\&    use 5.010;       # the // operator is new in perl 5.010
\&    print $x // $y;  # ok
.Ve
.PP
If you don't have the \f(CW\*(C`Perl::MinimumVersion\*(C'\fR module then nothing is
reported.  Certain nasty hacks are used to extract reasons and locations
from \f(CW\*(C`Perl::MinimumVersion\*(C'\fR.
.PP
This policy is under the \*(L"compatibility\*(R" theme (see \*(L"\s-1POLICY
THEMES\*(R"\s0 in Perl::Critic).  Its best use is when it picks up things like \f(CW\*(C`//\*(C'\fR or \f(CW\*(C`qr\*(C'\fR which
are only available in a newer Perl than you meant to target.
.PP
An explicit \f(CW\*(C`use 5.xxx\*(C'\fR can be a little tedious, but has the advantage of
making it clear what's needed (or supposed to be needed) and it gives a good
error message if run on an older Perl.
.SS "Disabling"
.IX Subsection "Disabling"
The config options below let you limit how far back to go.  Or if you don't
care at all about this sort of thing you can always disable the policy
completely from your \fI~/.perlcriticrc\fR file in the usual way (see
\&\*(L"\s-1CONFIGURATION\*(R"\s0 in Perl::Critic),
.PP
.Vb 1
\&    [\-Compatibility::PerlMinimumVersionAndWhy]
.Ve
.SS "MinimumVersion Mangling"
.IX Subsection "MinimumVersion Mangling"
Some mangling is applied to what \f(CW\*(C`Perl::MinimumVersion\*(C'\fR normally reports
(as of its version 1.28).
.IP "\(bu" 4
A multi-constant hash with the \f(CW\*(C`constant\*(C'\fR module is not
reported, since that's covered better by
Compatibility::ConstantPragmaHash.
.IP "\(bu" 4
Module requirements for things like \f(CW\*(C`use Errno\*(C'\fR are dropped, since you
might get a back-port from \s-1CPAN\s0 etc and the need for a module is better
expressed in a distribution \*(L"prereq\*(R".
.Sp
But pragma modules like \f(CW\*(C`use warnings\*(C'\fR are still reported.  They're
normally an interface to a feature new in the Perl version it comes with and
can't be back-ported.  (See \*(L"\s-1OTHER NOTES\*(R"\s0 below too.)
.SS "MinimumVersion Extras"
.IX Subsection "MinimumVersion Extras"
The following extra checks are added to \f(CW\*(C`Perl::MinimumVersion\*(C'\fR.
.IP "5.12 for" 4
.IX Item "5.12 for"
.RS 4
.PD 0
.IP "\(bu" 4
.PD
new \f(CW\*(C`keys @array\*(C'\fR, \f(CW\*(C`values @array\*(C'\fR and \f(CW\*(C`each @array\*(C'\fR
.RE
.RS 4
.RE
.IP "5.10 for" 4
.IX Item "5.10 for"
.RS 4
.PD 0
.IP "\(bu" 4
.PD
\&\f(CW\*(C`qr//m\*(C'\fR, since \*(L"m\*(R" modifier doesn't propagate correctly on a \f(CW\*(C`qr\*(C'\fR until
5.10
.IP "\(bu" 4
\&\f(CW\*(C`\-e \-f \-x\*(C'\fR stacked filetest operators.
.IP "\(bu" 4
\&\f(CW\*(C`pack()\*(C'\fR new \f(CW\*(C`<\*(C'\fR and \f(CW\*(C`>\*(C'\fR endianness.
.IP "\(bu" 4
new \f(CW\*(C`UNIVERSAL.pm\*(C'\fR method \f(CW\*(C`DOES()\*(C'\fR
.RE
.RS 4
.RE
.IP "5.8 for" 4
.IX Item "5.8 for"
.RS 4
.PD 0
.IP "\(bu" 4
.PD
new \f(CW\*(C`word [newline] =>\*(C'\fR fat comma quoting across a newline
.Sp
For earlier Perl \f(CW\*(C`word\*(C'\fR ended up a function call.  It's presumed such code
is meant to quote in the 5.8 style, and thus requires 5.8 or higher.
.IP "\(bu" 4
\&\f(CW\*(C`eval \*(Aq#line ...\*(Aq\*(C'\fR with \f(CW\*(C`#line\*(C'\fR the very first thing
.Sp
In earlier Perl a \f(CW\*(C`#line\*(C'\fR as the very first thing in an \f(CW\*(C`eval\*(C'\fR doesn't
take effect.  Adding a blank line so it's not first is enough.
.IP "\(bu" 4
\&\f(CW\*(C`pack()\*(C'\fR new \f(CW\*(C`F\*(C'\fR native \s-1NV,\s0 \f(CW\*(C`D\*(C'\fR long double, \f(CW\*(C`i\*(C'\fR \s-1IV,\s0 \f(CW\*(C`j\*(C'\fR \s-1UV,\s0 \f(CW\*(C`()\*(C'\fR
group, \f(CW\*(C`[]\*(C'\fR repeat count
.RE
.RS 4
.RE
.IP "5.6 for" 4
.IX Item "5.6 for"
.RS 4
.PD 0
.IP "\(bu" 4
.PD
new \f(CW\*(C`exists &subr\*(C'\fR, \f(CW\*(C`exists $array[0]\*(C'\fR and \f(CW\*(C`delete $array[0]\*(C'\fR
.IP "\(bu" 4
new \f(CW\*(C`0b110011\*(C'\fR binary number literals
.IP "\(bu" 4
new \f(CW\*(C`open(my $fh,...)\*(C'\fR etc auto-creation of filehandle
.IP "\(bu" 4
\&\f(CW\*(C`syswrite()\*(C'\fR length parameter optional
.IP "\(bu" 4
\&\f(CW\*(C`Foo\->$method\*(C'\fR no-args call without parens
.Sp
For earlier Perl a no-args call to a method named in a variable must be
\&\f(CW\*(C`Foo\->$method()\*(C'\fR.  The parens are optional in 5.6 up.
.IP "\(bu" 4
\&\f(CW\*(C`pack()\*(C'\fR new \f(CW\*(C`Z\*(C'\fR asciz, \f(CW\*(C`q\*(C'\fR,\f(CW\*(C`Q\*(C'\fR quads, \f(CW\*(C`!\*(C'\fR native size, \f(CW\*(C`/\*(C'\fR counted
string, \f(CW\*(C`#\*(C'\fR comment
.RE
.RS 4
.RE
.IP "5.005 for" 4
.IX Item "5.005 for"
.RS 4
.PD 0
.IP "\(bu" 4
.PD
new \f(CW\*(C`Foo::Bar::\*(C'\fR double-colon package name quoting
.IP "\(bu" 4
new \f(CW\*(C`my ($x, undef, $y) = @values\*(C'\fR, using \f(CW\*(C`undef\*(C'\fR as a dummy in a \f(CW\*(C`my\*(C'\fR
list
.RE
.RS 4
.RE
.IP "5.004 for" 4
.IX Item "5.004 for"
.RS 4
.PD 0
.IP "\(bu" 4
.PD
new \f(CW\*(C`use 5.xxx\*(C'\fR Perl version check through \f(CW\*(C`use\*(C'\fR.  For earlier Perl it can
be \f(CW\*(C`BEGIN { require 5.000 }\*(C'\fR etc
.IP "\(bu" 4
new \f(CW\*(C`_\|_PACKAGE_\|_\*(C'\fR special literal
.IP "\(bu" 4
new \f(CW\*(C`foreach my $foo\*(C'\fR lexical loop variable
.IP "\(bu" 4
new \f(CW\*(C`$coderef\->()\*(C'\fR call with \f(CW\*(C`\->\*(C'\fR
.IP "\(bu" 4
new \f(CW\*(C`sysseek()\*(C'\fR builtin function
.IP "\(bu" 4
\&\f(CW\*(C`pack()\*(C'\fR new \f(CW\*(C`w\*(C'\fR \s-1BER\s0 integer
.IP "\(bu" 4
new \f(CW\*(C`UNIVERSAL.pm\*(C'\fR with \f(CW\*(C`VERSION()\*(C'\fR, \f(CW\*(C`isa()\*(C'\fR and \f(CW\*(C`can()\*(C'\fR methods
.RE
.RS 4
.RE
.PP
\&\f(CW\*(C`pack()\*(C'\fR and \f(CW\*(C`unpack()\*(C'\fR format strings are only checked if they're literal
strings or here-documents without interpolations, or \f(CW\*(C`.\*(C'\fR operator concats
of those.
.PP
The \f(CW\*(C`qr//m\*(C'\fR report concerns a misfeature fixed in perl 5.10.0 (see
perl5101delta).  In earlier versions a regexp like \f(CW\*(C`$re = qr/^x/m\*(C'\fR
within another regexp like \f(CW\*(C`/zz|$re/\*(C'\fR loses the \f(CW\*(C`/m\*(C'\fR attribute from
\&\f(CW$re\fR, changing the interpretation of the \f(CW\*(C`^\*(C'\fR (and \f(CW\*(C`$\*(C'\fR similarly).  Forms
like \f(CW\*(C`(\eA|\en)\*(C'\fR are a possible workaround, though are uncommon so may be a
little obscure.  \f(CW\*(C`RegularExpressions::RequireLineBoundaryMatching\*(C'\fR asks for
\&\f(CW\*(C`/m\*(C'\fR in all cases so if think you want that then you probably want Perl
5.10 or up for the fix too.
.ie n .SS """Modern::Perl"""
.el .SS "\f(CWModern::Perl\fP"
.IX Subsection "Modern::Perl"
\&\f(CW\*(C`use Modern::Perl\*(C'\fR is taken to mean Perl 5.10.  This is slightly
experimental and in principle the actual minimum it implies is forever
rising, and even now could be more, or depends on it date argument scheme.
Maybe if could say its actual current desire then an installed version could
be queried.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
.ie n .IP """above_version"" (version string, default none)" 4
.el .IP "\f(CWabove_version\fR (version string, default none)" 4
.IX Item "above_version (version string, default none)"
Set a minimum version of Perl you always use, so that reports are only about
things higher than this and higher than what the document declares.  The
value is anything the \f(CW\*(C`version.pm\*(C'\fR module can parse.
.Sp
.Vb 2
\&    [Compatibility::PerlMinimumVersionAndWhy]
\&    above_version = 5.006
.Ve
.Sp
For example if you always use Perl 5.6 and set 5.006 like this then you can
have \f(CW\*(C`our\*(C'\fR package variables without an explicit \f(CW\*(C`use 5.006\*(C'\fR.
.ie n .IP """skip_checks"" (list of check names, default none)" 4
.el .IP "\f(CWskip_checks\fR (list of check names, default none)" 4
.IX Item "skip_checks (list of check names, default none)"
Skip the given MinimumVersion checks (a space separated list).  The check
names are shown in the violation message and come from
\&\f(CW\*(C`Perl::MinimumVersion::CHECKS\*(C'\fR.  For example,
.Sp
.Vb 2
\&    [Compatibility::PerlMinimumVersionAndWhy]
\&    skip_checks = _some_thing _another_thing
.Ve
.Sp
This can be used for checks you believe are wrong, or where the
compatibility matter only affects limited circumstances which you
understand.
.Sp
The check names are likely to be a moving target, especially the Pulp
additions.  Unknown checks in the list are quietly ignored.
.SH "OTHER NOTES"
.IX Header "OTHER NOTES"
\&\f(CW\*(C`use warnings\*(C'\fR is reported as a Perl 5.6 feature since the lexically-scoped
fine grain warnings control it gives is new in that version.  If targeting
earlier versions then it's often enough to drop \f(CW\*(C`use warnings\*(C'\fR, ensure your
code runs cleanly under \f(CW\*(C`perl \-w\*(C'\fR, and leave it to applications to
use \f(CW\*(C`\-w\*(C'\fR (or set \f(CW$^W\fR) if they desire.
.PP
\&\f(CW\*(C`warnings::compat\*(C'\fR offers a \f(CW\*(C`use warnings\*(C'\fR for earlier Perl, but it's not
lexical, instead setting \f(CW$^W\fR globally.  In a script this might be an
alternative to \f(CW\*(C`#!/usr/bin/perl \-w\*(C'\fR (per perlrun), but in a module
it's probably not a good idea to change global settings.
.PP
The \f(CW\*(C`UNIVERSAL.pm\*(C'\fR methods \f(CW\*(C`VERSION()\*(C'\fR, \f(CW\*(C`isa()\*(C'\fR, \f(CW\*(C`can()\*(C'\fR or \f(CW\*(C`DOES()\*(C'\fR
might in principle be implemented explicitly by a particular class, but it's
assumed that's not so and that any call to those requires the respective
minimum Perl version.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Perl::Critic::Pulp,
Perl::Critic
.PP
Perl::Critic::Policy::Modules::PerlMinimumVersion, which is similar, but
compares against a Perl version configured in your \fI~/.perlcriticrc\fR rather
than a version in the document.
.PP
Perl::Critic::Policy::Modules::RequirePerlVersion
.SH "HOME PAGE"
.IX Header "HOME PAGE"
<http://user42.tuxfamily.org/perl\-critic\-pulp/index.html>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2019, 2021 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 <http://www.gnu.org/licenses/>.