NAME

Perl::Critic::Policy - Base class for all Policy modules

DESCRIPTION

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.

METHODS

new(key1 = value1, key2 => value2 ... )>

Returns a reference to a new subclass of Perl::Critic::Policy. If your Policy requires any special arguments, they should 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.

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.

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_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.

DOCUMENTATION

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.

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005-2006 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.