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.
new(key1 => value1, key2 => value2 ... )
Returns a reference to a new subclass of Perl::Critic::Policy. If your
Policy requires any special arguments, they will be passed in here as
key-value pairs. Users of perlcritic can specify these in their
config file. Unless you override the new method, the default
method simply returns a reference to an empty hash that has been
blessed into your subclass. However, you really should not override
this; override initialize_if_enabled() instead.
This constructor is always called regardless of whether the user has enabled this Policy or not.
initialize_if_enabled( { key1 => value1, key2 => value2 ... } )
This receives the same parameters as new(), but as a reference to a
hash, and is only invoked if this Policy is enabled by the user.
Thus, this is the preferred place for subclasses to do any
initialization.
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.
violates( $element, $document )
Given a PPI::Element and a PPI::Document, returns one or more
Perl::Critic::Violation objects if the $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 )
Returns a reference to a new 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()
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()
Returns a reference to an array containing instances of Perl::Critic::PolicyParameter.
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().
get_parameter( $parameter_name )
set_format( $FORMAT )
"%p\n". See
"OVERLOADS" for formatting options.
get_format()
to_string()
$FORMAT package
variable. See "OVERLOADS" for the details.
When your Policy module first uses 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. The format depends
on the current value of the $FORMAT package variable.
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 <thaljef@cpan.org>
Copyright (c) 2005-2008 Jeffrey Ryan Thalhammer. 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.