1Perl::Critic::Config(3)User Contributed Perl DocumentatioPnerl::Critic::Config(3)
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( [ -profile => $FILE, -severity => $N, -theme => $string, -include
23       => \@PATTERNS, -exclude => \@PATTERNS, -single-policy => $PATTERN, -top
24       => $N, -only => $B, -profile-strictness =>
25       $PROFILE_STRICTNESS_{WARN|FATAL|QUIET}, -force => $B, -verbose => $N,
26       -color => $B, -criticism-fatal => $B] )"
27       "new()"
28           Returns a reference to a new Perl::Critic::Config object.  The
29           default value for all arguments can be defined in your
30           .perlcriticrc file.  See the "CONFIGURATION" section for more
31           information about that.  All arguments are optional key-value pairs
32           as follows:
33
34           -profile is a path to a configuration file. If $FILE is not
35           defined, Perl::Critic::Config attempts to find a .perlcriticrc
36           configuration file in the current directory, and then in your home
37           directory.  Alternatively, you can set the "PERLCRITIC" environment
38           variable to point to a file in another location.  If a
39           configuration file can't be found, or if $FILE is an empty string,
40           then all Policies will be loaded with their default configuration.
41           See "CONFIGURATION" for more information.
42
43           -severity is the minimum severity level.  Only Policy modules that
44           have a severity greater than $N will be loaded into this Config.
45           Severity values are integers ranging from 1 (least severe) to 5
46           (most severe).  The default is 5.  For a given "-profile",
47           decreasing the "-severity" will usually result in more Policy
48           violations.  Users can redefine the severity level for any Policy
49           in their .perlcriticrc file.  See "CONFIGURATION" for more
50           information.
51
52           -theme is special string that defines a set of Policies based on
53           their respective themes.  If "-theme" is given, only policies that
54           are members of that set will be loaded.  See the "POLICY THEMES"
55           section for more information about themes.  Unless the "-severity"
56           option is explicitly given, setting "-theme" causes the "-severity"
57           to be set to 1.
58
59           -include is a reference to a list of string @PATTERNS.  Policies
60           that match at least one "m/$PATTERN/ixms" will be loaded into this
61           Config, irrespective of the severity settings.  You can use it in
62           conjunction with the "-exclude" option.  Note that "-exclude" takes
63           precedence over "-include" when a Policy matches both patterns.
64
65           -exclude is a reference to a list of string @PATTERNS.  Polices
66           that match at least one "m/$PATTERN/ixms" will not be loaded into
67           this Config, irrespective of the severity settings.  You can use it
68           in conjunction with the "-include" option.  Note that "-exclude"
69           takes precedence over "-include" when a Policy matches both
70           patterns.
71
72           -single-policy is a string "PATTERN".  Only the policy that matches
73           "m/$PATTERN/ixms" will be used.  This value overrides the
74           "-severity", "-theme", "-include", "-exclude", and "-only" options.
75
76           -top is the maximum number of Violations to return when ranked by
77           their severity levels.  This must be a positive integer.
78           Violations are still returned in the order that they occur within
79           the file.  Unless the "-severity" option is explicitly given,
80           setting "-top" silently causes the "-severity" to be set to 1.
81
82           -only is a boolean value.  If set to a true value, Perl::Critic
83           will only choose from Policies that are mentioned in the user's
84           profile.  If set to a false value (which is the default), then
85           Perl::Critic chooses from all the Policies that it finds at your
86           site.
87
88           -profile-strictness is an enumerated value, one of
89           "$PROFILE_STRICTNESS_WARN" in Perl::Critic::Utils::Constants (the
90           default), "$PROFILE_STRICTNESS_FATAL" in
91           Perl::Critic::Utils::Constants, and "$PROFILE_STRICTNESS_QUIET" in
92           Perl::Critic::Utils::Constants.  If set to
93           "$PROFILE_STRICTNESS_FATAL" in Perl::Critic::Utils::Constants,
94           Perl::Critic will make certain warnings about problems found in a
95           .perlcriticrc or file specified via the -profile option fatal.  For
96           example, Perl::Critic normally only "warn"s about profiles
97           referring to non-existent Policies, but this value makes this
98           situation fatal.  Correspondingly, "$PROFILE_STRICTNESS_QUIET" in
99           Perl::Critic::Utils::Constants makes Perl::Critic shut up about
100           these things.
101
102           -force controls whether Perl::Critic observes the magical "## no
103           critic" annotations in your code.  If set to a true value,
104           Perl::Critic will analyze all code.  If set to a false value (which
105           is the default) Perl::Critic will ignore code that is tagged with
106           these comments.  See "BENDING THE RULES" in Perl::Critic for more
107           information.
108
109           -verbose can be a positive integer (from 1 to 10), or a literal
110           format specification.  See Perl::Critic::Violations for an
111           explanation of format specifications.
112
113           -color and -pager are not used by Perl::Critic but is provided for
114           the benefit of perlcritic.
115
116           -criticism-fatal is not used by Perl::Critic but is provided for
117           the benefit of criticism.
118
119           -color-severity-highest is a string representing the highest
120           severity violation color, as expected by Term::ANSIColor. It is not
121           used by Perl::Critic, but is provided for the benefit of
122           perlcritic. It can also be specified as -colour-severity-highest,
123           -color-severity-5, or -colour-severity-5.
124
125           -color-severity-high is a string representing the high severity
126           violation color, as expected by Term::ANSIColor. It is not used by
127           Perl::Critic, but is provided for the benefit of perlcritic. It can
128           also be specified as -colour-severity-high, -color-severity-4, or
129           -colour-severity-4.
130
131           -color-severity-medium is a string representing the medium severity
132           violation color, as expected by Term::ANSIColor. It is not used by
133           Perl::Critic, but is provided for the benefit of perlcritic. It can
134           also be specified as -colour-severity-medium, -color-severity-3, or
135           -colour-severity-3.
136
137           -color-severity-low is a string representing the low severity
138           violation color, as expected by Term::ANSIColor. It is not used by
139           Perl::Critic, but is provided for the benefit of perlcritic. It can
140           also be specified as -colour-severity-low, -color-severity-2, or
141           -colour-severity-2.
142
143           -color-severity-lowest is a string representing the lowest severity
144           violation color, as expected by Term::ANSIColor. It is not used by
145           Perl::Critic, but is provided for the benefit of perlcritic. It can
146           also be specified as -colour-severity-lowest, -color-severity-1, or
147           -colour-severity-1.
148

