1PERLCRITIC(1) User Contributed Perl Documentation PERLCRITIC(1)
2
6 "perlcritic" - Command-line interface to critique Perl source.
7
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}] [--allow-unsafe]
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 [--program-extensions file_name_extension]
25 {FILE | DIRECTORY | STDIN}
26 perlcritic --profile-proto
28 perlcritic { --list | --list-enabled | --list-themes | --doc pattern [...] }
30 perlcritic { --help | --options | --man | --version }
32
34 "perlcritic" is a Perl source code analyzer. It is the executable
35 front-end to the Perl::Critic engine, which attempts to identify
36 awkward, hard to read, error-prone, or unconventional constructs in
37 your code. Most of the rules are based on Damian Conway's book Perl
38 Best Practices. However, "perlcritic" is not limited to enforcing PBP,
39 and it will even support rules that contradict Conway. All rules can
40 easily be configured or disabled to your liking.
41 This documentation only covers how to drive this command. For all
43 other information, including how to persistently configure this command
44 so that you don't have to say so much on the command-line, see the
45 documentation for Perl::Critic itself.
46
48 Before getting into all the gory details, here are some basic usage
49 examples to help get you started.
50 # Report only most severe violations (severity = 5)
52 perlcritic YourModule.pm
53 # Same as above, but read input from STDIN
55 perlcritic
56 # Recursively process all Perl files beneath directory
58 perlcritic /some/directory
59 # Report slightly less severe violations too (severity >= 4)
61 perlcritic -4 YourModule.pm
62 # Same as above, but using named severity level
64 perlcritic --stern YourModule.pm
65 # Report all violations, regardless of severity (severity >= 1)
67 perlcritic -1 YourModule.pm
68 # Same as above, but using named severity level
70 perlcritic --brutal YourModule.pm
71 # Report only violations of things from "Perl Best Practices"
73 perlcritic --theme pbp YourModule.pm
74 # Report top 20 most severe violations (severity >= 1)
76 perlcritic --top YourModule.pm
77 # Report additional violations of Policies that match m/variables/xms
79 perlcritic --include variables YourModule.pm
80 # Use defaults from somewhere other than ~/.perlcriticrc
82 perlcriticrc --profile project/specific/perlcriticrc YourModule.pm
83
85 The arguments are paths to the files you wish to analyze. You may
86 specify multiple files. If an argument is a directory, "perlcritic"
87 will analyze all Perl files below the directory. If no arguments are
88 specified, then input is read from STDIN.
89
91 Option names can be abbreviated to uniqueness and can be stated with
92 singe or double dashes, and option values can be separated from the
93 option name by a space or '=' (as with Getopt::Long). Option names are
94 also case-sensitive.
95 "--profile FILE" or "-p FILE"
97 Directs "perlcritic" to use a profile named by FILE rather than
98 looking for the default .perlcriticrc file in the current directory
99 or your home directory. See "CONFIGURATION" in Perl::Critic for
100 more information.
101 "--noprofile"
103 Directs "perlcritic" not to load any configuration file, thus
104 reverting to the default configuration for all Policies.
105 "--severity N"
107 Directs "perlcritic" to only apply Policies with a severity greater
108 than "N". Severity values are integers ranging from 1 (least
109 severe) to 5 (most severe). The default is 5. For a given
110 "--profile", decreasing the "--severity" will usually produce more
111 violations. You can set the default value for this option in your
112 .perlcriticrc file. You can also redefine the "severity" for any
113 Policy in your .perlcriticrc file. See "CONFIGURATION" for more
114 information.
115 "-5 | -4 | -3 | -2 | -1"
117 These are numeric shortcuts for setting the "--severity" option.
118 For example, "-4" is equivalent to "--severity 4". If multiple
119 shortcuts are specified, then the most restrictive one wins. If an
120 explicit "--severity" option is also given, then all shortcut
121 options are silently ignored. NOTE: Be careful not to put one of
122 the number severity shortcut options immediately after the "--top"
123 flag or "perlcritic" will interpret it as the number of violations
124 to report.
125 "--severity NAME"
127 If it is difficult for you to remember whether severity "5" is the
128 most or least restrictive level, then you can use one of these
129 named values:
130 SEVERITY NAME ...is equivalent to... SEVERITY NUMBER
132 --------------------------------------------------------
133 --severity gentle --severity 5
134 --severity stern --severity 4
135 --severity harsh --severity 3
136 --severity cruel --severity 2
137 --severity brutal --severity 1
138 "--gentle | --stern | --harsh | --cruel | --brutal"
140 These are named shortcuts for setting the "--severity" option. For
141 example, "--cruel" is equivalent to "--severity 2". If multiple
142 shortcuts are specified, then the most restrictive one wins. If an
143 explicit "--severity" option is also given, then all shortcut
144 options are silently ignored.
145 "--theme RULE"
147 Directs "perlcritic" to apply only Policies with themes that
148 satisfy the "RULE". Themes are arbitrary names for groups of
149 related policies. You can combine theme names with boolean
150 operators to create an arbitrarily complex "RULE". For example,
151 the following would apply only Policies that have a 'bugs' AND
152 'pbp' theme:
153 $> perlcritic --theme='bugs && pbp' MyModule.pm
155 Unless the "--severity" option is explicitly given, setting
157 "--theme" silently causes the "--severity" to be set to 1. You can
158 set the default value for this option in your .perlcriticrc file.
159 See "POLICY THEMES" in Perl::Critic for more information about
160 themes.
161 "--include PATTERN"
163 Directs "perlcritic" to apply additional Policies that match the
164 regex "/PATTERN/imx". Use this option to temporarily override your
165 profile and/or the severity settings at the command-line. For
166 example:
167 perlcritic --include=layout my_file.pl
169 This would cause "perlcritic" to apply all the "CodeLayout::*"
171 policies even if they have a severity level that is less than the
172 default level of 5, or have been disabled in your .perlcriticrc
173 file. You can specify multiple "--include" options and you can use
174 it in conjunction with the "--exclude" option. Note that
175 "--exclude" takes precedence over "--include" when a Policy matches
176 both patterns. You can set the default value for this option in
177 your .perlcriticrc file.
178 "--exclude PATTERN"
180 Directs "perlcritic" to not apply any Policy that matches the regex
181 "/PATTERN/imx". Use this option to temporarily override your
182 profile and/or the severity settings at the command-line. For
183 example:
184 perlcritic --exclude=strict my_file.pl
186 This would cause "perlcritic" to not apply the "RequireUseStrict"
188 and "ProhibitNoStrict" Policies even though they have the highest
189 severity level. You can specify multiple "--exclude" options and
190 you can use it in conjunction with the "--include" option. Note
191 that "--exclude" takes precedence over "--include" when a Policy
192 matches both patterns. You can set the default value for this
193 option in your .perlcriticrc file.
194 "--single-policy PATTERN" or "-s PATTERN"
196 Directs "perlcritic" to apply just one Policy module matching the
197 regex "/PATTERN/ixms", and exclude all other Policies. This option
198 has precedence over the "--severity", "--theme", "--include",
199 "--exclude", and "--only" options. For example:
200 perlcritic --single-policy=nowarnings my_file.pl
202 This would cause "perlcritic" to apply just the
204 "ProhibitNoWarnings" Policy, regardless of the severity level
205 setting. No other Policies would be applied.
206 This is equivalent to what one might intend by...
208 perlcritic --exclude=. --include=nowarnings my_file.pl
210 ... but this won't work because the "--exclude" option overrides
212 the "--include" option.
213 The equivalent of this option can be accomplished by creating a
215 custom profile containing only the desired policy and then
216 running...
217 perlcritic --profile=customprofile --only my_file.pl
219 "--top [ N ]"
221 Directs "perlcritic" to report only the top "N" Policy violations
222 in each file, ranked by their severity. If "N" is not specified,
223 it defaults to 20. If the "--severity" option (or one of the
224 shortcuts) is not explicitly given, the "--top" option implies that
225 the minimum severity level is "1" (i.e. "brutal"). Users can
226 redefine the severity for any Policy in their .perlcriticrc file.
227 See "CONFIGURATION" for more information. You can set the default
228 value for this option in your .perlcriticrc file. NOTE: Be careful
229 not to put one of the severity shortcut options immediately after
230 the "--top" flag or "perlcritic" will interpret it as the number of
231 violations to report.
232 "--force"
234 Directs "perlcritic" to ignore the magical "## no critic"
235 annotations in the source code. See "BENDING THE RULES" for more
236 information. You can set the default value for this option in your
237 .perlcriticrc file.
238 "--statistics"
240 Causes several statistics about the code being scanned and the
241 violations found to be reported after any other output.
242 "--statistics-only"
244 Like the "--statistics" option, but suppresses normal output and
245 only shows the statistics.
246 "--verbose N | FORMAT"
248 Sets the verbosity level or format for reporting violations. If
249 given a number ("N"), "perlcritic" reports violations using one of
250 the predefined formats described below. If given a string
251 ("FORMAT"), it is interpreted to be an actual format specification.
252 If the "--verbose" option is not specified, it defaults to either 4
253 or 5, depending on whether multiple files were given as arguments
254 to "perlcritic". You can set the default value for this option in
255 your .perlcriticrc file.
256 Verbosity Format Specification
258 ----------- -------------------------------------------------------
259 1 "%f:%l:%c:%m\n",
260 2 "%f: (%l:%c) %m\n",
261 3 "%m at %f line %l\n",
262 4 "%m at line %l, column %c. %e. (Severity: %s)\n",
263 5 "%f: %m at line %l, column %c. %e. (Severity: %s)\n",
264 6 "%m at line %l, near '%r'. (Severity: %s)\n",
265 7 "%f: %m at line %l near '%r'. (Severity: %s)\n",
266 8 "[%p] %m at line %l, column %c. (Severity: %s)\n",
267 9 "[%p] %m at line %l, near '%r'. (Severity: %s)\n",
268 10 "%m at line %l, column %c.\n %p (Severity: %s)\n%d\n",
269 11 "%m at line %l, near '%r'.\n %p (Severity: %s)\n%d\n"
270 Formats are a combination of literal and escape characters similar
272 to the way "sprintf" works. See String::Format for a full
273 explanation of the formatting capabilities. Valid escape
274 characters are:
275 Escape Meaning
277 ------- ------------------------------------------------------------
278 %c Column number where the violation occurred
279 %d Full diagnostic discussion of the violation
280 %e Explanation of violation or page numbers in PBP
281 %F Just the name of the file where the violation occurred.
282 %f Path to the file where the violation occurred.
283 %l Line number where the violation occurred
284 %m Brief description of the violation
285 %P Full name of the Policy module that created the violation
286 %p Name of the Policy without the Perl::Critic::Policy:: prefix
287 %r The string of source code that caused the violation
288 %C The class of the PPI::Element that caused the violation
289 %s The severity level of the violation
290 The purpose of these formats is to provide some compatibility with
292 text editors that have an interface for parsing certain kinds of
293 input. See "EDITOR INTEGRATION" for more information about that.
294 "--list"
296 Displays a condensed listing of all the Perl::Critic::Policy
297 modules that are found on this machine. This option lists all
298 Policies, regardless of your .perlcriticrc or command line options.
299 For each Policy, the name, default severity and default themes are
300 shown.
301 "--list-enabled"
303 Displays a condensed listing of all the Perl::Critic::Policy
304 modules that would be enforced, if you were actually going to
305 critique a file with this command. This is useful when you've
306 constructed a complicated command or modified your .perlcriticrc
307 file and you want to see exactly which Policies are going to be
308 enforced (or not enforced, as the case may be). For each Policy,
309 the name, default severity and default themes are shown.
310 "--list-themes"
312 Displays a list of all the themes of the Perl::Critic::Policy
313 modules that are found on this machine.
314 "--profile-proto"
316 Displays an expanded listing of all the Perl::Critic::Policy
317 modules that are found on this machine. For each Policy, the name,
318 default severity and default themes are shown, as well as the name
319 of any additional parameters that the Policy supports. The format
320 is suitable as a prototype for your .perlcriticrc file.
321 "--only"
323 Directs perlcritic to apply only Policies that are explicitly
324 mentioned in your .perlcriticrc file. This is useful if you want
325 to use just a small subset of Policies without having to disable
326 all the others. You can set the default value for this option in
327 your .perlcriticrc file.
328 "--profile-strictness {warn|fatal|quiet}"
330 Directs perlcritic how to treat certain recoverable problems found
331 in a .perlcriticrc or file specified via the "--profile" option.
332 Valid values are "warn" (the default), "fatal", and "quiet". For
333 example, perlcritic normally only warns about profiles referring to
334 non-existent Policies, but this option can make this situation
335 fatal. You can set the default value for this option in your
336 .perlcriticrc file.
337 "--count"
339 "-C"
340 Display only the number of violations for each file. Use this
341 feature to get a quick handle on where a large pile of code might
342 need the most attention.
343 "--Safari"
345 Report "Perl Best Practice" citations as section numbers from
346 <http://safari.oreilly.com> instead of page numbers from the actual
347 book. NOTE: This feature is not implemented yet.
348 "--color"
350 This option is on when outputting to a tty. When set, Severity 5
351 and 4 are colored red and yellow, respectively. Colorization only
352 happens if Term::ANSIColor is installed and it only works on non-
353 Windows environments. Negate this switch to disable color. You
354 can set the default value for this option in your .perlcriticrc
355 file.
356 Can also be specified as "--colour".
358 "--pager PAGER_COMMAND_STRING"
360 If set, perlcritic will pipe it's output to the given
361 PAGER_COMMAND_STRING. You can set the default value for this
362 option in your .perlcriticrc file.
363 Setting a pager turns off color by default. You will have to turn
365 color on explicitly. If you want color, you'll probably also want
366 to tell your pager to display raw characters. For "less" and
367 "more", use the -R switch.
368 "--color-severity-highest COLOR_SPECIFICATION"
370 Specifies the color to be used for highest severity violations, as
371 a Term::ANSIColor color specification. Can also be specified as
372 "--colour-severity-highest", "--color-severity-5", or
373 "--colour-severity-5".
374 "--color-severity-high COLOR_SPECIFICATION"
376 Specifies the color to be used for high severity violations, as a
377 Term::ANSIColor color specification. Can also be specified as
378 "--colour-severity-high", "--color-severity-4", or
379 "--colour-severity-4".
380 "--color-severity-medium COLOR_SPECIFICATION"
382 Specifies the color to be used for medium severity violations, as a
383 Term::ANSIColor color specification. Can also be specified as
384 "--colour-severity-medium", "--color-severity-3", or
385 "--colour-severity-3".
386 "--color-severity-low COLOR_SPECIFICATION"
388 Specifies the color to be used for low severity violations, as a
389 Term::ANSIColor color specification. Can also be specified as
390 "--colour-severity-low", "--color-severity-2", or
391 "--colour-severity-2".
392 "--color-severity-lowest COLOR_SPECIFICATION"
394 Specifies the color to be used for lowest severity violations, as a
395 Term::ANSIColor color specification. Can also be specified as
396 "--colour-severity-lowest", "--color-severity-1", or
397 "--colour-severity-1".
398 "--files-with-violations"
400 Display only the names of files with violations. Use this feature
401 with --single-policy to find files that contain violations of a
402 given policy. Can also be specified as "--l".
403 "--files-without-violations"
405 Display only the names of files without violations. Use this
406 feature with --single-policy to find files that do not contain
407 violations of a given policy. Can also be specified as "--L".
408 "--program-extensions file_name_extension"
410 Tell "perlcritic" to treat files whose names end in the given file
411 name extension as programs, not as modules. If a leading '.' is
412 desired it must be explicitly specified, e.g.
413 --program-extensions .pl
415 The matching is case-sensitive, and the option may be specified as
417 many times as desired, e.g.
418 --program-extensions .pl --program-extensions .cgi
420 The above can also be done by quoting the file name extensions:
422 --program-extensions '.pl .cgi'
424 Files whose name ends in '.PL' will always be considered programs.
426 "--doc PATTERN"
428 Displays the perldoc for all Perl::Critic::Policy modules that
429 match "m/PATTERN/ixms". Since Policy modules tend to have rather
430 long names, this just provides a more convenient way to say
431 something like: "perldoc
432 Perl::Critic::Policy::ValuesAndExpressions::RequireUpperCaseHeredocTerminator"
433 at the command prompt.
434 "--allow-unsafe"
436 This option directs "perlcritic" to allow the use of Policies that
437 have been marked as "unsafe". Unsafe Policies may result in risky
438 operations by compiling and executing the code they analyze. All
439 the Policies that ship in the core Perl::Critic distribution are
440 safe. However, third-party Policies, such as those in the
441 Perl::Critic::Dynamic distribution are not safe. Note that
442 "safety" is honorary -- if a Policy author marks a Policy as safe,
443 it is not a guarantee that it won't do nasty things. If you don't
444 trust your Policies and the code you are analyzing, then do not use
445 this switch.
446 "--quiet"
448 Suppress the "source OK" message when no violations are found.
449 "--help"
451 "-?"
452 "-H"
453 Displays a brief summary of options and exits.
454 "--options"
456 Displays the descriptions of the options and exits. While this
457 output is long, it it nowhere near the length of the output of
458 "--man".
459 "--man"
461 Displays the complete "perlcritic" manual and exits.
462 "--version"
464 "-V"
465 Displays the version number of "perlcritic" and exits.
466
468 Most of the settings for Perl::Critic and each of the Policy modules
469 can be controlled by a configuration file. The default configuration
470 file is called .perlcriticrc. "perlcritic" will look for this file in
471 the current directory first, and then in your home directory.
472 Alternatively, you can set the "PERLCRITIC" environment variable to
473 explicitly point to a different file in another location. If none of
474 these files exist, and the "--profile" option is not given on the
475 command-line, then all Policies will be loaded with their default
476 configuration.
477 The format of the configuration file is a series of INI-style blocks
479 that contain key-value pairs separated by "=". Comments should start
480 with "#" and can be placed on a separate line or after the name-value
481 pairs if you desire.
482 Default settings for perlcritic itself can be set before the first
484 named block. For example, putting any or all of these at the top of
485 your .perlcriticrc file will set the default value for the
486 corresponding command-line argument.
487 severity = 3 #Integer or named level
489 only = 1 #Zero or One
490 force = 0 #Zero or One
491 verbose = 4 #Integer or format spec
492 top = 50 #A positive integer
493 theme = (pbp + security) * bugs #A theme expression
494 include = NamingConventions ClassHierarchies #Space-delimited list
495 exclude = Variables Modules::RequirePackage #Space-delimited list
496 The remainder of the configuration file is a series of blocks like
498 this:
499 [Perl::Critic::Policy::Category::PolicyName]
501 severity = 1
502 set_themes = foo bar
503 add_themes = baz
504 arg1 = value1
505 arg2 = value2
506 "Perl::Critic::Policy::Category::PolicyName" is the full name of a
508 module that implements the policy. The Policy modules distributed with
509 Perl::Critic have been grouped into categories according to the table
510 of contents in Damian Conway's book Perl Best Practices. For brevity,
511 you can omit the 'Perl::Critic::Policy' part of the module name.
512 "severity" is the level of importance you wish to assign to the Policy.
514 All Policy modules are defined with a default severity value ranging
515 from 1 (least severe) to 5 (most severe). However, you may disagree
516 with the default severity and choose to give it a higher or lower
517 severity, based on your own coding philosophy. You can set the
518 "severity" to an integer from 1 to 5, or use one of the equivalent
519 names:
520 SEVERITY NAME ...is equivalent to... SEVERITY NUMBER
522 ----------------------------------------------------
523 gentle 5
524 stern 4
525 harsh 3
526 cruel 2
527 brutal 1
528 "set_themes" sets the theme for the Policy and overrides its default
530 theme. The argument is a string of one or more whitespace-delimited
531 alphanumeric words. Themes are case-insensitive. See "POLICY THEMES"
532 for more information.
533 "add_themes" appends to the default themes for this Policy. The
535 argument is a string of one or more whitespace-delimited words. Themes
536 are case-insensitive. See "POLICY THEMES" for more information.
537 The remaining key-value pairs are configuration parameters that will be
539 passed into the constructor of that Policy. The constructors for most
540 Policy modules do not support arguments, and those that do should have
541 reasonable defaults. See the documentation on the appropriate Policy
542 module for more details.
543 Instead of redefining the severity for a given Policy, you can
545 completely disable a Policy by prepending a '-' to the name of the
546 module in your configuration file. In this manner, the Policy will
547 never be loaded, regardless of the "--severity" given on the command
548 line.
549 A simple configuration might look like this:
551 #--------------------------------------------------------------
553 # I think these are really important, so always load them
554 [TestingAndDebugging::RequireUseStrict]
556 severity = 5
557 [TestingAndDebugging::RequireUseWarnings]
559 severity = 5
560 #--------------------------------------------------------------
562 # I think these are less important, so only load when asked
563 [Variables::ProhibitPackageVars]
565 severity = 2
566 [ControlStructures::ProhibitPostfixControls]
568 allow = if unless # My custom configuration
569 severity = cruel # Same as "severity = 2"
570 #--------------------------------------------------------------
572 # Give these policies a custom theme. I can activate just
573 # these policies by saying "perlcritic --theme 'larry || curly'"
574 [Modules::RequireFilenameMatchesPackage]
576 add_themes = larry
577 [TestingAndDebugging::RequireTestLabels]
579 add_themes = curly moe
580 #--------------------------------------------------------------
582 # I do not agree with these at all, so never load them
583 [-NamingConventions::Capitalization]
585 [-ValuesAndExpressions::ProhibitMagicNumbers]
586 #--------------------------------------------------------------
588 # For all other Policies, I accept the default severity,
589 # so no additional configuration is required for them.
590 Note that all policies included with the Perl::Critic distribution that
592 have integer parameters accept underscores ("_") in their values, as
593 with Perl numeric literals. For example,
594 [ValuesAndExpressions::RequireNumberSeparators]
596 min_value = 1_000
597 For additional configuration examples, see the perlcriticrc file that
599 is included in this examples directory of this distribution.
600 Damian Conway's own Perl::Critic configuration is also included in this
602 distribution as examples/perlcriticrc-conway.
603
605 A large number of Policy modules are distributed with Perl::Critic.
606 They are described briefly in the companion document
607 Perl::Critic::PolicySummary and in more detail in the individual
608 modules themselves. Say "perlcritic --doc PATTERN" to see the perldoc
609 for all Policy modules that match the regex "m/PATTERN/ixms"
610 There are a number of distributions of additional policies on CPAN. If
612 Perl::Critic doesn't contain a policy that you want, some one may have
613 already written it. See "SEE ALSO" in Perl::Critic for a list of some
614 of these distributions.
615
617 Each Policy is defined with one or more "themes". Themes can be used
618 to create arbitrary groups of Policies. They are intended to provide
619 an alternative mechanism for selecting your preferred set of Policies.
620 For example, you may wish disable a certain set of Policies when
621 analyzing test programs. Conversely, you may wish to enable only a
622 specific subset of Policies when analyzing modules.
623 The Policies that ship with Perl::Critic are have been divided into the
625 following themes. This is just our attempt to provide some basic
626 logical groupings. You are free to invent new themes that suit your
627 needs.
628 THEME DESCRIPTION
630 ------------------------------------------------------------------------
631 core All policies that ship with Perl::Critic
632 pbp Policies that come directly from "Perl Best Practices"
633 bugs Policies that that prevent or reveal bugs
634 maintenance Policies that affect the long-term health of the code
635 cosmetic Policies that only have a superficial effect
636 complexity Policies that specificaly relate to code complexity
637 security Policies that relate to security issues
638 tests Policies that are specific to test programs
639 Say "perlcritic --list" to get a listing of all available policies and
641 the themes that are associated with each one. You can also change the
642 theme for any Policy in your .perlcriticrc file. See the
643 "CONFIGURATION" section for more information about that.
644 Using the "--theme" command-line option, you can create an arbitrarily
646 complex rule that determines which Policies to apply. Precedence is
647 the same as regular Perl code, and you can use parentheses to enforce
648 precedence as well. Supported operators are:
649 Operator Altertative Example
651 -----------------------------------------------------------------
652 && and 'pbp && core'
653 || or 'pbp || (bugs && security)'
654 ! not 'pbp && ! (portability || complexity)'
655 Theme names are case-insensitive. If the "--theme" is set to an empty
657 string, then it evaluates as true all Policies.
658
660 Perl::Critic takes a hard-line approach to your code: either you comply
661 or you don't. In the real world, it is not always practical (or even
662 possible) to fully comply with coding standards. In such cases, it is
663 wise to show that you are knowingly violating the standards and that
664 you have a Damn Good Reason (DGR) for doing so.
665 To help with those situations, you can direct Perl::Critic to ignore
667 certain lines or blocks of code by using annotations:
668 require 'LegacyLibaray1.pl'; ## no critic
670 require 'LegacyLibrary2.pl'; ## no critic
671 for my $element (@list) {
673 ## no critic
675 $foo = ""; #Violates 'ProhibitEmptyQuotes'
677 $barf = bar() if $foo; #Violates 'ProhibitPostfixControls'
678 #Some more evil code...
679 ## use critic
681 #Some good code...
683 do_something($_);
684 }
685 The "## no critic" annotations direct Perl::Critic to ignore the
687 remaining lines of code until a "## use critic" annotation is found. If
688 the "## no critic" annotation is on the same line as a code statement,
689 then only that line of code is overlooked. To direct perlcritic to
690 ignore the "## no critic" annotations, use the "--force" option.
691 A bare "## no critic" annotation disables all the active Policies. If
693 you wish to disable only specific Policies, add a list of Policy names
694 as arguments just as you would for the "no strict" or "no warnings"
695 pragma. For example, this would disable the "ProhibitEmptyQuotes" and
696 "ProhibitPostfixControls" policies until the end of the block or until
697 the next "## use critic" annotation (whichever comes first):
698 ## no critic (EmptyQuotes, PostfixControls);
700 # Now exempt from ValuesAndExpressions::ProhibitEmptyQuotes
702 $foo = "";
703 # Now exempt ControlStructures::ProhibitPostfixControls
705 $barf = bar() if $foo;
706 # Still subject to ValuesAndExpression::RequireNumberSeparators
708 $long_int = 10000000000;
709 Since the Policy names are matched against the "## no critic" arguments
711 as regular expressions, you can abbreviate the Policy names or disable
712 an entire family of Policies in one shot like this:
713 ## no critic (NamingConventions)
715 # Now exempt from NamingConventions::Capitalization
717 my $camelHumpVar = 'foo';
718 # Now exempt from NamingConventions::Capitalization
720 sub camelHumpSub {}
721 The argument list must be enclosed in parentheses and must contain one
723 or more comma-separated barewords (i.e. don't use quotes). The "## no
724 critic" annotations can be nested, and Policies named by an inner
725 annotation will be disabled along with those already disabled an outer
726 annotation.
727 Some Policies like "Subroutines::ProhibitExcessComplexity" apply to an
729 entire block of code. In those cases, "## no critic" must appear on
730 the line where the violation is reported. For example:
731 sub complicated_function { ## no critic (ProhibitExcessComplexity)
733 # Your code here...
734 }
735 Some Policies like "Documentation::RequirePodSections" apply to the
737 entire document, in which case violations are reported at line 1. But
738 if the file requires a shebang line, it is impossible to put "## no
739 critic" on the first line of the file. This is a known limitation and
740 it will be addressed in a future release. As a workaround, you can
741 disable the affected policies at the command-line or in your
742 .perlcriticrc file. But beware that this will affect the analysis of
743 all files.
744 Use this feature wisely. "## no critic" should be used in the smallest
746 possible scope, or only on individual lines of code. And you should
747 always be as specific as possible about which policies you want to
748 disable (i.e. never use a bare "## no critic"). If Perl::Critic
749 complains about your code, try and find a compliant solution before
750 resorting to this feature.
751
753 For ease-of-use, "perlcritic" can be integrated with your favorite text
754 editor. The output-formatting capabilities of "perlcritic" are
755 specifically intended for use with the "grep" or "compile" modes
756 available in editors like "emacs" and "vim". In these modes, you can
757 run an arbitrary command and the editor will parse the output into an
758 interactive buffer that you can click on and jump to the relevant line
759 of code.
760 The Perl::Critic team thanks everyone who has helped integrate Perl-
762 Critic with their favorite editor. Your contributions in particular
763 have made Perl-Critic a convenient and user-friendly tool for Perl
764 developers of all stripes. We sincerely appreciate your hard work.
765 EMACS
767 Joshua ben Jore has authored a minor-mode for emacs that allows you to
768 run perlcritic on the current region or buffer. You can run it on
769 demand, or configure it to run automatically when you save the buffer.
770 The output appears in a hot-linked compiler buffer. The code and
771 installation instructions can be found in the extras directory inside
772 this distribution.
773 VIM
775 Scott Peshak has published perlchecker.vim, which is available at
776 <http://www.vim.org/scripts/script.php?script_id=1731>.
777 gVIM
779 Fritz Mehner recently added support for "perlcritic" to his fantastic
780 gVIM plugin. In addition to providing a very Perlish IDE, Fritz's
781 plugin enables one-click access to "perlcritic" and many other very
782 useful utilities. And all is seamlessly integrated into the editor.
783 See <http://lug.fh-swf.de/vim/vim-perl/screenshots-en.html> for
784 complete details.
785 EPIC
787 EPIC is an open source Perl IDE based on the Eclipse platform.
788 Features include syntax highlighting, on-the-fly syntax check, content
789 assist, code completion, perldoc support, source formatting with
790 Perl::Tidy, code templates, a regular expression editing tool, and
791 integration with the Perl debugger. Recent versions of EPIC also have
792 built-in support for Perl::Critic. At least one Perl::Critic
793 contributor swears by EPIC. Go to <http://e-p-i-c.sourceforge.net> for
794 more information about EPIC.
795 BBEdit
797 Josh Clark has produced an excellent Perl-Critic plugin for BBEdit. See
798 <http://globalmoxie.com/projects/bbedit-perl-critic/index.shtml> for
799 download, installation, and usage instructions. Apple users rejoice!
800 Komodo
802 Komodo is a proprietary IDE for Perl and several other dynamic
803 languages. Starting in version 5.1.1, Komodo has built-in support for
804 Perl-Critic, if you have the Perl::Critic and criticism modules
805 installed. Free trial copies of Komodo can be obtained from the
806 ActiveState website at <http://www.activestate.com>.
807 ActivePerl
809 ActivePerl includes a very slick graphical interface for configuring
810 and running Perl-Critic called "perlcritic-gui". A free community
811 edition of ActivePerl can be obtained from the ActiveState website at
812 <http://www.activestate.com>.
813
815 If "perlcritic" has any errors itself, exits with status == 1. If
816 there are no errors, but "perlcritic" finds Policy violations in your
817 source code, exits with status == 2. If there were no errors and no
818 violations were found, exits with status == 0.
819
821 Coding standards are deeply personal and highly subjective. The
822 goal of Perl::Critic is to help you write code that conforms with a
823 set of best practices. Our primary goal is not to dictate what
824 those practices are, but rather, to implement the practices
825 discovered by others. Ultimately, you make the rules --
826 Perl::Critic is merely a tool for encouraging consistency. If
827 there is a policy that you think is important or that we have
828 overlooked, we would be very grateful for contributions, or you can
829 simply load your own private set of policies into Perl::Critic.
830
832 The modular design of Perl::Critic is intended to facilitate the
833 addition of new Policies. You'll need to have some understanding of
834 PPI, but most Policy modules are pretty straightforward and only
835 require about 20 lines of code, and half of those lines are simple use
836 statements and simple declarations.. Please see the
837 Perl::Critic::DEVELOPER file included in this distribution for a step-
838 by-step demonstration of how to create new Policy modules.
839 If you develop any new Policy modules, feel free to send them to
841 "<jeff@imaginative-software.com>" and I'll be happy to put them into
842 the Perl::Critic distribution. Or if you would like to work on the
843 Perl::Critic project directly, check out our repository at
844 <http://perlcritic.tigris.org>. To subscribe to our mailing list, send
845 a message to <mailto:dev-subscribe@perlcritic.tigris.org>.
846 The Perl::Critic team is also available for hire. If your organization
848 has its own coding standards, we can create custom Policies to enforce
849 your local guidelines. Or if your code base is prone to a particular
850 defect pattern, we can design Policies that will help you catch those
851 costly defects before they go into production. To discuss your needs
852 with the Perl::Critic team, just contact
853 "<jeff@imaginative-software.com>".
854
856 You are encouraged to subscribe to the mailing list; send a message to
857 <mailto:users-subscribe@perlcritic.tigris.org>. See also the archives
858 at
859 <http://perlcritic.tigris.org/servlets/SummarizeList?listName=users>.
860 You can also contact the author at "<jeff@imaginative-software.com>".
861 At least one member of the development team has started hanging around
863 in <irc://irc.perl.org/#perlcritic>.
864 You can also follow Perl::Critic on Twitter, at
866 <https://twitter.com/perlcritic>.
867
869 There are a number of distributions of additional Policies available.
870 A few are listed here:
871 Perl::Critic::More Perl::Critic::Bangs Perl::Critic::Lax
873 Perl::Critic::StricterSubs Perl::Critic::Swift
874 These distributions enable you to use Perl::Critic in your unit tests:
876 Test::Perl::Critic Test::Perl::Critic::Progressive
878 There is also a distribution that will install all the Perl::Critic
880 related modules known to the development team:
881 Task::Perl::Critic
883 Also, ActivePerl includes a very slick graphical interface to Perl-
885 Critic called "perlcritic-gui". You can get a free community edition
886 of ActivePerl from <http://www.activestate.com>.
887
889 Scrutinizing Perl code is hard for humans, let alone machines. If you
890 find any bugs, particularly false-positives or false-negatives from a
891 Perl::Critic::Policy, please submit them to
892 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Perl-Critic>. Thanks.
893 Most policies will produce false-negatives if they cannot understand a
895 particular block of code.
896
898 Adam Kennedy - For creating PPI, the heart and soul of Perl::Critic.
899 Damian Conway - For writing Perl Best Practices, finally :)
901 Chris Dolan - For contributing the best features and Policy modules.
903 Andy Lester - Wise sage and master of all-things-testing.
905 Elliot Shank - The self-proclaimed quality freak.
907 Giuseppe Maxia - For all the great ideas and positive encouragement.
909 and Sharon, my wife - For putting up with my all-night code sessions.
911
913 Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
914
916 Copyright (c) 2005-2011 Imaginative Software Systems. All rights
917 reserved.
918 This program is free software; you can redistribute it and/or modify it
920 under the same terms as Perl itself. The full text of this license can
921 be found in the LICENSE file included with this module.
922perl v5.16.3 2014-06-09 PERLCRITIC(1)