1PERLCRITIC(1)         User Contributed Perl Documentation        PERLCRITIC(1)
2
3
4

NAME

6       "perlcritic" - Command-line interface to critique Perl source.
7

SYNOPSIS

9         perlcritic [-12345 | --brutal | --cruel | --harsh | --stern | --gentle]
10                    [--severity number | name] [{-p | --profile} file | --noprofile]
11                    [--top [ number ]] [--theme expression] [--include pattern]
12                    [--exclude pattern] [{-s | --single-policy} pattern]
13                    [--only | --noonly] [--profile-strictness {warn|fatal|quiet}]
14                    [--force | --noforce] [--statistics] [--statistics-only]
15                    [--count | -C] [--verbose {number | format}]
16                    [--color | --nocolor] [--pager pager] [--quiet]
17                    [--color-severity-highest color_specification]
18                    [--color-severity-high color_specification]
19                    [--color-severity-medium color_specification]
20                    [--color-severity-low color_specification]
21                    [--color-severity-lowest color_specification]
22                    [--files-with-violations | -l]
23                    [--files-without-violations | -L]
24                    {FILE | DIRECTORY | STDIN}
25
26         perlcritic --profile-proto
27
28         perlcritic { --list | --list-enabled | --list-themes | --doc pattern [...] }
29
30         perlcritic { --help | --options | --man | --version }
31

DESCRIPTION

33       "perlcritic" is a Perl source code analyzer.  It is the executable
34       front-end to the Perl::Critic engine, which attempts to identify
35       awkward, hard to read, error-prone, or unconventional constructs in
36       your code.  Most of the rules are based on Damian Conway's book Perl
37       Best Practices.  However, "perlcritic" is not limited to enforcing PBP,
38       and it will even support rules that contradict Conway.  All rules can
39       easily be configured or disabled to your liking.
40
41       This documentation only covers how to drive this command.  For all
42       other information, including how to persistently configure this command
43       so that you don't have to say so much on the command-line, see the
44       documentation for Perl::Critic itself.
45

USAGE EXAMPLES

47       Before getting into all the gory details, here are some basic usage
48       examples to help get you started.
49
50           # Report only most severe violations (severity = 5)
51           perlcritic YourModule.pm
52
53           # Same as above, but read input from STDIN
54           perlcritic
55
56           # Recursively process all Perl files beneath directory
57           perlcritic /some/directory
58
59           # Report slightly less severe violations too (severity >= 4)
60           perlcritic -4 YourModule.pm
61
62           # Same as above, but using named severity level
63           perlcritic --stern YourModule.pm
64
65           # Report all violations, regardless of severity (severity >= 1)
66           perlcritic -1 YourModule.pm
67
68           # Same as above, but using named severity level
69           perlcritic --brutal YourModule.pm
70
71           # Report only violations of things from "Perl Best Practices"
72           perlcritic --theme pbp YourModule.pm
73
74           # Report top 20 most severe violations (severity >= 1)
75           perlcritic --top YourModule.pm
76
77           # Report additional violations of Policies that match m/variables/xms
78           perlcritic --include variables YourModule.pm
79
80           # Use defaults from somewhere other than ~/.perlcriticrc
81           perlcriticrc --profile project/specific/perlcriticrc YourModule.pm
82

ARGUMENTS

84       The arguments are paths to the files you wish to analyze.  You may
85       specify multiple files.  If an argument is a directory, "perlcritic"
86       will analyze all Perl files below the directory.  If no arguments are
87       specified, then input is read from STDIN.
88

OPTIONS

