Login
cb043d2f47810138e636a1a2c96a0bd5234b0b1a
[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         warn-about-useless-no-critic!
458     );
459 }
460
461 #-----------------------------------------------------------------------------
462
463 sub _colorize_by_severity {
464     my (@violations) = @_;
465     return @violations if _this_is_windows();
466     return @violations if not eval { require Term::ANSIColor };
467
468     my %color_of = (
469         $SEVERITY_HIGHEST => 'bold red',
470         $SEVERITY_HIGH    => 'magenta',
471     );
472     return map { _colorize( "$_", $color_of{$_->severity()} ) } @violations;
473
474 }
475
476 #-----------------------------------------------------------------------------
477
478 sub _colorize {
479     my ($string, $color) = @_;
480     return $string if not defined $color;
481     return  Term::ANSIColor::colored( $string, $color );
482 }
483
484 #-----------------------------------------------------------------------------
485
486 sub _this_is_windows {
487     return 1 if $OSNAME =~ m/MSWin32/xms;
488     return 0;
489 }
490
491 #-----------------------------------------------------------------------------
492
493 sub _at_tty {
494     return -t STDOUT; ## no critic (ProhibitInteractiveTest);
495 }
496
497 #-----------------------------------------------------------------------------
498
499 sub render_policy_listing {
500
501     require Perl::Critic::PolicyListing;
502     require Perl::Critic;
503
504     my %pc_params = (-profile => $EMPTY, -severity => $SEVERITY_LOWEST);
505     my @policies = Perl::Critic->new( %pc_params )->policies();
506     my $listing = Perl::Critic::PolicyListing->new( -policies => \@policies );
507     out $listing;
508     exit 0;
509 }
510
511 #-----------------------------------------------------------------------------
512
513 sub render_theme_listing {
514     require Perl::Critic::ThemeListing;
515     require Perl::Critic;
516
517     my %pc_params = (-profile => $EMPTY, -severity => $SEVERITY_LOWEST);
518     my @policies = Perl::Critic->new( %pc_params )->policies();
519     my $listing = Perl::Critic::ThemeListing->new( -policies => \@policies );
520     out $listing;
521     exit 0;
522 }
523
524 #-----------------------------------------------------------------------------
525
526 sub render_profile_prototype {
527
528     require Perl::Critic::ProfilePrototype;
529     require Perl::Critic;
530
531     my %pc_params = (-profile => $EMPTY, -severity => $SEVERITY_LOWEST);
532     my @policies = Perl::Critic->new( %pc_params )->policies();
533     my $prototype = Perl::Critic::ProfilePrototype->new( -policies => \@policies );
534     out $prototype;
535     exit 0;
536 }
537
538 #-----------------------------------------------------------------------------
539
540 sub policy_docs {
541
542     my (%opts) = @_;
543     my $pattern = delete $opts{-doc};
544
545     require Perl::Critic;
546     $critic = Perl::Critic->new(%opts);
547     set_up_pager($critic->config()->pager());
548
549     require Perl::Critic::PolicyFactory;
550     my @site_policies  = Perl::Critic::PolicyFactory->site_policy_names();
551     my @matching_policies  = grep { $_ =~ m/$pattern/ixms } @site_policies;
552
553     # "-T" means don't send to pager   
554     my @perldoc_output = map {`perldoc -T $_`} @matching_policies;  ## no critic (ProhibitBacktick)
555     out @perldoc_output;
556
557     exit 0;
558 }
559
560 1;
561
562 __END__
563
564 #-----------------------------------------------------------------------------
565
566 =pod
567
568 =for stopwords DGR INI-style vim-fu minibuffer -noprofile API
569 -profileproto -profile-proto ben Jore formatter Peshak pbp Komodo
570 screenshots tty emacs gVIM plugin Perlish templating ActiveState
571
572 =head1 NAME
573
574 C<perlcritic> - Command-line interface to critique Perl source.
575
576
577 =head1 SYNOPSIS
578
579   perlcritic [-12345 | --brutal | --cruel | --harsh | --stern | --gentle]
580              [--severity number | name] [--profile file | --noprofile]
581              [--top [ number ]] [--theme expression] [--include pattern]
582              [--exclude pattern] [{-s | --single-policy} pattern]
583              [--only | --noonly] [--profile-strictness {warn|fatal|quiet}]
584              [--force | --noforce] [--statistics] [--statistics-only]
585              [--count | -C] [--verbose {number | format}]
586              [--color | --nocolor] [--pager pager] [--quiet]
587              {FILE | DIRECTORY | STDIN}
588
589   perlcritic --profile-proto
590
591   perlcritic { --list | --list-themes | --doc pattern [...] }
592
593   perlcritic { --help | --options | --man | --version }
594
595
596 =head1 DESCRIPTION
597
598 C<perlcritic> is a Perl source code analyzer.  It is the executable
599 front-end to the L<Perl::Critic|Perl::Critic> engine, which attempts
600 to identify awkward, hard to read, error-prone, or unconventional
601 constructs in your code.  Most of the rules are based on Damian
602 Conway's book B<Perl Best Practices>.  However, C<perlcritic> is
603 B<not> limited to enforcing PBP, and it will even support rules that
604 contradict Conway.  All rules can easily be configured or disabled to
605 your liking.
606
607 This documentation only covers how to drive this command.  For all
608 other information, including how to persistently configure this
609 command so that you don't have to say so much on the command-line, see
610 the documentation for L<Perl::Critic|Perl::Critic> itself.
611
612
613 =head1 USAGE EXAMPLES
614
615 Before getting into all the gory details, here are some basic usage
616 examples to help get you started.
617
618     # Report only most severe violations (severity = 5)
619     perlcritic YourModule.pm
620
621     # Same as above, but read input from STDIN
622     perlcritic
623
624     # Recursively process all Perl files beneath directory
625     perlcritic /some/directory
626
627     # Report slightly less severe violations too (severity >= 4)
628     perlcritic -4 YourModule.pm
629
630     # Same as above, but using named severity level
631     perlcritic --stern YourModule.pm
632
633     # Report all violations, regardless of severity (severity >= 1)
634     perlcritic -1 YourModule.pm
635
636     # Same as above, but using named severity level
637     perlcritic --brutal YourModule.pm
638
639     # Report only violations of things from "Perl Best Practices"
640     perlcritic --theme pbp YourModule.pm
641
642     # Report top 20 most severe violations (severity >= 1)
643     perlcritic --top YourModule.pm
644
645     # Report additional violations of Policies that match m/variables/xms
646     perlcritic --include variables YourModule.pm
647
648     # Use defaults from somewhere other than ~/.perlcriticrc
649     perlcriticrc --profile project/specific/perlcriticrc YourModule.pm
650
651
652 =head1 ARGUMENTS
653
654 The arguments are paths to the files you wish to analyze.  You may
655 specify multiple files.  If an argument is a directory, C<perlcritic>
656 will analyze all Perl files below the directory.  If no arguments are
657 specified, then input is read from STDIN.
658
659
660 =head1 OPTIONS
661
662 Option names can be abbreviated to uniqueness and can be stated with
663 singe or double dashes, and option values can be separated from the
664 option name by a space or '=' (as with L<Getopt::Long|Getopt::Long>).
665 Option names are also case-sensitive.
666
667 =over
668
669 =item C<--profile FILE>
670
671 Directs C<perlcritic> to use a profile named by FILE rather than
672 looking for the default F<.perlcriticrc> file in the current directory
673 or your home directory.  See L<Perl::Critic/"CONFIGURATION"> for more
674 information.
675
676 =item C<--noprofile>
677
678 Directs C<perlcritic> not to load any configuration file, thus
679 reverting to the default configuration for all Policies.
680
681 =item C<--severity N>
682
683 Directs C<perlcritic> to only apply Policies with a severity greater
684 than C<N>.  Severity values are integers ranging from 1 (least severe)
685 to 5 (most severe).  The default is 5.  For a given C<--profile>,
686 decreasing the C<--severity> will usually produce more violations.
687 You can set the default value for this option in your F<.perlcriticrc>
688 file.  You can also redefine the C<severity> for any Policy in your
689 F<.perlcriticrc> file.  See L<"CONFIGURATION"> for more information.
690
691 =item C<-5 | -4 | -3 | -2 | -1>
692
693 These are numeric shortcuts for setting the C<--severity> option.  For
694 example, C<"-4"> is equivalent to C<"--severity 4">.  If multiple
695 shortcuts are specified, then the most restrictive one wins.  If an
696 explicit C<--severity> option is also given, then all shortcut options
697 are silently ignored.  NOTE: Be careful not to put one of the number
698 severity shortcut options immediately after the C<--top> flag or
699 C<perlcritic> will interpret it as the number of violations to report.
700
701 =item C<--severity NAME>
702
703 If it is difficult for you to remember whether severity "5" is the
704 most or least restrictive level, then you can use one of these named
705 values:
706
707     SEVERITY NAME   ...is equivalent to...   SEVERITY NUMBER
708     --------------------------------------------------------
709     --severity gentle                           --severity 5
710     --severity stern                            --severity 4
711     --severity harsh                            --severity 3
712     --severity cruel                            --severity 2
713     --severity brutal                           --severity 1
714
715 =item C<--gentle | --stern | --harsh | --cruel | --brutal>
716
717 These are named shortcuts for setting the C<--severity> option.  For
718 example, C<"--cruel"> is equivalent to C<"--severity 2">.  If multiple
719 shortcuts are specified, then the most restrictive one wins.  If an
720 explicit C<--severity> option is also given, then all shortcut options
721 are silently ignored.
722
723 =item C<--theme RULE>
724
725 Directs C<perlcritic> to apply only Policies with themes that satisfy
726 the C<RULE>.  Themes are arbitrary names for groups of related
727 policies.  You can combine theme names with boolean operators to
728 create an arbitrarily complex C<RULE>.  For example, the following
729 would apply only Policies that have a 'bugs' AND 'pbp' theme:
730
731     $> perlcritic --theme='bugs && pbp' MyModule.pm
732
733 Unless the C<--severity> option is explicitly given, setting
734 C<--theme> silently causes the C<--severity> to be set to 1.  You can
735 set the default value for this option in your F<.perlcriticrc> file.
736 See L<Perl::Critic/"POLICY THEMES"> for more information about themes.
737
738 =item C<--include PATTERN>
739
740 Directs C<perlcritic> to apply additional Policies that match the
741 regex C</PATTERN/imx>.  Use this option to temporarily override your
742 profile and/or the severity settings at the command-line.  For
743 example:
744
745     perlcritic --include=layout my_file.pl
746
747 This would cause C<perlcritic> to apply all the C<CodeLayout::*>
748 policies even if they have a severity level that is less than the
749 default level of 5, or have been disabled in your F<.perlcriticrc>
750 file.  You can specify multiple C<--include> options and you can use
751 it in conjunction with the C<--exclude> option.  Note that
752 C<--exclude> takes precedence over C<--include> when a Policy matches
753 both patterns.  You can set the default value for this option in your
754 F<.perlcriticrc> file.
755
756 =item C<--exclude PATTERN>
757
758 Directs C<perlcritic> to not apply any Policy that matches the regex
759 C</PATTERN/imx>.  Use this option to temporarily override your profile
760 and/or the severity settings at the command-line.  For example:
761
762     perlcritic --exclude=strict my_file.pl
763
764 This would cause C<perlcritic> to not apply the C<RequireUseStrict>
765 and C<ProhibitNoStrict> Policies even though they have the highest
766 severity level.  You can specify multiple C<--exclude> options and you
767 can use it in conjunction with the C<--include> option.  Note that
768 C<--exclude> takes precedence over C<--include> when a Policy matches
769 both patterns.  You can set the default value for this option in your
770 F<.perlcriticrc> file.
771
772 =item C<--single-policy PATTERN>
773
774 =item C<-s PATTERN>
775
776 Directs C<perlcritic> to apply just one Policy module matching the
777 regex C</PATTERN/ixms>, and exclude all other Policies.  This option
778 has precedence over the C<--severity>, C<--theme>, C<--include>,
779 C<--exclude>, and C<--only> options.  For example:
780
781     perlcritic --single-policy=nowarnings my_file.pl
782
783 This would cause C<perlcritic> to apply just the C<ProhibitNoWarnings>
784 Policy, regardless of the severity level setting.  No other Policies
785 would be applied.
786
787 This is equivalent to what one might intend by...
788
789     perlcritic --exclude=. --include=nowarnings my_file.pl
790
791 ... but this won't work because the C<--exclude> option overrides the
792 C<--include> option.
793
794 The equivalent of this option can be accomplished by creating a custom
795 profile containing only the desired policy and then running...
796
797     perlcritic --profile=customprofile --only my_file.pl
798
799 =item C<--top [ N ]>
800
801 Directs C<perlcritic> to report only the top C<N> Policy violations in
802 each file, ranked by their severity.  If C<N> is not specified, it
803 defaults to 20.  If the C<--severity> option (or one of the shortcuts)
804 is not explicitly given, the C<--top> option implies that the minimum
805 severity level is "1" (i.e. "brutal"). Users can redefine the severity
806 for any Policy in their F<.perlcriticrc> file.  See L<"CONFIGURATION">
807 for more information.  You can set the default value for this option
808 in your F<.perlcriticrc> file.  NOTE: Be careful not to put one of the
809 severity shortcut options immediately after the C<--top> flag or
810 C<perlcritic> will interpret it as the number of violations to report.
811
812 =item C<--force>
813
814 Directs C<perlcritic> to ignore the magical C<"## no critic">
815 pseudo-pragmas in the source code. See L<"BENDING THE RULES"> for more
816 information.  You can set the default value for this option in your
817 F<.perlcriticrc> file.
818
819 =item C<--statistics>
820
821 Causes several statistics about the code being scanned and the
822 violations found to be reported after any other output.
823
824 =item C<--statistics-only>
825
826 Like the C<--statistics> option, but suppresses normal output and only
827 shows the statistics.
828
829 =item C<--verbose N | FORMAT>
830
831 Sets the verbosity level or format for reporting violations.  If given
832 a number (C<N>), C<perlcritic> reports violations using one of the
833 predefined formats described below.  If given a string (C<FORMAT>), it
834 is interpreted to be an actual format specification.  If the
835 C<--verbose> option is not specified, it defaults to either 4 or 5,
836 depending on whether multiple files were given as arguments to
837 C<perlcritic>.  You can set the default value for this option in your
838 F<.perlcriticrc> file.
839
840     Verbosity     Format Specification
841     -----------   -------------------------------------------------------
842      1            "%f:%l:%c:%m\n",
843      2            "%f: (%l:%c) %m\n",
844      3            "%m at %f line %l\n",
845      4            "%m at line %l, column %c.  %e.  (Severity: %s)\n",
846      5            "%f: %m at line %l, column %c.  %e.  (Severity: %s)\n",
847      6            "%m at line %l, near '%r'.  (Severity: %s)\n",
848      7            "%f: %m at line %l near '%r'.  (Severity: %s)\n",
849      8            "[%p] %m at line %l, column %c.  (Severity: %s)\n",
850      9            "[%p] %m at line %l, near '%r'.  (Severity: %s)\n",
851     10            "%m at line %l, column %c.\n  %p (Severity: %s)\n%d\n",
852     11            "%m at line %l, near '%r'.\n  %p (Severity: %s)\n%d\n"
853
854 Formats are a combination of literal and escape characters similar to
855 the way C<sprintf> works.  See L<String::Format|String::Format> for a
856 full explanation of the formatting capabilities.  Valid escape
857 characters are:
858
859     Escape    Meaning
860     -------   ------------------------------------------------------------
861     %c        Column number where the violation occurred
862     %d        Full diagnostic discussion of the violation
863     %e        Explanation of violation or page numbers in PBP
864     %F        Just the name of the file where the violation occurred.
865     %f        Path to the file where the violation occurred.
866     %l        Line number where the violation occurred
867     %m        Brief description of the violation
868     %P        Full name of the Policy module that created the violation
869     %p        Name of the Policy without the Perl::Critic::Policy:: prefix
870     %r        The string of source code that caused the violation
871     %s        The severity level of the violation
872
873 The purpose of these formats is to provide some compatibility with
874 text editors that have an interface for parsing certain kinds of
875 input. See L<"EDITOR INTEGRATION"> for more information about that.
876
877 =item C<--list>
878
879 Displays a condensed listing of all the
880 L<Perl::Critic::Policy|Perl::Critic::Policy> modules that are found on
881 this machine.  For each Policy, the name, default severity and default
882 themes are shown.
883
884 =item C<--list-themes>
885
886 Displays a list of all the themes of the
887 L<Perl::Critic::Policy|Perl::Critic::Policy> modules that are found on
888 this machine.
889
890 =item C<--profile-proto>
891
892 Displays an expanded listing of all the
893 L<Perl::Critic::Policy|Perl::Critic::Policy> modules that are found on
894 this machine.  For each Policy, the name, default severity and default
895 themes are shown, as well as the name of any additional parameters
896 that the Policy supports.  The format is suitable as a prototype for
897 your F<.perlcriticrc> file.
898
899 =item C<--only>
900
901 Directs perlcritic to apply only Policies that are explicitly
902 mentioned in your F<.perlcriticrc> file.  This is useful if you want
903 to use just a small subset of Policies without having to disable all
904 the others.  You can set the default value for this option in your
905 F<.perlcriticrc> file.
906
907 =item C<--profile-strictness {warn|fatal|quiet}>
908
909 Directs perlcritic how to treat certain recoverable problems found in
910 a F<.perlcriticrc> or file specified via the C<--profile> option.
911 Valid values are C<warn> (the default), C<fatal>, and C<quiet>.  For
912 example, perlcritic normally only warns about profiles referring to
913 non-existent Policies, but this option can make this situation fatal.
914 You can set the default value for this option in your F<.perlcriticrc>
915 file.
916
917 =item C<--count>
918
919 =item C<-C>
920
921 Display only the number of violations for each file.  Use this feature
922 to get a quick handle on where a large pile of code might need the
923 most attention.
924
925 =item C<--Safari>
926
927 Report "Perl Best Practice" citations as section numbers from
928 L<http://safari.oreilly.com> instead of page numbers from the actual
929 book.  NOTE: This feature is not implemented yet.
930
931 =item C<--color>
932
933 This option is on when outputting to a tty.  When set, Severity 5 and 4 are
934 colored red and yellow, respectively.  Colorization only happens if
935 L<Term::ANSIColor|Term::ANSIColor> is installed and it only works on
936 non-Windows environments.  Negate this switch to disable color.  You can set
937 the default value for this option in your F<.perlcriticrc> file.
938
939 Can also be specified as C<--colour>.
940
941 =item C<--pager PAGER_COMMAND_STRING>
942
943 If set, perlcritic will pipe it's output to the given PAGER_COMMAND_STRING.
944 You can set the default value for this option in your F<.perlcriticrc> file.
945
946 Setting a pager turns off color by default.  You will have to turn color on
947 explicitly.  If you want color, you'll probably also want to tell your pager
948 to display raw characters.  For C<less> and C<more>, use the -R switch.
949
950 =item C<--doc PATTERN>
951
952 Displays the perldoc for all
953 L<Perl::Critic::Policy|Perl::Critic::Policy> modules that match
954 C<m/PATTERN/ixms>.  Since Policy modules tend to have rather long
955 names, this just provides a more convenient way to say something like:
956 C<"perldoc Perl::Critic::Policy::ValuesAndExpressions::RequireUpperCaseHeredocTerminator">
957 at the command prompt.
958
959 =item C<--quiet>
960
961 Suppress the "source OK" message when no violations are found.
962
963 =item C<--help>
964
965 =item C<-?>
966
967 =item C<-H>
968
969 Displays a brief summary of options and exits.
970
971 =item C<--options>
972
973 Displays the descriptions of the options and exits.  While this output
974 is long, it it nowhere near the length of the output of C<--man>.
975
976 =item C<--man>
977
978 Displays the complete C<perlcritic> manual and exits.
979
980 =item C<--version>
981
982 =item C<-V>
983
984 Displays the version number of C<perlcritic> and exits.
985
986 =back
987
988 =head1 CONFIGURATION
989
990 Most of the settings for Perl::Critic and each of the Policy modules
991 can be controlled by a configuration file.  The default configuration
992 file is called F<.perlcriticrc>.  C<perlcritic> will look for this
993 file in the current directory first, and then in your home directory.
994 Alternatively, you can set the C<PERLCRITIC> environment variable to
995 explicitly point to a different file in another location.  If none of
996 these files exist, and the C<--profile> option is not given on the
997 command-line, then all Policies will be loaded with their default
998 configuration.
999
1000 The format of the configuration file is a series of INI-style blocks
1001 that contain key-value pairs separated by "=". Comments should start
1002 with "#" and can be placed on a separate line or after the name-value
1003 pairs if you desire.
1004
1005 Default settings for perlcritic itself can be set B<before the first
1006 named block.> For example, putting any or all of these at the top of
1007 your F<.perlcriticrc> file will set the default value for the
1008 corresponding command-line argument.
1009
1010     severity  = 3                                     #Integer or named level
1011     only      = 1                                     #Zero or One
1012     force     = 0                                     #Zero or One
1013     verbose   = 4                                     #Integer or format spec
1014     top       = 50                                    #A positive integer
1015     theme     = (pbp + security) * bugs               #A theme expression
1016     include   = NamingConventions ClassHierarchies    #Space-delimited list
1017     exclude   = Variables  Modules::RequirePackage    #Space-delimited list
1018
1019 The remainder of the configuration file is a series of blocks like this:
1020
1021     [Perl::Critic::Policy::Category::PolicyName]
1022     severity = 1
1023     set_themes = foo bar
1024     add_themes = baz
1025     arg1 = value1
1026     arg2 = value2
1027
1028 C<Perl::Critic::Policy::Category::PolicyName> is the full name of a
1029 module that implements the policy.  The Policy modules distributed
1030 with Perl::Critic have been grouped into categories according to the
1031 table of contents in Damian Conway's book B<Perl Best Practices>. For
1032 brevity, you can omit the C<'Perl::Critic::Policy'> part of the module
1033 name.
1034
1035 C<severity> is the level of importance you wish to assign to the
1036 Policy.  All Policy modules are defined with a default severity value
1037 ranging from 1 (least severe) to 5 (most severe).  However, you may
1038 disagree with the default severity and choose to give it a higher or
1039 lower severity, based on your own coding philosophy.  You can set the
1040 C<severity> to an integer from 1 to 5, or use one of the equivalent
1041 names:
1042
1043     SEVERITY NAME ...is equivalent to... SEVERITY NUMBER
1044     ----------------------------------------------------
1045     gentle                                             5
1046     stern                                              4
1047     harsh                                              3
1048     cruel                                              2
1049     brutal                                             1
1050
1051 C<set_themes> sets the theme for the Policy and overrides its default
1052 theme.  The argument is a string of one or more whitespace-delimited
1053 alphanumeric words.  Themes are case-insensitive.  See L<"POLICY
1054 THEMES"> for more information.
1055
1056 C<add_themes> appends to the default themes for this Policy.  The
1057 argument is a string of one or more whitespace-delimited words.
1058 Themes are case-insensitive.  See L<"POLICY THEMES"> for more
1059 information.
1060
1061 The remaining key-value pairs are configuration parameters that will
1062 be passed into the constructor of that Policy.  The constructors for
1063 most Policy modules do not support arguments, and those that do should
1064 have reasonable defaults.  See the documentation on the appropriate
1065 Policy module for more details.
1066
1067 Instead of redefining the severity for a given Policy, you can
1068 completely disable a Policy by prepending a '-' to the name of the
1069 module in your configuration file.  In this manner, the Policy will
1070 never be loaded, regardless of the C<--severity> given on the command
1071 line.
1072
1073 A simple configuration might look like this:
1074
1075     #--------------------------------------------------------------
1076     # I think these are really important, so always load them
1077
1078     [TestingAndDebugging::RequireUseStrict]
1079     severity = 5
1080
1081     [TestingAndDebugging::RequireUseWarnings]
1082     severity = 5
1083
1084     #--------------------------------------------------------------
1085     # I think these are less important, so only load when asked
1086
1087     [Variables::ProhibitPackageVars]
1088     severity = 2
1089
1090     [ControlStructures::ProhibitPostfixControls]
1091     allow = if unless  # My custom configuration
1092     severity = cruel   # Same as "severity = 2"
1093
1094     #--------------------------------------------------------------
1095     # Give these policies a custom theme.  I can activate just
1096     # these policies by saying "perlcritic --theme 'larry || curly'"
1097
1098     [Modules::RequireFilenameMatchesPackage]
1099     add_themes = larry
1100
1101     [TestingAndDebugging::RequireTestLabels]
1102     add_themes = curly moe
1103
1104     #--------------------------------------------------------------
1105     # I do not agree with these at all, so never load them
1106
1107     [-NamingConventions::ProhibitMixedCaseVars]
1108     [-NamingConventions::ProhibitMixedCaseSubs]
1109
1110     #--------------------------------------------------------------
1111     # For all other Policies, I accept the default severity,
1112     # so no additional configuration is required for them.
1113
1114 Note that all policies included with the Perl::Critic distribution
1115 that have integer parameters accept underscores ("_") in their values,
1116 as with Perl numeric literals.  For example,
1117
1118     [ValuesAndExpressions::RequireNumberSeparators]
1119     min_value = 1_000
1120
1121 For additional configuration examples, see the F<perlcriticrc> file
1122 that is included in this F<examples> directory of this distribution.
1123
1124 Damian Conway's own Perl::Critic configuration is also included in
1125 this distribution as F<examples/perlcriticrc-conway>.
1126
1127
1128 =head1 THE POLICIES
1129
1130 A large number of Policy modules are distributed with Perl::Critic.
1131 They are described briefly in the companion document
1132 L<Perl::Critic::PolicySummary|Perl::Critic::PolicySummary> and in more
1133 detail in the individual modules themselves.  Say C<"perlcritic --doc
1134 PATTERN"> to see the perldoc for all Policy modules that match the
1135 regex C<m/PATTERN/ixms>
1136
1137 There are a number of distributions of additional policies on CPAN.
1138 If L<Perl::Critic|Perl::Critic> doesn't contain a policy that you
1139 want, some one may have already written it.  See L<Perl::Critic/"SEE
1140 ALSO"> for a list of some of these distributions.
1141
1142
1143 =head1 POLICY THEMES
1144
1145 Each Policy is defined with one or more "themes".  Themes can be used
1146 to create arbitrary groups of Policies.  They are intended to provide
1147 an alternative mechanism for selecting your preferred set of Policies.
1148 For example, you may wish disable a certain set of Policies when
1149 analyzing test scripts.  Conversely, you may wish to enable only a
1150 specific subset of Policies when analyzing modules.
1151
1152 The Policies that ship with Perl::Critic are have been divided into
1153 the following themes.  This is just our attempt to provide some basic
1154 logical groupings.  You are free to invent new themes that suit your
1155 needs.
1156
1157     THEME             DESCRIPTION
1158     ------------------------------------------------------------------------
1159     core              All policies that ship with Perl::Critic
1160     pbp               Policies that come directly from "Perl Best Practices"
1161     bugs              Policies that that prevent or reveal bugs
1162     maintenance       Policies that affect the long-term health of the code
1163     cosmetic          Policies that only have a superficial effect
1164     complexity        Policies that specificaly relate to code complexity
1165     security          Policies that relate to security issues
1166     tests             Policies that are specific to test scripts
1167
1168 Say C<"perlcritic --list"> to get a listing of all available policies
1169 and the themes that are associated with each one.  You can also change
1170 the theme for any Policy in your F<.perlcriticrc> file.  See the
1171 L<"CONFIGURATION"> section for more information about that.
1172
1173 Using the C<--theme> command-line option, you can create an
1174 arbitrarily complex rule that determines which Policies to apply.
1175 Precedence is the same as regular Perl code, and you can use
1176 parentheses to enforce precedence as well.  Supported operators are:
1177
1178     Operator    Altertative    Example
1179     -----------------------------------------------------------------
1180     &&          and            'pbp && core'
1181     ||          or             'pbp || (bugs && security)'
1182     !           not            'pbp && ! (portability || complexity)'
1183
1184 Theme names are case-insensitive.  If the C<--theme> is set to an
1185 empty string, then it evaluates as true all Policies.
1186
1187
1188 =head1 BENDING THE RULES
1189
1190 Perl::Critic takes a hard-line approach to your code: either you
1191 comply or you don't.  In the real world, it is not always practical
1192 (or even possible) to fully comply with coding standards.  In such
1193 cases, it is wise to show that you are knowingly violating the
1194 standards and that you have a Damn Good Reason (DGR) for doing so.
1195
1196 To help with those situations, you can direct Perl::Critic to ignore
1197 certain lines or blocks of code by using pseudo-pragmas:
1198
1199   require 'LegacyLibaray1.pl';  ## no critic
1200   require 'LegacyLibrary2.pl';  ## no critic
1201
1202   for my $element (@list) {
1203
1204       ## no critic
1205
1206       $foo = "";               #Violates 'ProhibitEmptyQuotes'
1207       $barf = bar() if $foo;   #Violates 'ProhibitPostfixControls'
1208       #Some more evil code...
1209
1210       ## use critic
1211
1212       #Some good code...
1213       do_something($_);
1214   }
1215
1216 The C<"## no critic"> comments direct Perl::Critic to ignore the
1217 remaining lines of code until the end of the current block, or until a
1218 C<"## use critic"> comment is found (whichever comes first).  If the
1219 C<"## no critic"> comment is on the same line as a code statement,
1220 then only that line of code is overlooked.  To direct perlcritic to
1221 ignore the C<"## no critic"> comments, use the C<--force> option.
1222
1223 A bare C<"## no critic"> comment disables all the active Policies.  If
1224 you wish to disable only specific Policies, add a list of Policy names
1225 as arguments just as you would for the C<"no strict"> or C<"no
1226 warnings"> pragma.  For example, this would disable the
1227 C<ProhibitEmptyQuotes> and C<ProhibitPostfixControls> policies until
1228 the end of the block or until the next C<"## use critic"> comment
1229 (whichever comes first):
1230
1231     ## no critic (EmptyQuotes, PostfixControls);
1232
1233     # Now exempt from ValuesAndExpressions::ProhibitEmptyQuotes
1234     $foo = "";
1235
1236     # Now exempt ControlStructures::ProhibitPostfixControls
1237     $barf = bar() if $foo;
1238
1239     # Still subject to ValuesAndExpression::RequireNumberSeparators
1240     $long_int = 10000000000;
1241
1242 Since the Policy names are matched against the C<"## no critic">
1243 arguments as regular expressions, you can abbreviate the Policy names
1244 or disable an entire family of Policies in one shot like this:
1245
1246     ## no critic (NamingConventions)
1247
1248     # Now exempt from NamingConventions::ProhibitMixedCaseVars
1249     my $camelHumpVar = 'foo';
1250
1251     # Now exempt from NamingConventions::ProhibitMixedCaseSubs
1252     sub camelHumpSub {}
1253
1254 The argument list must be enclosed in parentheses and must contain one
1255 or more comma-separated barewords (i.e. don't use quotes).  The C<"##
1256 no critic"> pragmas can be nested, and Policies named by an inner
1257 pragma will be disabled along with those already disabled an outer
1258 pragma.
1259
1260 Some Policies like C<Subroutines::ProhibitExcessComplexity> apply to
1261 an entire block of code.  In those cases, C<"## no critic"> must
1262 appear on the line where the violation is reported.  For example:
1263
1264     sub complicated_function {  ## no critic (ProhibitExcessComplexity)
1265         # Your code here...
1266     }
1267
1268 Some Policies like C<Documentation::RequirePodSections> apply to the
1269 entire document, in which case violations are reported at line 1.  But
1270 if the file requires a shebang line, it is impossible to put C<"## no
1271 critic"> on the first line of the file.  This is a known limitation
1272 and it will be addressed in a future release.  As a workaround, you
1273 can disable the affected policies at the command-line or in your
1274 F<.perlcriticrc> file.  But beware that this will affect the analysis
1275 of B<all> files.
1276
1277 Use this feature wisely.  C<"## no critic"> should be used in the
1278 smallest possible scope, or only on individual lines of code. And you
1279 should always be as specific as possible about which policies you want
1280 to disable (i.e. never use a bare C<"## no critic">).  If Perl::Critic
1281 complains about your code, try and find a compliant solution before
1282 resorting to this feature.
1283
1284
1285 =head1 EDITOR INTEGRATION
1286
1287 For ease-of-use, C<perlcritic> can be integrated with your favorite
1288 text editor.  The output-formatting capabilities of C<perlcritic> are
1289 specifically intended for use with the "grep" or "compile" modes
1290 available in editors like C<emacs> and C<vim>.  In these modes, you
1291 can run an arbitrary command and the editor will parse the output into
1292 an interactive buffer that you can click on and jump to the relevant
1293 line of code.
1294
1295 The Perl::Critic team thanks everyone who has helped integrate Perl-Critic
1296 with their favorite editor.  Your contributions in particular have made
1297 Perl-Critic a convenient and user-friendly tool for Perl developers of all
1298 stripes.  We sincerely appreciate your hard work.
1299
1300
1301 =head2 EMACS
1302
1303 Joshua ben Jore has authored a minor-mode for emacs that allows you to
1304 run perlcritic on the current region or buffer.  You can run it on
1305 demand, or configure it to run automatically when you save the buffer.
1306 The output appears in a hot-linked compiler buffer.  The code and
1307 installation instructions can be found in the F<extras> directory
1308 inside this distribution.
1309
1310
1311 =head2 VIM
1312
1313 Scott Peshak has published F<perlchecker.vim>, which is available at
1314 L<http://www.vim.org/scripts/script.php?script_id=1731>.
1315
1316
1317 =head2 gVIM
1318
1319 Fritz Mehner recently added support for C<perlcritic> to his fantastic
1320 gVIM plugin.  In addition to providing a very Perlish IDE, Fritz's
1321 plugin enables one-click access to C<perlcritic> and many other very
1322 useful utilities.  And all is seamlessly integrated into the editor.
1323 See L<http://lug.fh-swf.de/vim/vim-perl/screenshots-en.html> for
1324 complete details.
1325
1326
1327 =head2 EPIC
1328
1329 EPIC is an open source Perl IDE based on the Eclipse platform.
1330 Features include syntax highlighting, on-the-fly syntax check,
1331 content assist, code completion, perldoc support, source formatting 
1332 with L<Perl::Tidy>, code templates, a regular expression editing tool, 
1333 and integration with the Perl debugger.  Recent versions of EPIC also 
1334 have built-in support for Perl::Critic.  At least one Perl::Critic
1335 contributor swears by EPIC.  Go to L<http://e-p-i-c.sourceforge.net> 
1336 for more information about EPIC.
1337
1338 =head2 BBEdit
1339
1340 Josh Clark has produced an excellent Perl-Critic plugin for BBEdit. A
1341 copy is included in this distribution at
1342 F<extras/perl_critic_for_bbedit-1_0.zip>. See
1343 L<http://beta.bigmedium.com/projects/bbedit-perl-critic/index.shtml>
1344 for screenshots and additional installation info.  Apple users
1345 rejoice!
1346
1347
1348 =head2 Komodo
1349
1350 Komodo is a proprietary IDE for Perl and several other dynamic
1351 languages.  Free trial copies of Komodo can be obtained from the
1352 ActiveState website at L<http://www.activestate.com>. For instructions
1353 on integrating F<perlcritic> with Komodo, see
1354 F<extras/KomodoIntegration.pod> in this distribution.
1355
1356
1357 =head1 EXIT STATUS
1358
1359 If C<perlcritic> has any errors itself, exits with status == 1.  If
1360 there are no errors, but C<perlcritic> finds Policy violations in your
1361 source code, exits with status == 2.  If there were no errors and no
1362 violations were found, exits with status == 0.
1363
1364
1365 =head1 THE L<Perl::Critic|Perl::Critic> PHILOSOPHY
1366
1367 =over
1368
1369 Coding standards are deeply personal and highly subjective.  The goal
1370 of Perl::Critic is to help you write code that conforms with a set of
1371 best practices.  Our primary goal is not to dictate what those
1372 practices are, but rather, to implement the practices discovered by
1373 others.  Ultimately, you make the rules -- Perl::Critic is merely a
1374 tool for encouraging consistency.  If there is a policy that you think
1375 is important or that we have overlooked, we would be very grateful for
1376 contributions, or you can simply load your own private set of policies
1377 into Perl::Critic.
1378
1379 =back
1380
1381
1382 =head1 EXTENDING THE CRITIC
1383
1384 The modular design of Perl::Critic is intended to facilitate the
1385 addition of new Policies.  You'll need to have some understanding of
1386 L<PPI|PPI>, but most Policy modules are pretty straightforward and
1387 only require about 20 lines of code, and half of those lines are
1388 simple use statements and simple declarations..  Please see the
1389 L<Perl::Critic::DEVELOPER|Perl::Critic::DEVELOPER> file included in
1390 this distribution for a step-by-step demonstration of how to create
1391 new Policy modules.
1392
1393 If you develop any new Policy modules, feel free to send them to C<<
1394 <thaljef@cpan.org> >> and I'll be happy to put them into the
1395 Perl::Critic distribution.  Or if you would like to work on the
1396 Perl::Critic project directly, check out our repository at
1397 L<http://perlcritic.tigris.org>.  To subscribe to our mailing list,
1398 send a message to C<< <dev-subscribe@perlcritic.tigris.org> >>.
1399
1400 The Perl::Critic team is also available for hire.  If your
1401 organization has its own coding standards, we can create custom
1402 Policies to enforce your local guidelines.  Or if your code base is
1403 prone to a particular defect pattern, we can design Policies that will
1404 help you catch those costly defects B<before> they go into production.
1405 To discuss your needs with the Perl::Critic team, just contact C<<
1406 <thaljef@cpan.org> >>.
1407
1408
1409 =head1 CONTACTING THE DEVELOPMENT TEAM
1410
1411 You are encouraged to subscribe to the mailing list; send a message to
1412 C<< <users-subscribe@perlcritic.tigris.org> >>.  See also
1413 L<the archives|http://perlcritic.tigris.org/servlets/SummarizeList?listName=users>.
1414 You can also contact the author at C<< <thaljef@cpan.org> >>.
1415
1416 At least one member of the development team has started hanging around
1417 in L<irc://irc.perl.org/#perlcritic>.
1418
1419
1420 =head1 SEE ALSO
1421
1422 There are a number of distributions of additional Policies available.
1423 A few are listed here:
1424
1425 L<Perl::Critic::More|Perl::Critic::More>
1426 L<Perl::Critic::Bangs|Perl::Critic::Bangs>
1427 L<Perl::Critic::Lax|Perl::Critic::Lax>
1428 L<Perl::Critic::StricterSubs|Perl::Critic::StricterSubs>
1429 L<Perl::Critic::Swift|Perl::Critic::Swift>
1430
1431 These distributions enable you to use Perl::Critic in your unit tests:
1432
1433 L<Test::Perl::Critic|Test::Perl::Critic>
1434 L<Test::Perl::Critic::Progressive|Test::Perl::Critic::Progressive>
1435
1436 There are also a couple of distributions that will install all the
1437 Perl::Critic related modules known to the development team:
1438
1439 L<Bundle::Perl::Critic|Bundle::Perl::Critic>
1440 L<Task::Perl::Critic|Task::Perl::Critic>
1441
1442
1443 =head1 BUGS
1444
1445 Scrutinizing Perl code is hard for humans, let alone machines.  If you
1446 find any bugs, particularly false-positives or false-negatives from a
1447 Perl::Critic::Policy, please submit them to
1448 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Perl-Critic>.  Thanks.
1449
1450 Most policies will produce false-negatives if they cannot understand a
1451 particular block of code.
1452
1453
1454 =head1 CREDITS
1455
1456 Adam Kennedy - For creating L<PPI|PPI>, the heart and soul of
1457 L<Perl::Critic|Perl::Critic>.
1458
1459 Damian Conway - For writing B<Perl Best Practices>, finally :)
1460
1461 Chris Dolan - For contributing the best features and Policy modules.
1462
1463 Andy Lester - Wise sage and master of all-things-testing.
1464
1465 Elliot Shank - The self-proclaimed quality freak.
1466
1467 Giuseppe Maxia - For all the great ideas and positive encouragement.
1468
1469 and Sharon, my wife - For putting up with my all-night code sessions.
1470
1471
1472 =head1 AUTHOR
1473
1474 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
1475
1476
1477 =head1 COPYRIGHT
1478
1479 Copyright (c) 2005-2008 Jeffrey Ryan Thalhammer.  All rights reserved.
1480
1481 This program is free software; you can redistribute it and/or modify
1482 it under the same terms as Perl itself.  The full text of this license
1483 can be found in the LICENSE file included with this module.
1484
1485 =cut
1486
1487 ##############################################################################
1488 # Local Variables:
1489 #   mode: cperl
1490 #   cperl-indent-level: 4
1491 #   fill-column: 78
1492 #   indent-tabs-mode: nil
1493 #   c-indentation-style: bsd
1494 # End:
1495 # ex: set ts=8 sts=4 sw=4 tw=78 ft=perl expandtab shiftround :