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