90       Option names can be abbreviated to uniqueness and can be stated with
91       singe or double dashes, and option values can be separated from the
92       option name by a space or '=' (as with Getopt::Long).  Option names are
93       also case-sensitive.
94
95       "--profile FILE" or "-p FILE"
96           Directs "perlcritic" to use a profile named by FILE rather than
97           looking for the default .perlcriticrc file in the current directory
98           or your home directory.  See "CONFIGURATION" in Perl::Critic for
99           more information.
100
101       "--noprofile"
102           Directs "perlcritic" not to load any configuration file, thus
103           reverting to the default configuration for all Policies.
104
105       "--severity N"
106           Directs "perlcritic" to only apply Policies with a severity greater
107           than "N".  Severity values are integers ranging from 1 (least
108           severe) to 5 (most severe).  The default is 5.  For a given
109           "--profile", decreasing the "--severity" will usually produce more
110           violations.  You can set the default value for this option in your
111           .perlcriticrc file.  You can also redefine the "severity" for any
112           Policy in your .perlcriticrc file.  See "CONFIGURATION" for more
113           information.
114
115       "-5 | -4 | -3 | -2 | -1"
116           These are numeric shortcuts for setting the "--severity" option.
117           For example, "-4" is equivalent to "--severity 4".  If multiple
118           shortcuts are specified, then the most restrictive one wins.  If an
119           explicit "--severity" option is also given, then all shortcut
120           options are silently ignored.  NOTE: Be careful not to put one of
121           the number severity shortcut options immediately after the "--top"
122           flag or "perlcritic" will interpret it as the number of violations
123           to report.
124
125       "--severity NAME"
126           If it is difficult for you to remember whether severity "5" is the
127           most or least restrictive level, then you can use one of these
128           named values:
129
130               SEVERITY NAME   ...is equivalent to...   SEVERITY NUMBER
131               --------------------------------------------------------
132               --severity gentle                           --severity 5
133               --severity stern                            --severity 4
134               --severity harsh                            --severity 3
135               --severity cruel                            --severity 2
136               --severity brutal                           --severity 1
137
138       "--gentle | --stern | --harsh | --cruel | --brutal"
139           These are named shortcuts for setting the "--severity" option.  For
140           example, "--cruel" is equivalent to "--severity 2".  If multiple
141           shortcuts are specified, then the most restrictive one wins.  If an
142           explicit "--severity" option is also given, then all shortcut
143           options are silently ignored.
144
145       "--theme RULE"
146           Directs "perlcritic" to apply only Policies with themes that
147           satisfy the "RULE".  Themes are arbitrary names for groups of
148           related policies.  You can combine theme names with boolean
149           operators to create an arbitrarily complex "RULE".  For example,
150           the following would apply only Policies that have a 'bugs' AND
151           'pbp' theme:
152
153               $> perlcritic --theme='bugs && pbp' MyModule.pm
154
155           Unless the "--severity" option is explicitly given, setting
156           "--theme" silently causes the "--severity" to be set to 1.  You can
157           set the default value for this option in your .perlcriticrc file.
158           See "POLICY THEMES" in Perl::Critic for more information about
159           themes.
160
161       "--include PATTERN"
162           Directs "perlcritic" to apply additional Policies that match the
163           regex "/PATTERN/imx".  Use this option to temporarily override your
164           profile and/or the severity settings at the command-line.  For
165           example:
166
167               perlcritic --include=layout my_file.pl
168
169           This would cause "perlcritic" to apply all the "CodeLayout::*"
170           policies even if they have a severity level that is less than the
171           default level of 5, or have been disabled in your .perlcriticrc
172           file.  You can specify multiple "--include" options and you can use
173           it in conjunction with the "--exclude" option.  Note that
174           "--exclude" takes precedence over "--include" when a Policy matches
175           both patterns.  You can set the default value for this option in
176           your .perlcriticrc file.
177
178       "--exclude PATTERN"
179           Directs "perlcritic" to not apply any Policy that matches the regex
180           "/PATTERN/imx".  Use this option to temporarily override your
181           profile and/or the severity settings at the command-line.  For
182           example:
183
184               perlcritic --exclude=strict my_file.pl
185
186           This would cause "perlcritic" to not apply the "RequireUseStrict"
187           and "ProhibitNoStrict" Policies even though they have the highest
188           severity level.  You can specify multiple "--exclude" options and
189           you can use it in conjunction with the "--include" option.  Note
190           that "--exclude" takes precedence over "--include" when a Policy
191           matches both patterns.  You can set the default value for this
192           option in your .perlcriticrc file.
193
194       "--single-policy PATTERN" or "-s PATTERN"
195           Directs "perlcritic" to apply just one Policy module matching the
196           regex "/PATTERN/ixms", and exclude all other Policies.  This option
197           has precedence over the "--severity", "--theme", "--include",
198           "--exclude", and "--only" options.  For example:
199
200               perlcritic --single-policy=nowarnings my_file.pl
201
202           This would cause "perlcritic" to apply just the
203           "ProhibitNoWarnings" Policy, regardless of the severity level
204           setting.  No other Policies would be applied.
205
206           This is equivalent to what one might intend by...
207
208               perlcritic --exclude=. --include=nowarnings my_file.pl
209
210           ... but this won't work because the "--exclude" option overrides
211           the "--include" option.
212
213           The equivalent of this option can be accomplished by creating a
214           custom profile containing only the desired policy and then
215           running...
216
217               perlcritic --profile=customprofile --only my_file.pl
218
219       "--top [ N ]"
220           Directs "perlcritic" to report only the top "N" Policy violations
221           in each file, ranked by their severity.  If "N" is not specified,
222           it defaults to 20.  If the "--severity" option (or one of the
223           shortcuts) is not explicitly given, the "--top" option implies that
224           the minimum severity level is "1" (i.e. "brutal"). Users can
225           redefine the severity for any Policy in their .perlcriticrc file.
226           See "CONFIGURATION" for more information.  You can set the default
227           value for this option in your .perlcriticrc file.  NOTE: Be careful
228           not to put one of the severity shortcut options immediately after
229           the "--top" flag or "perlcritic" will interpret it as the number of
230           violations to report.
231
232       "--force"
233           Directs "perlcritic" to ignore the magical "## no critic"
234           annotations in the source code. See "BENDING THE RULES" for more
235           information.  You can set the default value for this option in your
236           .perlcriticrc file.
237
238       "--statistics"
239           Causes several statistics about the code being scanned and the
240           violations found to be reported after any other output.
241
242       "--statistics-only"
243           Like the "--statistics" option, but suppresses normal output and
244           only shows the statistics.
245
246       "--verbose N | FORMAT"
247           Sets the verbosity level or format for reporting violations.  If
248           given a number ("N"), "perlcritic" reports violations using one of
249           the predefined formats described below.  If given a string
250           ("FORMAT"), it is interpreted to be an actual format specification.
251           If the "--verbose" option is not specified, it defaults to either 4
252           or 5, depending on whether multiple files were given as arguments
253           to "perlcritic".  You can set the default value for this option in
254           your .perlcriticrc file.
255
256               Verbosity     Format Specification
257               -----------   -------------------------------------------------------
258                1            "%f:%l:%c:%m\n",
259                2            "%f: (%l:%c) %m\n",
260                3            "%m at %f line %l\n",
261                4            "%m at line %l, column %c.  %e.  (Severity: %s)\n",
262                5            "%f: %m at line %l, column %c.  %e.  (Severity: %s)\n",
263                6            "%m at line %l, near '%r'.  (Severity: %s)\n",
264                7            "%f: %m at line %l near '%r'.  (Severity: %s)\n",
265                8            "[%p] %m at line %l, column %c.  (Severity: %s)\n",
266                9            "[%p] %m at line %l, near '%r'.  (Severity: %s)\n",
267               10            "%m at line %l, column %c.\n  %p (Severity: %s)\n%d\n",
268               11            "%m at line %l, near '%r'.\n  %p (Severity: %s)\n%d\n"
269
270           Formats are a combination of literal and escape characters similar
271           to the way "sprintf" works.  See String::Format for a full
272           explanation of the formatting capabilities.  Valid escape
273           characters are:
274
275               Escape    Meaning
276               -------   ------------------------------------------------------------
277               %c        Column number where the violation occurred
278               %d        Full diagnostic discussion of the violation
279               %e        Explanation of violation or page numbers in PBP
280               %F        Just the name of the file where the violation occurred.
281               %f        Path to the file where the violation occurred.
282               %l        Line number where the violation occurred
283               %m        Brief description of the violation
284               %P        Full name of the Policy module that created the violation
285               %p        Name of the Policy without the Perl::Critic::Policy:: prefix
286               %r        The string of source code that caused the violation
287               %C        The class of the PPI::Element that caused the violation
288               %s        The severity level of the violation
289
290           The purpose of these formats is to provide some compatibility with
291           text editors that have an interface for parsing certain kinds of
292           input. See "EDITOR INTEGRATION" for more information about that.
293
294       "--list"
295           Displays a condensed listing of all the Perl::Critic::Policy
296           modules that are found on this machine.  This option lists all
297           Policies, regardless of your .perlcriticrc or command line options.
298           For each Policy, the name, default severity and default themes are
299           shown.
300
301       "--list-enabled"
302           Displays a condensed listing of all the Perl::Critic::Policy
303           modules that would be enforced, if you were actually going to
304           critique a file with this command.  This is useful when you've
305           constructed a complicated command or modified your .perlcriticrc
306           file and you want to see exactly which Policies are going to be
307           enforced (or not enforced, as the case may be). For each Policy,
308           the name, default severity and default themes are shown.
309
310       "--list-themes"
311           Displays a list of all the themes of the Perl::Critic::Policy
312           modules that are found on this machine.
313
314       "--profile-proto"
315           Displays an expanded listing of all the Perl::Critic::Policy
316           modules that are found on this machine.  For each Policy, the name,
317           default severity and default themes are shown, as well as the name
318           of any additional parameters that the Policy supports.  The format
319           is suitable as a prototype for your .perlcriticrc file.
320
321       "--only"
322           Directs perlcritic to apply only Policies that are explicitly
323           mentioned in your .perlcriticrc file.  This is useful if you want
324           to use just a small subset of Policies without having to disable
325           all the others.  You can set the default value for this option in
326           your .perlcriticrc file.
327
328       "--profile-strictness {warn|fatal|quiet}"
329           Directs perlcritic how to treat certain recoverable problems found
330           in a .perlcriticrc or file specified via the "--profile" option.
331           Valid values are "warn" (the default), "fatal", and "quiet".  For
332           example, perlcritic normally only warns about profiles referring to
333           non-existent Policies, but this option can make this situation
334           fatal.  You can set the default value for this option in your
335           .perlcriticrc file.
336
337       "--count"
338       "-C"
339           Display only the number of violations for each file.  Use this
340           feature to get a quick handle on where a large pile of code might
341           need the most attention.
342
343       "--Safari"
344           Report "Perl Best Practice" citations as section numbers from
345           <http://safari.oreilly.com> instead of page numbers from the actual
346           book.  NOTE: This feature is not implemented yet.
347
348       "--color"
349           This option is on when outputting to a tty.  When set, Severity 5
350           and 4 are colored red and yellow, respectively.  Colorization only
351           happens if Term::ANSIColor is installed and it only works on non-
352           Windows environments.  Negate this switch to disable color.  You
353           can set the default value for this option in your .perlcriticrc
354           file.
355
356           Can also be specified as "--colour".
357
358       "--pager PAGER_COMMAND_STRING"
359           If set, perlcritic will pipe it's output to the given
360           PAGER_COMMAND_STRING.  You can set the default value for this
361           option in your .perlcriticrc file.
362
363           Setting a pager turns off color by default.  You will have to turn
364           color on explicitly.  If you want color, you'll probably also want
365           to tell your pager to display raw characters.  For "less" and
366           "more", use the -R switch.
367
368       "--color-severity-highest COLOR_SPECIFICATION"
369           Specifies the color to be used for highest severity violations, as
370           a Term::ANSIColor color specification. Can also be specified as
371           "--colour-severity-highest", "--color-severity-5", or
372           "--colour-severity-5".
373
374       "--color-severity-high COLOR_SPECIFICATION"
375           Specifies the color to be used for high severity violations, as a
376           Term::ANSIColor color specification. Can also be specified as
377           "--colour-severity-high", "--color-severity-4", or
378           "--colour-severity-4".
379
380       "--color-severity-medium COLOR_SPECIFICATION"
381           Specifies the color to be used for medium severity violations, as a
382           Term::ANSIColor color specification. Can also be specified as
383           "--colour-severity-medium", "--color-severity-3", or
384           "--colour-severity-3".
385
386       "--color-severity-low COLOR_SPECIFICATION"
387           Specifies the color to be used for low severity violations, as a
388           Term::ANSIColor color specification. Can also be specified as
389           "--colour-severity-low", "--color-severity-2", or
390           "--colour-severity-2".
391
392       "--color-severity-lowest COLOR_SPECIFICATION"
393           Specifies the color to be used for lowest severity violations, as a
394           Term::ANSIColor color specification. Can also be specified as
395           "--colour-severity-lowest", "--color-severity-1", or
396           "--colour-severity-1".
397
398       "--files-with-violations"
399           Display only the names of files with violations.  Use this feature
400           with --single-policy to find files that contain violations of a
401           given policy. Can also be specified as "--l".
402
403       "--files-without-violations"
404           Display only the names of files without violations.  Use this
405           feature with --single-policy to find files that do not contain
406           violations of a given policy. Can also be specified as "--L".
407
408       "--doc PATTERN"
409           Displays the perldoc for all Perl::Critic::Policy modules that
410           match "m/PATTERN/ixms".  Since Policy modules tend to have rather
411           long names, this just provides a more convenient way to say
412           something like: "perldoc
413           Perl::Critic::Policy::ValuesAndExpressions::RequireUpperCaseHeredocTerminator"
414           at the command prompt.
415
416       "--quiet"
417           Suppress the "source OK" message when no violations are found.
418
419       "--help"
420       "-?"
421       "-H"
422           Displays a brief summary of options and exits.
423
424       "--options"
425           Displays the descriptions of the options and exits.  While this
426           output is long, it it nowhere near the length of the output of
427           "--man".
428
429       "--man"
430           Displays the complete "perlcritic" manual and exits.
431
432       "--version"
433       "-V"
434           Displays the version number of "perlcritic" and exits.
435

