The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Perl-Critic-0.12
River stage three • 131 direct dependents • 408 total dependents
130 ++
/ Perl::Critic::Policy

NAME

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

DESCRIPTION

Perl::Critic::Policy is the abstract base class for all Policy objects. 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.

IMPORTANT CHANGES

As new Policy modules were added to Perl::Critic, the overall performance started to deteriorate rapidily. Since each module would traverse the document (several times for some modules), a lot of time was spent iterating over the same document nodes. So starting in version 0.12, I have switched to a stream-based approach where the document is traversed once and every Policy module is tested at each node. The result is roughly 300% a improvement, and the Perl::Critic engine will scale better as more Policies are added.

Unfortunately, Policy modules prior to version 0.12 won't be compatible. Converting them to the stream-based model is fairly easy, and it actually results in somewhat cleaner code. Look at the ControlStrucutres::* modules for some good examples.

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 paris. 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 object if the $element violates this policy. If there are no violations, then it returns an empty list.

Perl::Critic will call violates() on every $element in the $document. Some Policies may need to look at the entire $document and probably only need to be executed once. In that case, you should write violates() so that it short-circuts if the Policy has already been executed. See Perl::Critic::Policy::Modules::ProhibitUnpackagedCode for an example of such a Policy.

violates() is an abstract method and it will croak if you attempt to invoke it directly. Your subclass must override this method.

DOCUMENTATION

When your Policy module first uses Perl::Critic::Violation, it will try and extrace 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 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.