METHODS

150       "add_policy( -policy => $policy_name, -params => \%param_hash )"
151           Creates a Policy object and loads it into this Config.  If the
152           object cannot be instantiated, it will throw a fatal exception.
153           Otherwise, it returns a reference to this Critic.
154
155           -policy is the name of a Perl::Critic::Policy subclass module.  The
156           'Perl::Critic::Policy' portion of the name can be omitted for
157           brevity.  This argument is required.
158
159           -params is an optional reference to a hash of Policy parameters.
160           The contents of this hash reference will be passed into to the
161           constructor of the Policy module.  See the documentation in the
162           relevant Policy module for a description of the arguments it
163           supports.
164
165       " all_policies_enabled_or_not() "
166           Returns a list containing references to all the Policy objects that
167           have been seen.  Note that the state of these objects is not
168           trustworthy.  In particular, it is likely that some of them are not
169           prepared to examine any documents.
170
171       " policies() "
172           Returns a list containing references to all the Policy objects that
173           have been enabled and loaded into this Config.
174
175       " exclude() "
176           Returns the value of the "-exclude" attribute for this Config.
177
178       " include() "
179           Returns the value of the "-include" attribute for this Config.
180
181       " force() "
182           Returns the value of the "-force" attribute for this Config.
183
184       " only() "
185           Returns the value of the "-only" attribute for this Config.
186
187       " profile_strictness() "
188           Returns the value of the "-profile-strictness" attribute for this
189           Config.
190
191       " severity() "
192           Returns the value of the "-severity" attribute for this Config.
193
194       " single_policy() "
195           Returns the value of the "-single-policy" attribute for this
196           Config.
197
198       " theme() "
199           Returns the Perl::Critic::Theme object that was created for this
200           Config.
201
202       " top() "
203           Returns the value of the "-top" attribute for this Config.
204
205       " verbose() "
206           Returns the value of the "-verbose" attribute for this Config.
207
208       " color() "
209           Returns the value of the "-color" attribute for this Config.
210
211       " pager() "
212           Returns the value of the "-pager" attribute for this Config.
213
214       " criticism_fatal() "
215           Returns the value of the "-criticsm-fatal" attribute for this
216           Config.
217
218       " color_severity_highest() "
219           Returns the value of the "-color-severity-highest" attribute for
220           this Config.
221
222       " color_severity_high() "
223           Returns the value of the "-color-severity-high" attribute for this
224           Config.
225
226       " color_severity_medium() "
227           Returns the value of the "-color-severity-medium" attribute for
228           this Config.
229
230       " color_severity_low() "
231           Returns the value of the "-color-severity-low" attribute for this
232           Config.
233
234       " color_severity_lowest() "
235           Returns the value of the "-color-severity-lowest" attribute for
236           this Config.
237

