Login
Consolidated the ProhibitExit policies into a single Policy.
[gknop/Perl-Critic.git] / bin / perlcritic
1 #!/usr/bin/perl
2
3 ##############################################################################
4 #      $URL$
5 #     $Date$
6 #   $Author$
7 # $Revision$
8 ##############################################################################
9
10 package main;
11
12 use 5.006001;
13 use strict;
14 use warnings;
15
16 use English qw< -no_match_vars >;
17 use Readonly;
18
19 use Getopt::Long qw< GetOptions >;
20 use List::Util qw< first >;
21 use Pod::Usage qw< pod2usage >;
22
23 use Perl::Critic::Exception::Parse ();
24 use Perl::Critic::Utils qw<
25     :characters :severities policy_short_name
26     $DEFAULT_VERBOSITY $DEFAULT_VERBOSITY_WITH_FILE_NAME
27 >;
28 use Perl::Critic::Violation qw<>;
29
30 #-----------------------------------------------------------------------------
31
32 our $VERSION = '1.095_001';
33
34 Readonly::Scalar my $DEFAULT_VIOLATIONS_FOR_TOP => 20;
35
36 Readonly::Scalar my $EXIT_SUCCESS           => 0;
37 Readonly::Scalar my $EXIT_NO_FILES          => 1;
38 Readonly::Scalar my $EXIT_HAD_VIOLATIONS    => 2;
39 Readonly::Scalar my $EXIT_HAD_FILE_PROBLEMS => 3;
40
41 #-----------------------------------------------------------------------------
42 # Begin script.  Don't run when loaded as a library
43
44 my @files = ();
45 my $critic = undef;
46 my $output = \*STDOUT;
47
48 # This %ENV check is to allow perlcritic to function when bundled under PAR,
49 # which invokes this program not as the top stack frame. -- rjbs, 2008-08-11
50 exit run() if not caller or $ENV{PAR_0};
51
52 #-----------------------------------------------------------------------------
53 # Begin subroutines
54
55 sub out {
56     my @lines = @_;
57     return print {$output} @lines;
58 }
59
60 #-----------------------------------------------------------------------------
61
62 sub run {
63     my %options    = get_options();
64     @files         = get_input(@ARGV);
65
66     my ($violations, $had_error_in_file) = critique(\%options, @files);
67
68     return $EXIT_HAD_FILE_PROBLEMS  if $had_error_in_file;
69     return $EXIT_NO_FILES           if not defined $violations;
70     return $EXIT_HAD_VIOLATIONS     if $violations;
71
72     return $EXIT_SUCCESS;
73 }
74
75 #-----------------------------------------------------------------------------
76
77 sub get_options {
78
79     my %opts = _parse_command_line();
80     _dispatch_special_requests( %opts );
81     _validate_options( %opts );
82
83     # Convert severity shortcut options.  If multiple shortcuts
84     # are given, the lowest one wins.  If an explicit --severity
85     # option has been given, then the shortcuts are ignored. The
86     # @SEVERITY_NAMES variable is exported by Perl::Critic::Utils.
87     $opts{-severity} ||= first { exists $opts{"-$_"} } @SEVERITY_NAMES;
88     $opts{-severity} ||= first { exists $opts{"-$_"} } ($SEVERITY_LOWEST ..  $SEVERITY_HIGHEST);
89
90
91     # If --top is specified, default the severity level to 1, unless an
92     # explicit severity is defined.  This provides us flexibility to
93     # report top-offenders across just some or all of the severity levels.
94     # We also default the --top count to twenty if none is given
95     if ( exists $opts{-top} ) {
96         $opts{-severity} ||= 1;
97         $opts{-top} ||= $DEFAULT_VIOLATIONS_FOR_TOP;
98     }
99
100     #Override profile, if --noprofile is specified
101     if ( exists $opts{-noprofile} ) {
102         $opts{-profile} = $EMPTY;
103     }
104
105     return %opts;
106 }
107
108 #-----------------------------------------------------------------------------
109
110 sub _parse_command_line {
111     my %opts;
112     my @opt_specs = _get_option_specification();
113     Getopt::Long::Configure('no_ignore_case');
114     GetOptions( \%opts, @opt_specs ) || pod2usage();           #Exits
115
116     # I've adopted the convention of using key-value pairs for
117     # arguments to most functions.  And to increase legibility,
118     # I have also adopted the familiar command-line practice
119     # of denoting argument names with a leading dash (-).
120     my %dashed_opts = map { ( "-$_" => $opts{$_} ) } keys %opts;
121     return %dashed_opts;
122 }
123
124 #-----------------------------------------------------------------------------
125
126 sub _dispatch_special_requests {
127     my (%opts) = @_;
128     if ( $opts{-help}            ) { pod2usage( -verbose => 0 )  }  #Exits
129     if ( $opts{-options}         ) { pod2usage( -verbose => 1 )  }  #Exits
130     if ( $opts{-man}             ) { pod2usage( -verbose => 2 )  }  #Exits
131     if ( $opts{-version}         ) { display_version()           }  #Exits
132     if ( $opts{-list}            ) { render_policy_listing();    }  #Exits
133     if ( $opts{'-list-themes'}   ) { render_theme_listing();     }  #Exits
134     if ( $opts{'-profile-proto'} ) { render_profile_prototype(); }  #Exits
135     if ( $opts{-doc}             ) { policy_docs( %opts );       }  #Exits
136     return 1;
137 }
138
139 #-----------------------------------------------------------------------------
140
141 sub _validate_options {
142     my (%opts) = @_;
143     my $msg = $EMPTY;
144
145
146     if ( $opts{-noprofile} && $opts{-profile} ) {
147         $msg .= qq{Warning: Cannot use -noprofile with -profile option.\n};
148     }
149
150     if ( $opts{-verbose} && $opts{-verbose} !~ m{(?: \d+ | %[mfFlcedrpPs] )}xms) {
151         $msg .= qq<Warning: --verbose arg "$opts{-verbose}" looks odd.  >;
152         $msg .= qq<Perhaps you meant to say "--verbose 3 $opts{-verbose}."\n>;
153     }
154
155     if ( exists $opts{-top} && $opts{-top} < 0 ) {
156         $msg .= qq<Warning: --top argument "$opts{-top}" is negative.  >;
157         $msg .= qq<Perhaps you meant to say "$opts{-top} --top".\n>;
158     }
159
160     if (
161             exists $opts{-severity}
162         &&  (
163                     $opts{-severity} < $SEVERITY_LOWEST
164                 ||  $opts{-severity} > $SEVERITY_HIGHEST
165             )
166     ) {
167         $msg .= qq<Warning: --severity arg "$opts{-severity}" out of range.  >;
168         $msg .= qq<Severities range from "$SEVERITY_LOWEST" (lowest) to >;
169         $msg .= qq<"$SEVERITY_HIGHEST" (highest).\n>;
170     }
171
172
173     if ( $msg ) {
174         pod2usage( -exitstatus => 1, -message => $msg, -verbose => 0); #Exits
175     }
176
177
178     return 1;
179 }
180
181 #-----------------------------------------------------------------------------
182
183 sub get_input {
184
185     my @args = @_;
186
187     if ( !@args || (@args == 1 && $args[0] eq q{-}) )  {
188
189         # Reading code from STDIN.  All the code is slurped into
190         # a string.  PPI will barf if the string is just whitespace.
191         my $code_string = do { local $RS = undef; <STDIN> };
192
193         # Notice if STDIN was closed (pipe error, etc)
194         if ( ! defined $code_string ) {
195             $code_string = $EMPTY;
196         }
197
198         $code_string =~ m{ \S+ }xms || die qq{Nothing to critique.\n};
199         return \$code_string;    #Convert to SCALAR ref for PPI
200     }
201     else {
202
203         # Test to make sure all the specified files or directories
204         # actually exist.  If any one of them is bogus, then die.
205         if ( my $nonexistent = first { ! -e $_ } @args ) {
206             my $msg = qq{No such file or directory: '$nonexistent'};
207             pod2usage( -exitstatus => 1, -message => $msg, -verbose => 0);
208         }
209
210         # Reading code from files or dirs.  If argument is a file,
211         # then we process it as-is (even though it may not actually
212         # be Perl code).  If argument is a directory, recursively
213         # search the directory for files that look like Perl code.
214         return map { -d $_ ? Perl::Critic::Utils::all_perl_files($_) : $_ } @args;
215     }
216 }
217
218 #------------------------------------------------------------------------------
219
220 sub critique {
221
222     my ( $opts_ref, @files_to_critique ) = @_;
223     @files_to_critique || die "No perl files were found.\n";
224
225     # Perl::Critic has lots of dependencies, so loading is delayed
226     # until it is really needed.  This hack reduces startup time for
227     # doing other things like getting the version number or dumping
228     # the man page. Arguably, those things are pretty rare, but hey,
229     # why not save a few seconds if you can.
230
231     require Perl::Critic;
232     $critic = Perl::Critic->new( %{$opts_ref} );
233     $critic->policies() || die "No policies selected.\n";
234
235     set_up_pager($critic->config()->pager());
236
237     my $number_of_violations = undef;
238     my $had_error_in_file = 0;
239
240     for my $file (@files_to_critique) {
241
242         eval {
243             my @violations = $critic->critique($file);
244             $number_of_violations += scalar @violations;
245
246             if (not $opts_ref->{'-statistics-only'}) {
247                 render_report( $file, $opts_ref, @violations )
248             }
249             1;
250         }
251         or do {
252             if ( my $exception = Perl::Critic::Exception::Parse->caught() ) {
253                 $had_error_in_file = 1;
254                 warn qq<Problem while critiquing "$file": $EVAL_ERROR\n>;
255             }
256             elsif ($EVAL_ERROR) {
257                 # P::C::Exception::Fatal includes the stack trace in its
258                 # stringification.
259                 die qq<Fatal error while critiquing "$file": $EVAL_ERROR\n>;
260             }
261             else {
262                 die qq<Fatal error while critiquing "$file". Unfortunately, >,
263                     q<$@/$EVAL_ERROR >, ## no critic (RequireInterpolationOfMetachars)
264                     qq<is empty, so the reason can't be shown.\n>;
265             }
266         }
267     }
268
269     if ( $opts_ref->{-statistics} or $opts_ref->{'-statistics-only'} ) {
270         my $stats = $critic->statistics();
271         report_statistics( $opts_ref, $stats );
272     }
273
274     return $number_of_violations, $had_error_in_file;
275 }
276
277 #------------------------------------------------------------------------------
278
279 sub render_report {
280
281     my ( $file, $opts_ref, @violations ) = @_;
282
283     # Only report the number of violations, if asked.
284     my $number_of_violations = scalar @violations;
285     if( $opts_ref->{-count} ){
286         ref $file || out "$file: ";
287         out "$number_of_violations\n";
288         return $number_of_violations;
289     }
290
291     # Hail all-clear unless we should shut up.
292     if( !@violations && !$opts_ref->{-quiet} ) {
293         ref $file || out "$file ";
294         out "source OK\n";
295         return 0;
296     }
297
298     # Otherwise, format and print violations
299     my $verbosity = $critic->config->verbose();
300     # $verbosity can be numeric or string, so use "eq" for comparison;
301     $verbosity =
302         ($verbosity eq $DEFAULT_VERBOSITY && @files > 1)
303             ? $DEFAULT_VERBOSITY_WITH_FILE_NAME
304             : $verbosity;
305     my $fmt = Perl::Critic::Utils::verbosity_to_format( $verbosity );
306     if (not -f $file) { $fmt =~ s< \%[fF] ><STDIN>xms; } #HACK!
307     Perl::Critic::Violation::set_format( $fmt );
308
309     my $color = $critic->config->color();
310     out $color ? _colorize_by_severity(@violations) : @violations;
311
312     return $number_of_violations;
313 }
314
315 #-----------------------------------------------------------------------------
316
317 sub set_up_pager {
318     my ($pager_command) = @_;
319     return if not $pager_command;
320     return if not _at_tty();
321
322     open my $pager, q<|->, $pager_command  ## no critic (InputOutput::RequireBriefOpen)
323         or die qq<Unable to pipe to pager "$pager_command": $ERRNO\n>;
324
325     $output = $pager;
326
327     return;
328 }
329
330 #-----------------------------------------------------------------------------
331
332 sub report_statistics {
333     my ($opts_ref, $statistics) = @_;
334
335     if (
336             not $opts_ref->{'-statistics-only'}
337         and (
338                 $statistics->total_violations()
339             or  not $opts_ref->{-quiet} and $statistics->modules()
340         )
341     ) {
342         out "\n"; # There's prior output that we want to separate from.
343     }
344
345     out _commaify($statistics->modules()), " files.\n";
346     out _commaify($statistics->subs()), " subroutines/methods.\n";
347     out _commaify($statistics->statements_other_than_subs()), " statements.\n";
348     out _commaify($statistics->lines()), " lines.\n";
349
350     my $average_sub_mccabe = $statistics->average_sub_mccabe();
351     if (defined $average_sub_mccabe) {
352         out sprintf
353             "\nAverage McCabe score of subroutines was %.2f.\n",
354             $average_sub_mccabe;
355     }
356
357     out "\n";
358
359     out _commaify($statistics->total_violations()), " violations.\n";
360
361     my $violations_per_file = $statistics->violations_per_file();
362     if (defined $violations_per_file) {
363         out sprintf
364             "Violations per file was %.3f.\n",
365             $violations_per_file;
366     }
367     my $violations_per_statement = $statistics->violations_per_statement();
368     if (defined $violations_per_statement) {
369         out sprintf
370             "Violations per statement was %.3f.\n",
371             $violations_per_statement;
372     }
373     my $violations_per_line = $statistics->violations_per_line_of_code();
374     if (defined $violations_per_line) {
375         out sprintf
376             "Violations per line of code was %.3f.\n",
377             $violations_per_line;
378     }
379
380     if ( $statistics->total_violations() ) {
381         out "\n";
382
383         my %severity_violations = %{ $statistics->violations_by_severity() };
384         foreach my $severity ( reverse sort keys %severity_violations ) {
385             out
386                 _commaify($severity_violations{$severity}),
387                 " severity $severity violations.\n";
388         }
389
390         out "\n";
391
392         my %policy_violations = %{ $statistics->violations_by_policy() };
393         foreach my $policy ( sort keys %policy_violations ) {
394             out
395                 _commaify($policy_violations{$policy}),
396                 ' violations of ',
397                 policy_short_name($policy),
398                 ".\n";
399         }
400     }
401
402     return;
403 }
404
405 #-----------------------------------------------------------------------------
406
407 # Only works for integers.
408 sub _commaify {
409     my ( $number ) = @_;
410
411     while ($number =~ s/ \A ( [-+]? \d+ ) ( \d{3} ) /$1,$2/xms) {
412         # nothing
413     }
414
415     return $number;
416 }
417
418 #-----------------------------------------------------------------------------
419
420 sub _get_option_specification {
421
422     return qw(
423         5 4 3 2 1
424         Safari
425         version
426         brutal
427         count|C
428         cruel
429         doc=s
430         exclude=s@
431         force!
432         gentle
433         harsh
434         help|?|H
435         include=s@
436         list
437         list-themes
438         man
439         color|colour!
440         noprofile
441         only!
442         options
443         pager=s
444         profile=s
445         profile-proto
446         quiet
447         severity=i
448         single-policy|s=s
449         stern
450         statistics!
451         statistics-only!
452         profile-strictness=s
453         theme=s
454         top:i
455         verbose=s
456         color-severity-highest|colour-severity-highest|color-severity-5|colour-severity-5=s
457         color-severity-high|colour-severity-high|color-severity-4|colour-severity-4=s
458         color-severity-medium|colour-severity-medium|color-severity-3|colour-severity-3=s
459         color-severity-low|colour-severity-low|color-severity-2|colour-severity-2=s
460         color-severity-lowest|colour-severity-lowest|color-severity-1|colour-severity-1=s
461     );
462 }
463
464 #-----------------------------------------------------------------------------
465
466 sub _colorize_by_severity {
467     my @violations = @_;
468     return @violations if _this_is_windows();
469     return @violations if not eval { require Term::ANSIColor; 1; };
470
471     my $config = $critic->config();
472     my %color_of = (
473         $SEVERITY_HIGHEST   => $config->color_severity_highest(),
474         $SEVERITY_HIGH      => $config->color_severity_high(),
475         $SEVERITY_MEDIUM    => $config->color_severity_medium(),
476         $SEVERITY_LOW       => $config->color_severity_low(),
477         $SEVERITY_LOWEST    => $config->color_severity_lowest(),
478     );
479
480     return map { _colorize( "$_", $color_of{$_->severity()} ) } @violations;
481
482 }
483
484 #-----------------------------------------------------------------------------
485
486 sub _colorize {
487     my ($string, $color) = @_;
488     return $string if not defined $color;
489     return $string if $color eq $EMPTY;
490     # $terminator is a purely cosmetic change to make the color end at the end
491     # of the line rather than right before the next line. It is here because
492     # if you use background colors, some console windows display a little
493     # fragment of colored background before the next uncolored (or
494     # differently-colored) line.
495     my $terminator = chomp $string ? "\n" : $EMPTY;
496     return  Term::ANSIColor::colored( $string, $color ) . $terminator;
497 }
498
499 #-----------------------------------------------------------------------------
500
501 sub _this_is_windows {
502     return 1 if $OSNAME =~ m/MSWin32/xms;
503     return 0;
504 }
505
506 #-----------------------------------------------------------------------------
507
508 sub _at_tty {
509     return -t STDOUT; ## no critic (ProhibitInteractiveTest);
510 }
511
512 #-----------------------------------------------------------------------------
513
514 sub render_policy_listing {
515
516     require Perl::Critic::PolicyListing;
517     require Perl::Critic;
518
519     my %pc_params = (-profile => $EMPTY, -severity => $SEVERITY_LOWEST);
520     my @policies = Perl::Critic->new( %pc_params )->policies();
521     my $listing = Perl::Critic::PolicyListing->new( -policies => \@policies );
522     out $listing;
523
524     exit $EXIT_SUCCESS; ## no critic qw(ProhibitExit)
525 }
526
527 #-----------------------------------------------------------------------------
528
529 sub render_theme_listing {
530
531     require Perl::Critic::ThemeListing;
532     require Perl::Critic;
533
534     my %pc_params = (-profile => $EMPTY, -severity => $SEVERITY_LOWEST);
535     my @policies = Perl::Critic->new( %pc_params )->policies();
536     my $listing = Perl::Critic::ThemeListing->new( -policies => \@policies );
537     out $listing;
538
539     exit $EXIT_SUCCESS; ## no critic qw(ProhibitExit)
540 }
541
542 #-----------------------------------------------------------------------------
543
544 sub render_profile_prototype {
545
546     require Perl::Critic::ProfilePrototype;
547     require Perl::Critic;
548
549     my %pc_params = (-profile => $EMPTY, -severity => $SEVERITY_LOWEST);
550     my @policies = Perl::Critic->new( %pc_params )->policies();
551     my $prototype = Perl::Critic::ProfilePrototype->new( -policies => \@policies );
552     out $prototype;
553
554     exit $EXIT_SUCCESS; ## no critic qw(ProhibitExit)
555 }
556
557 #-----------------------------------------------------------------------------
558
559 sub policy_docs {
560
561     my (%opts) = @_;
562     my $pattern = delete $opts{-doc};
563
564     require Perl::Critic;
565     $critic = Perl::Critic->new(%opts);
566     set_up_pager($critic->config()->pager());
567
568     require Perl::Critic::PolicyFactory;
569     my @site_policies  = Perl::Critic::PolicyFactory->site_policy_names();
570     my @matching_policies  = grep { $_ =~ m/$pattern/ixms } @site_policies;
571
572     # "-T" means don't send to pager
573     my @perldoc_output = map {`perldoc -T $_`} @matching_policies;  ## no critic (ProhibitBacktick)
574     out @perldoc_output;
575
576     exit $EXIT_SUCCESS; ## no critic qw(ProhibitExit)
577 }
578
579 #-----------------------------------------------------------------------------
580
581 sub display_version {
582     out "$VERSION\n";
583     exit $EXIT_SUCCESS;  ## no critic qw(ProhibitExit)
584 }
585
586 #-----------------------------------------------------------------------------
587 1;
588
589 __END__
590
591 #-----------------------------------------------------------------------------
592
593 =pod
594
595 =for stopwords DGR INI-style vim-fu minibuffer -noprofile API
596 -profileproto -profile-proto ben Jore formatter Peshak pbp Komodo
597 screenshots tty emacs gVIM plugin Perlish templating ActiveState
598
599 =head1 NAME
600
601 C<perlcritic> - Command-line interface to critique Perl source.
602
603
604 =head1 SYNOPSIS
605
606   perlcritic [-12345 | --brutal | --cruel | --harsh | --stern | --gentle]
607              [--severity number | name] [--profile file | --noprofile]
608              [--top [ number ]] [--theme expression] [--include pattern]
609              [--exclude pattern] [{-s | --single-policy} pattern]
610              [--only | --noonly] [--profile-strictness {warn|fatal|quiet}]
611              [--force | --noforce] [--statistics] [--statistics-only]
612              [--count | -C] [--verbose {number | format}]
613              [--color | --nocolor] [--pager pager] [--quiet]
614              [--color-severity-highest color_specification]
615              [--color-severity-high color_specification]
616              [--color-severity-medium color_specification]
617              [--color-severity-low color_specification]
618              [--color-severity-lowest color_specification]
619              {FILE | DIRECTORY | STDIN}
620
621   perlcritic --profile-proto
622
623   perlcritic { --list | --list-themes | --doc pattern [...] }
624
625   perlcritic { --help | --options | --man | --version }
626
627
628 =head1 DESCRIPTION
629
630 C<perlcritic> is a Perl source code analyzer.  It is the executable
631 front-end to the L<Perl::Critic|Perl::Critic> engine, which attempts
632 to identify awkward, hard to read, error-prone, or unconventional
633 constructs in your code.  Most of the rules are based on Damian
634 Conway's book B<Perl Best Practices>.  However, C<perlcritic> is
635 B<not> limited to enforcing PBP, and it will even support rules that
636 contradict Conway.  All rules can easily be configured or disabled to
637 your liking.
638
639 This documentation only covers how to drive this command.  For all
640 other information, including how to persistently configure this
641 command so that you don't have to say so much on the command-line, see
642 the documentation for L<Perl::Critic|Perl::Critic> itself.
643
644
645 =head1 USAGE EXAMPLES
646
647 Before getting into all the gory details, here are some basic usage
648 examples to help get you started.
649
650     # Report only most severe violations (severity = 5)
651     perlcritic YourModule.pm
652
653     # Same as above, but read input from STDIN
654     perlcritic
655
656     # Recursively process all Perl files beneath directory
657     perlcritic /some/directory
658
659     # Report slightly less severe violations too (severity >= 4)
660     perlcritic -4 YourModule.pm
661
662     # Same as above, but using named severity level
663     perlcritic --stern YourModule.pm
664
665     # Report all violations, regardless of severity (severity >= 1)
666     perlcritic -1 YourModule.pm
667
668     # Same as above, but using named severity level
669     perlcritic --brutal YourModule.pm
670
671     # Report only violations of things from "Perl Best Practices"
672     perlcritic --theme pbp YourModule.pm
673
674     # Report top 20 most severe violations (severity >= 1)
675     perlcritic --top YourModule.pm
676
677     # Report additional violations of Policies that match m/variables/xms
678     perlcritic --include variables YourModule.pm
679
680     # Use defaults from somewhere other than ~/.perlcriticrc
681     perlcriticrc --profile project/specific/perlcriticrc YourModule.pm
682
683
684 =head1 ARGUMENTS
685
686 The arguments are paths to the files you wish to analyze.  You may
687 specify multiple files.  If an argument is a directory, C<perlcritic>
688 will analyze all Perl files below the directory.  If no arguments are
689 specified, then input is read from STDIN.
690
691
692 =head1 OPTIONS
693
694 Option names can be abbreviated to uniqueness and can be stated with
695 singe or double dashes, and option values can be separated from the
696 option name by a space or '=' (as with L<Getopt::Long|Getopt::Long>).
697 Option names are also case-sensitive.
698
699 =over
700
701 =item C<--profile FILE>
702
703 Directs C<perlcritic> to use a profile named by FILE rather than
704 looking for the default F<.perlcriticrc> file in the current directory
705 or your home directory.  See L<Perl::Critic/"CONFIGURATION"> for more
706 information.
707
708 =item C<--noprofile>
709
710 Directs C<perlcritic> not to load any configuration file, thus
711 reverting to the default configuration for all Policies.
712
713 =item C<--severity N>
714
715 Directs C<perlcritic> to only apply Policies with a severity greater
716 than C<N>.  Severity values are integers ranging from 1 (least severe)
717 to 5 (most severe).  The default is 5.  For a given C<--profile>,
718 decreasing the C<--severity> will usually produce more violations.
719 You can set the default value for this option in your F<.perlcriticrc>
720 file.  You can also redefine the C<severity> for any Policy in your
721 F<.perlcriticrc> file.  See L<"CONFIGURATION"> for more information.
722
723 =item C<-5 | -4 | -3 | -2 | -1>
724
725 These are numeric shortcuts for setting the C<--severity> option.  For
726 example, C<"-4"> is equivalent to C<"--severity 4">.  If multiple
727 shortcuts are specified, then the most restrictive one wins.  If an
728 explicit C<--severity> option is also given, then all shortcut options
729 are silently ignored.  NOTE: Be careful not to put one of the number
730 severity shortcut options immediately after the C<--top> flag or
731 C<perlcritic> will interpret it as the number of violations to report.
732
733 =item C<--severity NAME>
734
735 If it is difficult for you to remember whether severity "5" is the
736 most or least restrictive level, then you can use one of these named
737 values:
738
739     SEVERITY NAME   ...is equivalent to...   SEVERITY NUMBER
740     --------------------------------------------------------
741     --severity gentle                           --severity 5
742     --severity stern                            --severity 4
743     --severity harsh                            --severity 3
744     --severity cruel                            --severity 2
745     --severity brutal                           --severity 1
746
747 =item C<--gentle | --stern | --harsh | --cruel | --brutal>
748
749 These are named shortcuts for setting the C<--severity> option.  For
750 example, C<"--cruel"> is equivalent to C<"--severity 2">.  If multiple
751 shortcuts are specified, then the most restrictive one wins.  If an
752 explicit C<--severity> option is also given, then all shortcut options
753 are silently ignored.
754
755 =item C<--theme RULE>
756
757 Directs C<perlcritic> to apply only Policies with themes that satisfy
758 the C<RULE>.  Themes are arbitrary names for groups of related
759 policies.  You can combine theme names with boolean operators to
760 create an arbitrarily complex C<RULE>.  For example, the following
761 would apply only Policies that have a 'bugs' AND 'pbp' theme:
762
763     $> perlcritic --theme='bugs && pbp' MyModule.pm
764
765 Unless the C<--severity> option is explicitly given, setting
766 C<--theme> silently causes the C<--severity> to be set to 1.  You can
767 set the default value for this option in your F<.perlcriticrc> file.
768 See L<Perl::Critic/"POLICY THEMES"> for more information about themes.
769
770 =item C<--include PATTERN>
771
772 Directs C<perlcritic> to apply additional Policies that match the
773 regex C</PATTERN/imx>.  Use this option to temporarily override your
774 profile and/or the severity settings at the command-line.  For
775 example:
776
777     perlcritic --include=layout my_file.pl
778
779 This would cause C<perlcritic> to apply all the C<CodeLayout::*>
780 policies even if they have a severity level that is less than the
781 default level of 5, or have been disabled in your F<.perlcriticrc>
782 file.  You can specify multiple C<--include> options and you can use
783 it in conjunction with the C<--exclude> option.  Note that
784 C<--exclude> takes precedence over C<--include> when a Policy matches
785 both patterns.  You can set the default value for this option in your
786 F<.perlcriticrc> file.
787
788 =item C<--exclude PATTERN>
789
790 Directs C<perlcritic> to not apply any Policy that matches the regex
791 C</PATTERN/imx>.  Use this option to temporarily override your profile
792 and/or the severity settings at the command-line.  For example:
793
794     perlcritic --exclude=strict my_file.pl
795
796 This would cause C<perlcritic> to not apply the C<RequireUseStrict>
797 and C<ProhibitNoStrict> Policies even though they have the highest
798 severity level.  You can specify multiple C<--exclude> options and you
799 can use it in conjunction with the C<--include> option.  Note that
800 C<--exclude> takes precedence over C<--include> when a Policy matches
801 both patterns.  You can set the default value for this option in your
802 F<.perlcriticrc> file.
803
804 =item C<--single-policy PATTERN>
805
806 =item C<-s PATTERN>
807
808 Directs C<perlcritic> to apply just one Policy module matching the
809 regex C</PATTERN/ixms>, and exclude all other Policies.  This option
810 has precedence over the C<--severity>, C<--theme>, C<--include>,
811 C<--exclude>, and C<--only> options.  For example:
812
813     perlcritic --single-policy=nowarnings my_file.pl
814
815 This would cause C<perlcritic> to apply just the C<ProhibitNoWarnings>
816 Policy, regardless of the severity level setting.  No other Policies
817 would be applied.
818
819 This is equivalent to what one might intend by...
820
821     perlcritic --exclude=. --include=nowarnings my_file.pl
822
823 ... but this won't work because the C<--exclude> option overrides the
824 C<--include> option.
825
826 The equivalent of this option can be accomplished by creating a custom
827 profile containing only the desired policy and then running...
828
829     perlcritic --profile=customprofile --only my_file.pl
830
831 =item C<--top [ N ]>
832
833 Directs C<perlcritic> to report only the top C<N> Policy violations in
834 each file, ranked by their severity.  If C<N> is not specified, it
835 defaults to 20.  If the C<--severity> option (or one of the shortcuts)
836 is not explicitly given, the C<--top> option implies that the minimum
837 severity level is "1" (i.e. "brutal"). Users can redefine the severity
838 for any Policy in their F<.perlcriticrc> file.  See L<"CONFIGURATION">
839 for more information.  You can set the default value for this option
840 in your F<.perlcriticrc> file.  NOTE: Be careful not to put one of the
841 severity shortcut options immediately after the C<--top> flag or
842 C<perlcritic> will interpret it as the number of violations to report.
843
844 =item C<--force>
845
846 Directs C<perlcritic> to ignore the magical C<"## no critic">
847 annotations in the source code. See L<"BENDING THE RULES"> for more
848 information.  You can set the default value for this option in your
849 F<.perlcriticrc> file.
850
851 =item C<--statistics>
852
853 Causes several statistics about the code being scanned and the
854 violations found to be reported after any other output.
855
856 =item C<--statistics-only>
857
858 Like the C<--statistics> option, but suppresses normal output and only
859 shows the statistics.
860
861 =item C<--verbose N | FORMAT>
862
863 Sets the verbosity level or format for reporting violations.  If given
864 a number (C<N>), C<perlcritic> reports violations using one of the
865 predefined formats described below.  If given a string (C<FORMAT>), it
866 is interpreted to be an actual format specification.  If the
867 C<--verbose> option is not specified, it defaults to either 4 or 5,
868 depending on whether multiple files were given as arguments to
869 C<perlcritic>.  You can set the default value for this option in your
870 F<.perlcriticrc> file.
871
872     Verbosity     Format Specification
873     -----------   -------------------------------------------------------
874      1            "%f:%l:%c:%m\n",
875      2            "%f: (%l:%c) %m\n",
876      3            "%m at %f line %l\n",
877      4            "%m at line %l, column %c.  %e.  (Severity: %s)\n",
878      5            "%f: %m at line %l, column %c.  %e.  (Severity: %s)\n",
879      6            "%m at line %l, near '%r'.  (Severity: %s)\n",
880      7            "%f: %m at line %l near '%r'.  (Severity: %s)\n",
881      8            "[%p] %m at line %l, column %c.  (Severity: %s)\n",
882      9            "[%p] %m at line %l, near '%r'.  (Severity: %s)\n",
883     10            "%m at line %l, column %c.\n  %p (Severity: %s)\n%d\n",
884     11            "%m at line %l, near '%r'.\n  %p (Severity: %s)\n%d\n"
885
886 Formats are a combination of literal and escape characters similar to
887 the way C<sprintf> works.  See L<String::Format|String::Format> for a
888 full explanation of the formatting capabilities.  Valid escape
889 characters are:
890
891     Escape    Meaning
892     -------   ------------------------------------------------------------
893     %c        Column number where the violation occurred
894     %d        Full diagnostic discussion of the violation
895     %e        Explanation of violation or page numbers in PBP
896     %F        Just the name of the file where the violation occurred.
897     %f        Path to the file where the violation occurred.
898     %l        Line number where the violation occurred
899     %m        Brief description of the violation
900     %P        Full name of the Policy module that created the violation
901     %p        Name of the Policy without the Perl::Critic::Policy:: prefix
902     %r        The string of source code that caused the violation
903     %s        The severity level of the violation
904
905 The purpose of these formats is to provide some compatibility with
906 text editors that have an interface for parsing certain kinds of
907 input. See L<"EDITOR INTEGRATION"> for more information about that.
908
909 =item C<--list>
910
911 Displays a condensed listing of all the
912 L<Perl::Critic::Policy|Perl::Critic::Policy> modules that are found on
913 this machine.  For each Policy, the name, default severity and default
914 themes are shown.
915
916 =item C<--list-themes>
917
918 Displays a list of all the themes of the
919 L<Perl::Critic::Policy|Perl::Critic::Policy> modules that are found on
920 this machine.
921
922 =item C<--profile-proto>
923
924 Displays an expanded listing of all the
925 L<Perl::Critic::Policy|Perl::Critic::Policy> modules that are found on
926 this machine.  For each Policy, the name, default severity and default
927 themes are shown, as well as the name of any additional parameters
928 that the Policy supports.  The format is suitable as a prototype for
929 your F<.perlcriticrc> file.
930
931 =item C<--only>
932
933 Directs perlcritic to apply only Policies that are explicitly
934 mentioned in your F<.perlcriticrc> file.  This is useful if you want
935 to use just a small subset of Policies without having to disable all
936 the others.  You can set the default value for this option in your
937 F<.perlcriticrc> file.
938
939 =item C<--profile-strictness {warn|fatal|quiet}>
940
941 Directs perlcritic how to treat certain recoverable problems found in
942 a F<.perlcriticrc> or file specified via the C<--profile> option.
943 Valid values are C<warn> (the default), C<fatal>, and C<quiet>.  For
944 example, perlcritic normally only warns about profiles referring to
945 non-existent Policies, but this option can make this situation fatal.
946 You can set the default value for this option in your F<.perlcriticrc>
947 file.
948
949 =item C<--count>
950
951 =item C<-C>
952
953 Display only the number of violations for each file.  Use this feature
954 to get a quick handle on where a large pile of code might need the
955 most attention.
956
957 =item C<--Safari>
958
959 Report "Perl Best Practice" citations as section numbers from
960 L<http://safari.oreilly.com> instead of page numbers from the actual
961 book.  NOTE: This feature is not implemented yet.
962
963 =item C<--color>
964
965 This option is on when outputting to a tty.  When set, Severity 5 and 4 are
966 colored red and yellow, respectively.  Colorization only happens if
967 L<Term::ANSIColor|Term::ANSIColor> is installed and it only works on
968 non-Windows environments.  Negate this switch to disable color.  You can set
969 the default value for this option in your F<.perlcriticrc> file.
970
971 Can also be specified as C<--colour>.
972
973 =item C<--pager PAGER_COMMAND_STRING>
974
975 If set, perlcritic will pipe it's output to the given PAGER_COMMAND_STRING.
976 You can set the default value for this option in your F<.perlcriticrc> file.
977
978 Setting a pager turns off color by default.  You will have to turn color on
979 explicitly.  If you want color, you'll probably also want to tell your pager
980 to display raw characters.  For C<less> and C<more>, use the -R switch.
981
982 =item C<--color-severity-highest COLOR_SPECIFICATION>
983
984 Specifies the color to be used for highest severity violations, as a
985 Term::ANSIColor color specification. Can also be specified as
986 C<--colour-severity-highest>, C<--color-severity-5>, or
987 C<--colour-severity-5>.
988
989 =item C<--color-severity-high COLOR_SPECIFICATION>
990
991 Specifies the color to be used for high severity violations, as a
992 Term::ANSIColor color specification. Can also be specified as
993 C<--colour-severity-high>, C<--color-severity-4>, or
994 C<--colour-severity-4>.
995
996 =item C<--color-severity-medium COLOR_SPECIFICATION>
997
998 Specifies the color to be used for medium severity violations, as a
999 Term::ANSIColor color specification. Can also be specified as
1000 C<--colour-severity-medium>, C<--color-severity-3>, or
1001 C<--colour-severity-3>.
1002
1003 =item C<--color-severity-low COLOR_SPECIFICATION>
1004
1005 Specifies the color to be used for low severity violations, as a
1006 Term::ANSIColor color specification. Can also be specified as
1007 C<--colour-severity-low>, C<--color-severity-2>, or
1008 C<--colour-severity-2>.
1009
1010 =item C<--color-severity-lowest COLOR_SPECIFICATION>
1011
1012 Specifies the color to be used for lowest severity violations, as a
1013 Term::ANSIColor color specification. Can also be specified as
1014 C<--colour-severity-lowest>, C<--color-severity-1>, or
1015 C<--colour-severity-1>.
1016
1017 =item C<--doc PATTERN>
1018
1019 Displays the perldoc for all
1020 L<Perl::Critic::Policy|Perl::Critic::Policy> modules that match
1021 C<m/PATTERN/ixms>.  Since Policy modules tend to have rather long
1022 names, this just provides a more convenient way to say something like:
1023 C<"perldoc Perl::Critic::Policy::ValuesAndExpressions::RequireUpperCaseHeredocTerminator">
1024 at the command prompt.
1025
1026 =item C<--quiet>
1027
1028 Suppress the "source OK" message when no violations are found.
1029
1030 =item C<--help>
1031
1032 =item C<-?>
1033
1034 =item C<-H>
1035
1036 Displays a brief summary of options and exits.
1037
1038 =item C<--options>
1039
1040 Displays the descriptions of the options and exits.  While this output
1041 is long, it it nowhere near the length of the output of C<--man>.
1042
1043 =item C<--man>
1044
1045 Displays the complete C<perlcritic> manual and exits.
1046
1047 =item C<--version>
1048
1049 =item C<-V>
1050
1051 Displays the version number of C<perlcritic> and exits.
1052
1053 =back
1054
1055 =head1 CONFIGURATION
1056
1057 Most of the settings for Perl::Critic and each of the Policy modules
1058 can be controlled by a configuration file.  The default configuration
1059 file is called F<.perlcriticrc>.  C<perlcritic> will look for this
1060 file in the current directory first, and then in your home directory.
1061 Alternatively, you can set the C<PERLCRITIC> environment variable to
1062 explicitly point to a different file in another location.  If none of
1063 these files exist, and the C<--profile> option is not given on the
1064 command-line, then all Policies will be loaded with their default
1065 configuration.
1066
1067 The format of the configuration file is a series of INI-style blocks
1068 that contain key-value pairs separated by "=". Comments should start
1069 with "#" and can be placed on a separate line or after the name-value
1070 pairs if you desire.
1071
1072 Default settings for perlcritic itself can be set B<before the first
1073 named block.> For example, putting any or all of these at the top of
1074 your F<.perlcriticrc> file will set the default value for the
1075 corresponding command-line argument.
1076
1077     severity  = 3                                     #Integer or named level
1078     only      = 1                                     #Zero or One
1079     force     = 0                                     #Zero or One
1080     verbose   = 4                                     #Integer or format spec
1081     top       = 50                                    #A positive integer
1082     theme     = (pbp + security) * bugs               #A theme expression
1083     include   = NamingConventions ClassHierarchies    #Space-delimited list
1084     exclude   = Variables  Modules::RequirePackage    #Space-delimited list
1085
1086 The remainder of the configuration file is a series of blocks like this:
1087
1088     [Perl::Critic::Policy::Category::PolicyName]
1089     severity = 1
1090     set_themes = foo bar
1091     add_themes = baz
1092     arg1 = value1
1093     arg2 = value2
1094
1095 C<Perl::Critic::Policy::Category::PolicyName> is the full name of a
1096 module that implements the policy.  The Policy modules distributed
1097 with Perl::Critic have been grouped into categories according to the
1098 table of contents in Damian Conway's book B<Perl Best Practices>. For
1099 brevity, you can omit the C<'Perl::Critic::Policy'> part of the module
1100 name.
1101
1102 C<severity> is the level of importance you wish to assign to the
1103 Policy.  All Policy modules are defined with a default severity value
1104 ranging from 1 (least severe) to 5 (most severe).  However, you may
1105 disagree with the default severity and choose to give it a higher or
1106 lower severity, based on your own coding philosophy.  You can set the
1107 C<severity> to an integer from 1 to 5, or use one of the equivalent
1108 names:
1109
1110     SEVERITY NAME ...is equivalent to... SEVERITY NUMBER
1111     ----------------------------------------------------
1112     gentle                                             5
1113     stern                                              4
1114     harsh                                              3
1115     cruel                                              2
1116     brutal                                             1
1117
1118 C<set_themes> sets the theme for the Policy and overrides its default
1119 theme.  The argument is a string of one or more whitespace-delimited
1120 alphanumeric words.  Themes are case-insensitive.  See L<"POLICY
1121 THEMES"> for more information.
1122
1123 C<add_themes> appends to the default themes for this Policy.  The
1124 argument is a string of one or more whitespace-delimited words.
1125 Themes are case-insensitive.  See L<"POLICY THEMES"> for more
1126 information.
1127
1128 The remaining key-value pairs are configuration parameters that will
1129 be passed into the constructor of that Policy.  The constructors for
1130 most Policy modules do not support arguments, and those that do should
1131 have reasonable defaults.  See the documentation on the appropriate
1132 Policy module for more details.
1133
1134 Instead of redefining the severity for a given Policy, you can
1135 completely disable a Policy by prepending a '-' to the name of the
1136 module in your configuration file.  In this manner, the Policy will
1137 never be loaded, regardless of the C<--severity> given on the command
1138 line.
1139
1140 A simple configuration might look like this:
1141
1142     #--------------------------------------------------------------
1143     # I think these are really important, so always load them
1144
1145     [TestingAndDebugging::RequireUseStrict]
1146     severity = 5
1147
1148     [TestingAndDebugging::RequireUseWarnings]
1149     severity = 5
1150
1151     #--------------------------------------------------------------
1152     # I think these are less important, so only load when asked
1153
1154     [Variables::ProhibitPackageVars]
1155     severity = 2
1156
1157     [ControlStructures::ProhibitPostfixControls]
1158     allow = if unless  # My custom configuration
1159     severity = cruel   # Same as "severity = 2"
1160
1161     #--------------------------------------------------------------
1162     # Give these policies a custom theme.  I can activate just
1163     # these policies by saying "perlcritic --theme 'larry || curly'"
1164
1165     [Modules::RequireFilenameMatchesPackage]
1166     add_themes = larry
1167
1168     [TestingAndDebugging::RequireTestLabels]
1169     add_themes = curly moe
1170
1171     #--------------------------------------------------------------
1172     # I do not agree with these at all, so never load them
1173
1174     [-NamingConventions::Capitalization]
1175     [-ValuesAndExpressions::ProhibitMagicNumbers]
1176
1177     #--------------------------------------------------------------
1178     # For all other Policies, I accept the default severity,
1179     # so no additional configuration is required for them.
1180
1181 Note that all policies included with the Perl::Critic distribution
1182 that have integer parameters accept underscores ("_") in their values,
1183 as with Perl numeric literals.  For example,
1184
1185     [ValuesAndExpressions::RequireNumberSeparators]
1186     min_value = 1_000
1187
1188 For additional configuration examples, see the F<perlcriticrc> file
1189 that is included in this F<examples> directory of this distribution.
1190
1191 Damian Conway's own Perl::Critic configuration is also included in
1192 this distribution as F<examples/perlcriticrc-conway>.
1193
1194
1195 =head1 THE POLICIES
1196
1197 A large number of Policy modules are distributed with Perl::Critic.
1198 They are described briefly in the companion document
1199 L<Perl::Critic::PolicySummary|Perl::Critic::PolicySummary> and in more
1200 detail in the individual modules themselves.  Say C<"perlcritic --doc
1201 PATTERN"> to see the perldoc for all Policy modules that match the
1202 regex C<m/PATTERN/ixms>
1203
1204 There are a number of distributions of additional policies on CPAN.
1205 If L<Perl::Critic|Perl::Critic> doesn't contain a policy that you
1206 want, some one may have already written it.  See L<Perl::Critic/"SEE
1207 ALSO"> for a list of some of these distributions.
1208
1209
1210 =head1 POLICY THEMES
1211
1212 Each Policy is defined with one or more "themes".  Themes can be used
1213 to create arbitrary groups of Policies.  They are intended to provide
1214 an alternative mechanism for selecting your preferred set of Policies.
1215 For example, you may wish disable a certain set of Policies when
1216 analyzing test scripts.  Conversely, you may wish to enable only a
1217 specific subset of Policies when analyzing modules.
1218
1219 The Policies that ship with Perl::Critic are have been divided into
1220 the following themes.  This is just our attempt to provide some basic
1221 logical groupings.  You are free to invent new themes that suit your
1222 needs.
1223
1224     THEME             DESCRIPTION
1225     ------------------------------------------------------------------------
1226     core              All policies that ship with Perl::Critic
1227     pbp               Policies that come directly from "Perl Best Practices"
1228     bugs              Policies that that prevent or reveal bugs
1229     maintenance       Policies that affect the long-term health of the code
1230     cosmetic          Policies that only have a superficial effect
1231     complexity        Policies that specificaly relate to code complexity
1232     security          Policies that relate to security issues
1233     tests             Policies that are specific to test scripts
1234
1235 Say C<"perlcritic --list"> to get a listing of all available policies
1236 and the themes that are associated with each one.  You can also change
1237 the theme for any Policy in your F<.perlcriticrc> file.  See the
1238 L<"CONFIGURATION"> section for more information about that.
1239
1240 Using the C<--theme> command-line option, you can create an
1241 arbitrarily complex rule that determines which Policies to apply.
1242 Precedence is the same as regular Perl code, and you can use
1243 parentheses to enforce precedence as well.  Supported operators are:
1244
1245     Operator    Altertative    Example
1246     -----------------------------------------------------------------
1247     &&          and            'pbp && core'
1248     ||          or             'pbp || (bugs && security)'
1249     !           not            'pbp && ! (portability || complexity)'
1250
1251 Theme names are case-insensitive.  If the C<--theme> is set to an
1252 empty string, then it evaluates as true all Policies.
1253
1254
1255 =head1 BENDING THE RULES
1256
1257 Perl::Critic takes a hard-line approach to your code: either you
1258 comply or you don't.  In the real world, it is not always practical
1259 (or even possible) to fully comply with coding standards.  In such
1260 cases, it is wise to show that you are knowingly violating the
1261 standards and that you have a Damn Good Reason (DGR) for doing so.
1262
1263 To help with those situations, you can direct Perl::Critic to ignore
1264 certain lines or blocks of code by using annotations:
1265
1266   require 'LegacyLibaray1.pl';  ## no critic
1267   require 'LegacyLibrary2.pl';  ## no critic
1268
1269   for my $element (@list) {
1270
1271       ## no critic
1272
1273       $foo = "";               #Violates 'ProhibitEmptyQuotes'
1274       $barf = bar() if $foo;   #Violates 'ProhibitPostfixControls'
1275       #Some more evil code...
1276
1277       ## use critic
1278
1279       #Some good code...
1280       do_something($_);
1281   }
1282
1283 The C<"## no critic"> annotations direct Perl::Critic to ignore the
1284 remaining lines of code until the end of the current block, or until a
1285 C<"## use critic"> annotation is found (whichever comes first).  If the
1286 C<"## no critic"> annotation is on the same line as a code statement,
1287 then only that line of code is overlooked.  To direct perlcritic to
1288 ignore the C<"## no critic"> annotations, use the C<--force> option.
1289
1290 A bare C<"## no critic"> annotation disables all the active Policies.  If
1291 you wish to disable only specific Policies, add a list of Policy names
1292 as arguments just as you would for the C<"no strict"> or C<"no
1293 warnings"> pragma.  For example, this would disable the
1294 C<ProhibitEmptyQuotes> and C<ProhibitPostfixControls> policies until
1295 the end of the block or until the next C<"## use critic"> annotation
1296 (whichever comes first):
1297
1298     ## no critic (EmptyQuotes, PostfixControls);
1299
1300     # Now exempt from ValuesAndExpressions::ProhibitEmptyQuotes
1301     $foo = "";
1302
1303     # Now exempt ControlStructures::ProhibitPostfixControls
1304     $barf = bar() if $foo;
1305
1306     # Still subject to ValuesAndExpression::RequireNumberSeparators
1307     $long_int = 10000000000;
1308
1309 Since the Policy names are matched against the C<"## no critic">
1310 arguments as regular expressions, you can abbreviate the Policy names
1311 or disable an entire family of Policies in one shot like this:
1312
1313     ## no critic (NamingConventions)
1314
1315     # Now exempt from NamingConventions::Capitalization
1316     my $camelHumpVar = 'foo';
1317
1318     # Now exempt from NamingConventions::Capitalization
1319     sub camelHumpSub {}
1320
1321 The argument list must be enclosed in parentheses and must contain one
1322 or more comma-separated barewords (i.e. don't use quotes).  The C<"##
1323 no critic"> annotations can be nested, and Policies named by an inner
1324 annotation will be disabled along with those already disabled an outer
1325 annotation.
1326
1327 Some Policies like C<Subroutines::ProhibitExcessComplexity> apply to
1328 an entire block of code.  In those cases, C<"## no critic"> must
1329 appear on the line where the violation is reported.  For example:
1330
1331     sub complicated_function {  ## no critic (ProhibitExcessComplexity)
1332         # Your code here...
1333     }
1334
1335 Some Policies like C<Documentation::RequirePodSections> apply to the
1336 entire document, in which case violations are reported at line 1.  But
1337 if the file requires a shebang line, it is impossible to put C<"## no
1338 critic"> on the first line of the file.  This is a known limitation
1339 and it will be addressed in a future release.  As a workaround, you
1340 can disable the affected policies at the command-line or in your
1341 F<.perlcriticrc> file.  But beware that this will affect the analysis
1342 of B<all> files.
1343
1344 Use this feature wisely.  C<"## no critic"> should be used in the
1345 smallest possible scope, or only on individual lines of code. And you
1346 should always be as specific as possible about which policies you want
1347 to disable (i.e. never use a bare C<"## no critic">).  If Perl::Critic
1348 complains about your code, try and find a compliant solution before
1349 resorting to this feature.
1350
1351
1352 =head1 EDITOR INTEGRATION
1353
1354 For ease-of-use, C<perlcritic> can be integrated with your favorite
1355 text editor.  The output-formatting capabilities of C<perlcritic> are
1356 specifically intended for use with the "grep" or "compile" modes
1357 available in editors like C<emacs> and C<vim>.  In these modes, you
1358 can run an arbitrary command and the editor will parse the output into
1359 an interactive buffer that you can click on and jump to the relevant
1360 line of code.
1361
1362 The Perl::Critic team thanks everyone who has helped integrate Perl-Critic
1363 with their favorite editor.  Your contributions in particular have made
1364 Perl-Critic a convenient and user-friendly tool for Perl developers of all
1365 stripes.  We sincerely appreciate your hard work.
1366
1367
1368 =head2 EMACS
1369
1370 Joshua ben Jore has authored a minor-mode for emacs that allows you to
1371 run perlcritic on the current region or buffer.  You can run it on
1372 demand, or configure it to run automatically when you save the buffer.
1373 The output appears in a hot-linked compiler buffer.  The code and
1374 installation instructions can be found in the F<extras> directory
1375 inside this distribution.
1376
1377
1378 =head2 VIM
1379
1380 Scott Peshak has published F<perlchecker.vim>, which is available at
1381 L<http://www.vim.org/scripts/script.php?script_id=1731>.
1382
1383
1384 =head2 gVIM
1385
1386 Fritz Mehner recently added support for C<perlcritic> to his fantastic
1387 gVIM plugin.  In addition to providing a very Perlish IDE, Fritz's
1388 plugin enables one-click access to C<perlcritic> and many other very
1389 useful utilities.  And all is seamlessly integrated into the editor.
1390 See L<http://lug.fh-swf.de/vim/vim-perl/screenshots-en.html> for
1391 complete details.
1392
1393
1394 =head2 EPIC
1395
1396 EPIC is an open source Perl IDE based on the Eclipse platform.
1397 Features include syntax highlighting, on-the-fly syntax check,
1398 content assist, code completion, perldoc support, source formatting
1399 with L<Perl::Tidy>, code templates, a regular expression editing tool,
1400 and integration with the Perl debugger.  Recent versions of EPIC also
1401 have built-in support for Perl::Critic.  At least one Perl::Critic
1402 contributor swears by EPIC.  Go to L<http://e-p-i-c.sourceforge.net>
1403 for more information about EPIC.
1404
1405 =head2 BBEdit
1406
1407 Josh Clark has produced an excellent Perl-Critic plugin for BBEdit. A
1408 copy is included in this distribution at
1409 F<extras/perl_critic_for_bbedit-1_0.zip>. See
1410 L<http://beta.bigmedium.com/projects/bbedit-perl-critic/index.shtml>
1411 for screenshots and additional installation info.  Apple users
1412 rejoice!
1413
1414
1415 =head2 Komodo
1416
1417 Komodo is a proprietary IDE for Perl and several other dynamic
1418 languages.  Free trial copies of Komodo can be obtained from the
1419 ActiveState website at L<http://www.activestate.com>. For instructions
1420 on integrating F<perlcritic> with Komodo, see
1421 F<extras/KomodoIntegration.pod> in this distribution.
1422
1423
1424 =head1 EXIT STATUS
1425
1426 If C<perlcritic> has any errors itself, exits with status == 1.  If
1427 there are no errors, but C<perlcritic> finds Policy violations in your
1428 source code, exits with status == 2.  If there were no errors and no
1429 violations were found, exits with status == 0.
1430
1431
1432 =head1 THE L<Perl::Critic|Perl::Critic> PHILOSOPHY
1433
1434 =over
1435
1436 Coding standards are deeply personal and highly subjective.  The goal
1437 of Perl::Critic is to help you write code that conforms with a set of
1438 best practices.  Our primary goal is not to dictate what those
1439 practices are, but rather, to implement the practices discovered by
1440 others.  Ultimately, you make the rules -- Perl::Critic is merely a
1441 tool for encouraging consistency.  If there is a policy that you think
1442 is important or that we have overlooked, we would be very grateful for
1443 contributions, or you can simply load your own private set of policies
1444 into Perl::Critic.
1445
1446 =back
1447
1448
1449 =head1 EXTENDING THE CRITIC
1450
1451 The modular design of Perl::Critic is intended to facilitate the
1452 addition of new Policies.  You'll need to have some understanding of
1453 L<PPI|PPI>, but most Policy modules are pretty straightforward and
1454 only require about 20 lines of code, and half of those lines are
1455 simple use statements and simple declarations..  Please see the
1456 L<Perl::Critic::DEVELOPER|Perl::Critic::DEVELOPER> file included in
1457 this distribution for a step-by-step demonstration of how to create
1458 new Policy modules.
1459
1460 If you develop any new Policy modules, feel free to send them to C<<
1461 <thaljef@cpan.org> >> and I'll be happy to put them into the
1462 Perl::Critic distribution.  Or if you would like to work on the
1463 Perl::Critic project directly, check out our repository at
1464 L<http://perlcritic.tigris.org>.  To subscribe to our mailing list,
1465 send a message to C<< <dev-subscribe@perlcritic.tigris.org> >>.
1466
1467 The Perl::Critic team is also available for hire.  If your
1468 organization has its own coding standards, we can create custom
1469 Policies to enforce your local guidelines.  Or if your code base is
1470 prone to a particular defect pattern, we can design Policies that will
1471 help you catch those costly defects B<before> they go into production.
1472 To discuss your needs with the Perl::Critic team, just contact C<<
1473 <thaljef@cpan.org> >>.
1474
1475
1476 =head1 CONTACTING THE DEVELOPMENT TEAM
1477
1478 You are encouraged to subscribe to the mailing list; send a message to
1479 C<< <users-subscribe@perlcritic.tigris.org> >>.  See also
1480 L<the archives|http://perlcritic.tigris.org/servlets/SummarizeList?listName=users>.
1481 You can also contact the author at C<< <thaljef@cpan.org> >>.
1482
1483 At least one member of the development team has started hanging around
1484 in L<irc://irc.perl.org/#perlcritic>.
1485
1486
1487 =head1 SEE ALSO
1488
1489 There are a number of distributions of additional Policies available.
1490 A few are listed here:
1491
1492 L<Perl::Critic::More|Perl::Critic::More>
1493 L<Perl::Critic::Bangs|Perl::Critic::Bangs>
1494 L<Perl::Critic::Lax|Perl::Critic::Lax>
1495 L<Perl::Critic::StricterSubs|Perl::Critic::StricterSubs>
1496 L<Perl::Critic::Swift|Perl::Critic::Swift>
1497
1498 These distributions enable you to use Perl::Critic in your unit tests:
1499
1500 L<Test::Perl::Critic|Test::Perl::Critic>
1501 L<Test::Perl::Critic::Progressive|Test::Perl::Critic::Progressive>
1502
1503 There are also a couple of distributions that will install all the
1504 Perl::Critic related modules known to the development team:
1505
1506 L<Bundle::Perl::Critic|Bundle::Perl::Critic>
1507 L<Task::Perl::Critic|Task::Perl::Critic>
1508
1509
1510 =head1 BUGS
1511
1512 Scrutinizing Perl code is hard for humans, let alone machines.  If you
1513 find any bugs, particularly false-positives or false-negatives from a
1514 Perl::Critic::Policy, please submit them to
1515 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Perl-Critic>.  Thanks.
1516
1517 Most policies will produce false-negatives if they cannot understand a
1518 particular block of code.
1519
1520
1521 =head1 CREDITS
1522
1523 Adam Kennedy - For creating L<PPI|PPI>, the heart and soul of
1524 L<Perl::Critic|Perl::Critic>.
1525
1526 Damian Conway - For writing B<Perl Best Practices>, finally :)
1527
1528 Chris Dolan - For contributing the best features and Policy modules.
1529
1530 Andy Lester - Wise sage and master of all-things-testing.
1531
1532 Elliot Shank - The self-proclaimed quality freak.
1533
1534 Giuseppe Maxia - For all the great ideas and positive encouragement.
1535
1536 and Sharon, my wife - For putting up with my all-night code sessions.
1537
1538
1539 =head1 AUTHOR
1540
1541 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
1542
1543
1544 =head1 COPYRIGHT
1545
1546 Copyright (c) 2005-2008 Jeffrey Ryan Thalhammer.  All rights reserved.
1547
1548 This program is free software; you can redistribute it and/or modify
1549 it under the same terms as Perl itself.  The full text of this license
1550 can be found in the LICENSE file included with this module.
1551
1552 =cut
1553
1554 ##############################################################################
1555 # Local Variables:
1556 #   mode: cperl
1557 #   cperl-indent-level: 4
1558 #   fill-column: 78
1559 #   indent-tabs-mode: nil
1560 #   c-indentation-style: bsd
1561 # End:
1562 # ex: set ts=8 sts=4 sw=4 tw=78 ft=perl expandtab shiftround :