1Perl::Critic::Config(3pUms)er Contributed Perl DocumentatPieornl::Critic::Config(3pm)
2
6 Perl::Critic::Config - The final derived Perl::Critic configuration,
7 combined from any profile file and command-line parameters.
8
10 Perl::Critic::Config takes care of finding and processing user-
11 preferences for Perl::Critic. The Config object defines which Policy
12 modules will be loaded into the Perl::Critic engine and how they should
13 be configured. You should never really need to instantiate
14 Perl::Critic::Config directly because the Perl::Critic constructor will
15 do it for you.
16
18 This is considered to be a non-public class. Its interface is subject
19 to change without notice.
20
22 new(...)
23 Not properly documented because you shouldn't be using this.
24
26 "add_policy( -policy => $policy_name, -params => \%param_hash )"
27 Creates a Policy object and loads it into this Config. If the
28 object cannot be instantiated, it will throw a fatal exception.
29 Otherwise, it returns a reference to this Critic.
30 -policy is the name of a Perl::Critic::Policy subclass module. The
32 'Perl::Critic::Policy' portion of the name can be omitted for
33 brevity. This argument is required.
34 -params is an optional reference to a hash of Policy parameters.
36 The contents of this hash reference will be passed into to the
37 constructor of the Policy module. See the documentation in the
38 relevant Policy module for a description of the arguments it
39 supports.
40 all_policies_enabled_or_not()
42 Returns a list containing references to all the Policy objects that
43 have been seen. Note that the state of these objects is not
44 trustworthy. In particular, it is likely that some of them are not
45 prepared to examine any documents.
46 policies()
48 Returns a list containing references to all the Policy objects that
49 have been enabled and loaded into this Config.
50 exclude()
52 Returns the value of the "-exclude" attribute for this Config.
53 include()
55 Returns the value of the "-include" attribute for this Config.
56 force()
58 Returns the value of the "-force" attribute for this Config.
59 only()
61 Returns the value of the "-only" attribute for this Config.
62 profile_strictness()
64 Returns the value of the "-profile-strictness" attribute for this
65 Config.
66 severity()
68 Returns the value of the "-severity" attribute for this Config.
69 single_policy()
71 Returns the value of the "-single-policy" attribute for this
72 Config.
73 theme()
75 Returns the Perl::Critic::Theme object that was created for this
76 Config.
77 top()
79 Returns the value of the "-top" attribute for this Config.
80 verbose()
82 Returns the value of the "-verbose" attribute for this Config.
83 color()
85 Returns the value of the "-color" attribute for this Config.
86 pager()
88 Returns the value of the "-pager" attribute for this Config.
89 unsafe_allowed()
91 Returns the value of the "-allow-unsafe" attribute for this Config.
92 criticism_fatal()
94 Returns the value of the "-criticism-fatal" attribute for this
95 Config.
96 color_severity_highest()
98 Returns the value of the "-color-severity-highest" attribute for
99 this Config.
100 color_severity_high()
102 Returns the value of the "-color-severity-high" attribute for this
103 Config.
104 color_severity_medium()
106 Returns the value of the "-color-severity-medium" attribute for
107 this Config.
108 color_severity_low()
110 Returns the value of the "-color-severity-low" attribute for this
111 Config.
112 color_severity_lowest()
114 Returns the value of the "-color-severity-lowest" attribute for
115 this Config.
116 program_extensions()
118 Returns the value of the "-program_extensions" attribute for this
119 Config. This is an array of the file name extensions that
120 represent program files.
121 program_extensions_as_regexes()
123 Returns the value of the "-program_extensions" attribute for this
124 Config, as an array of case-sensitive regexes matching the ends of
125 the file names that represent program files.
126
128 Perl::Critic::Config has a few static subroutines that are used
129 internally, but may be useful to you in some way.
130 site_policy_names()
132 Returns a list of all the Policy modules that are currently
133 installed in the Perl::Critic:Policy namespace. These will include
134 modules that are distributed with Perl::Critic plus any third-party
135 modules that have been installed.
136
138 Most of the settings for Perl::Critic and each of the Policy modules
139 can be controlled by a configuration file. The default configuration
140 file is called .perlcriticrc. Perl::Critic::Config will look for this
141 file in the current directory first, and then in your home directory.
142 Alternatively, you can set the "PERLCRITIC" environment variable to
143 explicitly point to a different file in another location. If none of
144 these files exist, and the "-profile" option is not given to the
145 constructor, then all Policies will be loaded with their default
146 configuration.
147 The format of the configuration file is a series of INI-style blocks
149 that contain key-value pairs separated by '='. Comments should start
150 with '#' and can be placed on a separate line or after the name-value
151 pairs if you desire.
152 Default settings for Perl::Critic itself can be set before the first
154 named block. For example, putting any or all of these at the top of
155 your configuration file will set the default value for the
156 corresponding Perl::Critic constructor argument.
157 severity = 3 #Integer from 1 to 5
159 only = 1 #Zero or One
160 force = 0 #Zero or One
161 verbose = 4 #Integer or format spec
162 top = 50 #A positive integer
163 theme = risky + (pbp * security) - cosmetic #A theme expression
164 include = NamingConventions ClassHierarchies #Space-delimited list
165 exclude = Variables Modules::RequirePackage #Space-delimited list
166 color = 1 #Zero or One
167 allow_unsafe = 1 #Zero or One
168 color-severity-highest = bold red #Term::ANSIColor
169 color-severity-high = magenta #Term::ANSIColor
170 color-severity-medium = #no coloring
171 color-severity-low = #no coloring
172 color-severity-lowest = #no coloring
173 program-extensions = #Space-delimited list
174 The remainder of the configuration file is a series of blocks like
176 this:
177 [Perl::Critic::Policy::Category::PolicyName]
179 severity = 1
180 set_themes = foo bar
181 add_themes = baz
182 arg1 = value1
183 arg2 = value2
184 "Perl::Critic::Policy::Category::PolicyName" is the full name of a
186 module that implements the policy. The Policy modules distributed with
187 Perl::Critic have been grouped into categories according to the table
188 of contents in Damian Conway's book Perl Best Practices. For brevity,
189 you can omit the 'Perl::Critic::Policy' part of the module name.
190 "severity" is the level of importance you wish to assign to the Policy.
192 All Policy modules are defined with a default severity value ranging
193 from 1 (least severe) to 5 (most severe). However, you may disagree
194 with the default severity and choose to give it a higher or lower
195 severity, based on your own coding philosophy.
196 The remaining key-value pairs are configuration parameters that will be
198 passed into the constructor of that Policy. The constructors for most
199 Policy modules do not support arguments, and those that do should have
200 reasonable defaults. See the documentation on the appropriate Policy
201 module for more details.
202 Instead of redefining the severity for a given Policy, you can
204 completely disable a Policy by prepending a '-' to the name of the
205 module in your configuration file. In this manner, the Policy will
206 never be loaded, regardless of the "-severity" given to the
207 Perl::Critic::Config constructor.
208 A simple configuration might look like this:
210 #--------------------------------------------------------------
212 # I think these are really important, so always load them
213 [TestingAndDebugging::RequireUseStrict]
215 severity = 5
216 [TestingAndDebugging::RequireUseWarnings]
218 severity = 5
219 #--------------------------------------------------------------
221 # I think these are less important, so only load when asked
222 [Variables::ProhibitPackageVars]
224 severity = 2
225 [ControlStructures::ProhibitPostfixControls]
227 allow = if unless #My custom configuration
228 severity = 2
229 #--------------------------------------------------------------
231 # Give these policies a custom theme. I can activate just
232 # these policies by saying (-theme => 'larry + curly')
233 [Modules::RequireFilenameMatchesPackage]
235 add_themes = larry
236 [TestingAndDebugging::RequireTestLabels]
238 add_themes = curly moe
239 #--------------------------------------------------------------
241 # I do not agree with these at all, so never load them
242 [-NamingConventions::Capitalization]
244 [-ValuesAndExpressions::ProhibitMagicNumbers]
245 #--------------------------------------------------------------
247 # For all other Policies, I accept the default severity, theme
248 # and other parameters, so no additional configuration is
249 # required for them.
250 For additional configuration examples, see the perlcriticrc file that
252 is included in this t/examples directory of this distribution.
253
255 A large number of Policy modules are distributed with Perl::Critic.
256 They are described briefly in the companion document
257 Perl::Critic::PolicySummary and in more detail in the individual
258 modules themselves.
259
261 Each Policy is defined with one or more "themes". Themes can be used
262 to create arbitrary groups of Policies. They are intended to provide
263 an alternative mechanism for selecting your preferred set of Policies.
264 For example, you may wish disable a certain subset of Policies when
265 analyzing test programs. Conversely, you may wish to enable only a
266 specific subset of Policies when analyzing modules.
267 The Policies that ship with Perl::Critic are have been broken into the
269 following themes. This is just our attempt to provide some basic
270 logical groupings. You are free to invent new themes that suit your
271 needs.
272 THEME DESCRIPTION
274 --------------------------------------------------------------------------
275 core All policies that ship with Perl::Critic
276 pbp Policies that come directly from "Perl Best Practices"
277 bugs Policies that prevent or reveal bugs
278 maintenance Policies that affect the long-term health of the code
279 cosmetic Policies that only have a superficial effect
280 complexity Policies that specifically relate to code complexity
281 security Policies that relate to security issues
282 tests Policies that are specific to test programs
283 Say `perlcritic -list` to get a listing of all available policies and
285 the themes that are associated with each one. You can also change the
286 theme for any Policy in your .perlcriticrc file. See the
287 "CONFIGURATION" section for more information about that.
288 Using the "-theme" option, you can combine theme names with
290 mathematical and boolean operators to create an arbitrarily complex
291 expression that represents a custom "set" of Policies. The following
292 operators are supported
293 Operator Alternative Meaning
295 ----------------------------------------------------------------------------
296 * and Intersection
297 - not Difference
298 + or Union
299 Operator precedence is the same as that of normal mathematics. You can
301 also use parenthesis to enforce precedence. Here are some examples:
302 Expression Meaning
304 ----------------------------------------------------------------------------
305 pbp * bugs All policies that are "pbp" AND "bugs"
306 pbp and bugs Ditto
307 bugs + cosmetic All policies that are "bugs" OR "cosmetic"
309 bugs or cosmetic Ditto
310 pbp - cosmetic All policies that are "pbp" BUT NOT "cosmetic"
312 pbp not cosmetic Ditto
313 -maintenance All policies that are NOT "maintenance"
315 not maintenance Ditto
316 (pbp - bugs) * complexity All policies that are "pbp" BUT NOT "bugs",
318 AND "complexity"
319 (pbp not bugs) and complexity Ditto
320 Theme names are case-insensitive. If "-theme" is set to an empty
322 string, then it is equivalent to the set of all Policies. A theme name
323 that doesn't exist is equivalent to an empty set. Please See
324 <http://en.wikipedia.org/wiki/Set> for a discussion on set theory.
325
327 Perl::Critic::OptionsProcessor, Perl::Critic::UserProfile
328
330 Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
331
333 Copyright (c) 2005-2023 Imaginative Software Systems
334 This program is free software; you can redistribute it and/or modify it
336 under the same terms as Perl itself. The full text of this license can
337 be found in the LICENSE file included with this module.
338perl v5.38.0 2023-09-25 Perl::Critic::Config(3pm)