Login
Created a new Policy to prohibit an unrestricted ## no critic.
[gknop/Perl-Critic.git] / lib / Perl / Critic.pm
CommitLineData
6036a254 1##############################################################################
aaa8512c
JRT
2# $URL$
3# $Date$
4# $Author$
5# $Revision$
6036a254 6##############################################################################
aaa8512c 7
59b05e08
JRT
8package Perl::Critic;
9
df6dee2b 10use 5.006001;
59b05e08
JRT
11use strict;
12use warnings;
712f83ea 13
c680a9c9 14use English qw(-no_match_vars);
c680a9c9
ES
15use Readonly;
16
f7f62580
JRT
17use base qw(Exporter);
18
59b05e08 19use File::Spec;
389109ec 20use Scalar::Util qw(blessed);
c680a9c9
ES
21
22use PPI::Document;
23use PPI::Document::File;
24
558488f7 25use Perl::Critic::Exception::Configuration::Generic;
94472d4a 26use Perl::Critic::Exception::Parse qw{ throw_parse };
59b05e08 27use Perl::Critic::Config;
dc93df4f 28use Perl::Critic::Violation;
5bf96118 29use Perl::Critic::Document;
2ce0b9ee 30use Perl::Critic::Statistics;
bbf4108c 31use Perl::Critic::Utils qw{ :characters };
59b05e08 32
6036a254 33#-----------------------------------------------------------------------------
f7f62580 34
173667ce 35our $VERSION = '1.093_01';
c680a9c9 36
70f3f307 37Readonly::Array our @EXPORT_OK => qw(critique);
f7f62580 38
6036a254 39#-----------------------------------------------------------------------------
dff08b70 40
59b05e08 41sub new {
59b05e08 42 my ( $class, %args ) = @_;
e01de056 43 my $self = bless {}, $class;
1e7b8681 44 $self->{_config} = $args{-config} || Perl::Critic::Config->new( %args );
2ce0b9ee 45 $self->{_stats} = Perl::Critic::Statistics->new();
59b05e08
JRT
46 return $self;
47}
48
6036a254 49#-----------------------------------------------------------------------------
59b05e08 50
dff08b70
JRT
51sub config {
52 my $self = shift;
53 return $self->{_config};
54}
59b05e08 55
6036a254 56#-----------------------------------------------------------------------------
59b05e08 57
dff08b70
JRT
58sub add_policy {
59 my ( $self, @args ) = @_;
60 #Delegate to Perl::Critic::Config
61 return $self->config()->add_policy( @args );
62}
59b05e08 63
6036a254 64#-----------------------------------------------------------------------------
dff08b70
JRT
65
66sub policies {
67 my $self = shift;
46a3f49d 68
dff08b70
JRT
69 #Delegate to Perl::Critic::Config
70 return $self->config()->policies();
59b05e08
JRT
71}
72
6036a254 73#-----------------------------------------------------------------------------
dff08b70 74
2ce0b9ee
JRT
75sub statistics {
76 my $self = shift;
77 return $self->{_stats};
78}
79
80#-----------------------------------------------------------------------------
81
6e7d6c9f 82sub critique { ##no critic (ArgUnpacking)
7ed796a7 83
f7f62580
JRT
84 #-------------------------------------------------------------------
85 # This subroutine can be called as an object method or as a static
86 # function. In the latter case, the first argument can be a
87 # hashref of configuration parameters that shall be used to create
88 # an object behind the scenes. Note that this object does not
89 # persist. In other words, it is not a singleton. Here are some
90 # of the ways this subroutine might get called:
91 #
92 # #Object style...
93 # $critic->critique( $code );
94 #
95 # #Functional style...
96 # critique( $code );
97 # critique( {}, $code );
98 # critique( {-foo => bar}, $code );
99 #------------------------------------------------------------------
100
101 my ( $self, $source_code ) = @_ >= 2 ? @_ : ( {}, $_[0] );
102 $self = ref $self eq 'HASH' ? __PACKAGE__->new(%{ $self }) : $self;
de2dc641 103 return if not defined $source_code; # If no code, then nothing to do.
59b05e08 104
fb1d7f95 105 my $doc = $self->_create_perl_critic_document($source_code);
576f6411 106
558488f7
ES
107 if ( 0 == $self->policies() ) {
108 Perl::Critic::Exception::Configuration::Generic->throw(
109 message => 'There are no enabled policies.',
110 )
111 }
112
576f6411
ES
113 return $self->_gather_violations($doc);
114}
115
576f6411
ES
116#=============================================================================
117# PRIVATE functions
118
119sub _create_perl_critic_document {
fb1d7f95 120 my ($self, $source_code) = @_;
576f6411 121
4e771b0b
JRT
122 # $source_code can be a file name, or a reference to a
123 # PPI::Document, or a reference to a scalar containing source
124 # code. In the last case, PPI handles the translation for us.
f7f62580 125
e58ec45b
JRT
126 my $doc = _is_ppi_doc( $source_code ) ? $source_code
127 : ref $source_code ? PPI::Document->new($source_code)
128 : PPI::Document::File->new($source_code);
59b05e08
JRT
129
130 # Bail on error
dc93df4f 131 if ( not defined $doc ) {
0e91e2bf
JRT
132 my $errstr = PPI::Document::errstr();
133 my $file = ref $source_code ? undef : $source_code;
94472d4a
ES
134 throw_parse
135 message => qq<Can't parse code: $errstr>,
136 file_name => $file;
59b05e08
JRT
137 }
138
139 # Pre-index location of each node (for speed)
140 $doc->index_locations();
141
5bf96118 142 # Wrap the doc in a caching layer
576f6411
ES
143 return Perl::Critic::Document->new($doc);
144}
145
146#-----------------------------------------------------------------------------
147
148sub _gather_violations {
149 my ($self, $doc) = @_;
5bf96118 150
1bef6e21
JRT
151 # Disable the magic shebang fix
152 my %is_line_disabled = _unfix_shebang($doc);
59b05e08 153
7ed796a7 154 # Filter exempt code, if desired
dc93df4f 155 if ( not $self->config->force() ) {
410cf90b 156 my @site_policies = $self->config->site_policy_names();
1bef6e21
JRT
157 %is_line_disabled = ( %is_line_disabled,
158 _filter_code($doc, @site_policies) );
7ed796a7 159 }
1e7b8681 160
e58ec45b 161 # Evaluate each policy
46a3f49d
ES
162 my @policies = $self->config->policies();
163 my @violations =
164 map { _critique( $_, $doc, \%is_line_disabled) } @policies;
dc93df4f 165
2ce0b9ee
JRT
166 # Accumulate statistics
167 $self->statistics->accumulate( $doc, \@violations );
168
e58ec45b
JRT
169 # If requested, rank violations by their severity and return the top N.
170 if ( @violations && (my $top = $self->config->top()) ) {
171 my $limit = @violations < $top ? $#violations : $top-1;
172 @violations = Perl::Critic::Violation::sort_by_severity(@violations);
173 @violations = ( reverse @violations )[ 0 .. $limit ]; #Slicing...
174 }
dc93df4f 175
e58ec45b
JRT
176 # Always return violations sorted by location
177 return Perl::Critic::Violation->sort_by_location(@violations);
178}
1bef6e21 179
576f6411 180#-----------------------------------------------------------------------------
1bef6e21 181
e58ec45b
JRT
182sub _is_ppi_doc {
183 my ($ref) = @_;
184 return blessed($ref) && $ref->isa('PPI::Document');
185}
dc93df4f 186
e58ec45b 187#-----------------------------------------------------------------------------
c70a9ff6 188
e58ec45b 189sub _critique {
e58ec45b 190 my ($policy, $doc, $is_line_disabled) = @_;
bb5a5c57 191
78afb6d4 192 return if not $policy->prepare_to_scan_document($doc);
bb5a5c57 193
6b79d701
ES
194 my $maximum_violations = $policy->get_maximum_violations_per_document();
195
196 if (defined $maximum_violations && $maximum_violations == 0) {
197 return;
198 }
c70a9ff6 199
bb5a5c57 200 my @violations = ();
f409e8e7
ES
201 my $policy_name = $policy->get_long_name();
202
e58ec45b
JRT
203 TYPE:
204 for my $type ( $policy->applies_to() ) {
e01de056 205
e58ec45b
JRT
206 ELEMENT:
207 for my $element ( @{ $doc->find($type) || [] } ) {
208
209 # Evaluate the policy on this $element. A policy may
210 # return zero or more violations. We only want the
211 # violations that occur on lines that have not been
212 # disabled.
213
214 VIOLATION:
215 for my $violation ( $policy->violates( $element, $doc ) ) {
e58ec45b 216 my $line = $violation->location()->[0];
1c6e69da 217 if (exists $is_line_disabled->{$line}) {
05e2d404
JRT
218 next VIOLATION if $is_line_disabled->{$line}->{$policy_name}
219 && $policy->can_be_disabled();
220 next VIOLATION if $is_line_disabled->{$line}->{ALL}
221 && $policy->can_be_disabled();
1c6e69da 222 }
6b79d701 223
e58ec45b 224 push @violations, $violation;
6b79d701
ES
225 if (
226 defined $maximum_violations
227 and @violations >= $maximum_violations
228 ) {
229 last TYPE;
230 }
e58ec45b
JRT
231 }
232 }
e01de056
JRT
233 }
234
e58ec45b 235 return @violations;
59b05e08
JRT
236}
237
e58ec45b 238#-----------------------------------------------------------------------------
59b05e08
JRT
239
240sub _filter_code {
241
f4938b54 242 my ($doc, @site_policies)= @_;
682ce894 243
59b05e08 244 my $nodes_ref = $doc->find('PPI::Token::Comment') || return;
7ed796a7
JRT
245 my %disabled_lines;
246
682ce894
CD
247 _filter_shebang_line($nodes_ref, \%disabled_lines, \@site_policies);
248 _filter_other_lines($nodes_ref, \%disabled_lines, \@site_policies);
249 return %disabled_lines;
250}
251
252sub _filter_shebang_line {
253 my ($nodes_ref, $disabled_lines, $site_policies) = @_;
254
f135623f 255 my $shebang_no_critic = qr{\A [#]! .*? [#][#] \s* no \s+ critic}xms;
682ce894 256
1c6e69da
CD
257 # Special case for the very beginning of the file: allow "##no critic" after the shebang
258 if (0 < @{$nodes_ref}) {
259 my $loc = $nodes_ref->[0]->location;
260 if (1 == $loc->[0] && 1 == $loc->[1] && $nodes_ref->[0] =~ $shebang_no_critic) {
261 my $pragma = shift @{$nodes_ref};
682ce894
CD
262 for my $policy (_parse_nocritic_import($pragma, $site_policies)) {
263 $disabled_lines->{ 1 }->{$policy} = 1;
1c6e69da
CD
264 }
265 }
266 }
682ce894
CD
267 return;
268}
269
270sub _filter_other_lines {
271 my ($nodes_ref, $disabled_lines, $site_policies) = @_;
272
f135623f
ES
273 my $no_critic = qr{\A \s* [#][#] \s* no \s+ critic}xms;
274 my $use_critic = qr{\A \s* [#][#] \s* use \s+ critic}xms;
1c6e69da 275
59b05e08
JRT
276 PRAGMA:
277 for my $pragma ( grep { $_ =~ $no_critic } @{$nodes_ref} ) {
278
c70a9ff6
JRT
279 # Parse out the list of Policy names after the
280 # 'no critic' pragma. I'm thinking of this just
281 # like a an C<import> argument for real pragmas.
682ce894 282 my @no_policies = _parse_nocritic_import($pragma, $site_policies);
c70a9ff6
JRT
283
284 # Grab surrounding nodes to determine the context.
285 # This determines whether the pragma applies to
286 # the current line or the block that follows.
209eb6db
JRT
287 my $parent = $pragma->parent();
288 my $grandparent = $parent ? $parent->parent() : undef;
289 my $sib = $pragma->sprevious_sibling();
290
c70a9ff6 291
209eb6db
JRT
292 # Handle single-line usage on simple statements
293 if ( $sib && $sib->location->[0] == $pragma->location->[0] ) {
c70a9ff6
JRT
294 my $line = $pragma->location->[0];
295 for my $policy ( @no_policies ) {
682ce894 296 $disabled_lines->{ $line }->{$policy} = 1;
c70a9ff6 297 }
209eb6db
JRT
298 next PRAGMA;
299 }
300
301
302 # Handle single-line usage on compound statements
303 if ( ref $parent eq 'PPI::Structure::Block' ) {
5c1bf20d
JRT
304 if ( ref $grandparent eq 'PPI::Statement::Compound'
305 || ref $grandparent eq 'PPI::Statement::Sub' ) {
209eb6db 306 if ( $parent->location->[0] == $pragma->location->[0] ) {
c70a9ff6
JRT
307 my $line = $grandparent->location->[0];
308 for my $policy ( @no_policies ) {
682ce894 309 $disabled_lines->{ $line }->{$policy} = 1;
c70a9ff6 310 }
209eb6db
JRT
311 next PRAGMA;
312 }
59b05e08
JRT
313 }
314 }
315
209eb6db
JRT
316
317 # Handle multi-line usage. This is either a "no critic" ..
318 # "use critic" region or a block where "no critic" persists
319 # until the end of the scope. The start is the always the "no
320 # critic" which we already found. So now we have to search
321 # for the end.
7ed796a7
JRT
322
323 my $start = $pragma;
324 my $end = $pragma;
325
59b05e08 326 SIB:
7ed796a7
JRT
327 while ( my $sib = $end->next_sibling() ) {
328 $end = $sib; # keep track of last sibling encountered in this scope
329 last SIB
c70a9ff6 330 if $sib->isa('PPI::Token::Comment') && $sib =~ $use_critic;
7ed796a7
JRT
331 }
332
333 # We either found an end or hit the end of the scope.
334 # Flag all intervening lines
335 for my $line ( $start->location->[0] .. $end->location->[0] ) {
c70a9ff6 336 for my $policy ( @no_policies ) {
682ce894 337 $disabled_lines->{ $line }->{$policy} = 1;
c70a9ff6 338 }
59b05e08 339 }
59b05e08 340 }
dff08b70 341
682ce894 342 return;
59b05e08 343}
dff08b70 344
6036a254 345#-----------------------------------------------------------------------------
7ed796a7 346
c70a9ff6
JRT
347sub _parse_nocritic_import {
348
1c6e69da 349 my ($pragma, $site_policies) = @_;
c70a9ff6 350
f135623f
ES
351 my $module = qr{ [\w:]+ }xms;
352 my $delim = qr{ \s* [,\s] \s* }xms;
353 my $qw = qr{ (?: qw )? }xms;
354 my $qualifier = qr{ $qw [(]? \s* ( $module (?: $delim $module)* ) \s* [)]? }xms;
355 my $no_critic = qr{ \#\# \s* no \s+ critic \s* $qualifier }xms; ##no critic(EscapedMetacharacters)
1bef6e21 356
c48094aa 357 if ( my ($module_list) = $pragma =~ $no_critic ) {
c0137eab 358 my @modules = split $delim, $module_list;
369abea9
CD
359
360 # Compose the specified modules into a regex alternation. Wrap each
361 # in a no-capturing group to permit "|" in the modules specification
362 # (backward compatibility)
363 my $re = join q{|}, map {"(?:$_)"} @modules;
f135623f 364 return grep {m/$re/ixms} @{$site_policies};
c70a9ff6
JRT
365 }
366
a9c73f99 367 # Default to disabling ALL policies.
c70a9ff6
JRT
368 return qw(ALL);
369}
370
6036a254 371#-----------------------------------------------------------------------------
59b05e08
JRT
372sub _unfix_shebang {
373
0e91e2bf
JRT
374 # When you install a script using ExtUtils::MakeMaker or Module::Build, it
375 # inserts some magical code into the top of the file (just after the
376 # shebang). This code allows people to call your script using a shell,
377 # like `sh my_script`. Unfortunately, this code causes several Policy
378 # violations, so we just disable it as if a "## no critic" comment had
379 # been attached.
59b05e08 380
7ed796a7 381 my $doc = shift;
59b05e08
JRT
382 my $first_stmnt = $doc->schild(0) || return;
383
f135623f 384 # Different versions of MakeMaker and Build use slightly different shebang
0e91e2bf
JRT
385 # fixing strings. This matches most of the ones I've found in my own Perl
386 # distribution, but it may not be bullet-proof.
59b05e08 387
f135623f 388 my $fixin_rx = qr{^eval 'exec .* \$0 \${1\+"\$@"}'\s*[\r\n]\s*if.+;}ms; ## no critic (RequireExtendedFormatting)
7ed796a7 389 if ( $first_stmnt =~ $fixin_rx ) {
1bef6e21 390 my $line = $first_stmnt->location()->[0];
c70a9ff6 391 return ( $line => {ALL => 1}, $line + 1 => {ALL => 1} );
7ed796a7 392 }
dff08b70 393
1bef6e21 394 #No magic shebang was found!
7ed796a7 395 return;
59b05e08
JRT
396}
397
0e91e2bf 398#-----------------------------------------------------------------------------
0e91e2bf 399
59b05e08
JRT
4001;
401
6036a254 402#-----------------------------------------------------------------------------
59b05e08
JRT
403
404__END__
405
406=pod
407
c296c678 408=for stopwords DGR INI-style API -params pbp refactored ActivePerl
369abea9 409ben Jore Dolan's
821d0eb5 410
59b05e08
JRT
411=head1 NAME
412
c728943a 413Perl::Critic - Critique Perl source code for best-practices.
59b05e08 414
df89052a 415
59b05e08
JRT
416=head1 SYNOPSIS
417
418 use Perl::Critic;
6bf9b465
JRT
419 my $file = shift;
420 my $critic = Perl::Critic->new();
421 my @violations = $critic->critique($file);
422 print @violations;
59b05e08 423
df89052a 424
59b05e08
JRT
425=head1 DESCRIPTION
426
11f53956
ES
427Perl::Critic is an extensible framework for creating and applying
428coding standards to Perl source code. Essentially, it is a static
429source code analysis engine. Perl::Critic is distributed with a
430number of L<Perl::Critic::Policy|Perl::Critic::Policy> modules that
431attempt to enforce various coding guidelines. Most Policy modules are
432based on Damian Conway's book B<Perl Best Practices>. However,
433Perl::Critic is B<not> limited to PBP and will even support Policies
434that contradict Conway. You can enable, disable, and customize those
435Polices through the Perl::Critic interface. You can also create new
436Policy modules that suit your own tastes.
437
438For a command-line interface to Perl::Critic, see the documentation
439for L<perlcritic|perlcritic>. If you want to integrate Perl::Critic
440with your build process, L<Test::Perl::Critic|Test::Perl::Critic>
441provides an interface that is suitable for test scripts. Also,
442L<Test::Perl::Critic::Progressive|Test::Perl::Critic::Progressive> is
443useful for gradually applying coding standards to legacy code. For
444the ultimate convenience (at the expense of some flexibility) see the
445L<criticism|criticism> pragma.
446
447Win32 and ActivePerl users can find PPM distributions of Perl::Critic
448at L<http://theoryx5.uwinnipeg.ca/ppms/>.
449
450If you'd like to try L<Perl::Critic|Perl::Critic> without installing
451anything, there is a web-service available at
452L<http://perlcritic.com>. The web-service does not yet support all
453the configuration features that are available in the native
454Perl::Critic API, but it should give you a good idea of what it does.
455You can also invoke the perlcritic web-service from the command-line
456by doing an HTTP-post, such as one of these:
e518ead4 457
7711a331
JRT
458 $> POST http://perlcritic.com/perl/critic.pl < MyModule.pm
459 $> lwp-request -m POST http://perlcritic.com/perl/critic.pl < MyModule.pm
460 $> wget -q -O - --post-file=MyModule.pm http://perlcritic.com/perl/critic.pl
e518ead4 461
11f53956
ES
462Please note that the perlcritic web-service is still alpha code. The
463URL and interface to the service are subject to change.
8d36cd6f 464
df89052a 465
59b05e08
JRT
466=head1 CONSTRUCTOR
467
df89052a 468=over
59b05e08 469
89b50090 470=item C<< new( [ -profile => $FILE, -severity => $N, -theme => $string, -include => \@PATTERNS, -exclude => \@PATTERNS, -top => $N, -only => $B, -profile-strictness => $PROFILE_STRICTNESS_{WARN|FATAL|QUIET}, -force => $B, -verbose => $N ], -color => $B, -pager => $string, -criticism-fatal => $B) >>
7b84ff16 471
7b84ff16 472=item C<< new() >>
59b05e08 473
11f53956
ES
474Returns a reference to a new Perl::Critic object. Most arguments are
475just passed directly into
476L<Perl::Critic::Config|Perl::Critic::Config>, but I have described
477them here as well. The default value for all arguments can be defined
478in your F<.perlcriticrc> file. See the L<"CONFIGURATION"> section for
479more information about that. All arguments are optional key-value
480pairs as follows:
481
482B<-profile> is a path to a configuration file. If C<$FILE> is not
483defined, Perl::Critic::Config attempts to find a F<.perlcriticrc>
484configuration file in the current directory, and then in your home
485directory. Alternatively, you can set the C<PERLCRITIC> environment
486variable to point to a file in another location. If a configuration
487file can't be found, or if C<$FILE> is an empty string, then all
488Policies will be loaded with their default configuration. See
489L<"CONFIGURATION"> for more information.
490
491B<-severity> is the minimum severity level. Only Policy modules that
492have a severity greater than C<$N> will be applied. Severity values
493are integers ranging from 1 (least severe) to 5 (most severe). The
494default is 5. For a given C<-profile>, decreasing the C<-severity>
495will usually reveal more Policy violations. You can set the default
496value for this option in your F<.perlcriticrc> file. Users can
497redefine the severity level for any Policy in their F<.perlcriticrc>
498file. See L<"CONFIGURATION"> for more information.
499
500If it is difficult for you to remember whether severity "5" is the
501most or least restrictive level, then you can use one of these named
502values:
097f3455 503
7711a331 504 SEVERITY NAME ...is equivalent to... SEVERITY NUMBER
097f3455
JRT
505 --------------------------------------------------------
506 -severity => 'gentle' -severity => 5
507 -severity => 'stern' -severity => 4
508 -severity => 'harsh' -severity => 3
509 -severity => 'cruel' -severity => 2
510 -severity => 'brutal' -severity => 1
511
11f53956
ES
512B<-theme> is special expression that determines which Policies to
513apply based on their respective themes. For example, the following
514would load only Policies that have a 'bugs' AND 'pbp' theme:
7b84ff16 515
1c5955e4
JRT
516 my $critic = Perl::Critic->new( -theme => 'bugs && pbp' );
517
11f53956
ES
518Unless the C<-severity> option is explicitly given, setting C<-theme>
519silently causes the C<-severity> to be set to 1. You can set the
520default value for this option in your F<.perlcriticrc> file. See the
521L<"POLICY THEMES"> section for more information about themes.
7b84ff16 522
7b84ff16 523
11f53956 524B<-include> is a reference to a list of string C<@PATTERNS>. Policy
f135623f 525modules that match at least one C<m/$PATTERN/ixms> will always be
11f53956 526loaded, irrespective of all other settings. For example:
6bf9b465
JRT
527
528 my $critic = Perl::Critic->new(-include => ['layout'] -severity => 4);
529
11f53956
ES
530This would cause Perl::Critic to apply all the C<CodeLayout::*> Policy
531modules even though they have a severity level that is less than 4.
532You can set the default value for this option in your F<.perlcriticrc>
533file. You can also use C<-include> in conjunction with the
534C<-exclude> option. Note that C<-exclude> takes precedence over
535C<-include> when a Policy matches both patterns.
6bf9b465 536
11f53956 537B<-exclude> is a reference to a list of string C<@PATTERNS>. Policy
f135623f 538modules that match at least one C<m/$PATTERN/ixms> will not be loaded,
11f53956 539irrespective of all other settings. For example:
6bf9b465
JRT
540
541 my $critic = Perl::Critic->new(-exclude => ['strict'] -severity => 1);
542
1edbd692 543This would cause Perl::Critic to not apply the C<RequireUseStrict> and
11f53956
ES
544C<ProhibitNoStrict> Policy modules even though they have a severity
545level that is greater than 1. You can set the default value for this
546option in your F<.perlcriticrc> file. You can also use C<-exclude> in
547conjunction with the C<-include> option. Note that C<-exclude> takes
548precedence over C<-include> when a Policy matches both patterns.
549
550B<-single-policy> is a string C<PATTERN>. Only one policy that
f135623f 551matches C<m/$PATTERN/ixms> will be used. Policies that do not match
11f53956
ES
552will be excluded. This option has precedence over the C<-severity>,
553C<-theme>, C<-include>, C<-exclude>, and C<-only> options. You can
554set the default value for this option in your F<.perlcriticrc> file.
555
556B<-top> is the maximum number of Violations to return when ranked by
557their severity levels. This must be a positive integer. Violations
558are still returned in the order that they occur within the file.
559Unless the C<-severity> option is explicitly given, setting C<-top>
560silently causes the C<-severity> to be set to 1. You can set the
561default value for this option in your F<.perlcriticrc> file.
562
563B<-only> is a boolean value. If set to a true value, Perl::Critic
564will only choose from Policies that are mentioned in the user's
565profile. If set to a false value (which is the default), then
566Perl::Critic chooses from all the Policies that it finds at your site.
567You can set the default value for this option in your F<.perlcriticrc>
568file.
e01de056 569
9f12283e
ES
570B<-profile-strictness> is an enumerated value, one of
571L<Perl::Critic::Utils::Constants/"$PROFILE_STRICTNESS_WARN"> (the
572default),
573L<Perl::Critic::Utils::Constants/"$PROFILE_STRICTNESS_FATAL">, and
574L<Perl::Critic::Utils::Constants/"$PROFILE_STRICTNESS_QUIET">. If set
575to L<Perl::Critic::Utils::Constants/"$PROFILE_STRICTNESS_FATAL">,
576Perl::Critic will make certain warnings about problems found in a
577F<.perlcriticrc> or file specified via the B<-profile> option fatal.
578For example, Perl::Critic normally only C<warn>s about profiles
579referring to non-existent Policies, but this value makes this
580situation fatal. Correspondingly,
581L<Perl::Critic::Utils::Constants/"$PROFILE_STRICTNESS_QUIET"> makes
582Perl::Critic shut up about these things.
66186ba3 583
11f53956
ES
584B<-force> is a boolean value that controls whether Perl::Critic
585observes the magical C<"## no critic"> pseudo-pragmas in your code.
586If set to a true value, Perl::Critic will analyze all code. If set to
587a false value (which is the default) Perl::Critic will ignore code
588that is tagged with these comments. See L<"BENDING THE RULES"> for
589more information. You can set the default value for this option in
590your F<.perlcriticrc> file.
59b05e08 591
11f53956
ES
592B<-verbose> can be a positive integer (from 1 to 11), or a literal
593format specification. See
594L<Perl::Critic::Violation|Perl::Critic::Violation> for an explanation
595of format specifications. You can set the default value for this
596option in your F<.perlcriticrc> file.
7b84ff16 597
89b50090 598B<-color> and B<-pager> are not used by Perl::Critic but is provided for the benefit
11f53956 599of L<perlcritic|perlcritic>.
25792f52 600
11f53956
ES
601B<-criticism-fatal> is not used by Perl::Critic but is provided for
602the benefit of L<criticism|criticism>.
badbf753 603
59b05e08
JRT
604=back
605
df89052a 606
59b05e08
JRT
607=head1 METHODS
608
df89052a 609=over
59b05e08 610
6d9feae6 611=item C<critique( $source_code )>
1e7b8681
JRT
612
613Runs the C<$source_code> through the Perl::Critic engine using all the
11f53956
ES
614Policies that have been loaded into this engine. If C<$source_code>
615is a scalar reference, then it is treated as a string of actual Perl
616code. If C<$source_code> is a reference to an instance of
617L<PPI::Document|PPI::Document>, then that instance is used directly.
618Otherwise, it is treated as a path to a local file containing Perl
619code. This method returns a list of
620L<Perl::Critic::Violation|Perl::Critic::Violation> objects for each
621violation of the loaded Policies. The list is sorted in the order
622that the Violations appear in the code. If there are no violations,
623this method returns an empty list.
1e7b8681 624
520f00c6 625=item C<< add_policy( -policy => $policy_name, -params => \%param_hash ) >>
59b05e08 626
11f53956
ES
627Creates a Policy object and loads it into this Critic. If the object
628cannot be instantiated, it will throw a fatal exception. Otherwise,
629it returns a reference to this Critic.
59b05e08 630
11f53956
ES
631B<-policy> is the name of a
632L<Perl::Critic::Policy|Perl::Critic::Policy> subclass module. The
633C<'Perl::Critic::Policy'> portion of the name can be omitted for
634brevity. This argument is required.
59b05e08 635
11f53956
ES
636B<-params> is an optional reference to a hash of Policy parameters.
637The contents of this hash reference will be passed into to the
638constructor of the Policy module. See the documentation in the
639relevant Policy module for a description of the arguments it supports.
59b05e08 640
dc93df4f 641=item C< policies() >
59b05e08 642
11f53956
ES
643Returns a list containing references to all the Policy objects that
644have been loaded into this engine. Objects will be in the order that
645they were loaded.
59b05e08 646
dc93df4f 647=item C< config() >
dff08b70 648
11f53956
ES
649Returns the L<Perl::Critic::Config|Perl::Critic::Config> object that
650was created for or given to this Critic.
dff08b70 651
2ce0b9ee
JRT
652=item C< statistics() >
653
11f53956
ES
654Returns the L<Perl::Critic::Statistics|Perl::Critic::Statistics>
655object that was created for this Critic. The Statistics object
656accumulates data for all files that are analyzed by this Critic.
2ce0b9ee 657
59b05e08
JRT
658=back
659
df89052a 660
f7f62580
JRT
661=head1 FUNCTIONAL INTERFACE
662
11f53956
ES
663For those folks who prefer to have a functional interface, The
664C<critique> method can be exported on request and called as a static
665function. If the first argument is a hashref, its contents are used
666to construct a new Perl::Critic object internally. The keys of that
667hash should be the same as those supported by the C<Perl::Critic::new>
668method. Here are some examples:
f7f62580
JRT
669
670 use Perl::Critic qw(critique);
671
672 # Use default parameters...
673 @violations = critique( $some_file );
674
675 # Use custom parameters...
676 @violations = critique( {-severity => 2}, $some_file );
677
d47377d5
JRT
678 # As a one-liner
679 %> perl -MPerl::Critic=critique -e 'print critique(shift)' some_file.pm
680
f7f62580
JRT
681None of the other object-methods are currently supported as static
682functions. Sorry.
683
df89052a 684
59b05e08
JRT
685=head1 CONFIGURATION
686
11f53956
ES
687Most of the settings for Perl::Critic and each of the Policy modules
688can be controlled by a configuration file. The default configuration
689file is called F<.perlcriticrc>. Perl::Critic will look for this file
690in the current directory first, and then in your home directory.
691Alternatively, you can set the C<PERLCRITIC> environment variable to
692explicitly point to a different file in another location. If none of
693these files exist, and the C<-profile> option is not given to the
694constructor, then all the modules that are found in the
7b84ff16
JRT
695Perl::Critic::Policy namespace will be loaded with their default
696configuration.
697
11f53956
ES
698The format of the configuration file is a series of INI-style blocks
699that contain key-value pairs separated by '='. Comments should start
700with '#' and can be placed on a separate line or after the name-value
701pairs if you desire.
7b84ff16 702
11f53956
ES
703Default settings for Perl::Critic itself can be set B<before the first
704named block.> For example, putting any or all of these at the top of
705your configuration file will set the default value for the
706corresponding constructor argument.
7b84ff16 707
097f3455 708 severity = 3 #Integer or named level
c3b1b521
JRT
709 only = 1 #Zero or One
710 force = 0 #Zero or One
711 verbose = 4 #Integer or format spec
712 top = 50 #A positive integer
1edbd692 713 theme = (pbp || security) && bugs #A theme expression
c3b1b521
JRT
714 include = NamingConventions ClassHierarchies #Space-delimited list
715 exclude = Variables Modules::RequirePackage #Space-delimited list
badbf753 716 criticism-fatal = 1 #Zero or One
51ae9d9b 717 color = 1 #Zero or One
89b50090 718 pager = less #pager to pipe output to
7b84ff16 719
11f53956
ES
720The remainder of the configuration file is a series of blocks like
721this:
59b05e08 722
7b84ff16
JRT
723 [Perl::Critic::Policy::Category::PolicyName]
724 severity = 1
4cd0567c 725 set_themes = foo bar
c94fb804 726 add_themes = baz
35ab5036 727 maximum_violations_per_document = 57
7b84ff16
JRT
728 arg1 = value1
729 arg2 = value2
59b05e08 730
11f53956
ES
731C<Perl::Critic::Policy::Category::PolicyName> is the full name of a
732module that implements the policy. The Policy modules distributed
733with Perl::Critic have been grouped into categories according to the
734table of contents in Damian Conway's book B<Perl Best Practices>. For
735brevity, you can omit the C<'Perl::Critic::Policy'> part of the module
736name.
737
738C<severity> is the level of importance you wish to assign to the
739Policy. All Policy modules are defined with a default severity value
740ranging from 1 (least severe) to 5 (most severe). However, you may
741disagree with the default severity and choose to give it a higher or
742lower severity, based on your own coding philosophy. You can set the
743C<severity> to an integer from 1 to 5, or use one of the equivalent
744names:
097f3455 745
7711a331 746 SEVERITY NAME ...is equivalent to... SEVERITY NUMBER
097f3455
JRT
747 ----------------------------------------------------
748 gentle 5
749 stern 4
750 harsh 3
751 cruel 2
752 brutal 1
753
11f53956
ES
754C<set_themes> sets the theme for the Policy and overrides its default
755theme. The argument is a string of one or more whitespace-delimited
756alphanumeric words. Themes are case-insensitive. See L<"POLICY
757THEMES"> for more information.
097f3455 758
11f53956
ES
759C<add_themes> appends to the default themes for this Policy. The
760argument is a string of one or more whitespace-delimited words.
761Themes are case-insensitive. See L<"POLICY THEMES"> for more
762information.
59b05e08 763
11f53956
ES
764C<maximum_violations_per_document> limits the number of Violations the
765Policy will return for a given document. Some Policies have a default
766limit; see the documentation for the individual Policies to see
767whether there is one. To force a Policy to not have a limit, specify
768"no_limit" or the empty string for the value of this parameter.
35ab5036 769
11f53956
ES
770The remaining key-value pairs are configuration parameters that will
771be passed into the constructor for that Policy. The constructors for
772most Policy objects do not support arguments, and those that do should
773have reasonable defaults. See the documentation on the appropriate
774Policy module for more details.
59b05e08 775
11f53956
ES
776Instead of redefining the severity for a given Policy, you can
777completely disable a Policy by prepending a '-' to the name of the
778module in your configuration file. In this manner, the Policy will
779never be loaded, regardless of the C<-severity> given to the
780Perl::Critic constructor.
59b05e08
JRT
781
782A simple configuration might look like this:
783
7b84ff16
JRT
784 #--------------------------------------------------------------
785 # I think these are really important, so always load them
786
787 [TestingAndDebugging::RequireUseStrict]
788 severity = 5
59b05e08 789
7b84ff16
JRT
790 [TestingAndDebugging::RequireUseWarnings]
791 severity = 5
59b05e08 792
7b84ff16
JRT
793 #--------------------------------------------------------------
794 # I think these are less important, so only load when asked
59b05e08 795
7b84ff16
JRT
796 [Variables::ProhibitPackageVars]
797 severity = 2
59b05e08 798
7b84ff16 799 [ControlStructures::ProhibitPostfixControls]
097f3455
JRT
800 allow = if unless # My custom configuration
801 severity = cruel # Same as "severity = 2"
59b05e08 802
7b84ff16
JRT
803 #--------------------------------------------------------------
804 # Give these policies a custom theme. I can activate just
805 # these policies by saying `perlcritic -theme larry`
59b05e08 806
7b84ff16 807 [Modules::RequireFilenameMatchesPackage]
c94fb804 808 add_themes = larry
59b05e08 809
7b84ff16 810 [TestingAndDebugging::RequireTestLables]
c94fb804 811 add_themes = larry curly moe
59b05e08 812
7b84ff16
JRT
813 #--------------------------------------------------------------
814 # I do not agree with these at all, so never load them
1e7b8681 815
7b84ff16
JRT
816 [-NamingConventions::ProhibitMixedCaseVars]
817 [-NamingConventions::ProhibitMixedCaseSubs]
818
819 #--------------------------------------------------------------
820 # For all other Policies, I accept the default severity,
821 # so no additional configuration is required for them.
8bc162ba 822
b87fc7eb 823For additional configuration examples, see the F<perlcriticrc> file
16cfe89e 824that is included in this F<examples> directory of this distribution.
b87fc7eb 825
11f53956
ES
826Damian Conway's own Perl::Critic configuration is also included in
827this distribution as F<examples/perlcriticrc-conway>.
e87a2153 828
df89052a 829
59b05e08
JRT
830=head1 THE POLICIES
831
11f53956
ES
832A large number of Policy modules are distributed with Perl::Critic.
833They are described briefly in the companion document
834L<Perl::Critic::PolicySummary|Perl::Critic::PolicySummary> and in more
835detail in the individual modules themselves. Say C<"perlcritic -doc
836PATTERN"> to see the perldoc for all Policy modules that match the
f135623f 837regex C<m/PATTERN/ixms>
38ce10c1 838
11f53956
ES
839There are a number of distributions of additional policies on CPAN.
840If L<Perl::Critic|Perl::Critic> doesn't contain a policy that you
841want, some one may have already written it. See the L</"SEE ALSO">
842section below for a list of some of these distributions.
a41e8614 843
7b84ff16 844
7711a331 845=head1 POLICY THEMES
2c2751eb 846
11f53956
ES
847Each Policy is defined with one or more "themes". Themes can be used
848to create arbitrary groups of Policies. They are intended to provide
849an alternative mechanism for selecting your preferred set of Policies.
850For example, you may wish disable a certain subset of Policies when
851analyzing test scripts. Conversely, you may wish to enable only a
852specific subset of Policies when analyzing modules.
7b84ff16 853
c8dbb393 854The Policies that ship with Perl::Critic are have been broken into the
11f53956
ES
855following themes. This is just our attempt to provide some basic
856logical groupings. You are free to invent new themes that suit your
857needs.
c8dbb393
JRT
858
859 THEME DESCRIPTION
860 --------------------------------------------------------------------------
861 core All policies that ship with Perl::Critic
862 pbp Policies that come directly from "Perl Best Practices"
863 bugs Policies that that prevent or reveal bugs
864 maintenance Policies that affect the long-term health of the code
865 cosmetic Policies that only have a superficial effect
866 complexity Policies that specificaly relate to code complexity
7711a331 867 security Policies that relate to security issues
c8dbb393
JRT
868 tests Policies that are specific to test scripts
869
870
11f53956
ES
871Any Policy may fit into multiple themes. Say C<"perlcritic -list"> to
872get a listing of all available Policies and the themes that are
873associated with each one. You can also change the theme for any
874Policy in your F<.perlcriticrc> file. See the L<"CONFIGURATION">
875section for more information about that.
7b84ff16 876
11f53956
ES
877Using the C<-theme> option, you can create an arbitrarily complex rule
878that determines which Policies will be loaded. Precedence is the same
879as regular Perl code, and you can use parentheses to enforce
880precedence as well. Supported operators are:
7b84ff16 881
14d80662 882 Operator Altertative Example
c3b1b521 883 ----------------------------------------------------------------------------
14d80662
JRT
884 && and 'pbp && core'
885 || or 'pbp || (bugs && security)'
886 ! not 'pbp && ! (portability || complexity)'
7b84ff16 887
11f53956
ES
888Theme names are case-insensitive. If the C<-theme> is set to an empty
889string, then it evaluates as true all Policies.
7b84ff16 890
df89052a 891
59b05e08
JRT
892=head1 BENDING THE RULES
893
11f53956
ES
894Perl::Critic takes a hard-line approach to your code: either you
895comply or you don't. In the real world, it is not always practical
896(nor even possible) to fully comply with coding standards. In such
897cases, it is wise to show that you are knowingly violating the
898standards and that you have a Damn Good Reason (DGR) for doing so.
59b05e08 899
11f53956
ES
900To help with those situations, you can direct Perl::Critic to ignore
901certain lines or blocks of code by using pseudo-pragmas:
59b05e08
JRT
902
903 require 'LegacyLibaray1.pl'; ## no critic
904 require 'LegacyLibrary2.pl'; ## no critic
905
906 for my $element (@list) {
907
908 ## no critic
909
910 $foo = ""; #Violates 'ProhibitEmptyQuotes'
911 $barf = bar() if $foo; #Violates 'ProhibitPostfixControls'
912 #Some more evil code...
913
914 ## use critic
915
916 #Some good code...
917 do_something($_);
918 }
919
11f53956
ES
920The C<"## no critic"> comments direct Perl::Critic to ignore the
921remaining lines of code until the end of the current block, or until a
922C<"## use critic"> comment is found (whichever comes first). If the
923C<"## no critic"> comment is on the same line as a code statement,
924then only that line of code is overlooked. To direct perlcritic to
925ignore the C<"## no critic"> comments, use the C<-force> option.
926
927A bare C<"## no critic"> comment disables all the active Policies. If
928you wish to disable only specific Policies, add a list of Policy names
929as arguments, just as you would for the C<"no strict"> or C<"no
930warnings"> pragmas. For example, this would disable the
931C<ProhibitEmptyQuotes> and C<ProhibitPostfixControls> policies until
932the end of the block or until the next C<"## use critic"> comment
933(whichever comes first):
c70a9ff6 934
c48094aa 935 ## no critic (EmptyQuotes, PostfixControls)
c70a9ff6 936
7711a331
JRT
937 # Now exempt from ValuesAndExpressions::ProhibitEmptyQuotes
938 $foo = "";
939
940 # Now exempt ControlStructures::ProhibitPostfixControls
941 $barf = bar() if $foo;
c70a9ff6 942
7711a331
JRT
943 # Still subjected to ValuesAndExpression::RequireNumberSeparators
944 $long_int = 10000000000;
945
11f53956
ES
946Since the Policy names are matched against the C<"## no critic">
947arguments as regular expressions, you can abbreviate the Policy names
948or disable an entire family of Policies in one shot like this:
c70a9ff6 949
c48094aa 950 ## no critic (NamingConventions)
c70a9ff6 951
7711a331
JRT
952 # Now exempt from NamingConventions::ProhibitMixedCaseVars
953 my $camelHumpVar = 'foo';
954
955 # Now exempt from NamingConventions::ProhibitMixedCaseSubs
956 sub camelHumpSub {}
c70a9ff6 957
11f53956
ES
958The argument list must be enclosed in parentheses and must contain one
959or more comma-separated barewords (e.g. don't use quotes). The
960C<"## no critic"> pragmas can be nested, and Policies named by an
961inner pragma will be disabled along with those already disabled an
962outer pragma.
c70a9ff6 963
11f53956
ES
964Some Policies like C<Subroutines::ProhibitExcessComplexity> apply to
965an entire block of code. In those cases, C<"## no critic"> must
966appear on the line where the violation is reported. For example:
35892a39
JRT
967
968 sub complicated_function { ## no critic (ProhibitExcessComplexity)
969 # Your code here...
970 }
971
11f53956
ES
972Policies such as C<Documentation::RequirePodSections> apply to the
973entire document, in which case violations are reported at line 1.
35892a39 974
11f53956
ES
975Use this feature wisely. C<"## no critic"> should be used in the
976smallest possible scope, or only on individual lines of code. And you
977should always be as specific as possible about which policies you want
978to disable (i.e. never use a bare C<"## no critic">). If Perl::Critic
979complains about your code, try and find a compliant solution before
980resorting to this feature.
1c5955e4 981
1bef6e21 982
11f53956 983=head1 THE L<Perl::Critic|Perl::Critic> PHILOSOPHY
b87b00dd 984
11f53956
ES
985Coding standards are deeply personal and highly subjective. The goal
986of Perl::Critic is to help you write code that conforms with a set of
987best practices. Our primary goal is not to dictate what those
988practices are, but rather, to implement the practices discovered by
989others. Ultimately, you make the rules -- Perl::Critic is merely a
990tool for encouraging consistency. If there is a policy that you think
991is important or that we have overlooked, we would be very grateful for
992contributions, or you can simply load your own private set of policies
993into Perl::Critic.
b87b00dd 994
df89052a 995
59b05e08
JRT
996=head1 EXTENDING THE CRITIC
997
11f53956
ES
998The modular design of Perl::Critic is intended to facilitate the
999addition of new Policies. You'll need to have some understanding of
1000L<PPI|PPI>, but most Policy modules are pretty straightforward and
1001only require about 20 lines of code. Please see the
1002L<Perl::Critic::DEVELOPER|Perl::Critic::DEVELOPER> file included in
1003this distribution for a step-by-step demonstration of how to create
1004new Policy modules.
59b05e08 1005
524bce7c 1006If you develop any new Policy modules, feel free to send them to C<<
11f53956
ES
1007<thaljef@cpan.org> >> and I'll be happy to put them into the
1008Perl::Critic distribution. Or if you would like to work on the
1009Perl::Critic project directly, check out our repository at
1010L<http://perlcritic.tigris.org>. To subscribe to our mailing list,
1011send a message to C<< <dev-subscribe@perlcritic.tigris.org> >>.
524bce7c 1012
11f53956
ES
1013The Perl::Critic team is also available for hire. If your
1014organization has its own coding standards, we can create custom
1015Policies to enforce your local guidelines. Or if your code base is
1016prone to a particular defect pattern, we can design Policies that will
1017help you catch those costly defects B<before> they go into production.
1018To discuss your needs with the Perl::Critic team, just contact C<<
1019<thaljef@cpan.org> >>.
59b05e08 1020
df89052a 1021
59b05e08
JRT
1022=head1 PREREQUISITES
1023
1024Perl::Critic requires the following modules:
1025
11f53956 1026L<B::Keywords|B::Keywords>
1edbd692 1027
11f53956 1028L<Config::Tiny|Config::Tiny>
59b05e08 1029
11f53956 1030L<Exception::Class|Exception::Class>
f7bb182e 1031
11f53956 1032L<File::Spec|File::Spec>
59b05e08 1033
11f53956 1034L<File::Spec::Unix|File::Spec::Unix>
1e7b8681 1035
11f53956 1036L<IO::String|IO::String>
59b05e08 1037
11f53956 1038L<List::MoreUtils|List::MoreUtils>
59b05e08 1039
11f53956 1040L<List::Util|List::Util>
f7bb182e 1041
11f53956 1042L<Module::Pluggable|Module::Pluggable>
1e7b8681 1043
11f53956 1044L<PPI|PPI>
1e7b8681 1045
11f53956 1046L<Pod::PlainText|Pod::PlainText>
a60e94d6 1047
11f53956 1048L<Pod::Usage|Pod::Usage>
59b05e08 1049
11f53956 1050L<Readonly|Readonly>
59b05e08 1051
11f53956 1052L<Scalar::Util|Scalar::Util>
f7bb182e 1053
11f53956 1054L<String::Format|String::Format>
59b05e08 1055
11f53956 1056L<version|version>
a60e94d6 1057
df89052a 1058
59b05e08
JRT
1059The following modules are optional, but recommended for complete
1060testing:
1061
11f53956 1062L<File::HomeDir|File::HomeDir>
a60e94d6 1063
11f53956 1064L<File::Which|File::Which>
a60e94d6 1065
11f53956 1066L<IO::String|IO::String>
a60e94d6 1067
11f53956 1068L<IPC::Open2|IPC::Open2>
a60e94d6 1069
11f53956 1070L<Perl::Tidy|Perl::Tidy>
a60e94d6 1071
11f53956 1072L<Pod::Spell|Pod::Spell>
a60e94d6 1073
11f53956 1074L<Test::Pod|Test::Pod>
59b05e08 1075
11f53956 1076L<Test::Pod::Coverage|Test::Pod::Coverage>
59b05e08 1077
11f53956 1078L<Text::ParseWords|Text::ParseWords>
a60e94d6 1079
df89052a 1080
25e89cf1
ES
1081=head1 CONTACTING THE DEVELOPMENT TEAM
1082
1083You are encouraged to subscribe to the mailing list; send a message to
1084C<< <users-subscribe@perlcritic.tigris.org> >>. See also
1085L<the archives|http://perlcritic.tigris.org/servlets/SummarizeList?listName=users>.
1086You can also contact the author at C<< <thaljef@cpan.org> >>.
1087
11f53956
ES
1088At least one member of the development team has started hanging around
1089in L<irc://irc.perl.org/#perlcritic>.
098d393b 1090
df89052a 1091
3123bf46
ES
1092=head1 SEE ALSO
1093
11f53956
ES
1094There are a number of distributions of additional Policies available.
1095A few are listed here:
3123bf46 1096
11f53956 1097L<Perl::Critic::More|Perl::Critic::More>
a60e94d6 1098
11f53956 1099L<Perl::Critic::Bangs|Perl::Critic::Bangs>
a60e94d6 1100
11f53956 1101L<Perl::Critic::Lax|Perl::Critic::Lax>
a60e94d6 1102
11f53956 1103L<Perl::Critic::StricterSubs|Perl::Critic::StricterSubs>
a60e94d6 1104
11f53956 1105L<Perl::Critic::Swift|Perl::Critic::Swift>
3123bf46 1106
11f53956 1107L<Perl::Critic::Tics|Perl::Critic::Tics>
a60e94d6 1108
d032ff5e
JRT
1109These distributions enable you to use Perl::Critic in your unit tests:
1110
11f53956 1111L<Test::Perl::Critic|Test::Perl::Critic>
a60e94d6 1112
11f53956 1113L<Test::Perl::Critic::Progressive|Test::Perl::Critic::Progressive>
d032ff5e 1114
3123bf46
ES
1115There are also a couple of distributions that will install all the
1116Perl::Critic related modules known to the development team:
1117
11f53956 1118L<Bundle::Perl::Critic|Bundle::Perl::Critic>
a60e94d6 1119
11f53956 1120L<Task::Perl::Critic|Task::Perl::Critic>
3123bf46 1121
11f53956
ES
1122If you want to make sure you have absolutely everything, you can use
1123these:
a60e94d6 1124
11f53956 1125L<Bundle::Perl::Critic::IncludingOptionalDependencies|Bundle::Perl::Critic::IncludingOptionalDependencies>
a60e94d6 1126
11f53956 1127L<Task::Perl::Critic::IncludingOptionalDependencies|Task::Perl::Critic::IncludingOptionalDependencies>
a60e94d6 1128
df89052a 1129
59b05e08
JRT
1130=head1 BUGS
1131
11f53956
ES
1132Scrutinizing Perl code is hard for humans, let alone machines. If you
1133find any bugs, particularly false-positives or false-negatives from a
1bef6e21 1134Perl::Critic::Policy, please submit them to
59b05e08
JRT
1135L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Perl-Critic>. Thanks.
1136
fc0fffee
ES
1137Most policies will produce false-negatives if they cannot understand a
1138particular block of code.
1139
df89052a 1140
59b05e08
JRT
1141=head1 CREDITS
1142
11f53956
ES
1143Adam Kennedy - For creating L<PPI|PPI>, the heart and soul of
1144L<Perl::Critic|Perl::Critic>.
59b05e08 1145
b87b00dd 1146Damian Conway - For writing B<Perl Best Practices>, finally :)
59b05e08 1147
b87b00dd 1148Chris Dolan - For contributing the best features and Policy modules.
59b05e08 1149
7711a331 1150Andy Lester - Wise sage and master of all-things-testing.
9cdbdce6 1151
7711a331 1152Elliot Shank - The self-proclaimed quality freak.
9cdbdce6 1153
7711a331 1154Giuseppe Maxia - For all the great ideas and positive encouragement.
9cdbdce6 1155
b87b00dd 1156and Sharon, my wife - For putting up with my all-night code sessions.
59b05e08 1157
11f53956
ES
1158Thanks also to the Perl Foundation for providing a grant to support
1159Chris Dolan's project to implement twenty PBP policies.
369abea9
CD
1160L<http://www.perlfoundation.org/april_1_2007_new_grant_awards>
1161
df89052a 1162
59b05e08
JRT
1163=head1 AUTHOR
1164
1165Jeffrey Ryan Thalhammer <thaljef@cpan.org>
1166
df89052a 1167
59b05e08
JRT
1168=head1 COPYRIGHT
1169
20dfddeb 1170Copyright (c) 2005-2008 Jeffrey Ryan Thalhammer. All rights reserved.
59b05e08 1171
11f53956
ES
1172This program is free software; you can redistribute it and/or modify
1173it under the same terms as Perl itself. The full text of this license
1174can be found in the LICENSE file included with this module.
59b05e08
JRT
1175
1176=cut
737d3b65 1177
7711a331 1178##############################################################################
737d3b65
CD
1179# Local Variables:
1180# mode: cperl
1181# cperl-indent-level: 4
1182# fill-column: 78
1183# indent-tabs-mode: nil
1184# c-indentation-style: bsd
1185# End:
96fed375 1186# ex: set ts=8 sts=4 sw=4 tw=78 ft=perl expandtab shiftround :