|
|
| |
Perl::Critic::Policy(3) |
User Contributed Perl Documentation |
Perl::Critic::Policy(3) |
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( ... )"
- 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.
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
- Name of the Policy module.
- %p
- Name of the Policy without the
"Perl::Critic::Policy::" prefix.
- %a
- The policy abstract.
- %O
- List of supported policy parameters. Takes an option of a format string
for "to_formatted_string" in Perl::Critic::PolicyParameter. For
example, this can be used like "%{%n -
%d\n}O" to get a list of parameter names followed by their
descriptions.
- %U
- A message stating that the parameters for the policy are unknown if
"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
- The default severity level of the policy.
- %s
- The current severity level of the policy.
- %T
- The default themes for the policy.
- %t
- The current themes for the policy.
- %V
- The default maximum number of violations per document of the policy.
- %v
- The current maximum number of violations per document of the policy.
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.
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc. |