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