CONFIGURATION

437       Most of the settings for Perl::Critic and each of the Policy modules
438       can be controlled by a configuration file.  The default configuration
439       file is called .perlcriticrc.  "perlcritic" will look for this file in
440       the current directory first, and then in your home directory.
441       Alternatively, you can set the "PERLCRITIC" environment variable to
442       explicitly point to a different file in another location.  If none of
443       these files exist, and the "--profile" option is not given on the
444       command-line, then all Policies will be loaded with their default
445       configuration.
446
447       The format of the configuration file is a series of INI-style blocks
448       that contain key-value pairs separated by "=". Comments should start
449       with "#" and can be placed on a separate line or after the name-value
450       pairs if you desire.
451
452       Default settings for perlcritic itself can be set before the first
453       named block. For example, putting any or all of these at the top of
454       your .perlcriticrc file will set the default value for the
455       corresponding command-line argument.
456
457           severity  = 3                                     #Integer or named level
458           only      = 1                                     #Zero or One
459           force     = 0                                     #Zero or One
460           verbose   = 4                                     #Integer or format spec
461           top       = 50                                    #A positive integer
462           theme     = (pbp + security) * bugs               #A theme expression
463           include   = NamingConventions ClassHierarchies    #Space-delimited list
464           exclude   = Variables  Modules::RequirePackage    #Space-delimited list
465
466       The remainder of the configuration file is a series of blocks like
467       this:
468
469           [Perl::Critic::Policy::Category::PolicyName]
470           severity = 1
471           set_themes = foo bar
472           add_themes = baz
473           arg1 = value1
474           arg2 = value2
475
476       "Perl::Critic::Policy::Category::PolicyName" is the full name of a
477       module that implements the policy.  The Policy modules distributed with
478       Perl::Critic have been grouped into categories according to the table
479       of contents in Damian Conway's book Perl Best Practices. For brevity,
480       you can omit the 'Perl::Critic::Policy' part of the module name.
481
482       "severity" is the level of importance you wish to assign to the Policy.
483       All Policy modules are defined with a default severity value ranging
484       from 1 (least severe) to 5 (most severe).  However, you may disagree
485       with the default severity and choose to give it a higher or lower
486       severity, based on your own coding philosophy.  You can set the
487       "severity" to an integer from 1 to 5, or use one of the equivalent
488       names:
489
490           SEVERITY NAME ...is equivalent to... SEVERITY NUMBER
491           ----------------------------------------------------
492           gentle                                             5
493           stern                                              4
494           harsh                                              3
495           cruel                                              2
496           brutal                                             1
497
498       "set_themes" sets the theme for the Policy and overrides its default
499       theme.  The argument is a string of one or more whitespace-delimited
500       alphanumeric words.  Themes are case-insensitive.  See "POLICY THEMES"
501       for more information.
502
503       "add_themes" appends to the default themes for this Policy.  The
504       argument is a string of one or more whitespace-delimited words.  Themes
505       are case-insensitive.  See "POLICY THEMES" for more information.
506
507       The remaining key-value pairs are configuration parameters that will be
508       passed into the constructor of that Policy.  The constructors for most
509       Policy modules do not support arguments, and those that do should have
510       reasonable defaults.  See the documentation on the appropriate Policy
511       module for more details.
512
513       Instead of redefining the severity for a given Policy, you can
514       completely disable a Policy by prepending a '-' to the name of the
515       module in your configuration file.  In this manner, the Policy will
516       never be loaded, regardless of the "--severity" given on the command
517       line.
518
519       A simple configuration might look like this:
520
521           #--------------------------------------------------------------
522           # I think these are really important, so always load them
523
524           [TestingAndDebugging::RequireUseStrict]
525           severity = 5
526
527           [TestingAndDebugging::RequireUseWarnings]
528           severity = 5
529
530           #--------------------------------------------------------------
531           # I think these are less important, so only load when asked
532
533           [Variables::ProhibitPackageVars]
534           severity = 2
535
536           [ControlStructures::ProhibitPostfixControls]
537           allow = if unless  # My custom configuration
538           severity = cruel   # Same as "severity = 2"
539
540           #--------------------------------------------------------------
541           # Give these policies a custom theme.  I can activate just
542           # these policies by saying "perlcritic --theme 'larry || curly'"
543
544           [Modules::RequireFilenameMatchesPackage]
545           add_themes = larry
546
547           [TestingAndDebugging::RequireTestLabels]
548           add_themes = curly moe
549
550           #--------------------------------------------------------------
551           # I do not agree with these at all, so never load them
552
553           [-NamingConventions::Capitalization]
554           [-ValuesAndExpressions::ProhibitMagicNumbers]
555
556           #--------------------------------------------------------------
557           # For all other Policies, I accept the default severity,
558           # so no additional configuration is required for them.
559
560       Note that all policies included with the Perl::Critic distribution that
561       have integer parameters accept underscores ("_") in their values, as
562       with Perl numeric literals.  For example,
563
564           [ValuesAndExpressions::RequireNumberSeparators]
565           min_value = 1_000
566
567       For additional configuration examples, see the perlcriticrc file that
568       is included in this examples directory of this distribution.
569
570       Damian Conway's own Perl::Critic configuration is also included in this
571       distribution as examples/perlcriticrc-conway.
572