SUBROUTINES

239       Perl::Critic::Config has a few static subroutines that are used
240       internally, but may be useful to you in some way.
241
242       "site_policy_names()"
243           Returns a list of all the Policy modules that are currently
244           installed in the Perl::Critic:Policy namespace.  These will include
245           modules that are distributed with Perl::Critic plus any third-party
246           modules that have been installed.
247

CONFIGURATION

249       Most of the settings for Perl::Critic and each of the Policy modules
250       can be controlled by a configuration file.  The default configuration
251       file is called .perlcriticrc.  Perl::Critic::Config will look for this
252       file in the current directory first, and then in your home directory.
253       Alternatively, you can set the "PERLCRITIC" environment variable to
254       explicitly point to a different file in another location.  If none of
255       these files exist, and the "-profile" option is not given to the
256       constructor, then all Policies will be loaded with their default
257       configuration.
258
259       The format of the configuration file is a series of INI-style blocks
260       that contain key-value pairs separated by '='. Comments should start
261       with '#' and can be placed on a separate line or after the name-value
262       pairs if you desire.
263
264       Default settings for Perl::Critic itself can be set before the first
265       named block.  For example, putting any or all of these at the top of
266       your configuration file will set the default value for the
267       corresponding Perl::Critic constructor argument.
268
269           severity  = 3                                     #Integer from 1 to 5
270           only      = 1                                     #Zero or One
271           force     = 0                                     #Zero or One
272           verbose   = 4                                     #Integer or format spec
273           top       = 50                                    #A positive integer
274           theme     = risky + (pbp * security) - cosmetic   #A theme expression
275           include   = NamingConventions ClassHierarchies    #Space-delimited list
276           exclude   = Variables  Modules::RequirePackage    #Space-delimited list
277           color     = 1                                     #Zero or One
278           color-severity-highest = bold red                 #Term::ANSIColor
279           color-severity-high = magenta                     #Term::ANSIColor
280           color-severity-medium =                           #no coloring
281           color-severity-low =                              #no coloring
282           color-severity-lowest =                           #no coloring
283
284       The remainder of the configuration file is a series of blocks like
285       this:
286
287           [Perl::Critic::Policy::Category::PolicyName]
288           severity = 1
289           set_themes = foo bar
290           add_themes = baz
291           arg1 = value1
292           arg2 = value2
293
294       "Perl::Critic::Policy::Category::PolicyName" is the full name of a
295       module that implements the policy.  The Policy modules distributed with
296       Perl::Critic have been grouped into categories according to the table
297       of contents in Damian Conway's book Perl Best Practices. For brevity,
298       you can omit the 'Perl::Critic::Policy' part of the module name.
299
300       "severity" is the level of importance you wish to assign to the Policy.
301       All Policy modules are defined with a default severity value ranging
302       from 1 (least severe) to 5 (most severe).  However, you may disagree
303       with the default severity and choose to give it a higher or lower
304       severity, based on your own coding philosophy.
305
306       The remaining key-value pairs are configuration parameters that will be
307       passed into the constructor of that Policy.  The constructors for most
308       Policy modules do not support arguments, and those that do should have
309       reasonable defaults.  See the documentation on the appropriate Policy
310       module for more details.
311
312       Instead of redefining the severity for a given Policy, you can
313       completely disable a Policy by prepending a '-' to the name of the
314       module in your configuration file.  In this manner, the Policy will
315       never be loaded, regardless of the "-severity" given to the
316       Perl::Critic::Config constructor.
317
318       A simple configuration might look like this:
319
320           #--------------------------------------------------------------
321           # I think these are really important, so always load them
322
323           [TestingAndDebugging::RequireUseStrict]
324           severity = 5
325
326           [TestingAndDebugging::RequireUseWarnings]
327           severity = 5
328
329           #--------------------------------------------------------------
330           # I think these are less important, so only load when asked
331
332           [Variables::ProhibitPackageVars]
333           severity = 2
334
335           [ControlStructures::ProhibitPostfixControls]
336           allow = if unless  #My custom configuration
337           severity = 2
338
339           #--------------------------------------------------------------
340           # Give these policies a custom theme.  I can activate just
341           # these policies by saying (-theme => 'larry + curly')
342
343           [Modules::RequireFilenameMatchesPackage]
344           add_themes = larry
345
346           [TestingAndDebugging::RequireTestLables]
347           add_themes = curly moe
348
349           #--------------------------------------------------------------
350           # I do not agree with these at all, so never load them
351
352           [-NamingConventions::Capitalization]
353           [-ValuesAndExpressions::ProhibitMagicNumbers]
354
355           #--------------------------------------------------------------
356           # For all other Policies, I accept the default severity, theme
357           # and other parameters, so no additional configuration is
358           # required for them.
359
360       For additional configuration examples, see the perlcriticrc file that
361       is included in this t/examples directory of this distribution.
362

