1Perl::Critic::Policy(3)User Contributed Perl DocumentatioPnerl::Critic::Policy(3)
2
3
4

NAME

6       Perl::Critic::Policy - Base class for all Policy modules.
7

DESCRIPTION

9       Perl::Critic::Policy is the abstract base class for all Policy objects.
10       If you're developing your own Policies, your job is to implement and
11       override its methods in a subclass.  To work with the Perl::Critic
12       engine, your implementation must behave as described below.  For a
13       detailed explanation on how to make new Policy modules, please see the
14       Perl::Critic::DEVELOPER document included in this distribution.
15

INTERFACE SUPPORT

17       This is considered to be a public class.  Any changes to its interface
18       will go through a deprecation cycle.
19

METHODS

21       new( ... )
22           Don't call this.  As a Policy author, do not implement this.  Use
23           the initialize_if_enabled() method for your Policy setup.  See the
24           developer documentation for more.
25
26       initialize_if_enabled( $config )
27           This receives an instance of Perl::Critic::PolicyConfig as a
28           parameter, and is only invoked if this Policy is enabled by the
29           user.  Thus, this is the preferred place for subclasses to do any
30           initialization.
31
32           Implementations of this method should return a boolean value
33           indicating whether the Policy should continue to be enabled.  For
34           most subclasses, this will always be $TRUE.  Policies that depend
35           upon external modules or other system facilities that may or may
36           not be available should test for the availability of these
37           dependencies and return $FALSE if they are not.
38
39       prepare_to_scan_document( $document )
40           The parameter is about to be scanned by this Policy.  Whatever this
41           Policy wants to do in terms of preparation should happen here.
42           Returns a boolean value indicating whether the document should be
43           scanned at all; if this is a false value, this Policy won't be
44           applied to the document.  By default, does nothing but return
45           $TRUE.
46
47       " violates( $element, $document ) "
48           Given a PPI::Element and a PPI::Document, returns one or more
49           Perl::Critic::Violation objects if the $element violates this
50           Policy.  If there are no violations, then it returns an empty list.
51           If the Policy encounters an exception, then it should "croak" with
52           an error message and let the caller decide how to handle it.
53
54           violates() is an abstract method and it will abort if you attempt
55           to invoke it directly.  It is the heart of all Policy modules, and
56           your subclass must override this method.
57
58       " violation( $description, $explanation, $element ) "
59           Returns a reference to a new "Perl::Critic::Violation" object. The
60           arguments are a description of the violation (as string), an
61           explanation for the policy (as string) or a series of page numbers
62           in PBP (as an ARRAY ref), a reference to the PPI element that
63           caused the violation.
64
65           These are the same as the constructor to Perl::Critic::Violation,
66           but without the severity.  The Policy itself knows the severity.
67
68       " new_parameter_value_exception( $option_name, $option_value, $source,
69       $message_suffix ) "
70           Create a
71           Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue
72           for this Policy.
73
74       " throw_parameter_value_exception( $option_name, $option_value,
75       $source, $message_suffix ) "
76           Create and throw a
77           Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue.
78           Useful in parameter parser implementations.
79
80        get_long_name()
81           Return the full package name of this policy.
82
83        get_short_name()
84           Return the name of this policy without the "Perl::Critic::Policy::"
85           prefix.
86
87        is_enabled()
88           Answer whether this policy is really active or not.  Returns a true
89           value if it is, a false, yet defined, value if it isn't, and an
90           undefined value if it hasn't yet been decided whether it will be.
91
92        applies_to()
93           Returns a list of the names of PPI classes that this Policy cares
94           about.  By default, the result is "PPI::Element".  Overriding this
95           method in Policy subclasses should lead to significant performance
96           increases.
97
98        default_maximum_violations_per_document()
99           Returns the default maximum number of violations for this policy to
100           report per document.  By default, this not defined, but subclasses
101           may override this.
102
103        get_maximum_violations_per_document()
104           Returns the maximum number of violations this policy will report
105           for a single document.  If this is not defined, then there is no
106           limit.  If "set_maximum_violations_per_document()" has not been
107           invoked, then "default_maximum_violations_per_document()" is
108           returned.
109
110        set_maximum_violations_per_document()
111           Specify the maximum violations that this policy should report for a
112           document.
113
114        default_severity()
115           Returns the default severity for violating this Policy.  See the
116           $SEVERITY constants in Perl::Critic::Utils for an enumeration of
117           possible severity values.  By default, this method returns
118           $SEVERITY_LOWEST.  Authors of Perl::Critic::Policy subclasses
119           should override this method to return a value that they feel is
120           appropriate for their Policy.  In general, Polices that are widely
121           accepted or tend to prevent bugs should have a higher severity than
122           those that are more subjective or cosmetic in nature.
123
124        get_severity()
125           Returns the severity of violating this Policy.  If the severity has
126           not been explicitly defined by calling "set_severity", then the
127           "default_severity" is returned.  See the $SEVERITY constants in
128           Perl::Critic::Utils for an enumeration of possible severity values.
129
130        set_severity( $N )
131           Sets the severity for violating this Policy.  Clients of
132           Perl::Critic::Policy objects can call this method to assign a
133           different severity to the Policy if they don't agree with the
134           "default_severity".  See the $SEVERITY constants in
135           Perl::Critic::Utils for an enumeration of possible values.
136
137        default_themes()
138           Returns a sorted list of the default themes associated with this
139           Policy.  The default method returns an empty list.  Policy authors
140           should override this method to return a list of themes that are
141           appropriate for their policy.
142
143        get_themes()
144           Returns a sorted list of the themes associated with this Policy.
145           If you haven't added themes or set the themes explicitly, this
146           method just returns the default themes.
147
148        set_themes( @THEME_LIST )
149           Sets the themes associated with this Policy.  Any existing themes
150           are overwritten.  Duplicate themes will be removed.
151
152        add_themes( @THEME_LIST )
153           Appends additional themes to this Policy.  Any existing themes are
154           preserved.  Duplicate themes will be removed.
155
156        get_abstract()
157           Retrieve the abstract for this policy (the part of the NAME section
158           of the POD after the module name), if it is available.
159
160        get_raw_abstract()
161           Retrieve the abstract for this policy (the part of the NAME section
162           of the POD after the module name), if it is available, in the
163           unparsed form.
164
165        parameter_metadata_available()
166           Returns whether information about the parameters is available.
167
168        get_parameters()
169           Returns a reference to an array containing instances of
170           Perl::Critic::PolicyParameter.
171
172           Note that this will return an empty list if the parameters for this
173           policy are unknown.  In order to differentiate between this
174           circumstance and the one where this policy does not take any
175           parameters, it is necessary to call parameter_metadata_available().
176
177       set_format( $format )
178           Class method.  Sets the format for all Policy objects when they are
179           evaluated in string context.  The default is "%p\n".  See
180           "OVERLOADS" for formatting options.
181
182       get_format()
183           Class method. Returns the current format for all Policy objects
184           when they are evaluated in string context.
185
186       to_string()
187           Returns a string representation of the policy.  The content of the
188           string depends on the current value returned by get_format().  See
189           "OVERLOADS" for the details.
190
191       is_safe()
192           Answer whether this Policy can be used to analyze untrusted code,
193           i.e. the Policy doesn't have any potential side effects.
194
195           This method returns a true value by default.
196
197           An "unsafe" policy might attempt to compile the code, which, if you
198           have "BEGIN" or "CHECK" blocks that affect files or connect to
199           databases, is not a safe thing to do.  If you are writing a such a
200           Policy, then you should override this method to return false.
201
202           By default Perl::Critic will not run unsafe policies.
203

