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