THE POLICIES

364       A large number of Policy modules are distributed with Perl::Critic.
365       They are described briefly in the companion document
366       Perl::Critic::PolicySummary and in more detail in the individual
367       modules themselves.
368

POLICY THEMES

370       Each Policy is defined with one or more "themes".  Themes can be used
371       to create arbitrary groups of Policies.  They are intended to provide
372       an alternative mechanism for selecting your preferred set of Policies.
373       For example, you may wish disable a certain subset of Policies when
374       analyzing test scripts.  Conversely, you may wish to enable only a
375       specific subset of Policies when analyzing modules.
376
377       The Policies that ship with Perl::Critic are have been broken into the
378       following themes.  This is just our attempt to provide some basic
379       logical groupings.  You are free to invent new themes that suit your
380       needs.
381
382           THEME             DESCRIPTION
383           --------------------------------------------------------------------------
384           core              All policies that ship with Perl::Critic
385           pbp               Policies that come directly from "Perl Best Practices"
386           bugs              Policies that that prevent or reveal bugs
387           maintenance       Policies that affect the long-term health of the code
388           cosmetic          Policies that only have a superficial effect
389           complexity        Policies that specificaly relate to code complexity
390           security          Policies that relate to security issues
391           tests             Policies that are specific to test scripts
392
393       Say "`perlcritic -list`" to get a listing of all available policies and
394       the themes that are associated with each one.  You can also change the
395       theme for any Policy in your .perlcriticrc file.  See the
396       "CONFIGURATION" section for more information about that.
397
398       Using the "-theme" option, you can combine theme names with
399       mathematical and boolean operators to create an arbitrarily complex
400       expression that represents a custom "set" of Policies.  The following
401       operators are supported
402
403          Operator       Alternative         Meaning
404          ----------------------------------------------------------------------------
405          *              and                 Intersection
406          -              not                 Difference
407          +              or                  Union
408
409       Operator precedence is the same as that of normal mathematics.  You can
410       also use parenthesis to enforce precedence.  Here are some examples:
411
412          Expression                  Meaning
413          ----------------------------------------------------------------------------
414          pbp * bugs                  All policies that are "pbp" AND "bugs"
415          pbp and bugs                Ditto
416
417          bugs + cosmetic             All policies that are "bugs" OR "cosmetic"
418          bugs or cosmetic            Ditto
419
420          pbp - cosmetic              All policies that are "pbp" BUT NOT "cosmetic"
421          pbp not cosmetic            Ditto
422
423          -maintenance                All policies that are NOT "maintenance"
424          not maintenance             Ditto
425
426          (pbp - bugs) * complexity     All policies that are "pbp" BUT NOT "bugs",
427                                           AND "complexity"
428          (pbp not bugs) and complexity  Ditto
429
430       Theme names are case-insensitive.  If "-theme" is set to an empty
431       string, then it is equivalent to the set of all Policies.  A theme name
432       that doesn't exist is equivalent to an empty set.  Please See
433       <http://en.wikipedia.org/wiki/Set> for a discussion on set theory.
434

SEE ALSO

436       Perl::Critic::OptionsProcessor, Perl::Critic::UserProfile
437

AUTHOR

439       Jeffrey Ryan Thalhammer <thaljef@cpan.org>
440
442       Copyright (c) 2005-2009 Jeffrey Ryan Thalhammer.  All rights reserved.
443
444       This program is free software; you can redistribute it and/or modify it
445       under the same terms as Perl itself.  The full text of this license can
446       be found in the LICENSE file included with this module.
447
448
449
450perl v5.12.1                      2010-09-08           Perl::Critic::Config(3)
Impressum