DOCUMENTATION

205       When your Policy module first "use"s Perl::Critic::Violation, it will
206       try and extract the DESCRIPTION section of your Policy module's POD.
207       This information is displayed by Perl::Critic if the verbosity level is
208       set accordingly.  Therefore, please include a DESCRIPTION section in
209       the POD for any Policy modules that you author.  Thanks.
210

OVERLOADS

212       Perl::Critic::Violation overloads the "" operator to produce neat
213       little messages when evaluated in string context.
214
215       Formats are a combination of literal and escape characters similar to
216       the way "sprintf" works.  If you want to know the specific formatting
217       capabilities, look at String::Format. Valid escape characters are:
218
219       %P  Name of the Policy module.
220
221       %p  Name of the Policy without the "Perl::Critic::Policy::" prefix.
222
223       %a  The policy abstract.
224
225       %O  List of supported policy parameters.  Takes an option of a format
226           string for "to_formatted_string" in Perl::Critic::PolicyParameter.
227           For example, this can be used like "%{%n - %d\n}O" to get a list of
228           parameter names followed by their descriptions.
229
230       %U  A message stating that the parameters for the policy are unknown if
231           parameter_metadata_available() returns false.  Takes an option of
232           what the message should be, which defaults to "Cannot
233           programmatically discover what parameters this policy takes.".  The
234           value of this option is interpolated in order to expand the
235           standard escape sequences ("\n", "\t", etc.).
236
237       %S  The default severity level of the policy.
238
239       %s  The current severity level of the policy.
240
241       %T  The default themes for the policy.
242
243       %t  The current themes for the policy.
244
245       %V  The default maximum number of violations per document of the
246           policy.
247
248       %v  The current maximum number of violations per document of the
249           policy.
250

AUTHOR

252       Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
253
255       Copyright (c) 2005-2011 Imaginative Software Systems.  All rights
256       reserved.
257
258       This program is free software; you can redistribute it and/or modify it
259       under the same terms as Perl itself.  The full text of this license can
260       be found in the LICENSE file included with this module.
261
262
263
264perl v5.36.0                      2023-03-05           Perl::Critic::Policy(3)
Impressum