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}]
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 perlcritic --profile-proto
27 perlcritic { --list | --list-enabled | --list-themes | --doc pattern [...] }
29 perlcritic { --help | --options | --man | --version }
31
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 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
47 Before getting into all the gory details, here are some basic usage
48 examples to help get you started.
49 # Report only most severe violations (severity = 5)
51 perlcritic YourModule.pm
52 # Same as above, but read input from STDIN
54 perlcritic
55 # Recursively process all Perl files beneath directory
57 perlcritic /some/directory
58 # Report slightly less severe violations too (severity >= 4)
60 perlcritic -4 YourModule.pm
61 # Same as above, but using named severity level
63 perlcritic --stern YourModule.pm
64 # Report all violations, regardless of severity (severity >= 1)
66 perlcritic -1 YourModule.pm
67 # Same as above, but using named severity level
69 perlcritic --brutal YourModule.pm
70 # Report only violations of things from "Perl Best Practices"
72 perlcritic --theme pbp YourModule.pm
73 # Report top 20 most severe violations (severity >= 1)
75 perlcritic --top YourModule.pm
76 # Report additional violations of Policies that match m/variables/xms
78 perlcritic --include variables YourModule.pm
79 # Use defaults from somewhere other than ~/.perlcriticrc
81 perlcriticrc --profile project/specific/perlcriticrc YourModule.pm
82
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
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 "--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 "--noprofile"
102 Directs "perlcritic" not to load any configuration file, thus
103 reverting to the default configuration for all Policies.
104 "--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 "-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 "--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 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 "--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 "--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 $> perlcritic --theme='bugs && pbp' MyModule.pm
154 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 "--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 perlcritic --include=layout my_file.pl
168 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 "--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 perlcritic --exclude=strict my_file.pl
185 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 "--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 perlcritic --single-policy=nowarnings my_file.pl
201 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 This is equivalent to what one might intend by...
207 perlcritic --exclude=. --include=nowarnings my_file.pl
209 ... but this won't work because the "--exclude" option overrides
211 the "--include" option.
212 The equivalent of this option can be accomplished by creating a
214 custom profile containing only the desired policy and then
215 running...
216 perlcritic --profile=customprofile --only my_file.pl
218 "--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 "--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 "--statistics"
239 Causes several statistics about the code being scanned and the
240 violations found to be reported after any other output.
241 "--statistics-only"
243 Like the "--statistics" option, but suppresses normal output and
244 only shows the statistics.
245 "--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 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 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 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 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 "--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 "--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 "--list-themes"
311 Displays a list of all the themes of the Perl::Critic::Policy
312 modules that are found on this machine.
313 "--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 "--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 "--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 "--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 "--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 "--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 Can also be specified as "--colour".
357 "--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 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 "--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 "--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 "--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 "--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 "--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 "--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 "--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 "--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 "--quiet"
417 Suppress the "source OK" message when no violations are found.
418 "--help"
420 "-?"
421 "-H"
422 Displays a brief summary of options and exits.
423 "--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 "--man"
430 Displays the complete "perlcritic" manual and exits.
431 "--version"
433 "-V"
434 Displays the version number of "perlcritic" and exits.
435
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 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 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 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 The remainder of the configuration file is a series of blocks like
467 this:
468 [Perl::Critic::Policy::Category::PolicyName]
470 severity = 1
471 set_themes = foo bar
472 add_themes = baz
473 arg1 = value1
474 arg2 = value2
475 "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 "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 SEVERITY NAME ...is equivalent to... SEVERITY NUMBER
491 ----------------------------------------------------
492 gentle 5
493 stern 4
494 harsh 3
495 cruel 2
496 brutal 1
497 "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 "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 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 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 A simple configuration might look like this:
520 #--------------------------------------------------------------
522 # I think these are really important, so always load them
523 [TestingAndDebugging::RequireUseStrict]
525 severity = 5
526 [TestingAndDebugging::RequireUseWarnings]
528 severity = 5
529 #--------------------------------------------------------------
531 # I think these are less important, so only load when asked
532 [Variables::ProhibitPackageVars]
534 severity = 2
535 [ControlStructures::ProhibitPostfixControls]
537 allow = if unless # My custom configuration
538 severity = cruel # Same as "severity = 2"
539 #--------------------------------------------------------------
541 # Give these policies a custom theme. I can activate just
542 # these policies by saying "perlcritic --theme 'larry || curly'"
543 [Modules::RequireFilenameMatchesPackage]
545 add_themes = larry
546 [TestingAndDebugging::RequireTestLabels]
548 add_themes = curly moe
549 #--------------------------------------------------------------
551 # I do not agree with these at all, so never load them
552 [-NamingConventions::Capitalization]
554 [-ValuesAndExpressions::ProhibitMagicNumbers]
555 #--------------------------------------------------------------
557 # For all other Policies, I accept the default severity,
558 # so no additional configuration is required for them.
559 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 [ValuesAndExpressions::RequireNumberSeparators]
565 min_value = 1_000
566 For additional configuration examples, see the perlcriticrc file that
568 is included in this examples directory of this distribution.
569 Damian Conway's own Perl::Critic configuration is also included in this
571 distribution as examples/perlcriticrc-conway.
572
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 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
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 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 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 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 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 Operator Altertative Example
620 -----------------------------------------------------------------
621 && and 'pbp && core'
622 || or 'pbp || (bugs && security)'
623 ! not 'pbp && ! (portability || complexity)'
624 Theme names are case-insensitive. If the "--theme" is set to an empty
626 string, then it evaluates as true all Policies.
627
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 To help with those situations, you can direct Perl::Critic to ignore
636 certain lines or blocks of code by using annotations:
637 require 'LegacyLibaray1.pl'; ## no critic
639 require 'LegacyLibrary2.pl'; ## no critic
640 for my $element (@list) {
642 ## no critic
644 $foo = ""; #Violates 'ProhibitEmptyQuotes'
646 $barf = bar() if $foo; #Violates 'ProhibitPostfixControls'
647 #Some more evil code...
648 ## use critic
650 #Some good code...
652 do_something($_);
653 }
654 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 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 ## no critic (EmptyQuotes, PostfixControls);
670 # Now exempt from ValuesAndExpressions::ProhibitEmptyQuotes
672 $foo = "";
673 # Now exempt ControlStructures::ProhibitPostfixControls
675 $barf = bar() if $foo;
676 # Still subject to ValuesAndExpression::RequireNumberSeparators
678 $long_int = 10000000000;
679 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 ## no critic (NamingConventions)
685 # Now exempt from NamingConventions::Capitalization
687 my $camelHumpVar = 'foo';
688 # Now exempt from NamingConventions::Capitalization
690 sub camelHumpSub {}
691 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 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 sub complicated_function { ## no critic (ProhibitExcessComplexity)
703 # Your code here...
704 }
705 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 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
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 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 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 VIM
745 Scott Peshak has published perlchecker.vim, which is available at
746 <http://www.vim.org/scripts/script.php?script_id=1731>.
747 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 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 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 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
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
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
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 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 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
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 At least one member of the development team has started hanging around
833 in <irc://irc.perl.org/#perlcritic>.
834 You can also follow Perl::Critic on Twitter, at
836 <https://twitter.com/perlcritic>.
837
839 There are a number of distributions of additional Policies available.
840 A few are listed here:
841 Perl::Critic::More Perl::Critic::Bangs Perl::Critic::Lax
843 Perl::Critic::StricterSubs Perl::Critic::Swift
844 These distributions enable you to use Perl::Critic in your unit tests:
846 Test::Perl::Critic Test::Perl::Critic::Progressive
848 There is also a distribution that will install all the Perl::Critic
850 related modules known to the development team:
851 Task::Perl::Critic
853 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
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 Most policies will produce false-negatives if they cannot understand a
866 particular block of code.
867
869 Adam Kennedy - For creating PPI, the heart and soul of Perl::Critic.
870 Damian Conway - For writing Perl Best Practices, finally :)
872 Chris Dolan - For contributing the best features and Policy modules.
874 Andy Lester - Wise sage and master of all-things-testing.
876 Elliot Shank - The self-proclaimed quality freak.
878 Giuseppe Maxia - For all the great ideas and positive encouragement.
880 and Sharon, my wife - For putting up with my all-night code sessions.
882
884 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
885
887 Copyright (c) 2005-2009 Jeffrey Ryan Thalhammer. All rights reserved.
888 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.
892perl v5.12.1 2010-09-08 PERLCRITIC(1)