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 "-V"
458 Displays the version number of "perlcritic" and exits.
459
461 Most of the settings for Perl::Critic and each of the Policy modules
462 can be controlled by a configuration file. The default configuration
463 file is called .perlcriticrc. "perlcritic" will look for this file in
464 the current directory first, and then in your home directory.
465 Alternatively, you can set the "PERLCRITIC" environment variable to
466 explicitly point to a different file in another location. If none of
467 these files exist, and the "--profile" option is not given on the
468 command-line, then all Policies will be loaded with their default
469 configuration.
470 The format of the configuration file is a series of INI-style blocks
472 that contain key-value pairs separated by "=". Comments should start
473 with "#" and can be placed on a separate line or after the name-value
474 pairs if you desire.
475 Default settings for perlcritic itself can be set before the first
477 named block. For example, putting any or all of these at the top of
478 your .perlcriticrc file will set the default value for the
479 corresponding command-line argument.
480 severity = 3 #Integer or named level
482 only = 1 #Zero or One
483 force = 0 #Zero or One
484 verbose = 4 #Integer or format spec
485 top = 50 #A positive integer
486 theme = (pbp + security) * bugs #A theme expression
487 include = NamingConventions ClassHierarchies #Space-delimited list
488 exclude = Variables Modules::RequirePackage #Space-delimited list
489 The remainder of the configuration file is a series of blocks like
491 this:
492 [Perl::Critic::Policy::Category::PolicyName]
494 severity = 1
495 set_themes = foo bar
496 add_themes = baz
497 arg1 = value1
498 arg2 = value2
499 "Perl::Critic::Policy::Category::PolicyName" is the full name of a
501 module that implements the policy. The Policy modules distributed with
502 Perl::Critic have been grouped into categories according to the table
503 of contents in Damian Conway's book Perl Best Practices. For brevity,
504 you can omit the 'Perl::Critic::Policy' part of the module name.
505 "severity" is the level of importance you wish to assign to the Policy.
507 All Policy modules are defined with a default severity value ranging
508 from 1 (least severe) to 5 (most severe). However, you may disagree
509 with the default severity and choose to give it a higher or lower
510 severity, based on your own coding philosophy. You can set the
511 "severity" to an integer from 1 to 5, or use one of the equivalent
512 names:
513 SEVERITY NAME ...is equivalent to... SEVERITY NUMBER
515 ----------------------------------------------------
516 gentle 5
517 stern 4
518 harsh 3
519 cruel 2
520 brutal 1
521 "set_themes" sets the theme for the Policy and overrides its default
523 theme. The argument is a string of one or more whitespace-delimited
524 alphanumeric words. Themes are case-insensitive. See "POLICY THEMES"
525 for more information.
526 "add_themes" appends to the default themes for this Policy. The
528 argument is a string of one or more whitespace-delimited words. Themes
529 are case- insensitive. See "POLICY THEMES" for more information.
530 The remaining key-value pairs are configuration parameters that will be
532 passed into the constructor of that Policy. The constructors for most
533 Policy modules do not support arguments, and those that do should have
534 reasonable defaults. See the documentation on the appropriate Policy
535 module for more details.
536 Instead of redefining the severity for a given Policy, you can
538 completely disable a Policy by prepending a '-' to the name of the
539 module in your configuration file. In this manner, the Policy will
540 never be loaded, regardless of the "--severity" given on the command
541 line.
542 A simple configuration might look like this:
544 #--------------------------------------------------------------
546 # I think these are really important, so always load them
547 [TestingAndDebugging::RequireUseStrict]
549 severity = 5
550 [TestingAndDebugging::RequireUseWarnings]
552 severity = 5
553 #--------------------------------------------------------------
555 # I think these are less important, so only load when asked
556 [Variables::ProhibitPackageVars]
558 severity = 2
559 [ControlStructures::ProhibitPostfixControls]
561 allow = if unless # My custom configuration
562 severity = cruel # Same as "severity = 2"
563 #--------------------------------------------------------------
565 # Give these policies a custom theme. I can activate just
566 # these policies by saying "perlcritic --theme 'larry || curly'"
567 [Modules::RequireFilenameMatchesPackage]
569 add_themes = larry
570 [TestingAndDebugging::RequireTestLabels]
572 add_themes = curly moe
573 #--------------------------------------------------------------
575 # I do not agree with these at all, so never load them
576 [-NamingConventions::Capitalization]
578 [-ValuesAndExpressions::ProhibitMagicNumbers]
579 #--------------------------------------------------------------
581 # For all other Policies, I accept the default severity,
582 # so no additional configuration is required for them.
583 Note that all policies included with the Perl::Critic distribution that
585 have integer parameters accept underscores ("_") in their values, as
586 with Perl numeric literals. For example,
587 [ValuesAndExpressions::RequireNumberSeparators]
589 min_value = 1_000
590 For additional configuration examples, see the perlcriticrc file that
592 is included in this examples directory of this distribution.
593 Damian Conway's own Perl::Critic configuration is also included in this
595 distribution as examples/perlcriticrc-conway.
596
598 A large number of Policy modules are distributed with Perl::Critic.
599 They are described briefly in the companion document
600 Perl::Critic::PolicySummary and in more detail in the individual
601 modules themselves. Say "perlcritic --doc PATTERN" to see the perldoc
602 for all Policy modules that match the regex "m/PATTERN/ixms"
603 There are a number of distributions of additional policies on CPAN. If
605 Perl::Critic doesn't contain a policy that you want, some one may have
606 already written it. See "SEE ALSO" in Perl::Critic for a list of some
607 of these distributions.
608
610 Each Policy is defined with one or more "themes". Themes can be used
611 to create arbitrary groups of Policies. They are intended to provide
612 an alternative mechanism for selecting your preferred set of Policies.
613 For example, you may wish disable a certain set of Policies when
614 analyzing test programs. Conversely, you may wish to enable only a
615 specific subset of Policies when analyzing modules.
616 The Policies that ship with Perl::Critic are have been divided into the
618 following themes. This is just our attempt to provide some basic
619 logical groupings. You are free to invent new themes that suit your
620 needs.
621 THEME DESCRIPTION
623 ------------------------------------------------------------------------
624 core All policies that ship with Perl::Critic
625 pbp Policies that come directly from "Perl Best Practices"
626 bugs Policies that that prevent or reveal bugs
627 certrec Policies that CERT recommends
628 certrule Policies that CERT considers rules
629 maintenance Policies that affect the long-term health of the code
630 cosmetic Policies that only have a superficial effect
631 complexity Policies that specificaly relate to code complexity
632 security Policies that relate to security issues
633 tests Policies that are specific to test programs
634 Say "perlcritic --list" to get a listing of all available policies and
636 the themes that are associated with each one. You can also change the
637 theme for any Policy in your .perlcriticrc file. See the
638 "CONFIGURATION" section for more information about that.
639 Using the "--theme" command-line option, you can create an arbitrarily
641 complex rule that determines which Policies to apply. Precedence is the
642 same as regular Perl code, and you can use parentheses to enforce
643 precedence as well. Supported operators are:
644 Operator Altertative Example
646 -----------------------------------------------------------------
647 && and 'pbp && core'
648 || or 'pbp || (bugs && security)'
649 ! not 'pbp && ! (portability || complexity)'
650 Theme names are case-insensitive. If the "--theme" is set to an empty
652 string, then it evaluates as true all Policies.
653
655 Perl::Critic takes a hard-line approach to your code: either you comply
656 or you don't. In the real world, it is not always practical (or even
657 possible) to fully comply with coding standards. In such cases, it is
658 wise to show that you are knowingly violating the standards and that
659 you have a Damn Good Reason (DGR) for doing so.
660 To help with those situations, you can direct Perl::Critic to ignore
662 certain lines or blocks of code by using annotations:
663 require 'LegacyLibaray1.pl'; ## no critic
665 require 'LegacyLibrary2.pl'; ## no critic
666 for my $element (@list) {
668 ## no critic
670 $foo = ""; #Violates 'ProhibitEmptyQuotes'
672 $barf = bar() if $foo; #Violates 'ProhibitPostfixControls'
673 #Some more evil code...
674 ## use critic
676 #Some good code...
678 do_something($_);
679 }
680 The "## no critic" annotations direct Perl::Critic to ignore the
682 remaining lines of code until a "## use critic" annotation is found. If
683 the "## no critic" annotation is on the same line as a code statement,
684 then only that line of code is overlooked. To direct perlcritic to
685 ignore the "## no critic" annotations, use the "--force" option.
686 A bare "## no critic" annotation disables all the active Policies. If
688 you wish to disable only specific Policies, add a list of Policy names
689 as arguments just as you would for the "no strict" or "no warnings"
690 pragma. For example, this would disable the "ProhibitEmptyQuotes" and
691 "ProhibitPostfixControls" policies until the end of the block or until
692 the next "## use critic" annotation (whichever comes first):
693 ## no critic (EmptyQuotes, PostfixControls);
695 # Now exempt from ValuesAndExpressions::ProhibitEmptyQuotes
697 $foo = "";
698 # Now exempt ControlStructures::ProhibitPostfixControls
700 $barf = bar() if $foo;
701 # Still subject to ValuesAndExpression::RequireNumberSeparators
703 $long_int = 10000000000;
704 Since the Policy names are matched against the "## no critic" arguments
706 as regular expressions, you can abbreviate the Policy names or disable
707 an entire family of Policies in one shot like this:
708 ## no critic (NamingConventions)
710 # Now exempt from NamingConventions::Capitalization
712 my $camelHumpVar = 'foo';
713 # Now exempt from NamingConventions::Capitalization
715 sub camelHumpSub {}
716 The argument list must be enclosed in parentheses and must contain one
718 or more comma-separated barewords (i.e. don't use quotes). The "## no
719 critic" annotations can be nested, and Policies named by an inner
720 annotation will be disabled along with those already disabled an outer
721 annotation.
722 Some Policies like "Subroutines::ProhibitExcessComplexity" apply to an
724 entire block of code. In those cases, "## no critic" must appear on
725 the line where the violation is reported. For example:
726 sub complicated_function { ## no critic (ProhibitExcessComplexity)
728 # Your code here...
729 }
730 Some Policies like "Documentation::RequirePodSections" apply to the
732 entire document, in which case violations are reported at line 1. But
733 if the file requires a shebang line, it is impossible to put "## no
734 critic" on the first line of the file. This is a known limitation and
735 it will be addressed in a future release. As a workaround, you can
736 disable the affected policies at the command-line or in your
737 .perlcriticrc file. But beware that this will affect the analysis of
738 all files.
739 Use this feature wisely. "## no critic" should be used in the smallest
741 possible scope, or only on individual lines of code. And you should
742 always be as specific as possible about which policies you want to
743 disable (i.e. never use a bare "## no critic"). If Perl::Critic
744 complains about your code, try and find a compliant solution before
745 resorting to this feature.
746
748 For ease-of-use, "perlcritic" can be integrated with your favorite text
749 editor. The output-formatting capabilities of "perlcritic" are
750 specifically intended for use with the "grep" or "compile" modes
751 available in editors like "emacs" and "vim". In these modes, you can
752 run an arbitrary command and the editor will parse the output into an
753 interactive buffer that you can click on and jump to the relevant line
754 of code.
755 The Perl::Critic team thanks everyone who has helped integrate Perl-
757 Critic with their favorite editor. Your contributions in particular
758 have made Perl- Critic a convenient and user-friendly tool for Perl
759 developers of all stripes. We sincerely appreciate your hard work.
760 EMACS
762 Joshua ben Jore has authored a minor-mode for emacs that allows you to
763 run perlcritic on the current region or buffer. You can run it on
764 demand, or configure it to run automatically when you save the buffer.
765 The output appears in a hot-linked compiler buffer. The code and
766 installation instructions can be found in the extras directory inside
767 this distribution.
768 VIM
770 Scott Peshak has published perlchecker.vim, which is available at
771 <http://www.vim.org/scripts/script.php?script_id=1731>.
772 gVIM
774 Fritz Mehner recently added support for "perlcritic" to his fantastic
775 gVIM plugin. In addition to providing a very Perlish IDE, Fritz's
776 plugin enables one-click access to "perlcritic" and many other very
777 useful utilities. And all is seamlessly integrated into the editor.
778 See <http://lug.fh-swf.de/vim/vim-perl/screenshots-en.html> for
779 complete details.
780 EPIC
782 EPIC is an open source Perl IDE based on the Eclipse platform. Features
783 include syntax highlighting, on-the-fly syntax check, content assist,
784 code completion, perldoc support, source formatting with Perl::Tidy,
785 code templates, a regular expression editing tool, and integration with
786 the Perl debugger. Recent versions of EPIC also have built-in support
787 for Perl::Critic. At least one Perl::Critic contributor swears by
788 EPIC. Go to <http://e-p-i-c.sourceforge.net> for more information
789 about EPIC.
790 BBEdit
792 Josh Clark has produced an excellent Perl-Critic plugin for BBEdit. See
793 <http://globalmoxie.com/projects/bbedit-perl-critic/index.shtml> for
794 download, installation, and usage instructions. Apple users rejoice!
795 Komodo
797 Komodo is a proprietary IDE for Perl and several other dynamic
798 languages. Starting in version 5.1.1, Komodo has built-in support for
799 Perl-Critic, if you have the Perl::Critic and criticism modules
800 installed. Free trial copies of Komodo can be obtained from the
801 ActiveState website at <http://www.activestate.com>.
802 ActivePerl
804 ActivePerl includes a very slick graphical interface for configuring
805 and running Perl-Critic called "perlcritic-gui". A free community
806 edition of ActivePerl can be obtained from the ActiveState website at
807 <http://www.activestate.com>.
808
810 If "perlcritic" has any errors itself, exits with status == 1. If
811 there are no errors, but "perlcritic" finds Policy violations in your
812 source code, exits with status == 2. If there were no errors and no
813 violations were found, exits with status == 0.
814
816 Coding standards are deeply personal and highly subjective. The
817 goal of Perl::Critic is to help you write code that conforms with a
818 set of best practices. Our primary goal is not to dictate what
819 those practices are, but rather, to implement the practices
820 discovered by others. Ultimately, you make the rules --
821 Perl::Critic is merely a tool for encouraging consistency. If
822 there is a policy that you think is important or that we have
823 overlooked, we would be very grateful for contributions, or you can
824 simply load your own private set of policies into Perl::Critic.
825
827 The modular design of Perl::Critic is intended to facilitate the
828 addition of new Policies. You'll need to have some understanding of
829 PPI, but most Policy modules are pretty straightforward and only
830 require about 20 lines of code. Please see the Perl::Critic::DEVELOPER
831 file included in this distribution for a step-by-step demonstration of
832 how to create new Policy modules.
833 If you develop any new Policy modules, feel free to send them to
835 "<team@perlcritic.com>" and I'll be happy to consider putting them into
836 the Perl::Critic distribution. Or if you would like to work on the
837 Perl::Critic project directly, you can fork our repository at
838 <https://github.com/Perl-Critic/Perl-Critic.git>.
839 The Perl::Critic team is also available for hire. If your organization
841 has its own coding standards, we can create custom Policies to enforce
842 your local guidelines. Or if your code base is prone to a particular
843 defect pattern, we can design Policies that will help you catch those
844 costly defects before they go into production. To discuss your needs
845 with the Perl::Critic team, just contact "<team@perlcritic.com>".
846
848 You are encouraged to subscribe to the mailing list at
849 <https://groups.google.com/d/forum/perl-critic>. At least one member
850 of the development team is usually hanging around in
851 <irc://irc.perl.org/#perlcritic> and you can follow Perl::Critic on
852 Twitter, at <https://twitter.com/perlcritic>.
853
855 There are a number of distributions of additional Policies available. A
856 few are listed here:
857 Perl::Critic::More
859 Perl::Critic::Bangs
861 Perl::Critic::Lax
863 Perl::Critic::StricterSubs
865 Perl::Critic::Swift
867 Perl::Critic::Tics
869 These distributions enable you to use Perl::Critic in your unit tests:
871 Test::Perl::Critic
873 Test::Perl::Critic::Progressive
875 There is also a distribution that will install all the Perl::Critic
877 related modules known to the development team:
878 Task::Perl::Critic
880
882 Scrutinizing Perl code is hard for humans, let alone machines. If you
883 find any bugs, particularly false-positives or false-negatives from a
884 Perl::Critic::Policy, please submit them at
885 <https://github.com/Perl-Critic/Perl-Critic/issues>. Thanks.
886
888 Adam Kennedy - For creating PPI, the heart and soul of Perl::Critic.
889 Damian Conway - For writing Perl Best Practices, finally :)
891 Chris Dolan - For contributing the best features and Policy modules.
893 Andy Lester - Wise sage and master of all-things-testing.
895 Elliot Shank - The self-proclaimed quality freak.
897 Giuseppe Maxia - For all the great ideas and positive encouragement.
899 and Sharon, my wife - For putting up with my all-night code sessions.
901 Thanks also to the Perl Foundation for providing a grant to support
903 Chris Dolan's project to implement twenty PBP policies.
904 <http://www.perlfoundation.org/april_1_2007_new_grant_awards>
905
907 Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
908
910 Copyright (c) 2005-2011 Imaginative Software Systems. All rights
911 reserved.
912 This program is free software; you can redistribute it and/or modify it
914 under the same terms as Perl itself. The full text of this license can
915 be found in the LICENSE file included with this module.
916perl v5.36.0 2022-07-22 PERLCRITIC(1)