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