new( ... )
Don't call this. As a Policy author, do not implement this. Use the initialize_if_enabled() method
for your Policy setup. See the developer documentation for more.
initialize_if_enabled( $config )
This receives an instance of Perl::Critic::PolicyConfig as a parameter, 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.
prepare_to_scan_document( $document )
The parameter is about to be scanned by this Policy. Whatever this Policy wants to do in terms of
preparation should happen here. Returns a boolean value indicating whether the document should be
scanned at all; if this is a false value, this Policy won't be applied to the document. By default,
does nothing but return $TRUE.
" 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 ) "
Create a Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue for this Policy.
" throw_parameter_value_exception( $option_name, $option_value, $source, $message_suffix ) "
Create and throw a Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue. Useful in
parameter parser implementations.
get_long_name()
Return the full package name of this policy.
get_short_name()
Return the name of this policy without the "Perl::Critic::Policy::" prefix.
is_enabled()
Answer whether this policy is really active or not. Returns a true value if it is, a false, yet
defined, value if it isn't, and an undefined value if it hasn't yet been decided whether it will be.
applies_to()
Returns a list of the names of PPI classes that this Policy cares about. By default, the result is
"PPI::Element". Overriding this method in Policy subclasses should lead to significant performance
increases.
default_maximum_violations_per_document()
Returns the default maximum number of violations for this policy to report per document. By default,
this not defined, but subclasses may override this.
get_maximum_violations_per_document()
Returns the maximum number of violations this policy will report for a single document. If this is
not defined, then there is no limit. If "set_maximum_violations_per_document()" has not been
invoked, then "default_maximum_violations_per_document()" is returned.
set_maximum_violations_per_document()
Specify the maximum violations that this policy should report for a document.
default_severity()
Returns the default severity for violating this Policy. See the $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()
Returns the severity of violating this Policy. If the severity has not been explicitly defined by
calling "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 )
Sets the severity for violating this Policy. Clients of Perl::Critic::Policy objects can call this
method to assign a different severity to the Policy if they don't agree with the "default_severity".
See the $SEVERITY constants in Perl::Critic::Utils for an enumeration of possible values.
default_themes()
Returns a sorted list of the default themes associated with this Policy. The default method returns
an empty list. Policy authors should override this method to return a list of themes that are
appropriate for their policy.
get_themes()
Returns a sorted list of the themes associated with this Policy. If you haven't added themes or set
the themes explicitly, this method just returns the default themes.
set_themes( @THEME_LIST )
Sets the themes associated with this Policy. Any existing themes are overwritten. Duplicate themes
will be removed.
add_themes( @THEME_LIST )
Appends additional themes to this Policy. Any existing themes are preserved. Duplicate themes will
be removed.
get_abstract()
Retrieve the abstract for this policy (the part of the NAME section of the POD after the module
name), if it is available.
get_raw_abstract()
Retrieve the abstract for this policy (the part of the NAME section of the POD after the module
name), if it is available, in the unparsed form.
parameter_metadata_available()
Returns whether information about the parameters is 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().
set_format( $format )
Class method. Sets the format for all Policy objects when they are evaluated in string context. The
default is "%p\n". See "OVERLOADS" for formatting options.
get_format()
Class method. Returns the current format for all Policy objects when they are evaluated in string
context.
to_string()
Returns a string representation of the policy. The content of the string depends on the current
value returned by get_format(). See "OVERLOADS" for the details.
is_safe()
Answer whether this Policy can be used to analyze untrusted code, i.e. the Policy doesn't have any
potential side effects.
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.
Install Now
PNG Icons