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, such as API reference and alternative interfaces,
44 please see the 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 perlcritic --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 "--color"
344 "--colour"
345 This option is on when outputting to a tty. When set, Severity 5
346 and 4 are colored red and yellow, respectively. Colorization only
347 happens if Term::ANSIColor is installed. For Windows environments,
348 Win32::Console::ANSI must also be installed. Negate this switch to
349 disable color. You can set the default value for this option in
350 your .perlcriticrc file.
351 "--pager PAGER_COMMAND_STRING"
353 If set, perlcritic will pipe it's output to the given
354 PAGER_COMMAND_STRING. You can set the default value for this
355 option in your .perlcriticrc file.
356 Setting a pager turns off color by default. You will have to turn
358 color on explicitly. If you want color, you'll probably also want
359 to tell your pager to display raw characters. For "less" and
360 "more", use the -R switch.
361 "--color-severity-highest COLOR_SPECIFICATION"
363 Specifies the color to be used for highest severity violations, as
364 a Term::ANSIColor color specification. Can also be specified as
365 "--colour- severity-highest", "--color-severity-5", or
366 "--colour-severity-5".
367 "--color-severity-high COLOR_SPECIFICATION"
369 Specifies the color to be used for high severity violations, as a
370 Term::ANSIColor color specification. Can also be specified as
371 "--colour- severity-high", "--color-severity-4", or
372 "--colour-severity-4".
373 "--color-severity-medium COLOR_SPECIFICATION"
375 Specifies the color to be used for medium severity violations, as a
376 Term::ANSIColor color specification. Can also be specified as
377 "--colour- severity-medium", "--color-severity-3", or
378 "--colour-severity-3".
379 "--color-severity-low COLOR_SPECIFICATION"
381 Specifies the color to be used for low severity violations, as a
382 Term::ANSIColor color specification. Can also be specified as
383 "--colour- severity-low", "--color-severity-2", or
384 "--colour-severity-2".
385 "--color-severity-lowest COLOR_SPECIFICATION"
387 Specifies the color to be used for lowest severity violations, as a
388 Term::ANSIColor color specification. Can also be specified as
389 "--colour- severity-lowest", "--color-severity-1", or
390 "--colour-severity-1".
391 "--files-with-violations"
393 Display only the names of files with violations. Use this feature
394 with --single-policy to find files that contain violations of a
395 given policy. Can also be specified as "--l".
396 "--files-without-violations"
398 Display only the names of files without violations. Use this
399 feature with --single-policy to find files that do not contain
400 violations of a given policy. Can also be specified as "--L".
401 "--program-extensions file_name_extension"
403 Tell "perlcritic" to treat files whose names end in the given file
404 name extension as programs, not as modules. If a leading '.' is
405 desired it must be explicitly specified, e.g.
406 --program-extensions .pl
408 The matching is case-sensitive, and the option may be specified as
410 many times as desired, e.g.
411 --program-extensions .pl --program-extensions .cgi
413 The above can also be done by quoting the file name extensions:
415 --program-extensions '.pl .cgi'
417 Files whose name ends in '.PL' will always be considered programs.
419 "--doc PATTERN"
421 Displays the perldoc for all Perl::Critic::Policy modules that
422 match "m/PATTERN/ixms". Since Policy modules tend to have rather
423 long names, this just provides a more convenient way to say
424 something like: "perldoc
425 Perl::Critic::Policy::ValuesAndExpressions::RequireUpperCaseH
426 eredocTerminator" at the command prompt.
427 "--allow-unsafe"
429 This option directs "perlcritic" to allow the use of Policies that
430 have been marked as "unsafe". Unsafe Policies may result in risky
431 operations by compiling and executing the code they analyze. All
432 the Policies that ship in the core Perl::Critic distribution are
433 safe. However, third- party Policies, such as those in the
434 Perl::Critic::Dynamic distribution are not safe. Note that "safety"
435 is honorary -- if a Policy author marks a Policy as safe, it is not
436 a guarantee that it won't do nasty things. If you don't trust your
437 Policies and the code you are analyzing, then do not use this
438 switch.
439 "--quiet"
441 Suppress the "source OK" message when no violations are found.
442 "--help"
444 "-?"
445 "-H"
446 Displays a brief summary of options and exits.
447 "--options"
449 Displays the descriptions of the options and exits. While this
450 output is long, it it nowhere near the length of the output of
451 "--man".
452 "--man"
454 Displays the complete "perlcritic" manual and exits.
455 "--version"
457 Displays the version number of "perlcritic" and exits.
458
460 Most of the settings for Perl::Critic and each of the Policy modules
461 can be controlled by a configuration file. The default configuration
462 file is called .perlcriticrc. "perlcritic" will look for this file in
463 the current directory first, and then in your home directory.
464 Alternatively, you can set the "PERLCRITIC" environment variable to
465 explicitly point to a different file in another location. If none of
466 these files exist, and the "--profile" option is not given on the
467 command-line, then all Policies will be loaded with their default
468 configuration.
469 The format of the configuration file is a series of INI-style blocks
471 that contain key-value pairs separated by "=". Comments should start
472 with "#" and can be placed on a separate line or after the name-value
473 pairs if you desire.
474 Default settings for perlcritic itself can be set before the first
476 named block. For example, putting any or all of these at the top of
477 your .perlcriticrc file will set the default value for the
478 corresponding command-line argument.
479 severity = 3 #Integer or named level
481 only = 1 #Zero or One
482 force = 0 #Zero or One
483 verbose = 4 #Integer or format spec
484 top = 50 #A positive integer
485 theme = (pbp + security) * bugs #A theme expression
486 include = NamingConventions ClassHierarchies #Space-delimited list
487 exclude = Variables Modules::RequirePackage #Space-delimited list
488 The remainder of the configuration file is a series of blocks like
490 this:
491 [Perl::Critic::Policy::Category::PolicyName]
493 severity = 1
494 set_themes = foo bar
495 add_themes = baz
496 arg1 = value1
497 arg2 = value2
498 "Perl::Critic::Policy::Category::PolicyName" is the full name of a
500 module that implements the policy. The Policy modules distributed with
501 Perl::Critic have been grouped into categories according to the table
502 of contents in Damian Conway's book Perl Best Practices. For brevity,
503 you can omit the 'Perl::Critic::Policy' part of the module name.
504 "severity" is the level of importance you wish to assign to the Policy.
506 All Policy modules are defined with a default severity value ranging
507 from 1 (least severe) to 5 (most severe). However, you may disagree
508 with the default severity and choose to give it a higher or lower
509 severity, based on your own coding philosophy. You can set the
510 "severity" to an integer from 1 to 5, or use one of the equivalent
511 names:
512 SEVERITY NAME ...is equivalent to... SEVERITY NUMBER
514 ----------------------------------------------------
515 gentle 5
516 stern 4
517 harsh 3
518 cruel 2
519 brutal 1
520 "set_themes" sets the theme for the Policy and overrides its default
522 theme. The argument is a string of one or more whitespace-delimited
523 alphanumeric words. Themes are case-insensitive. See "POLICY THEMES"
524 for more information.
525 "add_themes" appends to the default themes for this Policy. The
527 argument is a string of one or more whitespace-delimited words. Themes
528 are case- insensitive. See "POLICY THEMES" for more information.
529 The remaining key-value pairs are configuration parameters that will be
531 passed into the constructor of that Policy. The constructors for most
532 Policy modules do not support arguments, and those that do should have
533 reasonable defaults. See the documentation on the appropriate Policy
534 module for more details.
535 Instead of redefining the severity for a given Policy, you can
537 completely disable a Policy by prepending a '-' to the name of the
538 module in your configuration file. In this manner, the Policy will
539 never be loaded, regardless of the "--severity" given on the command
540 line.
541 A simple configuration might look like this:
543 #--------------------------------------------------------------
545 # I think these are really important, so always load them
546 [TestingAndDebugging::RequireUseStrict]
548 severity = 5
549 [TestingAndDebugging::RequireUseWarnings]
551 severity = 5
552 #--------------------------------------------------------------
554 # I think these are less important, so only load when asked
555 [Variables::ProhibitPackageVars]
557 severity = 2
558 [ControlStructures::ProhibitPostfixControls]
560 allow = if unless # My custom configuration
561 severity = cruel # Same as "severity = 2"
562 #--------------------------------------------------------------
564 # Give these policies a custom theme. I can activate just
565 # these policies by saying "perlcritic --theme 'larry || curly'"
566 [Modules::RequireFilenameMatchesPackage]
568 add_themes = larry
569 [TestingAndDebugging::RequireTestLabels]
571 add_themes = curly moe
572 #--------------------------------------------------------------
574 # I do not agree with these at all, so never load them
575 [-NamingConventions::Capitalization]
577 [-ValuesAndExpressions::ProhibitMagicNumbers]
578 #--------------------------------------------------------------
580 # For all other Policies, I accept the default severity,
581 # so no additional configuration is required for them.
582 Note that all policies included with the Perl::Critic distribution that
584 have integer parameters accept underscores ("_") in their values, as
585 with Perl numeric literals. For example,
586 [ValuesAndExpressions::RequireNumberSeparators]
588 min_value = 1_000
589 For additional configuration examples, see the perlcriticrc file that
591 is included in this examples directory of this distribution.
592 Damian Conway's own Perl::Critic configuration is also included in this
594 distribution as examples/perlcriticrc-conway.
595
597 A large number of Policy modules are distributed with Perl::Critic.
598 They are described briefly in the companion document
599 Perl::Critic::PolicySummary and in more detail in the individual
600 modules themselves. Say "perlcritic --doc PATTERN" to see the perldoc
601 for all Policy modules that match the regex "m/PATTERN/ixms"
602 There are a number of distributions of additional policies on CPAN. If
604 Perl::Critic doesn't contain a policy that you want, some one may have
605 already written it. See "SEE ALSO" in Perl::Critic for a list of some
606 of these distributions.
607
609 Each Policy is defined with one or more "themes". Themes can be used
610 to create arbitrary groups of Policies. They are intended to provide
611 an alternative mechanism for selecting your preferred set of Policies.
612 For example, you may wish disable a certain set of Policies when
613 analyzing test programs. Conversely, you may wish to enable only a
614 specific subset of Policies when analyzing modules.
615 The Policies that ship with Perl::Critic are have been divided into the
617 following themes. This is just our attempt to provide some basic
618 logical groupings. You are free to invent new themes that suit your
619 needs.
620 THEME DESCRIPTION
622 ------------------------------------------------------------------------
623 core All policies that ship with Perl::Critic
624 pbp Policies that come directly from "Perl Best Practices"
625 bugs Policies that that prevent or reveal bugs
626 certrec Policies that CERT recommends
627 certrule Policies that CERT considers rules
628 maintenance Policies that affect the long-term health of the code
629 cosmetic Policies that only have a superficial effect
630 complexity Policies that specifically relate to code complexity
631 security Policies that relate to security issues
632 tests Policies that are specific to test programs
633 Say "perlcritic --list" to get a listing of all available policies and
635 the themes that are associated with each one. You can also change the
636 theme for any Policy in your .perlcriticrc file. See the
637 "CONFIGURATION" section for more information about that.
638 Using the "--theme" command-line option, you can create an arbitrarily
640 complex rule that determines which Policies to apply. Precedence is the
641 same as regular Perl code, and you can use parentheses to enforce
642 precedence as well. Supported operators are:
643 Operator Altertative Example
645 -----------------------------------------------------------------
646 && and 'pbp && core'
647 || or 'pbp || (bugs && security)'
648 ! not 'pbp && ! (portability || complexity)'
649 Theme names are case-insensitive. If the "--theme" is set to an empty
651 string, then it evaluates as true all Policies.
652
654 Perl::Critic takes a hard-line approach to your code: either you comply
655 or you don't. In the real world, it is not always practical (or even
656 possible) to fully comply with coding standards. In such cases, it is
657 wise to show that you are knowingly violating the standards and that
658 you have a Damn Good Reason (DGR) for doing so.
659 To help with those situations, you can direct Perl::Critic to ignore
661 certain lines or blocks of code by using annotations:
662 require 'LegacyLibaray1.pl'; ## no critic
664 require 'LegacyLibrary2.pl'; ## no critic
665 for my $element (@list) {
667 ## no critic
669 $foo = ""; #Violates 'ProhibitEmptyQuotes'
671 $barf = bar() if $foo; #Violates 'ProhibitPostfixControls'
672 #Some more evil code...
673 ## use critic
675 #Some good code...
677 do_something($_);
678 }
679 The "## no critic" annotations direct Perl::Critic to ignore the
681 remaining lines of code until a "## use critic" annotation is found. If
682 the "## no critic" annotation is on the same line as a code statement,
683 then only that line of code is overlooked. To direct perlcritic to
684 ignore the "## no critic" annotations, use the "--force" option.
685 A bare "## no critic" annotation disables all the active Policies. If
687 you wish to disable only specific Policies, add a list of Policy names
688 as arguments just as you would for the "no strict" or "no warnings"
689 pragma. For example, this would disable the "ProhibitEmptyQuotes" and
690 "ProhibitPostfixControls" policies until the end of the block or until
691 the next "## use critic" annotation (whichever comes first):
692 ## no critic (EmptyQuotes, PostfixControls);
694 # Now exempt from ValuesAndExpressions::ProhibitEmptyQuotes
696 $foo = "";
697 # Now exempt ControlStructures::ProhibitPostfixControls
699 $barf = bar() if $foo;
700 # Still subject to ValuesAndExpression::RequireNumberSeparators
702 $long_int = 10000000000;
703 Since the Policy names are matched against the "## no critic" arguments
705 as regular expressions, you can abbreviate the Policy names or disable
706 an entire family of Policies in one shot like this:
707 ## no critic (NamingConventions)
709 # Now exempt from NamingConventions::Capitalization
711 my $camelHumpVar = 'foo';
712 # Now exempt from NamingConventions::Capitalization
714 sub camelHumpSub {}
715 The argument list must be enclosed in parentheses and must contain one
717 or more comma-separated barewords (i.e. don't use quotes). The "## no
718 critic" annotations can be nested, and Policies named by an inner
719 annotation will be disabled along with those already disabled an outer
720 annotation.
721 Some Policies like "Subroutines::ProhibitExcessComplexity" apply to an
723 entire block of code. In those cases, "## no critic" must appear on
724 the line where the violation is reported. For example:
725 sub complicated_function { ## no critic (ProhibitExcessComplexity)
727 # Your code here...
728 }
729 Some Policies like "Documentation::RequirePodSections" apply to the
731 entire document, in which case violations are reported at line 1. But
732 if the file requires a shebang line, it is impossible to put "## no
733 critic" on the first line of the file. This is a known limitation and
734 it will be addressed in a future release. As a workaround, you can
735 disable the affected policies at the command-line or in your
736 .perlcriticrc file. But beware that this will affect the analysis of
737 all files.
738 Use this feature wisely. "## no critic" should be used in the smallest
740 possible scope, or only on individual lines of code. And you should
741 always be as specific as possible about which policies you want to
742 disable (i.e. never use a bare "## no critic"). If Perl::Critic
743 complains about your code, try and find a compliant solution before
744 resorting to this feature.
745
747 For ease-of-use, "perlcritic" can be integrated with your favorite text
748 editor. The output-formatting capabilities of "perlcritic" are
749 specifically intended for use with the "grep" or "compile" modes
750 available in editors like "emacs" and "vim". In these modes, you can
751 run an arbitrary command and the editor will parse the output into an
752 interactive buffer that you can click on and jump to the relevant line
753 of code.
754 The Perl::Critic team thanks everyone who has helped integrate Perl-
756 Critic with their favorite editor. Your contributions in particular
757 have made Perl- Critic a convenient and user-friendly tool for Perl
758 developers of all stripes. We sincerely appreciate your hard work.
759 EMACS
761 Joshua ben Jore has authored a minor-mode for emacs that allows you to
762 run perlcritic on the current region or buffer. You can run it on
763 demand, or configure it to run automatically when you save the buffer.
764 The output appears in a hot-linked compiler buffer. The code and
765 installation instructions can be found in the extras directory inside
766 this distribution.
767 VIM
769 Scott Peshak has published perlchecker.vim, which is available at
770 <http://www.vim.org/scripts/script.php?script_id=1731>.
771 gVIM
773 Fritz Mehner recently added support for "perlcritic" to his fantastic
774 gVIM plugin. In addition to providing a very Perlish IDE, Fritz's
775 plugin enables one-click access to "perlcritic" and many other very
776 useful utilities. And all is seamlessly integrated into the editor.
777 See <http://lug.fh-swf.de/vim/vim-perl/screenshots-en.html> for
778 complete details.
779 EPIC
781 EPIC is an open source Perl IDE based on the Eclipse platform. Features
782 include syntax highlighting, on-the-fly syntax check, content assist,
783 code completion, perldoc support, source formatting with Perl::Tidy,
784 code templates, a regular expression editing tool, and integration with
785 the Perl debugger. Recent versions of EPIC also have built-in support
786 for Perl::Critic. At least one Perl::Critic contributor swears by
787 EPIC. Go to <http://e-p-i-c.sourceforge.net> for more information
788 about EPIC.
789 BBEdit
791 Josh Clark has produced an excellent Perl-Critic plugin for BBEdit. See
792 <http://globalmoxie.com/projects/bbedit-perl-critic/index.shtml> for
793 download, installation, and usage instructions. Apple users rejoice!
794 Komodo
796 Komodo is a proprietary IDE for Perl and several other dynamic
797 languages. Starting in version 5.1.1, Komodo has built-in support for
798 Perl-Critic, if you have the Perl::Critic and criticism modules
799 installed. Free trial copies of Komodo can be obtained from the
800 ActiveState website at <http://www.activestate.com>.
801 ActivePerl
803 ActivePerl includes a very slick graphical interface for configuring
804 and running Perl-Critic called "perlcritic-gui". A free community
805 edition of ActivePerl can be obtained from the ActiveState website at
806 <http://www.activestate.com>.
807 Visual Studio Code
809 Visual Studio Code is a lightweight but powerful source code editor
810 which runs on your desktop and is available for Windows, macOS and
811 Linux.
812 The perlcritic extension can be found here:
814 <https://marketplace.visualstudio.com/items?itemName=sfodje.perlcritic>
815 The steps to install the perlcritic extension:
817 1. Menu: View->Command Palette
819 2. Type in "Extensions"
820 3. Select "Extensions: Install Extension"
821 4. In the search box type "perlcritic" and the extensions pane will
822 open.
823 5. perlcritic should be the first entry
824 6. Select the "install" button
825 7. Once installed go to Preferences->Settings
826 8. Type in "perlcritic" in the search box
827 9. The settings options for perlcritic will show and you configure the
828 extension here.
829 9a. If you want perlcritic to run automatically when the file is saved,
830 select "only critique on save".
831 Open a Perl file. Save it and perlcritic should fire. There is a
833 triangle with an exclamation point on the status bar. Click it and it
834 will open the issues that perlcritic has found.
835
837 If "perlcritic" has any errors itself, exits with status == 1. If
838 there are no errors, but "perlcritic" finds Policy violations in your
839 source code, exits with status == 2. If there were no errors and no
840 violations were found, exits with status == 0.
841
843 Coding standards are deeply personal and highly subjective. The
844 goal of Perl::Critic is to help you write code that conforms with a
845 set of best practices. Our primary goal is not to dictate what
846 those practices are, but rather, to implement the practices
847 discovered by others. Ultimately, you make the rules --
848 Perl::Critic is merely a tool for encouraging consistency. If
849 there is a policy that you think is important or that we have
850 overlooked, we would be very grateful for contributions, or you can
851 simply load your own private set of policies into Perl::Critic.
852
854 The modular design of Perl::Critic is intended to facilitate the
855 addition of new Policies. You'll need to have some understanding of
856 PPI, but most Policy modules are pretty straightforward and only
857 require about 20 lines of code. Please see the Perl::Critic::DEVELOPER
858 file included in this distribution for a step-by-step demonstration of
859 how to create new Policy modules.
860 If you develop any new Policy modules, feel free to send them to
862 "<team@perlcritic.com>" and I'll be happy to consider putting them into
863 the Perl::Critic distribution. Or if you would like to work on the
864 Perl::Critic project directly, you can fork our repository at
865 <https://github.com/Perl-Critic/Perl-Critic.git>.
866 The Perl::Critic team is also available for hire. If your organization
868 has its own coding standards, we can create custom Policies to enforce
869 your local guidelines. Or if your code base is prone to a particular
870 defect pattern, we can design Policies that will help you catch those
871 costly defects before they go into production. To discuss your needs
872 with the Perl::Critic team, just contact "<team@perlcritic.com>".
873
875 You are encouraged to subscribe to the mailing list at
876 <https://groups.google.com/d/forum/perl-critic>. At least one member
877 of the development team is usually hanging around in
878 <irc://irc.perl.org/#perlcritic> and you can follow Perl::Critic on
879 Twitter, at <https://twitter.com/perlcritic>.
880
882 There are a number of distributions of additional Policies available. A
883 few are listed here:
884 Perl::Critic::More
886 Perl::Critic::Bangs
888 Perl::Critic::Lax
890 Perl::Critic::StricterSubs
892 Perl::Critic::Swift
894 Perl::Critic::Tics
896 These distributions enable you to use Perl::Critic in your unit tests:
898 Test::Perl::Critic
900 Test::Perl::Critic::Progressive
902 There is also a distribution that will install all the Perl::Critic
904 related modules known to the development team:
905 Task::Perl::Critic
907
909 Scrutinizing Perl code is hard for humans, let alone machines. If you
910 find any bugs, particularly false-positives or false-negatives from a
911 Perl::Critic::Policy, please submit them at
912 <https://github.com/Perl-Critic/Perl-Critic/issues>. Thanks.
913
915 Adam Kennedy - For creating PPI, the heart and soul of Perl::Critic.
916 Damian Conway - For writing Perl Best Practices, finally :)
918 Chris Dolan - For contributing the best features and Policy modules.
920 Andy Lester - Wise sage and master of all-things-testing.
922 Elliot Shank - The self-proclaimed quality freak.
924 Giuseppe Maxia - For all the great ideas and positive encouragement.
926 and Sharon, my wife - For putting up with my all-night code sessions.
928 Thanks also to the Perl Foundation for providing a grant to support
930 Chris Dolan's project to implement twenty PBP policies.
931 <http://www.perlfoundation.org/april_1_2007_new_grant_awards>
932
934 Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
935
937 Copyright (c) 2005-2021 Imaginative Software Systems. All rights
938 reserved.
939 This program is free software; you can redistribute it and/or modify it
941 under the same terms as Perl itself. The full text of this license can
942 be found in the LICENSE file included with this module.
943perl v5.38.0 2023-09-25 PERLCRITIC(1)