Perl::Critic::Pulp(3)

NAME
Perl::Critic::Pulp - some add-on perlcritic policies

DESCRIPTION
This is a collection of add-on policies for "Perl::Critic". They're under a "pulp" theme plus other themes according to their purpose (see "POLICY THEMES" in Perl::Critic).

  Bugs

CodeLayout::ProhibitFatCommaNewline
    Avoid newline before "=>" not quoting.

CodeLayout::ProhibitIfIfSameLine
    Avoid "} if () {" perhaps meant to be "elsif".

Miscellanea::TextDomainPlaceholders
    Check keyword arguments to "__x()", "__nx()", etc.

Modules::ProhibitUseQuotedVersion
    Don't quote a version requirement like "use Foo '1.5'"

ValuesAndExpressions::RequireNumericVersion
    $VERSION plain number for comparisons and checking.

ValuesAndExpressions::ConstantBeforeLt
    Avoid problems with "FOO < 123"

ValuesAndExpressions::NotWithCompare
    Avoid problems with "! $x == $y"

ValuesAndExpressions::ProhibitArrayAssignAref
    Dubious "@array=[1,2,3]" array/arrayref assignments.

ValuesAndExpressions::ProhibitDuplicateHashKeys
    Duplicate literal keys "%h = (xyz=>123, xyz=>456)".

ValuesAndExpressions::ProhibitFiletest_f
    Don't use "-f".

ValuesAndExpressions::UnexpandedSpecialLiteral
    "__PACKAGE__" etc special words not expanding.

  Compatibility

Compatibility::ConstantPragmaHash
    Version requirement for hash style multi-constants.

Compatibility::ConstantLeadingUnderscore
    Version requirement for constants with leading underscore.

Compatibility::Gtk2Constants
    Gtk2 module version requirement for some constants.

Compatibility::PerlMinimumVersionAndWhy
    Perl version declared against features used.

Compatibility::PodMinimumVersion
    Perl version declared against POD features used.

Compatibility::ProhibitUnixDevNull
    Prefer "File::Spec->devnull" over /dev/null.

  Efficiency

Documentation::RequireEndBeforeLastPod
    Put "__END__" before POD at end of file.

Miscellanea::TextDomainUnused
    "Locale::TextDomain" imported but not used.

Modules::ProhibitPOSIXimport
    Don't import the whole of "POSIX".

  Cosmetic

CodeLayout::RequireTrailingCommaAtNewline
    Comma "," at the end of list, if at a newline.

CodeLayout::RequireFinalSemicolon
    Semicolon ";" on the last statement of a subroutine or block.

ValuesAndExpressions::ProhibitEmptyCommas
    Stray consecutive commas ",,"

ValuesAndExpressions::ProhibitNullStatements
    Stray semicolons ";"

ValuesAndExpressions::ProhibitUnknownBackslash
    Unknown "\z" etc escapes in strings.

ValuesAndExpressions::ProhibitBarewordDoubleColon
    Double-colon barewords "Foo::Bar::"

Modules::ProhibitModuleShebang
    No "#!" interpreter line in .pm files.

  Documentation

Documentation::ProhibitUnbalancedParens
    Unbalanced or mismatched ( ) parens, brackets and braces.

Documentation::ProhibitAdjacentLinks
    Put commas or some text between adjacent "L<>" links.

Documentation::ProhibitDuplicateHeadings
    Don't duplicate "=head" headings.

Documentation::ProhibitDuplicateSeeAlso
    Don't duplicate "L<>" links in SEE ALSO sections.

Documentation::ProhibitBadAproposMarkup
    Avoid "C<>" in NAME section, bad for man's "apropos" output.

Documentation::RequireFilenameMarkup
    Markup /foo filenames.

Documentation::ProhibitLinkToSelf
    Don't "L<>" link to the document itself.

Documentation::ProhibitParagraphEndComma
    Don't end paragraph with "," comma.

Documentation::ProhibitParagraphTwoDots
    Don't end paragraph with ".." (stray extra dot).

Documentation::ProhibitVerbatimMarkup
    Verbatim paragraphs not expanding "C<>" etc markup.

Documentation::RequireFinalCut
    Have a "=cut" at end of file.

Documentation::RequireLinkedURLs
    Use "L<>" markup on URLs.

  Selecting
You can always enable or disable the policies you do or don't want (see "CONFIGURATION" in Perl::Critic). You may have already realized that there's a wide range of builtin and add-on perlcritic policies ranging from buggy practice to deliberately restrictive or even quite bizarre. You're not meant to pass everything. Some policies may even be mutually contradictory.

The restrictive policies are meant as building blocks for a house style. For example "ProhibitBarewordDoubleColon" here, or something like "ProhibitUnlessBlocks". They're usually a matter of personal preference, and "non de gustibus disputandum" as they say in the classics. Trying to follow all such policies would give away big parts of the language and quite likely result in very un-typical code.

Some of the restrictive policies are geared towards beginners. "ProhibitUnknownBackslash" here or "RequireInitializationForLocalVars" are along those lines. There might for instance be good backslashing which the prohibition doesn't recognise, or local variable initializers make no sense for output variables like $!, once you get to the level of knowing to use "local" to preserve such globals.

In general the POD of each policy is supposed to explain the motivation so you can see whether you want it or not. If you're not turning off or drastically customizing at least half of all policies then you're either not trying or you're much too easily lead!

OTHER NOTES
In most of the perlcritic documentation, including the Pulp add-ons here, policy names appear without the full "Perl::Critic::Policy::..." class part. In Emacs try "man-completion.el" to make "M-x man" automatically expand a suffix part at point, or "ffap-perl-module.el" for the same to go to the source.

•   <http://user42.tuxfamily.org/man-completion/index.html>

•   <http://user42.tuxfamily.org/ffap-perl-module/index.html>

In perlcritic's output you can ask for %P to see the full policy package name to run "perldoc" or copy or follow etc. Here's a good output format you can put in your .perlcriticrc. The file:line:column: part is a style Emacs will recognise.

    verbose=%f:%l:%c:\n %P\n %m\n

See Perl::Critic::Violation for all available "%" escapes. "perlcritic.el" which comes with perlcritic has regexp patterns for Emacs to recognise the builtin perlcritic formats, but it's easier to output "file:line:column:" in the first place.

SEE ALSO
Perl::Critic

HOME PAGE
<http://user42.tuxfamily.org/perl-critic-pulp/index.html>

COPYRIGHT
Copyright 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2021 Kevin Ryde

Perl-Critic-Pulp is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Perl-Critic-Pulp is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Perl-Critic-Pulp. If not, see <http://www.gnu.org/licenses/>.