NAME

       criticism - Perl pragma to enforce coding standards and best-practices

SYNOPSIS

         use criticism;

         use criticism 'gentle';
         use criticism 'stern';
         use criticism 'harsh';
         use criticism 'cruel';
         use criticism 'brutal';

         use criticism ( -profile => '/foo/bar/perlcriticrc' );
         use criticism ( -severity => 3, -verbose => '%m at %f line %l' );

DESCRIPTION

       This pragma enforces coding standards and promotes best-practices by running your file
       through Perl::Critic before every execution.  In a production system, this usually isn't
       feasible because it adds a lot of overhead at start-up.  If you have a separate
       development environment, you can effectively bypass the "criticism" pragma by not
       installing Perl::Critic in the production environment.  If Perl::Critic can't be loaded,
       then "criticism" just fails silently.

       Alternatively, the "perlcritic" command-line (which is distributed with Perl::Critic) can
       be used to analyze your files on-demand and has some additional configuration features.
       And Test::Perl::Critic provides a nice interface for analyzing files during the build
       process.

       If you'd like to try Perl::Critic without installing anything, there is a web-service
       available at <http://perlcritic.com>.  The web-service does not yet support all the
       configuration features that are available in the native Perl::Critic API, but it should
       give you a good idea of what it does.  You can also invoke the perlcritic web-service from
       the command line by doing an HTTP-post, such as one of these:

         $> POST http://perlcritic.com/perl/critic.pl < MyModule.pm
         $> lwp-request -m POST http://perlcritic.com/perl/critic.pl < MyModule.pm
         $> wget -q -O - --post-file=MyModule.pm http://perlcritic.com/perl/critic.pl

       Please note that the perlcritic web-service is still alpha code.  The URL and interface to
       the service are subject to change.

CONFIGURATION

       If there is exactly one import argument, then it is taken to be a named equivalent to one
       of the numeric severity levels supported by Perl::Critic.  For example, "use criticism
       'gentle';" is equivalent to setting the "-severity => 5", which reports only the most
       dangerous violations.  On the other hand, "use criticism 'brutal';" is like setting the
       "-severity => 1", which reports every violation.  If there are no import arguments, then
       it defaults to 'gentle'.

       If there is more than one import argument, then they will all be passed directly into the
       Perl::Critic constructor.  So you can use whatever arguments are supported by
       Perl::Critic.

       The "criticism" pragma will also obey whatever configurations you have set in your
       .perlcriticrc file.  In particular, setting the "criticism-fatal" option to a true value
       will cause your program to immediately "die" if any Perl::Critic violations are found.
       Otherwise, violations are merely advisory.  This option can be set in the global section
       at the top of your .perlcriticrc file, like this:

         # Top of your .perlcriticrc file...
         criticism-fatal = 1

         # per-policy configurations follow...

       You can also pass "('-criticism-fatal' => 1)" as import arguments, just like any other
       Perl::Critic argument.  See "CONFIGURATION" in Perl::Critic for details on the other
       configuration options.

DIAGNOSTICS

       Usually, the "criticism" pragma fails silently if it cannot load Perl::Critic.  So by not
       installing Perl::Critic in your production environment, you can leave the "criticism"
       pragma in your production source code and it will still compile, but it won't be analyzed
       by Perl::Critic each time it runs.

       However, if you set the "DEBUG" environment variable to a true value or run your program
       under the Perl debugger, you will get a warning when "criticism" fails to load
       Perl::Critic.

NOTES

       The "criticism" pragma applies to the entire file, so it is not affected by scope or
       package boundaries and "use"-ing it multiple times will just cause it to repeatedly
       process the same file.  There isn't a reciprocal "no criticism" pragma.  However,
       Perl::Critic does support a pseudo-pragma that directs it to overlook certain lines or
       blocks of code.  See "BENDING THE RULES" in Perl::Critic for more details.

AUTHOR

       Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

       Copyright (c) 2006-2007 Jeffrey Ryan Thalhammer.  All rights reserved.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.  The full text of this license can be found in the LICENSE file
       included with this module.