.perlcriticrc

# perlcritic is a useful tool for locating potentially 'dodgy' coding.
# This file customizes it to the specific needs of Perl::Tidy.

# Some useful links:
# https://manpages.ubuntu.com/manpages/xenial/man1/perlcritic.1p.html
# https://perlmaven.com/perl-critic

# Example command to run a single policy on single module:
# perlcritic --single-policy Subroutines::ProhibitSubroutinePrototypes Module.pm

# I have found that using 'no critic' comments is much too troublesome, so
# non-configurable policies are either 'on' or 'off'.  

# severity = 1 gives the most strict checking.
severity = 1

verbose = %f: [%p] %m at line %l, column %c.\n

#--------------------------------------------------------------
# Following is a list of policies to be skipped for severity=4:
#--------------------------------------------------------------

# There is a localization in Tokenizer.pm that is essential
[-Variables::ProhibitLocalVars] 

# Immediate initialization of locals is not appropriate where used
# in the Tokenizer.pm module
[-Variables::RequireInitializationForLocalVars] 

# There is a stringy eval in Formatter.pm and Tokenizer.pm which is essential
# for checking user input. So we have to skip this.  I would have liked
# to mark it with a nocritic side comment, but see note above for the trouble
# this causes.
[-BuiltinFunctions::ProhibitStringyEval]

# Tidy.pm exports 'perltidy'. Changing this could break existing scripts.
[-Modules::ProhibitAutomaticExportation]

# 'print' and 'close' homonyms are appropriate where they are used.
[-Subroutines::ProhibitBuiltinHomonyms]

# Nested subs are used for error handling in Tidy.pm.
[-Subroutines::ProhibitNestedSubs]

# Don't require arg unpacking for very short (possibly time-critical) subs.
[Subroutines::RequireArgUnpacking]
short_subroutine_statements = 2

# The advantages of 'use constant' greatly outweigh the
# few disadvantages.  Perl::Tidy relies heavily on constants for efficient and
# robust coding of array indexes and debug code, and to avoid autovivication
# problems that would occur if hashes were used instead.
[-ValuesAndExpressions::ProhibitConstantPragma]

# Completely Disagree: adding quotes on here doc terminators causes needless
# "line noise" in the source code.  Almost always the default works.  Besides,
# my editor uses color to make it clear if interpolation is in effect.
[-ValuesAndExpressions::RequireQuotedHeredocTerminator]

# Perlcritic doesn't know that ARGV in Perl::Tidy actually is localized
[-Variables::RequireLocalizedPunctuationVars]

# Unfortunately the perlcritic coding for this policy is buggy when lines=n is
# specified.  For example if I use lines=n to increase 'n' above the default of
# 9, then suddenly I get error messages for code which previously passed with
# the default. So we have to skip this.
[-InputOutput::RequireBriefOpen]

#--------------------------------------------------------------
# Following is a list of policies to be skipped for severity=3:
#--------------------------------------------------------------

# AUTOLOAD is used in perltidy to help find and debug programming errors.
# This is very useful, so we have to skip this.
[-ClassHierarchies::ProhibitAutoloading]

# This policy is very useful in locating complex code which might benefit from
# simplification.  The max value has to be set rather high here because there
# are some critical loops in Formatter.pm whose high mccabe values cannot
# be reduced without significantly increasing run time.
[Subroutines::ProhibitExcessComplexity]
max_mccabe=180

# This policy can be very helpful for locating complex code, but sometimes
# deep nests are the best option, especially in error handling and debug
# coding. So a large value is used here.
[ControlStructures::ProhibitDeepNests]
max_nests=9

# The if-elsif sequences in perltidy have all been profiled and
# are fine as is. Changing them would complicate the code without
# any benefit in reduced run time or clarity.
[-ControlStructures::ProhibitCascadingIfElse]

# This is a reasonable policy for new code but it is not worth changing
# debugged code for it.
[-ControlStructures::ProhibitNegativeExpressionsInUnlessAndUntilConditions]

# This is a good general policy but not always the best for efficiency
[-Subroutines::ProhibitManyArgs]

[-ClassHierarchies::ProhibitExplicitISA]

# These are okay where used
[-NamingConventions::ProhibitAmbiguousNames]

# I find that using lvalue substr much clearer than adding another arg to
# substr.  So skip this one.
[-BuiltinFunctions::ProhibitLvalueSubstr]

# The Tokenizer.pm needs package variables
[-Variables::ProhibitPackageVars]

