Perl::Critic::Policy - Base class for all Policy modules. |
Perl::Critic::Policy - Base class for all Policy modules.
Perl::Critic::Policy is the abstract base class for all Policy objects. If you're developing your own Policies, your job is to implement and override its methods in a subclass. To work with the Perl::Critic engine, your implementation must behave as described below. For a detailed explanation on how to make new Policy modules, please see the Perl::Critic::DEVELOPER document included in this distribution.
This is considered to be a public class. Any changes to its interface will go through a deprecation cycle.
new( ... )
initialize_if_enabled()
method for your Policy setup. See the
developer documentation for more.
initialize_if_enabled( $config )
Implementations of this method should return a boolean value
indicating whether the Policy should continue to be enabled. For most
subclasses, this will always be $TRUE
. Policies that depend upon
external modules or other system facilities that may or may not be
available should test for the availability of these dependencies and
return $FALSE
if they are not.
prepare_to_scan_document( $document )
$TRUE
.
violates( $element, $document )
$element
violates this Policy. If there are no violations, then it
returns an empty list. If the Policy encounters an exception, then it
should croak
with an error message and let the caller decide how to
handle it.
violates()
is an abstract method and it will abort if you attempt
to invoke it directly. It is the heart of all Policy modules, and
your subclass must override this method.
violation( $description, $explanation, $element )
Perl::Critic::Violation
object. The
arguments are a description of the violation (as string), an
explanation for the policy (as string) or a series of page numbers in
PBP (as an ARRAY ref), a reference to the PPI element that
caused the violation.
These are the same as the constructor to Perl::Critic::Violation, but without the severity. The Policy itself knows the severity.
new_parameter_value_exception( $option_name, $option_value, $source, $message_suffix )
throw_parameter_value_exception( $option_name, $option_value, $source, $message_suffix )
get_long_name()
get_short_name()
is_enabled()
applies_to()
PPI::Element
. Overriding this
method in Policy subclasses should lead to significant performance
increases.
default_maximum_violations_per_document()
get_maximum_violations_per_document()
set_maximum_violations_per_document()
default_severity()
$SEVERITY
constants in Perl::Critic::Utils
for an enumeration of possible severity values. By default, this
method returns $SEVERITY_LOWEST
. Authors of Perl::Critic::Policy
subclasses should override this method to return a value that they
feel is appropriate for their Policy. In general, Polices that are
widely accepted or tend to prevent bugs should have a higher severity
than those that are more subjective or cosmetic in nature.
get_severity()
set_severity
, then the
default_severity
is returned. See the $SEVERITY
constants in
Perl::Critic::Utils for an enumeration of
possible severity values.
set_severity( $N )
default_severity
. See the $SEVERITY
constants in
Perl::Critic::Utils for an enumeration of
possible values.
default_themes()
get_themes()
set_themes( @THEME_LIST )
add_themes( @THEME_LIST )
get_abstract()
get_raw_abstract()
parameter_metadata_available()
get_parameters()
Note that this will return an empty list if the parameters for this
policy are unknown. In order to differentiate between this
circumstance and the one where this policy does not take any
parameters, it is necessary to call parameter_metadata_available()
.
set_format( $format )
"%p\n"
. See
OVERLOADS for formatting options.
get_format()
to_string()
get_format()
.
See OVERLOADS for the details.
is_safe()
This method returns a true value by default.
An ``unsafe'' policy might attempt to compile the code, which, if you have
BEGIN
or CHECK
blocks that affect files or connect to databases, is not
a safe thing to do. If you are writing a such a Policy, then you should
override this method to return false.
By default Perl::Critic will not run unsafe policies.
When your Policy module first use
s
Perl::Critic::Violation, it will try and
extract the DESCRIPTION section of your Policy module's POD. This
information is displayed by Perl::Critic if the verbosity level is set
accordingly. Therefore, please include a DESCRIPTION section in the
POD for any Policy modules that you author. Thanks.
Perl::Critic::Violation overloads the ""
operator to produce neat
little messages when evaluated in string context.
Formats are a combination of literal and escape characters similar to
the way sprintf
works. If you want to know the specific formatting
capabilities, look at String::Format. Valid escape
characters are:
%P
%p
Perl::Critic::Policy::
prefix.
%a
%O
%{%n - %d\n}O
to get a list of
parameter names followed by their descriptions.
%U
parameter_metadata_available()
returns false. Takes an option of
what the message should be, which defaults to ``Cannot programmatically
discover what parameters this policy takes.''. The value of this
option is interpolated in order to expand the standard escape
sequences (\n
, \t
, etc.).
%S
%s
%T
%t
%V
%v
Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
Copyright (c) 2005-2011 Imaginative Software Systems. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.
Perl::Critic::Policy - Base class for all Policy modules. |