1Perl::Critic::Policy(3pUms)er Contributed Perl DocumentatPieornl::Critic::Policy(3pm)
2
6 Perl::Critic::Policy - Base class for all Policy modules.
7
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
17 This is considered to be a public class. Any changes to its interface
18 will go through a deprecation cycle.
19
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 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 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 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 " 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 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 " 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 These are the same as the constructor to Perl::Critic::Violation,
66 but without the severity. The Policy itself knows the severity.
67 " 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 " 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 get_long_name()
81 Return the full package name of this policy.
82 get_short_name()
84 Return the name of this policy without the "Perl::Critic::Policy::"
85 prefix.
86 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 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 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 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 set_maximum_violations_per_document()
111 Specify the maximum violations that this policy should report for a
112 document.
113 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 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 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 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 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 set_themes( @THEME_LIST )
149 Sets the themes associated with this Policy. Any existing themes
150 are overwritten. Duplicate themes will be removed.
151 add_themes( @THEME_LIST )
153 Appends additional themes to this Policy. Any existing themes are
154 preserved. Duplicate themes will be removed.
155 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 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 parameter_metadata_available()
166 Returns whether information about the parameters is available.
167 get_parameters()
169 Returns a reference to an array containing instances of
170 Perl::Critic::PolicyParameter.
171 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 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 get_format()
183 Class method. Returns the current format for all Policy objects
184 when they are evaluated in string context.
185 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 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 This method returns a true value by default.
196 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 By default Perl::Critic will not run unsafe policies.
203
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
212 Perl::Critic::Violation overloads the "" operator to produce neat
213 little messages when evaluated in string context.
214 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 %P Name of the Policy module.
220 %p Name of the Policy without the "Perl::Critic::Policy::" prefix.
222 %a The policy abstract.
224 %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 %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 %S The default severity level of the policy.
238 %s The current severity level of the policy.
240 %T The default themes for the policy.
242 %t The current themes for the policy.
244 %V The default maximum number of violations per document of the
246 policy.
247 %v The current maximum number of violations per document of the
249 policy.
250
252 Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
253
255 Copyright (c) 2005-2011 Imaginative Software Systems. All rights
256 reserved.
257 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.
261perl v5.38.0 2023-09-25 Perl::Critic::Policy(3pm)