Login
svn merge -r 2029:2018 ProhibitNegativeExpressionsInUnlessAndUntilConditions.run.PL
[gknop/Perl-Critic.git] / README
CommitLineData
b9e35135
JRT
1NAME
2 Perl::Critic - Critique Perl source code for best-practices
3
4SYNOPSIS
5 use Perl::Critic;
6 my $file = shift;
7 my $critic = Perl::Critic->new();
8 my @violations = $critic->critique($file);
9 print @violations;
10
11DESCRIPTION
12 Perl::Critic is an extensible framework for creating and applying coding
13 standards to Perl source code. Essentially, it is a static source code
14 analysis engine. Perl::Critic is distributed with a number of
15 Perl::Critic::Policy modules that attempt to enforce various coding
16 guidelines. Most Policy modules are based on Damian Conway's book Perl
17 Best Practices. However, Perl::Critic is not limited to PBP and will
18 even support Policies that contradict Conway. You can enable, disable,
19 and customize those Polices through the Perl::Critic interface. You can
20 also create new Policy modules that suit your own tastes.
21
b4c7e33c
JRT
22 For a command-line interface to Perl::Critic, see the documentation for
23 perlcritic. If you want to integrate Perl::Critic with your build
24 process, Test::Perl::Critic provides an interface that is suitable for
a60e94d6
ES
25 test scripts. Also, Test::Perl::Critic::Progressive is useful for
26 gradually applying coding standards to legacy code. For the ultimate
27 convenience (at the expense of some flexibility) see the criticism
28 pragma.
b9e35135
JRT
29
30 Win32 and ActivePerl users can find PPM distributions of Perl::Critic at
31 <http://theoryx5.uwinnipeg.ca/ppms/>.
32
a3f5707d
JRT
33 If you'd like to try Perl::Critic without installing anything, there is
34 a web-service available at <http://perlcritic.com>. The web-service does
b9e35135
JRT
35 not yet support all the configuration features that are available in the
36 native Perl::Critic API, but it should give you a good idea of what it
7b2c2404
JRT
37 does. You can also invoke the perlcritic web-service from the
38 command-line by doing an HTTP-post, such as one of these:
a3f5707d 39
b4c7e33c
JRT
40 $> POST http://perlcritic.com/perl/critic.pl < MyModule.pm
41 $> lwp-request -m POST http://perlcritic.com/perl/critic.pl < MyModule.pm
42 $> wget -q -O - --post-file=MyModule.pm http://perlcritic.com/perl/critic.pl
a3f5707d
JRT
43
44 Please note that the perlcritic web-service is still alpha code. The URL
45 and interface to the service are subject to change.
b9e35135
JRT
46
47CONSTRUCTOR
a3f5707d 48 "new( [ -profile => $FILE, -severity => $N, -theme => $string, -include
a60e94d6
ES
49 => \@PATTERNS, -exclude => \@PATTERNS, -top => $N, -only => $B,
50 -profile-strictness => $PROFILE_STRICTNESS_{WARN|FATAL|QUIET}, -force =>
51 $B, -verbose => $N ], -color => $B )"
b4c7e33c 52 "new( -config => Perl::Critic::Config->new() )"
a3f5707d 53 "new()" Returns a reference to a new Perl::Critic object. Most arguments
b9e35135 54 are just passed directly into Perl::Critic::Config, but I have
a3f5707d
JRT
55 described them here as well. The default value for all arguments
56 can be defined in your .perlcriticrc file. See the
57 "CONFIGURATION" section for more information about that. All
58 arguments are optional key-value pairs as follows:
b9e35135
JRT
59
60 -profile is a path to a configuration file. If $FILE is not
61 defined, Perl::Critic::Config attempts to find a .perlcriticrc
62 configuration file in the current directory, and then in your
63 home directory. Alternatively, you can set the "PERLCRITIC"
64 environment variable to point to a file in another location. If
65 a configuration file can't be found, or if $FILE is an empty
66 string, then all Policies will be loaded with their default
67 configuration. See "CONFIGURATION" for more information.
68
69 -severity is the minimum severity level. Only Policy modules
7b2c2404 70 that have a severity greater than $N will be applied. Severity
b9e35135
JRT
71 values are integers ranging from 1 (least severe) to 5 (most
72 severe). The default is 5. For a given "-profile", decreasing
7b2c2404
JRT
73 the "-severity" will usually reveal more Policy violations. You
74 can set the default value for this option in your .perlcriticrc
75 file. Users can redefine the severity level for any Policy in
76 their .perlcriticrc file. See "CONFIGURATION" for more
77 information.
b9e35135 78
b4c7e33c
JRT
79 If it is difficult for you to remember whether severity "5" is
80 the most or least restrictive level, then you can use one of
81 these named values:
82
83 SEVERITY NAME ...is equivalent to... SEVERITY NUMBER
84 --------------------------------------------------------
85 -severity => 'gentle' -severity => 5
86 -severity => 'stern' -severity => 4
87 -severity => 'harsh' -severity => 3
88 -severity => 'cruel' -severity => 2
89 -severity => 'brutal' -severity => 1
90
7b2c2404
JRT
91 -theme is special expression that determines which Policies to
92 apply based on their respective themes. For example, the
93 following would load only Policies that have a 'bugs' AND 'pbp'
94 theme:
a3f5707d 95
7b2c2404 96 my $critic = Perl::Critic->new( -theme => 'bugs && pbp' );
a3f5707d 97
7b2c2404
JRT
98 Unless the "-severity" option is explicitly given, setting
99 "-theme" silently causes the "-severity" to be set to 1. You can
100 set the default value for this option in your .perlcriticrc
101 file. See the "POLICY THEMES" section for more information about
102 themes.
a3f5707d 103
b9e35135
JRT
104 -include is a reference to a list of string @PATTERNS. Policy
105 modules that match at least one "m/$PATTERN/imx" will always be
a3f5707d 106 loaded, irrespective of all other settings. For example:
b9e35135
JRT
107
108 my $critic = Perl::Critic->new(-include => ['layout'] -severity => 4);
109
7b2c2404 110 This would cause Perl::Critic to apply all the "CodeLayout::*"
b9e35135 111 Policy modules even though they have a severity level that is
7b2c2404
JRT
112 less than 4. You can set the default value for this option in
113 your .perlcriticrc file. You can also use "-include" in
114 conjunction with the "-exclude" option. Note that "-exclude"
115 takes precedence over "-include" when a Policy matches both
116 patterns.
b9e35135
JRT
117
118 -exclude is a reference to a list of string @PATTERNS. Policy
119 modules that match at least one "m/$PATTERN/imx" will not be
a3f5707d 120 loaded, irrespective of all other settings. For example:
b9e35135
JRT
121
122 my $critic = Perl::Critic->new(-exclude => ['strict'] -severity => 1);
123
7b2c2404
JRT
124 This would cause Perl::Critic to not apply the
125 "RequireUseStrict" and "ProhibitNoStrict" Policy modules even
126 though they have a severity level that is greater than 1. You
127 can set the default value for this option in your .perlcriticrc
128 file. You can also use "-exclude" in conjunction with the
129 "-include" option. Note that "-exclude" takes precedence over
130 "-include" when a Policy matches both patterns.
b9e35135 131
a60e94d6 132 -single-policy is a string "PATTERN". Only one policy that
7b2c2404
JRT
133 matches "m/$PATTERN/imx" will be used. Policies that do not
134 match will be excluded. This option has precedence over the
ffe5f1a7 135 "-severity", "-theme", "-include", "-exclude", and "-only"
7b2c2404
JRT
136 options. You can set the default value for this option in your
137 .perlcriticrc file.
ffe5f1a7 138
b9e35135 139 -top is the maximum number of Violations to return when ranked
a3f5707d
JRT
140 by their severity levels. This must be a positive integer.
141 Violations are still returned in the order that they occur
142 within the file. Unless the "-severity" option is explicitly
143 given, setting "-top" silently causes the "-severity" to be set
7b2c2404
JRT
144 to 1. You can set the default value for this option in your
145 .perlcriticrc file.
a3f5707d
JRT
146
147 -only is a boolean value. If set to a true value, Perl::Critic
148 will only choose from Policies that are mentioned in the user's
149 profile. If set to a false value (which is the default), then
150 Perl::Critic chooses from all the Policies that it finds at your
7b2c2404
JRT
151 site. You can set the default value for this option in your
152 .perlcriticrc file.
b9e35135 153
a60e94d6
ES
154 -profile-strictness is an enumerated value, one of
155 "$PROFILE_STRICTNESS_WARN" in Perl::Critic::Utils::Constants
156 (the default), "$PROFILE_STRICTNESS_FATAL" in
157 Perl::Critic::Utils::Constants, and "$PROFILE_STRICTNESS_QUIET"
158 in Perl::Critic::Utils::Constants. If set to
159 "$PROFILE_STRICTNESS_FATAL" in Perl::Critic::Utils::Constants,
160 Perl::Critic will make certain warnings about problems found in
161 a .perlcriticrc or file specified via the -profile option fatal.
162 For example, Perl::Critic normally only "warn"s about profiles
163 referring to non-existent Policies, but this value makes this
164 situation fatal. Correspondingly, "$PROFILE_STRICTNESS_QUIET" in
165 Perl::Critic::Utils::Constants makes Perl::Critic shut up about
166 these things.
167
b4c7e33c
JRT
168 -force is a boolean value that controls whether Perl::Critic
169 observes the magical "## no critic" pseudo-pragmas in your code.
170 If set to a true value, Perl::Critic will analyze all code. If
171 set to a false value (which is the default) Perl::Critic will
172 ignore code that is tagged with these comments. See "BENDING THE
7b2c2404
JRT
173 RULES" for more information. You can set the default value for
174 this option in your .perlcriticrc file.
b9e35135 175
b4c7e33c 176 -verbose can be a positive integer (from 1 to 11), or a literal
a3f5707d 177 format specification. See Perl::Critic::Violations for an
7b2c2404
JRT
178 explanation of format specifications. You can set the default
179 value for this option in your .perlcriticrc file.
a3f5707d 180
a60e94d6
ES
181 -color is not used by Perl::Critic but is provided for the
182 benefit of perlcritic.
183
b9e35135
JRT
184 -config is a reference to a Perl::Critic::Config object. If you
185 have created your own Config object for some reason, you can
186 pass it in here instead of having Perl::Critic create one for
187 you. Using the "-config" option causes all the other options to
188 be silently ignored.
189
190METHODS
191 "critique( $source_code )"
192 Runs the $source_code through the Perl::Critic engine using all
193 the Policies that have been loaded into this engine. If
b4c7e33c
JRT
194 $source_code is a scalar reference, then it is treated as a
195 string of actual Perl code. If $source_code is a reference to an
b9e35135
JRT
196 instance of PPI::Document, then that instance is used directly.
197 Otherwise, it is treated as a path to a local file containing
b4c7e33c 198 Perl code. This method returns a list of Perl::Critic::Violation
b9e35135
JRT
199 objects for each violation of the loaded Policies. The list is
200 sorted in the order that the Violations appear in the code. If
201 there are no violations, this method returns an empty list.
202
a3f5707d 203 "add_policy( -policy => $policy_name, -params => \%param_hash )"
b9e35135 204 Creates a Policy object and loads it into this Critic. If the
a3f5707d
JRT
205 object cannot be instantiated, it will throw a fatal exception.
206 Otherwise, it returns a reference to this Critic.
b9e35135
JRT
207
208 -policy is the name of a Perl::Critic::Policy subclass module.
209 The 'Perl::Critic::Policy' portion of the name can be omitted
210 for brevity. This argument is required.
211
a3f5707d
JRT
212 -params is an optional reference to a hash of Policy parameters.
213 The contents of this hash reference will be passed into to the
214 constructor of the Policy module. See the documentation in the
215 relevant Policy module for a description of the arguments it
216 supports.
b9e35135 217
a3f5707d 218 " policies() "
b9e35135
JRT
219 Returns a list containing references to all the Policy objects
220 that have been loaded into this engine. Objects will be in the
221 order that they were loaded.
222
a3f5707d 223 " config() "
b9e35135
JRT
224 Returns the Perl::Critic::Config object that was created for or
225 given to this Critic.
226
a60e94d6
ES
227 " statistics() "
228 Returns the Perl::Critic::Statistics object that was created for
229 this Critic. The Statistics object accumulates data for all
230 files that are analyzed by this Critic.
231
b9e35135
JRT
232FUNCTIONAL INTERFACE
233 For those folks who prefer to have a functional interface, The
234 "critique" method can be exported on request and called as a static
235 function. If the first argument is a hashref, its contents are used to
236 construct a new Perl::Critic object internally. The keys of that hash
237 should be the same as those supported by the "Perl::Critic::new" method.
238 Here are some examples:
239
240 use Perl::Critic qw(critique);
241
242 # Use default parameters...
243 @violations = critique( $some_file );
244
245 # Use custom parameters...
246 @violations = critique( {-severity => 2}, $some_file );
247
248 # As a one-liner
249 %> perl -MPerl::Critic=critique -e 'print critique(shift)' some_file.pm
250
251 None of the other object-methods are currently supported as static
252 functions. Sorry.
253
254CONFIGURATION
a3f5707d
JRT
255 Most of the settings for Perl::Critic and each of the Policy modules can
256 be controlled by a configuration file. The default configuration file is
257 called .perlcriticrc. Perl::Critic will look for this file in the
258 current directory first, and then in your home directory. Alternatively,
259 you can set the "PERLCRITIC" environment variable to explicitly point to
260 a different file in another location. If none of these files exist, and
261 the "-profile" option is not given to the constructor, then all the
262 modules that are found in the Perl::Critic::Policy namespace will be
263 loaded with their default configuration.
264
265 The format of the configuration file is a series of INI-style blocks
b9e35135
JRT
266 that contain key-value pairs separated by '='. Comments should start
267 with '#' and can be placed on a separate line or after the name-value
a3f5707d
JRT
268 pairs if you desire.
269
270 Default settings for Perl::Critic itself can be set before the first
271 named block. For example, putting any or all of these at the top of your
272 configuration file will set the default value for the corresponding
7b2c2404 273 constructor argument.
a3f5707d 274
b4c7e33c 275 severity = 3 #Integer or named level
a3f5707d
JRT
276 only = 1 #Zero or One
277 force = 0 #Zero or One
278 verbose = 4 #Integer or format spec
279 top = 50 #A positive integer
7b2c2404 280 theme = (pbp || security) && bugs #A theme expression
a3f5707d
JRT
281 include = NamingConventions ClassHierarchies #Space-delimited list
282 exclude = Variables Modules::RequirePackage #Space-delimited list
a60e94d6 283 color = 1 #Zero or One
a3f5707d
JRT
284
285 The remainder of the configuration file is a series of blocks like this:
286
287 [Perl::Critic::Policy::Category::PolicyName]
288 severity = 1
ffe5f1a7
JRT
289 set_themes = foo bar
290 add_themes = baz
a3f5707d
JRT
291 arg1 = value1
292 arg2 = value2
b9e35135
JRT
293
294 "Perl::Critic::Policy::Category::PolicyName" is the full name of a
295 module that implements the policy. The Policy modules distributed with
296 Perl::Critic have been grouped into categories according to the table of
297 contents in Damian Conway's book Perl Best Practices. For brevity, you
298 can omit the 'Perl::Critic::Policy' part of the module name.
299
300 "severity" is the level of importance you wish to assign to the Policy.
301 All Policy modules are defined with a default severity value ranging
302 from 1 (least severe) to 5 (most severe). However, you may disagree with
303 the default severity and choose to give it a higher or lower severity,
b4c7e33c
JRT
304 based on your own coding philosophy. You can set the "severity" to an
305 integer from 1 to 5, or use one of the equivalent names:
306
307 SEVERITY NAME ...is equivalent to... SEVERITY NUMBER
308 ----------------------------------------------------
309 gentle 5
310 stern 4
311 harsh 3
312 cruel 2
313 brutal 1
314
315 "set_themes" sets the theme for the Policy and overrides its default
316 theme. The argument is a string of one or more whitespace-delimited
317 alphanumeric words. Themes are case-insensitive. See "POLICY THEMES" for
318 more information.
319
320 "add_themes" appends to the default themes for this Policy. The argument
321 is a string of one or more whitespace-delimited words. Themes are
322 case-insensitive. See "POLICY THEMES" for more information.
b9e35135
JRT
323
324 The remaining key-value pairs are configuration parameters that will be
325 passed into the constructor for that Policy. The constructors for most
326 Policy objects do not support arguments, and those that do should have
327 reasonable defaults. See the documentation on the appropriate Policy
328 module for more details.
329
330 Instead of redefining the severity for a given Policy, you can
331 completely disable a Policy by prepending a '-' to the name of the
332 module in your configuration file. In this manner, the Policy will never
333 be loaded, regardless of the "-severity" given to the Perl::Critic
334 constructor.
335
336 A simple configuration might look like this:
337
a3f5707d
JRT
338 #--------------------------------------------------------------
339 # I think these are really important, so always load them
340
341 [TestingAndDebugging::RequireUseStrict]
342 severity = 5
343
344 [TestingAndDebugging::RequireUseWarnings]
345 severity = 5
b9e35135 346
a3f5707d
JRT
347 #--------------------------------------------------------------
348 # I think these are less important, so only load when asked
b9e35135 349
a3f5707d
JRT
350 [Variables::ProhibitPackageVars]
351 severity = 2
b9e35135 352
a3f5707d 353 [ControlStructures::ProhibitPostfixControls]
b4c7e33c
JRT
354 allow = if unless # My custom configuration
355 severity = cruel # Same as "severity = 2"
b9e35135 356
a3f5707d
JRT
357 #--------------------------------------------------------------
358 # Give these policies a custom theme. I can activate just
359 # these policies by saying `perlcritic -theme larry`
b9e35135 360
a3f5707d 361 [Modules::RequireFilenameMatchesPackage]
ffe5f1a7 362 add_themes = larry
b9e35135 363
a3f5707d 364 [TestingAndDebugging::RequireTestLables]
ffe5f1a7 365 add_themes = larry curly moe
b9e35135 366
a3f5707d
JRT
367 #--------------------------------------------------------------
368 # I do not agree with these at all, so never load them
b9e35135 369
a3f5707d
JRT
370 [-NamingConventions::ProhibitMixedCaseVars]
371 [-NamingConventions::ProhibitMixedCaseSubs]
b9e35135 372
a3f5707d
JRT
373 #--------------------------------------------------------------
374 # For all other Policies, I accept the default severity,
375 # so no additional configuration is required for them.
b9e35135 376
ffe5f1a7 377 For additional configuration examples, see the perlcriticrc file that is
7b2c2404 378 included in this examples directory of this distribution.
ffe5f1a7 379
e1fb2898 380 Damian Conway's own Perl::Critic configuration is also included in this
34883f65 381 distribution as examples/perlcriticrc-conway.
e1fb2898 382
b9e35135
JRT
383THE POLICIES
384 A large number of Policy modules are distributed with Perl::Critic. They
385 are described briefly in the companion document
386 Perl::Critic::PolicySummary and in more detail in the individual modules
b4c7e33c
JRT
387 themselves. Say ""perlcritic -doc PATTERN"" to see the perldoc for all
388 Policy modules that match the regex "m/PATTERN/imx"
b9e35135 389
a60e94d6
ES
390 There are a number of distributions of additional policies on CPAN. If
391 Perl::Critic doesn't contain a policy that you want, some one may have
392 already written it. See the "SEE ALSO" section below for a list of some
393 of these distributions.
394
a3f5707d
JRT
395POLICY THEMES
396 Each Policy is defined with one or more "themes". Themes can be used to
397 create arbitrary groups of Policies. They are intended to provide an
b4c7e33c
JRT
398 alternative mechanism for selecting your preferred set of Policies. For
399 example, you may wish disable a certain subset of Policies when
400 analyzing test scripts. Conversely, you may wish to enable only a
401 specific subset of Policies when analyzing modules.
402
403 The Policies that ship with Perl::Critic are have been broken into the
404 following themes. This is just our attempt to provide some basic logical
405 groupings. You are free to invent new themes that suit your needs.
406
407 THEME DESCRIPTION
408 --------------------------------------------------------------------------
409 core All policies that ship with Perl::Critic
410 pbp Policies that come directly from "Perl Best Practices"
411 bugs Policies that that prevent or reveal bugs
412 maintenance Policies that affect the long-term health of the code
413 cosmetic Policies that only have a superficial effect
414 complexity Policies that specificaly relate to code complexity
415 security Policies that relate to security issues
416 tests Policies that are specific to test scripts
417
418 Any Policy may fit into multiple themes. Say "perlcritic -list" to get a
419 listing of all available Policies and the themes that are associated
420 with each one. You can also change the theme for any Policy in your
421 .perlcriticrc file. See the "CONFIGURATION" section for more information
422 about that.
423
7b2c2404
JRT
424 Using the "-theme" option, you can create an arbitrarily complex rule
425 that determines which Policies will be loaded. Precedence is the same as
426 regular Perl code, and you can use parens to enforce precedence as well.
427 Supported operators are:
a3f5707d 428
7b2c2404 429 Operator Altertative Example
a3f5707d 430 ----------------------------------------------------------------------------
7b2c2404
JRT
431 && and 'pbp && core'
432 || or 'pbp || (bugs && security)'
433 ! not 'pbp && ! (portability || complexity)'
a3f5707d 434
7b2c2404
JRT
435 Theme names are case-insensitive. If the "-theme" is set to an empty
436 string, then it evaluates as true all Policies.
a3f5707d 437
b9e35135
JRT
438BENDING THE RULES
439 Perl::Critic takes a hard-line approach to your code: either you comply
440 or you don't. In the real world, it is not always practical (nor even
441 possible) to fully comply with coding standards. In such cases, it is
442 wise to show that you are knowingly violating the standards and that you
443 have a Damn Good Reason (DGR) for doing so.
444
445 To help with those situations, you can direct Perl::Critic to ignore
446 certain lines or blocks of code by using pseudo-pragmas:
447
448 require 'LegacyLibaray1.pl'; ## no critic
449 require 'LegacyLibrary2.pl'; ## no critic
450
451 for my $element (@list) {
452
453 ## no critic
454
455 $foo = ""; #Violates 'ProhibitEmptyQuotes'
456 $barf = bar() if $foo; #Violates 'ProhibitPostfixControls'
457 #Some more evil code...
458
459 ## use critic
460
461 #Some good code...
462 do_something($_);
463 }
464
465 The "## no critic" comments direct Perl::Critic to ignore the remaining
7b2c2404
JRT
466 lines of code until the end of the current block, or until a ""## use
467 critic"" comment is found (whichever comes first). If the "## no critic"
b9e35135
JRT
468 comment is on the same line as a code statement, then only that line of
469 code is overlooked. To direct perlcritic to ignore the "## no critic"
470 comments, use the "-force" option.
471
472 A bare "## no critic" comment disables all the active Policies. If you
473 wish to disable only specific Policies, add a list of Policy names as
7b2c2404 474 arguments, just as you would for the "no strict" or "no warnings"
b9e35135
JRT
475 pragmas. For example, this would disable the "ProhibitEmptyQuotes" and
476 "ProhibitPostfixControls" policies until the end of the block or until
477 the next "## use critic" comment (whichever comes first):
478
479 ## no critic (EmptyQuotes, PostfixControls)
480
b4c7e33c
JRT
481 # Now exempt from ValuesAndExpressions::ProhibitEmptyQuotes
482 $foo = "";
483
484 # Now exempt ControlStructures::ProhibitPostfixControls
485 $barf = bar() if $foo;
b9e35135 486
b4c7e33c
JRT
487 # Still subjected to ValuesAndExpression::RequireNumberSeparators
488 $long_int = 10000000000;
489
490 Since the Policy names are matched against the "## no critic" arguments
491 as regular expressions, you can abbreviate the Policy names or disable
492 an entire family of Policies in one shot like this:
b9e35135
JRT
493
494 ## no critic (NamingConventions)
495
b4c7e33c
JRT
496 # Now exempt from NamingConventions::ProhibitMixedCaseVars
497 my $camelHumpVar = 'foo';
498
499 # Now exempt from NamingConventions::ProhibitMixedCaseSubs
500 sub camelHumpSub {}
b9e35135
JRT
501
502 The argument list must be enclosed in parens and must contain one or
7b2c2404
JRT
503 more comma-separated barewords (e.g. don't use quotes). The "## no
504 critic" pragmas can be nested, and Policies named by an inner pragma
b9e35135
JRT
505 will be disabled along with those already disabled an outer pragma.
506
7b2c2404
JRT
507 Some Policies like "Subroutines::ProhibitExcessComplexity" apply to an
508 entire block of code. In those cases, "## no critic" must appear on the
509 line where the violation is reported. For example:
510
511 sub complicated_function { ## no critic (ProhibitExcessComplexity)
512 # Your code here...
513 }
514
515 Policies such as "Documentation::RequirePodSections" apply to the entire
516 document, in which case violations are reported at line 1. But if the
517 file requires a shebang line, it is impossible to put "## no critic" on
518 the first line of the file. This is a known limitation and it will be
519 addressed in a future release. As a workaround, you can disable the
520 affected policies at the command-line or in your .perlcriticrc file. But
521 beware that this will affect the analysis of all files.
522
b9e35135
JRT
523 Use this feature wisely. "## no critic" should be used in the smallest
524 possible scope, or only on individual lines of code. And you should
525 always be as specific as possible about which policies you want to
526 disable (i.e. never use a bare "## no critic"). If Perl::Critic
527 complains about your code, try and find a compliant solution before
528 resorting to this feature.
529
530IMPORTANT CHANGES
531 Perl-Critic is evolving rapidly, so some of the interfaces have changed
532 in ways that are not backward-compatible. If you have been using an
533 older version of Perl-Critic and/or you have been developing custom
534 Policy modules, please read this section carefully.
535
7b2c2404
JRT
536 VERSION 0.23
537 In version 0.23, the syntax for theme rules changed. The mathematical
538 operators ( "*", "+", "-" ) are no longer supported. You must use
539 logical operators instead ( "&&", "!", "||" ). However the meanings of
540 these operators is effectively the same. See "POLICY THEMES" for more
541 details.
542
a3f5707d
JRT
543 VERSION 0.21
544 In version 0.21, we introduced the concept of policy "themes". All you
545 existing custom Policies should still be compatible. But to take
546 advantage of the theme feature, you should add a "default_themes" method
547 to your custom Policy modules. See Perl::Critic::DEVELOPER for an
548 up-to-date guide on creating Policy modules.
549
550 The internals of Perl::Critic were also refactored significantly. The
551 public API is largely unchanged, but if you've been accessing bits
552 inside Perl::Critic, then you may be in for a surprise.
553
b9e35135
JRT
554 VERSION 0.16
555 Starting in version 0.16, you can add a list Policy names as arguments
556 to the "## no critic" pseudo-pragma. This feature allows you to disable
557 specific policies. So if you have been in the habit of adding additional
558 words after "no critic", then those words might cause unexpected
7b2c2404 559 results. If you want to append other stuff to the "## no critic"
b9e35135
JRT
560 comment, then terminate the pseudo-pragma with a semi-colon, and then
561 start another comment. For example:
562
a3f5707d
JRT
563 #This may not work as expected.
564 $email = 'foo@bar.com'; ## no critic for literal '@'
b9e35135 565
a3f5707d
JRT
566 #This will work.
567 $email = 'foo@bar.com'; ## no critic; #for literal '@'
b9e35135 568
a3f5707d
JRT
569 #This is even better.
570 $email = 'foo@bar.com'; ## no critic (RequireInterpolation);
b9e35135
JRT
571
572 VERSION 0.14
573 Starting in version 0.14, the interface to Perl::Critic::Violation
574 changed. This will also break any custom Policy modules that you might
575 have written for earlier modules. See Perl::Critic::DEVELOPER for an
576 up-to-date guide on creating Policy modules.
577
578 The notion of "priority" was also replaced with "severity" in version
579 0.14. Consequently, the default behavior of Perl::Critic is to only load
580 the most "severe" Policy modules, rather than loading all of them. This
581 decision was based on user-feedback suggesting that Perl-Critic should
582 be less critical for new users, and should steer them toward gradually
583 increasing the strictness as they progressively adopt better coding
584 practices.
585
586 VERSION 0.11
587 Starting in version 0.11, the internal mechanics of Perl-Critic were
588 rewritten so that only one traversal of the PPI document tree is
589 required. Unfortunately, this will break any custom Policy modules that
590 you might have written for earlier versions. Converting your policies to
591 work with the new version is pretty easy and actually results in cleaner
592 code. See Perl::Critic::DEVELOPER for an up-to-date guide on creating
593 Policy modules.
594
595THE Perl::Critic PHILOSOPHY
596 Coding standards are deeply personal and highly subjective. The
597 goal of Perl::Critic is to help you write code that conforms with a
598 set of best practices. Our primary goal is not to dictate what
599 those practices are, but rather, to implement the practices
600 discovered by others. Ultimately, you make the rules --
601 Perl::Critic is merely a tool for encouraging consistency. If there
602 is a policy that you think is important or that we have overlooked,
603 we would be very grateful for contributions, or you can simply load
604 your own private set of policies into Perl::Critic.
605
606EXTENDING THE CRITIC
607 The modular design of Perl::Critic is intended to facilitate the
608 addition of new Policies. You'll need to have some understanding of PPI,
609 but most Policy modules are pretty straightforward and only require
610 about 20 lines of code. Please see the Perl::Critic::DEVELOPER file
611 included in this distribution for a step-by-step demonstration of how to
612 create new Policy modules.
613
614 If you develop any new Policy modules, feel free to send them to
759f1e90
JRT
615 "<thaljef@cpan.org>" and I'll be happy to put them into the Perl::Critic
616 distribution. Or if you would like to work on the Perl::Critic project
b9e35135
JRT
617 directly, check out our repository at <http://perlcritic.tigris.org>. To
618 subscribe to our mailing list, send a message to
759f1e90
JRT
619 "<dev-subscribe@perlcritic.tigris.org>".
620
621 The Perl::Critic team is also available for hire. If your organization
622 has its own coding standards, we can create custom Policies to enforce
623 your local guidelines. Or if your code base is prone to a particular
624 defect pattern, we can design Policies that will help you catch those
625 costly defects before they go into production. To discuss your needs
626 with the Perl::Critic team, just contact "<thaljef@cpan.org>".
b9e35135
JRT
627
628PREREQUISITES
629 Perl::Critic requires the following modules:
630
7b2c2404
JRT
631 B::Keywords
632
b9e35135
JRT
633 Config::Tiny
634
635 File::Spec
636
637 IO::String
638
639 List::Util
640
641 List::MoreUtils
642
643 Module::Pluggable
644
645 PPI
646
a60e94d6
ES
647 Pod::PlainText
648
b9e35135
JRT
649 Pod::Usage
650
a60e94d6 651 Readonly
b9e35135 652
b9e35135
JRT
653 String::Format
654
a60e94d6
ES
655 String::Util
656
b9e35135
JRT
657 The following modules are optional, but recommended for complete
658 testing:
659
a60e94d6
ES
660 File::HomeDir
661
662 File::Which
663
664 IO::String
665
666 IPC::Open2
667
668 Perl::Tidy
669
670 Pod::Spell
671
b9e35135
JRT
672 Test::Pod
673
674 Test::Pod::Coverage
675
a60e94d6
ES
676 Text::ParseWords
677
678CONTACTING THE DEVELOPMENT TEAM
679 You are encouraged to subscribe to the mailing list; send a message to
680 "<users-subscribe@perlcritic.tigris.org>". See also the archives. You
681 can also contact the author at "<thaljef@cpan.org>".
682
683 At least one member of the development team has started hanging around
684 in <irc://irc.perl.org/#perlcritic>.
685
686SEE ALSO
687 There are a number of distributions of additional Policies available. A
688 few are listed here:
689
690 Perl::Critic::More
691
692 Perl::Critic::Bangs
693
694 Perl::Critic::Lax
695
696 Perl::Critic::StricterSubs
697
698 Perl::Critic::Swift
699
700 Perl::Critic::Tics
701
702 These distributions enable you to use Perl::Critic in your unit tests:
703
704 Test::Perl::Critic
705
706 Test::Perl::Critic::Progressive
707
708 There are also a couple of distributions that will install all the
709 Perl::Critic related modules known to the development team:
710
711 Bundle::Perl::Critic
712
713 Task::Perl::Critic
714
715 If you want to make sure you have absolutely everything, you can use
716 these:
717
718 Bundle::Perl::Critic::IncludingOptionalDependencies
719
720 Task::Perl::Critic::IncludingOptionalDependencies
721
b9e35135
JRT
722BUGS
723 Scrutinizing Perl code is hard for humans, let alone machines. If you
724 find any bugs, particularly false-positives or false-negatives from a
725 Perl::Critic::Policy, please submit them to
726 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Perl-Critic>. Thanks.
727
a60e94d6
ES
728 Most policies will produce false-negatives if they cannot understand a
729 particular block of code.
730
b9e35135
JRT
731CREDITS
732 Adam Kennedy - For creating PPI, the heart and soul of Perl::Critic.
733
734 Damian Conway - For writing Perl Best Practices, finally :)
735
736 Chris Dolan - For contributing the best features and Policy modules.
737
b4c7e33c 738 Andy Lester - Wise sage and master of all-things-testing.
b9e35135 739
b4c7e33c 740 Elliot Shank - The self-proclaimed quality freak.
ffe5f1a7 741
b4c7e33c 742 Giuseppe Maxia - For all the great ideas and positive encouragement.
ffe5f1a7 743
b9e35135
JRT
744 and Sharon, my wife - For putting up with my all-night code sessions.
745
a60e94d6
ES
746 Thanks also to the Perl Foundation for providing a grant to support
747 Chris Dolan's project to implement twenty PBP policies.
748 <http://www.perlfoundation.org/april_1_2007_new_grant_awards>
749
b9e35135
JRT
750AUTHOR
751 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
752
753COPYRIGHT
7b2c2404 754 Copyright (c) 2005-2007 Jeffrey Ryan Thalhammer. All rights reserved.
b9e35135
JRT
755
756 This program is free software; you can redistribute it and/or modify it
757 under the same terms as Perl itself. The full text of this license can
758 be found in the LICENSE file included with this module.
759