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