1criticism(3)          User Contributed Perl Documentation         criticism(3)
2
3
4

NAME

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

SYNOPSIS

9         use criticism;
10
11         use criticism 'gentle';
12         use criticism 'stern';
13         use criticism 'harsh';
14         use criticism 'cruel';
15         use criticism 'brutal';
16
17         use criticism ( -profile => '/foo/bar/perlcriticrc' );
18         use criticism ( -severity => 3, -verbose => '%m at %f line %l' );
19

DESCRIPTION

21       This pragma enforces coding standards and promotes best-practices by
22       running your file through Perl::Critic before every execution.  In a
23       production system, this usually isn't feasible because it adds a lot of
24       overhead at start-up.  If you have a separate development environment,
25       you can effectively bypass the "criticism" pragma by not installing
26       Perl::Critic in the production environment.  If Perl::Critic can't be
27       loaded, then "criticism" just fails silently.
28
29       Alternatively, the "perlcritic" command-line (which is distributed with
30       Perl::Critic) can be used to analyze your files on-demand and has some
31       additional configuration features.  And Test::Perl::Critic provides a
32       nice interface for analyzing files during the build process.
33
34       If you'd like to try Perl::Critic without installing anything, there is
35       a web-service available at <http://perlcritic.com>.  The web-service
36       does not yet support all the configuration features that are available
37       in the native Perl::Critic API, but it should give you a good idea of
38       what it does.  You can also invoke the perlcritic web-service from the
39       command line by doing an HTTP-post, such as one of these:
40
41         $> POST http://perlcritic.com/perl/critic.pl < MyModule.pm
42         $> lwp-request -m POST http://perlcritic.com/perl/critic.pl < MyModule.pm
43         $> wget -q -O - --post-file=MyModule.pm http://perlcritic.com/perl/critic.pl
44
45       Please note that the perlcritic web-service is still alpha code.  The
46       URL and interface to the service are subject to change.
47

CONFIGURATION

49       If there is exactly one import argument, then it is taken to be a named
50       equivalent to one of the numeric severity levels supported by
51       Perl::Critic.  For example, "use criticism 'gentle';" is equivalent to
52       setting the "-severity => 5", which reports only the most dangerous
53       violations.  On the other hand, "use criticism 'brutal';" is like
54       setting the "-severity => 1", which reports every violation.  If there
55       are no import arguments, then it defaults to 'gentle'.
56
57       If there is more than one import argument, then they will all be passed
58       directly into the Perl::Critic constructor.  So you can use whatever
59       arguments are supported by Perl::Critic.
60
61       The "criticism" pragma will also obey whatever configurations you have
62       set in your .perlcriticrc file.  In particular, setting the
63       "criticism-fatal" option to a true value will cause your program to
64       immediately "die" if any Perl::Critic violations are found.  Otherwise,
65       violations are merely advisory.  This option can be set in the global
66       section at the top of your .perlcriticrc file, like this:
67
68         # Top of your .perlcriticrc file...
69         criticism-fatal = 1
70
71         # per-policy configurations follow...
72
73       You can also pass "('-criticism-fatal' => 1)" as import arguments, just
74       like any other Perl::Critic argument.  See "CONFIGURATION" in
75       Perl::Critic for details on the other configuration options.
76

DIAGNOSTICS

78       Usually, the "criticism" pragma fails silently if it cannot load
79       Perl::Critic.  So by not installing Perl::Critic in your production
80       environment, you can leave the "criticism" pragma in your production
81       source code and it will still compile, but it won't be analyzed by
82       Perl::Critic each time it runs.
83
84       However, if you set the "DEBUG" environment variable to a true value or
85       run your program under the Perl debugger, you will get a warning when
86       "criticism" fails to load Perl::Critic.
87

NOTES

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

AUTHOR

97       Jeffrey Ryan Thalhammer <thaljef@cpan.org>
98
100       Copyright (c) 2006-2007 Jeffrey Ryan Thalhammer.  All rights reserved.
101
102       This program is free software; you can redistribute it and/or modify it
103       under the same terms as Perl itself.  The full text of this license can
104       be found in the LICENSE file included with this module.
105
106
107
108perl v5.38.0                      2023-07-21                      criticism(3)
Impressum