THE POLICIES

574       A large number of Policy modules are distributed with Perl::Critic.
575       They are described briefly in the companion document
576       Perl::Critic::PolicySummary and in more detail in the individual
577       modules themselves.  Say "perlcritic --doc PATTERN" to see the perldoc
578       for all Policy modules that match the regex "m/PATTERN/ixms"
579
580       There are a number of distributions of additional policies on CPAN.  If
581       Perl::Critic doesn't contain a policy that you want, some one may have
582       already written it.  See "SEE ALSO" in Perl::Critic for a list of some
583       of these distributions.
584

POLICY THEMES

586       Each Policy is defined with one or more "themes".  Themes can be used
587       to create arbitrary groups of Policies.  They are intended to provide
588       an alternative mechanism for selecting your preferred set of Policies.
589       For example, you may wish disable a certain set of Policies when
590       analyzing test scripts.  Conversely, you may wish to enable only a
591       specific subset of Policies when analyzing modules.
592
593       The Policies that ship with Perl::Critic are have been divided into the
594       following themes.  This is just our attempt to provide some basic
595       logical groupings.  You are free to invent new themes that suit your
596       needs.
597
598           THEME             DESCRIPTION
599           ------------------------------------------------------------------------
600           core              All policies that ship with Perl::Critic
601           pbp               Policies that come directly from "Perl Best Practices"
602           bugs              Policies that that prevent or reveal bugs
603           maintenance       Policies that affect the long-term health of the code
604           cosmetic          Policies that only have a superficial effect
605           complexity        Policies that specificaly relate to code complexity
606           security          Policies that relate to security issues
607           tests             Policies that are specific to test scripts
608
609       Say "perlcritic --list" to get a listing of all available policies and
610       the themes that are associated with each one.  You can also change the
611       theme for any Policy in your .perlcriticrc file.  See the
612       "CONFIGURATION" section for more information about that.
613
614       Using the "--theme" command-line option, you can create an arbitrarily
615       complex rule that determines which Policies to apply.  Precedence is
616       the same as regular Perl code, and you can use parentheses to enforce
617       precedence as well.  Supported operators are:
618
619           Operator    Altertative    Example
620           -----------------------------------------------------------------
621           &&          and            'pbp && core'
622           ||          or             'pbp || (bugs && security)'
623           !           not            'pbp && ! (portability || complexity)'
624
625       Theme names are case-insensitive.  If the "--theme" is set to an empty
626       string, then it evaluates as true all Policies.
627