# These would be okay for new code, but do not change any debugged regular
# expressions without good reason.  It is too easy to introduce a subtle error.
[-RegularExpressions::RequireExtendedFormatting]
[-RegularExpressions::ProhibitComplexRegexes]
[-RegularExpressions::ProhibitUnusedCapture]
[-RegularExpressions::ProhibitCaptureWithoutTest]

#--------------------------------------------------------------
# Following is a list of policies to be skipped for severity=2:
#--------------------------------------------------------------

# Disagree. In fact, following this policy caused a parsing error in Perl
# version 5.14 at file test operators.  So skip this because it can cause
# loss of code robustness.
[-BuiltinFunctions::ProhibitUselessTopic]

# These would be okay for new code, but do not change any debugged regular
# expressions without good reason.  It is too easy to introduce a subtle error.
[-RegularExpressions::RequireDotMatchAnything]
[-RegularExpressions::RequireLineBoundaryMatching]

# Disagree. Is '#' really harder to read than q{#}?
[-ValuesAndExpressions::ProhibitNoisyQuotes]

# In some cases a postfix control shows the logical flow best
[-ControlStructures::ProhibitPostfixControls]

# Sometimes an unless statement is clearer than an if block, so why not use
# it?  For example, I might prefer the first of these:
#  return unless ($everything_is_ok);
# vs.
#  return if (!$everything_is_ok);
[-ControlStructures::ProhibitUnlessBlocks]

# The very few instances of boolean grep in Perl::Tidy are fine. Profiling
# shows that changing them would not result in a measureable improvement in
# speed.
[-BuiltinFunctions::ProhibitBooleanGrep] 

# The only escaped characters in Perl::Tidy are in code for detecting and
# setting line endings ( CR and LF ).  This is fully debugged coding and 
# best left unchanged.
[-ValuesAndExpressions::ProhibitEscapedCharacters] 

# This is a good general idea but has to be turned off because there are many
# cases where a number has been explained in a comment or is obvious.
[-ValuesAndExpressions::ProhibitMagicNumbers]

#--------------------------------------------------------------
# Following is a list of policies to be skipped for severity=1:
#--------------------------------------------------------------

# This is a good starting rule, but occasional capitalization can be quite
# effective or appropriate, so we have to ignore it as a general rule:
[-NamingConventions::Capitalization]

# It would be nice if this option were configurable to skip STDERR and STDOUT
# which are used by perltidy almost exclusively for debug statements.  I don't
# think {*STDOUT} is preferable to simply STDOUT. So skip it.
[-InputOutput::RequireBracedFileHandleWithPrint]

# PerlCritic should not suggest this policy for complex sorts because it can
# change program behavior when a stable sort has been assumed.  And it does not
# even make sense for sorts on multiple keys, like this one which got flagged
# in Perl::Tidy
#        @candidates =
#          sort { $b->[1] <=> $a->[1] || $a->[0] <=> $b->[0] } @candidates;
# Changing the first part requires changing the second part, so either way
# you have a comparison of the form $b->[*] <=> $a->[*]. So skip this.
[-BuiltinFunctions::ProhibitReverseSortBlock]

# These would be okay for new code, but do not change any debugged regular
# expressions without good reason.  It is too easy to introduce a subtle error.
[-RegularExpressions::ProhibitEscapedMetacharacters]
[-RegularExpressions::ProhibitEnumeratedClasses]
[-RegularExpressions::ProhibitUnusualDelimiters]
[-RegularExpressions::ProhibitSingleCharAlternation]
[-RegularExpressions::RequireBracesForMultiline]
[-RegularExpressions::ProhibitSingleCharAlternation]

# Disagree. Double quotes are easier to read than single quotes and allow a
# uniform style for quotes.  My editor has color coding which indicates
# interpolation. Double quotes do not increase processing time by any
# measurable amount.  Using them as default simplfies making editing changes.
# So skip this:
[-ValuesAndExpressions::ProhibitInterpolationOfLiterals]

# These have been checked and are correct as written 
[-ValuesAndExpressions::RequireInterpolationOfMetachars]

# Disagree: parens can add clarity and may even be essential, for example in
# ternary expressions. There is little to be gained by omitting them.
[-CodeLayout::ProhibitParensWithBuiltins] 

# This is OK if we exclude 'print'. Most of the 'print' statements
# in perltidy are for error reporting, and it does not help to add
# more extra error checks on top of them. 
[InputOutput::RequireCheckedSyscalls]
exclude_functions = print