1Perl::Critic::Config(3)User Contributed Perl DocumentatioPnerl::Critic::Config(3)
2
6 Perl::Critic::Config - Find and load Perl::Critic user-preferences
7
9 Perl::Critic::Config takes care of finding and processing user-prefer‐
10 ences for Perl::Critic. The Config object defines which Policy modules
11 will be loaded into the Perl::Critic engine and how they should be con‐
12 figured. You should never really need to instantiate
13 Perl::Critic::Config directly because the Perl::Critic constructor will
14 do it for you.
15
17 "new( [ -profile => $FILE, -severity => $N, -theme => $string, -include
18 => \@PATTERNS, -exclude => \@PATTERNS, -singlepolicy => $PATTERN, -top
19 => $N, -only => $B, -force => $B, -verbose => $N ] )"
20 "new()" Returns a reference to a new Perl::Critic::Config object. The
21 default value for all arguments can be defined in your .perl‐
22 criticrc file. See the "CONFIGURATION" section for more infor‐
23 mation about that. All arguments are optional key-value pairs
24 as follows:
25 -profile is a path to a configuration file. If $FILE is not
27 defined, Perl::Critic::Config attempts to find a .perlcriticrc
28 configuration file in the current directory, and then in your
29 home directory. Alternatively, you can set the "PERLCRITIC"
30 environment variable to point to a file in another location.
31 If a configuration file can't be found, or if $FILE is an empty
32 string, then all Policies will be loaded with their default
33 configuration. See "CONFIGURATION" for more information.
34 -severity is the minimum severity level. Only Policy modules
36 that have a severity greater than $N will be loaded into this
37 Config. Severity values are integers ranging from 1 (least
38 severe) to 5 (most severe). The default is 5. For a given
39 "-profile", decreasing the "-severity" will usually result in
40 more Policy violations. Users can redefine the severity level
41 for any Policy in their .perlcriticrc file. See "CONFIGURA‐
42 TION" for more information.
43 -theme is special string that defines a set of Policies based
45 on their respective themes. If "-theme" is given, only poli‐
46 cies that are members of that set will be loaded. See the
47 "POLICY THEMES" section for more information about themes.
48 Unless the "-severity" option is explicitly given, setting
49 "-theme" causes the "-severity" to be set to 1.
50 -include is a reference to a list of string @PATTERNS. Poli‐
52 cies that match at least one "m/$PATTERN/imx" will be loaded
53 into this Config, irrespective of the severity settings. You
54 can use it in conjunction with the "-exclude" option. Note
55 that "-exclude" takes precedence over "-include" when a Policy
56 matches both patterns.
57 -exclude is a reference to a list of string @PATTERNS. Polices
59 that match at least one "m/$PATTERN/imx" will not be loaded
60 into this Config, irrespective of the severity settings. You
61 can use it in conjunction with the "-include" option. Note
62 that "-exclude" takes precedence over "-include" when a Policy
63 matches both patterns.
64 -singlepolicy is a string "PATTERN". Only the policy that
66 matches "m/$PATTERN/imx" will be used. This value overrides
67 the "-severity", "-theme", "-include", "-exclude", and "-only"
68 options.
69 -top is the maximum number of Violations to return when ranked
71 by their severity levels. This must be a positive integer.
72 Violations are still returned in the order that they occur
73 within the file. Unless the "-severity" option is explicitly
74 given, setting "-top" silently causes the "-severity" to be set
75 to 1.
76 -only is a boolean value. If set to a true value, Perl::Critic
78 will only choose from Policies that are mentioned in the user's
79 profile. If set to a false value (which is the default), then
80 Perl::Critic chooses from all the Policies that it finds at
81 your site.
82 -force controls whether Perl::Critic observes the magical ""##
84 no critic"" pseudo-pragmas in your code. If set to a true
85 value, Perl::Critic will analyze all code. If set to a false
86 value (which is the default) Perl::Critic will ignore code that
87 is tagged with these comments. See "BENDING THE RULES" for
88 more information.
89 -verbose can be a positive integer (from 1 to 10), or a literal
91 format specification. See Perl::Critic::Violations for an
92 explanation of format specifications.
93
95 "add_policy( -policy => $policy_name, -params => \%param_hash )"
96 Creates a Policy object and loads it into this Config. If the
97 object cannot be instantiated, it will throw a fatal exception.
98 Otherwise, it returns a reference to this Critic.
99 -policy is the name of a Perl::Critic::Policy subclass module.
101 The 'Perl::Critic::Policy' portion of the name can be omitted
102 for brevity. This argument is required.
103 -params is an optional reference to a hash of Policy parame‐
105 ters. The contents of this hash reference will be passed into
106 to the constructor of the Policy module. See the documentation
107 in the relevant Policy module for a description of the argu‐
108 ments it supports.
109 " policies() "
111 Returns a list containing references to all the Policy objects
112 that have been loaded into this Config. Objects will be in the
113 order that they were loaded.
114 " exclude() "
116 Returns the value of the "-exclude" attribute for this Config.
117 " include() "
119 Returns the value of the "-include" attribute for this Config.
120 " force() "
122 Returns the value of the "-force" attribute for this Config.
123 " only() "
125 Returns the value of the "-only" attribute for this Config.
126 " severity() "
128 Returns the value of the "-severity" attribute for this Config.
129 " singlepolicy() "
131 Returns the value of the "-singlepolicy" attribute for this
132 Config.
133 " theme() "
135 Returns the Perl::Critic::Theme object that was created for
136 this Config.
137 " top() "
139 Returns the value of the "-top" attribute for this Config.
140 " verbose() "
142 Returns the value of the "-verbose" attribute for this Config.
143
145 Perl::Critic::Config has a few static subroutines that are used inter‐
146 nally, but may be useful to you in some way.
147 "site_policy_names()"
149 Returns a list of all the Policy modules that are currently
150 installed in the Perl::Critic:Policy namespace. These will
151 include modules that are distributed with Perl::Critic plus any
152 third-party modules that have been installed.
153
155 Most of the settings for Perl::Critic and each of the Policy modules
156 can be controlled by a configuration file. The default configuration
157 file is called .perlcriticrc. Perl::Critic::Config will look for this
158 file in the current directory first, and then in your home directory.
159 Alternatively, you can set the "PERLCRITIC" environment variable to
160 explicitly point to a different file in another location. If none of
161 these files exist, and the "-profile" option is not given to the con‐
162 structor, then all Policies will be loaded with their default configu‐
163 ration.
164 The format of the configuration file is a series of INI-style blocks
166 that contain key-value pairs separated by '='. Comments should start
167 with '#' and can be placed on a separate line or after the name-value
168 pairs if you desire.
169 Default settings for Perl::Critic itself can be set before the first
171 named block. For example, putting any or all of these at the top of
172 your configuration file will set the default value for the correspond‐
173 ing Perl::Critic constructor argument.
174 severity = 3 #Integer from 1 to 5
176 only = 1 #Zero or One
177 force = 0 #Zero or One
178 verbose = 4 #Integer or format spec
179 top = 50 #A positive integer
180 theme = risky + (pbp * security) - cosmetic #A theme expression
181 include = NamingConventions ClassHierarchies #Space-delimited list
182 exclude = Variables Modules::RequirePackage #Space-delimited list
183 The remainder of the configuration file is a series of blocks like
185 this:
186 [Perl::Critic::Policy::Category::PolicyName]
188 severity = 1
189 set_themes = foo bar
190 add_themes = baz
191 arg1 = value1
192 arg2 = value2
193 "Perl::Critic::Policy::Category::PolicyName" is the full name of a mod‐
195 ule that implements the policy. The Policy modules distributed with
196 Perl::Critic have been grouped into categories according to the table
197 of contents in Damian Conway's book Perl Best Practices. For brevity,
198 you can omit the 'Perl::Critic::Policy' part of the module name.
199 "severity" is the level of importance you wish to assign to the Policy.
201 All Policy modules are defined with a default severity value ranging
202 from 1 (least severe) to 5 (most severe). However, you may disagree
203 with the default severity and choose to give it a higher or lower
204 severity, based on your own coding philosophy.
205 The remaining key-value pairs are configuration parameters that will be
207 passed into the constructor of that Policy. The constructors for most
208 Policy modules do not support arguments, and those that do should have
209 reasonable defaults. See the documentation on the appropriate Policy
210 module for more details.
211 Instead of redefining the severity for a given Policy, you can com‐
213 pletely disable a Policy by prepending a '-' to the name of the module
214 in your configuration file. In this manner, the Policy will never be
215 loaded, regardless of the "-severity" given to the Perl::Critic::Config
216 constructor.
217 A simple configuration might look like this:
219 #--------------------------------------------------------------
221 # I think these are really important, so always load them
222 [TestingAndDebugging::RequireUseStrict]
224 severity = 5
225 [TestingAndDebugging::RequireUseWarnings]
227 severity = 5
228 #--------------------------------------------------------------
230 # I think these are less important, so only load when asked
231 [Variables::ProhibitPackageVars]
233 severity = 2
234 [ControlStructures::ProhibitPostfixControls]
236 allow = if unless #My custom configuration
237 severity = 2
238 #--------------------------------------------------------------
240 # Give these policies a custom theme. I can activate just
241 # these policies by saying (-theme => 'larry + curly')
242 [Modules::RequireFilenameMatchesPackage]
244 add_themes = larry
245 [TestingAndDebugging::RequireTestLables]
247 add_themes = curly moe
248 #--------------------------------------------------------------
250 # I do not agree with these at all, so never load them
251 [-NamingConventions::ProhibitMixedCaseVars]
253 [-NamingConventions::ProhibitMixedCaseSubs]
254 #--------------------------------------------------------------
256 # For all other Policies, I accept the default severity, theme
257 # and other parameters, so no additional configuration is
258 # required for them.
259 For additional configuration examples, see the perlcriticrc file that
261 is included in this t/examples directory of this distribution.
262
264 A large number of Policy modules are distributed with Perl::Critic.
265 They are described briefly in the companion document Perl::Critic::Pol‐
266 icySummary and in more detail in the individual modules themselves.
267
269 Each Policy is defined with one or more "themes". Themes can be used
270 to create arbitrary groups of Policies. They are intended to provide
271 an alternative mechanism for selecting your preferred set of Policies.
272 For example, you may wish disable a certain subset of Policies when
273 analyzing test scripts. Conversely, you may wish to enable only a spe‐
274 cific subset of Policies when analyzing modules.
275 The Policies that ship with Perl::Critic are have been broken into the
277 following themes. This is just our attempt to provide some basic logi‐
278 cal groupings. You are free to invent new themes that suit your needs.
279 THEME DESCRIPTION
281 --------------------------------------------------------------------------
282 core All policies that ship with Perl::Critic
283 pbp Policies that come directly from "Perl Best Practices"
284 bugs Policies that that prevent or reveal bugs
285 maintenance Policies that affect the long-term health of the code
286 cosmetic Policies that only have a superficial effect
287 complexity Policies that specificaly relate to code complexity
288 security Policies that relate to security issues
289 tests Policies that are specific to test scripts
290 Say `perlcritic -list` to get a listing of all available policies and
292 the themes that are associated with each one. You can also change the
293 theme for any Policy in your .perlcriticrc file. See the "CONFIGURA‐
294 TION" section for more information about that.
295 Using the "-theme" option, you can combine theme names with mathemati‐
297 cal and boolean operators to create an arbitrarily complex expression
298 that represents a custom "set" of Policies. The following operators
299 are supported
300 Operator Alternative Meaning
302 ----------------------------------------------------------------------------
303 * and Intersection
304 - not Difference
305 + or Union
306 Operator precedence is the same as that of normal mathematics. You can
308 also use parenthesis to enforce precedence. Here are some examples:
309 Expression Meaning
311 ----------------------------------------------------------------------------
312 pbp * bugs All policies that are "pbp" AND "bugs"
313 pbp and bugs Ditto
314 bugs + cosmetic All policies that are "bugs" OR "cosmetic"
316 bugs or cosmetic Ditto
317 pbp - cosmetic All policies that are "pbp" BUT NOT "cosmetic"
319 pbp not cosmetic Ditto
320 -maintenance All policies that are NOT "maintenance"
322 not maintenance Ditto
323 (pbp - bugs) * complexity All policies that are "pbp" BUT NOT "bugs",
325 AND "complexity"
326 (pbp not bugs) and complexity Ditto
327 Theme names are case-insensitive. If "-theme" is set to an empty
329 string, then it is equivalent to the set of all Policies. A theme name
330 that doesn't exist is equivalent to an empty set. Please See
331 <http://en.wikipedia.org/wiki/Set> for a discussion on set theory.
332
334 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
335
337 Copyright (c) 2005-2007 Jeffrey Ryan Thalhammer. All rights reserved.
338 This program is free software; you can redistribute it and/or modify it
340 under the same terms as Perl itself. The full text of this license can
341 be found in the LICENSE file included with this module.
342perl v5.8.8 2007-03-20 Perl::Critic::Config(3)