BENDING THE RULES

629       Perl::Critic takes a hard-line approach to your code: either you comply
630       or you don't.  In the real world, it is not always practical (or even
631       possible) to fully comply with coding standards.  In such cases, it is
632       wise to show that you are knowingly violating the standards and that
633       you have a Damn Good Reason (DGR) for doing so.
634
635       To help with those situations, you can direct Perl::Critic to ignore
636       certain lines or blocks of code by using annotations:
637
638         require 'LegacyLibaray1.pl';  ## no critic
639         require 'LegacyLibrary2.pl';  ## no critic
640
641         for my $element (@list) {
642
643             ## no critic
644
645             $foo = "";               #Violates 'ProhibitEmptyQuotes'
646             $barf = bar() if $foo;   #Violates 'ProhibitPostfixControls'
647             #Some more evil code...
648
649             ## use critic
650
651             #Some good code...
652             do_something($_);
653         }
654
655       The "## no critic" annotations direct Perl::Critic to ignore the
656       remaining lines of code until the end of the current block, or until a
657       "## use critic" annotation is found (whichever comes first).  If the
658       "## no critic" annotation is on the same line as a code statement, then
659       only that line of code is overlooked.  To direct perlcritic to ignore
660       the "## no critic" annotations, use the "--force" option.
661
662       A bare "## no critic" annotation disables all the active Policies.  If
663       you wish to disable only specific Policies, add a list of Policy names
664       as arguments just as you would for the "no strict" or "no warnings"
665       pragma.  For example, this would disable the "ProhibitEmptyQuotes" and
666       "ProhibitPostfixControls" policies until the end of the block or until
667       the next "## use critic" annotation (whichever comes first):
668
669           ## no critic (EmptyQuotes, PostfixControls);
670
671           # Now exempt from ValuesAndExpressions::ProhibitEmptyQuotes
672           $foo = "";
673
674           # Now exempt ControlStructures::ProhibitPostfixControls
675           $barf = bar() if $foo;
676
677           # Still subject to ValuesAndExpression::RequireNumberSeparators
678           $long_int = 10000000000;
679
680       Since the Policy names are matched against the "## no critic" arguments
681       as regular expressions, you can abbreviate the Policy names or disable
682       an entire family of Policies in one shot like this:
683
684           ## no critic (NamingConventions)
685
686           # Now exempt from NamingConventions::Capitalization
687           my $camelHumpVar = 'foo';
688
689           # Now exempt from NamingConventions::Capitalization
690           sub camelHumpSub {}
691
692       The argument list must be enclosed in parentheses and must contain one
693       or more comma-separated barewords (i.e. don't use quotes).  The "## no
694       critic" annotations can be nested, and Policies named by an inner
695       annotation will be disabled along with those already disabled an outer
696       annotation.
697
698       Some Policies like "Subroutines::ProhibitExcessComplexity" apply to an
699       entire block of code.  In those cases, "## no critic" must appear on
700       the line where the violation is reported.  For example:
701
702           sub complicated_function {  ## no critic (ProhibitExcessComplexity)
703               # Your code here...
704           }
705
706       Some Policies like "Documentation::RequirePodSections" apply to the
707       entire document, in which case violations are reported at line 1.  But
708       if the file requires a shebang line, it is impossible to put "## no
709       critic" on the first line of the file.  This is a known limitation and
710       it will be addressed in a future release.  As a workaround, you can
711       disable the affected policies at the command-line or in your
712       .perlcriticrc file.  But beware that this will affect the analysis of
713       all files.
714
715       Use this feature wisely.  "## no critic" should be used in the smallest
716       possible scope, or only on individual lines of code. And you should
717       always be as specific as possible about which policies you want to
718       disable (i.e. never use a bare "## no critic").  If Perl::Critic
719       complains about your code, try and find a compliant solution before
720       resorting to this feature.
721

EDITOR INTEGRATION

723       For ease-of-use, "perlcritic" can be integrated with your favorite text
724       editor.  The output-formatting capabilities of "perlcritic" are
725       specifically intended for use with the "grep" or "compile" modes
726       available in editors like "emacs" and "vim".  In these modes, you can
727       run an arbitrary command and the editor will parse the output into an
728       interactive buffer that you can click on and jump to the relevant line
729       of code.
730
731       The Perl::Critic team thanks everyone who has helped integrate Perl-
732       Critic with their favorite editor.  Your contributions in particular
733       have made Perl-Critic a convenient and user-friendly tool for Perl
734       developers of all stripes.  We sincerely appreciate your hard work.
735
736   EMACS
737       Joshua ben Jore has authored a minor-mode for emacs that allows you to
738       run perlcritic on the current region or buffer.  You can run it on
739       demand, or configure it to run automatically when you save the buffer.
740       The output appears in a hot-linked compiler buffer.  The code and
741       installation instructions can be found in the extras directory inside
742       this distribution.
743
744   VIM
745       Scott Peshak has published perlchecker.vim, which is available at
746       <http://www.vim.org/scripts/script.php?script_id=1731>.
747
748   gVIM
749       Fritz Mehner recently added support for "perlcritic" to his fantastic
750       gVIM plugin.  In addition to providing a very Perlish IDE, Fritz's
751       plugin enables one-click access to "perlcritic" and many other very
752       useful utilities.  And all is seamlessly integrated into the editor.
753       See http://lug.fh-swf.de/vim/vim-perl/screenshots-en.html
754       <http://lug.fh-swf.de/vim/vim-perl/screenshots-en.html> for complete
755       details.
756
757   EPIC
758       EPIC is an open source Perl IDE based on the Eclipse platform.
759       Features include syntax highlighting, on-the-fly syntax check, content
760       assist, code completion, perldoc support, source formatting with
761       Perl::Tidy, code templates, a regular expression editing tool, and
762       integration with the Perl debugger.  Recent versions of EPIC also have
763       built-in support for Perl::Critic.  At least one Perl::Critic
764       contributor swears by EPIC.  Go to http://e-p-i-c.sourceforge.net
765       <http://e-p-i-c.sourceforge.net> for more information about EPIC.
766
767   BBEdit
768       Josh Clark has produced an excellent Perl-Critic plugin for BBEdit. A
769       copy is included in this distribution at
770       extras/perl_critic_for_bbedit-1_0.zip. See
771       http://beta.bigmedium.com/projects/bbedit-perl-critic/index.shtml
772       <http://beta.bigmedium.com/projects/bbedit-perl-critic/index.shtml> for
773       screenshots and additional installation info.  Apple users rejoice!
774
775   Komodo
776       Komodo is a proprietary IDE for Perl and several other dynamic
777       languages.  Starting in version 5.1.1, Komodo has built-in support for
778       Perl-Critic, if you have the Perl::Critic and criticism modules
779       installed.  Free trial copies of Komodo can be obtained from the
780       ActiveState website at <http://www.activestate.com>. For instructions
781       on integrating perlcritic with older versions of Komodo, see
782       extras/KomodoIntegration.pod in this distribution.
783

EXIT STATUS

785       If "perlcritic" has any errors itself, exits with status == 1.  If
786       there are no errors, but "perlcritic" finds Policy violations in your
787       source code, exits with status == 2.  If there were no errors and no
788       violations were found, exits with status == 0.
789

THE Perl::Critic PHILOSOPHY

791           Coding standards are deeply personal and highly subjective.  The
792           goal of Perl::Critic is to help you write code that conforms with a
793           set of best practices.  Our primary goal is not to dictate what
794           those practices are, but rather, to implement the practices
795           discovered by others.  Ultimately, you make the rules --
796           Perl::Critic is merely a tool for encouraging consistency.  If
797           there is a policy that you think is important or that we have
798           overlooked, we would be very grateful for contributions, or you can
799           simply load your own private set of policies into Perl::Critic.
800

EXTENDING THE CRITIC

802       The modular design of Perl::Critic is intended to facilitate the
803       addition of new Policies.  You'll need to have some understanding of
804       PPI, but most Policy modules are pretty straightforward and only
805       require about 20 lines of code, and half of those lines are simple use
806       statements and simple declarations..  Please see the
807       Perl::Critic::DEVELOPER file included in this distribution for a step-
808       by-step demonstration of how to create new Policy modules.
809
810       If you develop any new Policy modules, feel free to send them to
811       "<thaljef@cpan.org>" and I'll be happy to put them into the
812       Perl::Critic distribution.  Or if you would like to work on the
813       Perl::Critic project directly, check out our repository at
814       <http://perlcritic.tigris.org>.  To subscribe to our mailing list, send
815       a message to mailto:dev-subscribe@perlcritic.tigris.org <mailto:dev-
816       subscribe@perlcritic.tigris.org>.
817
818       The Perl::Critic team is also available for hire.  If your organization
819       has its own coding standards, we can create custom Policies to enforce
820       your local guidelines.  Or if your code base is prone to a particular
821       defect pattern, we can design Policies that will help you catch those
822       costly defects before they go into production.  To discuss your needs
823       with the Perl::Critic team, just contact "<thaljef@cpan.org>".
824

CONTACTING THE DEVELOPMENT TEAM

826       You are encouraged to subscribe to the mailing list; send a message to
827       mailto:users-subscribe@perlcritic.tigris.org <mailto:users-
828       subscribe@perlcritic.tigris.org>.  See also the archives at
829       <http://perlcritic.tigris.org/servlets/SummarizeList?listName=users>.
830       You can also contact the author at "<thaljef@cpan.org>".
831
832       At least one member of the development team has started hanging around
833       in <irc://irc.perl.org/#perlcritic>.
834
835       You can also follow Perl::Critic on Twitter, at
836       <https://twitter.com/perlcritic>.
837

SEE ALSO

839       There are a number of distributions of additional Policies available.
840       A few are listed here:
841
842       Perl::Critic::More Perl::Critic::Bangs Perl::Critic::Lax
843       Perl::Critic::StricterSubs Perl::Critic::Swift
844
845       These distributions enable you to use Perl::Critic in your unit tests:
846
847       Test::Perl::Critic Test::Perl::Critic::Progressive
848
849       There is also a distribution that will install all the Perl::Critic
850       related modules known to the development team:
851
852       Task::Perl::Critic
853
854       Also, the Perl Development Kit (PDK 8.0) from ActiveState includes a
855       very slick graphical interface to Perl-Critic.  For details, go to
856       <http://www.activestate.com/perl_dev_kit>
857

BUGS

859       Scrutinizing Perl code is hard for humans, let alone machines.  If you
860       find any bugs, particularly false-positives or false-negatives from a
861       Perl::Critic::Policy, please submit them to
862       http://rt.cpan.org/NoAuth/Bugs.html?Dist=Perl-Critic
863       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Perl-Critic>.  Thanks.
864
865       Most policies will produce false-negatives if they cannot understand a
866       particular block of code.
867

CREDITS

869       Adam Kennedy - For creating PPI, the heart and soul of Perl::Critic.
870
871       Damian Conway - For writing Perl Best Practices, finally :)
872
873       Chris Dolan - For contributing the best features and Policy modules.
874
875       Andy Lester - Wise sage and master of all-things-testing.
876
877       Elliot Shank - The self-proclaimed quality freak.
878
879       Giuseppe Maxia - For all the great ideas and positive encouragement.
880
881       and Sharon, my wife - For putting up with my all-night code sessions.
882

AUTHOR

884       Jeffrey Ryan Thalhammer <thaljef@cpan.org>
885
887       Copyright (c) 2005-2009 Jeffrey Ryan Thalhammer.  All rights reserved.
888
889       This program is free software; you can redistribute it and/or modify it
890       under the same terms as Perl itself.  The full text of this license can
891       be found in the LICENSE file included with this module.
892
893
894
895perl v5.12.1                      2010-09-08                     PERLCRITIC(1)
Impressum