1Perl::Critic::Config(3pUms)er Contributed Perl DocumentatPieornl::Critic::Config(3pm)
2
3
4

NAME

6       Perl::Critic::Config - The final derived Perl::Critic configuration,
7       combined from any profile file and command-line parameters.
8

DESCRIPTION

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

INTERFACE SUPPORT

18       This is considered to be a non-public class.  Its interface is subject
19       to change without notice.
20

CONSTRUCTOR

22       new(...)
23           Not properly documented because you shouldn't be using this.
24

METHODS

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
31           -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
35           -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
41        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
47        policies()
48           Returns a list containing references to all the Policy objects that
49           have been enabled and loaded into this Config.
50
51        exclude()
52           Returns the value of the "-exclude" attribute for this Config.
53
54        include()
55           Returns the value of the "-include" attribute for this Config.
56
57        force()
58           Returns the value of the "-force" attribute for this Config.
59
60        only()
61           Returns the value of the "-only" attribute for this Config.
62
63        profile_strictness()
64           Returns the value of the "-profile-strictness" attribute for this
65           Config.
66
67        severity()
68           Returns the value of the "-severity" attribute for this Config.
69
70        single_policy()
71           Returns the value of the "-single-policy" attribute for this
72           Config.
73
74        theme()
75           Returns the Perl::Critic::Theme object that was created for this
76           Config.
77
78        top()
79           Returns the value of the "-top" attribute for this Config.
80
81        verbose()
82           Returns the value of the "-verbose" attribute for this Config.
83
84        color()
85           Returns the value of the "-color" attribute for this Config.
86
87        pager()
88           Returns the value of the "-pager" attribute for this Config.
89
90        unsafe_allowed()
91           Returns the value of the "-allow-unsafe" attribute for this Config.
92
93        criticism_fatal()
94           Returns the value of the "-criticism-fatal" attribute for this
95           Config.
96
97        color_severity_highest()
98           Returns the value of the "-color-severity-highest" attribute for
99           this Config.
100
101        color_severity_high()
102           Returns the value of the "-color-severity-high" attribute for this
103           Config.
104
105        color_severity_medium()
106           Returns the value of the "-color-severity-medium" attribute for
107           this Config.
108
109        color_severity_low()
110           Returns the value of the "-color-severity-low" attribute for this
111           Config.
112
113        color_severity_lowest()
114           Returns the value of the "-color-severity-lowest" attribute for
115           this Config.
116
117        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
122        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

SUBROUTINES

128       Perl::Critic::Config has a few static subroutines that are used
129       internally, but may be useful to you in some way.
130
131       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

CONFIGURATION

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
148       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
153       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
158           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
175       The remainder of the configuration file is a series of blocks like
176       this:
177
178           [Perl::Critic::Policy::Category::PolicyName]
179           severity = 1
180           set_themes = foo bar
181           add_themes = baz
182           arg1 = value1
183           arg2 = value2
184
185       "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
191       "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
197       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
203       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
209       A simple configuration might look like this:
210
211           #--------------------------------------------------------------
212           # I think these are really important, so always load them
213
214           [TestingAndDebugging::RequireUseStrict]
215           severity = 5
216
217           [TestingAndDebugging::RequireUseWarnings]
218           severity = 5
219
220           #--------------------------------------------------------------
221           # I think these are less important, so only load when asked
222
223           [Variables::ProhibitPackageVars]
224           severity = 2
225
226           [ControlStructures::ProhibitPostfixControls]
227           allow = if unless  #My custom configuration
228           severity = 2
229
230           #--------------------------------------------------------------
231           # Give these policies a custom theme.  I can activate just
232           # these policies by saying (-theme => 'larry + curly')
233
234           [Modules::RequireFilenameMatchesPackage]
235           add_themes = larry
236
237           [TestingAndDebugging::RequireTestLabels]
238           add_themes = curly moe
239
240           #--------------------------------------------------------------
241           # I do not agree with these at all, so never load them
242
243           [-NamingConventions::Capitalization]
244           [-ValuesAndExpressions::ProhibitMagicNumbers]
245
246           #--------------------------------------------------------------
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
251       For additional configuration examples, see the perlcriticrc file that
252       is included in this t/examples directory of this distribution.
253

THE POLICIES

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

POLICY THEMES

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
268       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
273           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
284       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
289       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
294          Operator       Alternative         Meaning
295          ----------------------------------------------------------------------------
296          *              and                 Intersection
297          -              not                 Difference
298          +              or                  Union
299
300       Operator precedence is the same as that of normal mathematics.  You can
301       also use parenthesis to enforce precedence.  Here are some examples:
302
303          Expression                  Meaning
304          ----------------------------------------------------------------------------
305          pbp * bugs                  All policies that are "pbp" AND "bugs"
306          pbp and bugs                Ditto
307
308          bugs + cosmetic             All policies that are "bugs" OR "cosmetic"
309          bugs or cosmetic            Ditto
310
311          pbp - cosmetic              All policies that are "pbp" BUT NOT "cosmetic"
312          pbp not cosmetic            Ditto
313
314          -maintenance                All policies that are NOT "maintenance"
315          not maintenance             Ditto
316
317          (pbp - bugs) * complexity     All policies that are "pbp" BUT NOT "bugs",
318                                           AND "complexity"
319          (pbp not bugs) and complexity  Ditto
320
321       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

SEE ALSO

327       Perl::Critic::OptionsProcessor, Perl::Critic::UserProfile
328

AUTHOR

330       Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
331
333       Copyright (c) 2005-2023 Imaginative Software Systems
334
335       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.
338
339
340
341perl v5.38.0                      2023-09-25         Perl::Critic::Config(3pm)
Impressum