NAME¶
Perl::Critic::DEVELOPER - How to make new Perl::Critic::Policy modules.
DESCRIPTION¶
For developers who want to create custom coding standards, the following tells
how to create a Policy module for Perl::Critic. Although the Perl::Critic
distribution already includes a number of Policies based on Damian Conway's
book
Perl Best Practices (which will be referred to via
"
PBP" from here on), Perl::Critic is not limited to his
guidelines and can be used to enforce any practice, preference, or style that
you want to follow. You can even write Policies to enforce contradictory
guidelines. All you need to do is write a corresponding Perl::Critic::Policy
subclass, which may require as little as 10 lines of code.
BACKGROUND¶
The heart of Perl::Critic is PPI, a parser and lexer for Perl. PPI transforms
Perl source code into a Document Object Model (DOM). Each token in the
document is represented by a PPI class, such as PPI::Token::Operator or
PPI::Token::Word, and then organized into structure classes, like
PPI::Statement::Expression and PPI::Structure::Subroutine. The root node of
the hierarchy is the PPI::Document.
The Perl::Critic engine traverses each node in the PPI::Document tree and
invokes each of the Perl::Critic::Policy subclasses at the appropriate node.
The Policy can inspect the node, look at the surrounding nodes, and do
whatever else it wants. If the Policy decides that that a coding standard has
been violated, it returns one or more Perl::Critic::Violation objects. If
there are no violations, then the Policy returns nothing.
Policies are usually written based on existing policies, so let's look at one to
see how it works. The
RequireBlockGrep.pm Policy is relatively simple
and demonstrates most of the important issues. The goal of this Policy is to
enforce that every call to "grep" uses a block for the first
argument and not an expression. The reasons for this Policy are discussed in
detail in
PBP.
EXAMPLE POLICY¶
First, the Policy module needs to have a name. Perl::Critic uses
Module::Pluggable to automatically discover all modules in the
"Perl::Critic::Policy" namespace. Also, we've adopted the convention
of grouping Policies into directories according to the chapters of
PBP.
Since the goal of this Policy is to enforce the use of block arguments to
"grep" and it comes from the "Builtin Functions" chapter
of
PBP, we call it
"Perl::Critic::Policy::BuiltinFunctions::RequireBlockGrep".
package Perl::Critic::Policy::BuiltinFunctions::RequireBlockGrep;
Next, we set some pragmas and load the modules that we'll need. All Policy
modules inherit from the Perl::Critic::Policy class, which provides no-op
implementations of the basic methods. Our job is to override these methods to
make them do something useful.
Technically, "use strict" and "use warnings" are optional,
but we don't want Perl::Critic to be a hypocrite, now do we?
use strict;
use warnings;
use Readonly;
use Perl::Critic::Utils qw{ :severities :classification :ppi };
use base 'Perl::Critic::Policy';
our $VERSION = '1.05';
Next, we'll declare a description and explanation for this Policy. The
description is always just a string that basically says "this is what's
wrong." The explanation can be either a string with further details, or a
reference to an array of integers that correspond to page numbers in
PBP. We make them read-only because they never change. (See
Perl::Critic::Policy::ValuesAndExpressions::ProhibitConstantPragma for why we
don't "use constant".)
Readonly::Scalar my $DESC => q{Expression form of "grep"};
Readonly::Scalar my $EXPL => [ 169 ];
Most policies don't need to override the "initialize_if_enabled()"
method provided by Perl::Critic::Policy. However, if your Policy is
configurable via
.perlcriticrc, you should implement a
"supported_parameters()" method and need to implement
"initialize_if_enabled()" to examine the $config values. Since this
Policy isn't configurable, we'll declare that by providing an implementation
of "supported_parameters()" that returns an empty list.
sub supported_parameters { return () }
Next, we define the "default_severity()" method, which must return an
integer indicating the severity of violating this Policy. Severity values
range from 1 to 5, where 5 is the "most severe." In general, level 5
is reserved for things that are frequently misused and/or cause bugs. Level 1
is for things that are highly subjective or purely cosmetic. The
Perl::Critic::Utils package exports several severity constants that you can
use here via the ":severities" tag.
sub default_severity { return $SEVERITY_HIGH }
Likewise, the "default_themes()" method returns a list of theme names.
Themes are intended to be named groups of Policies. All Policies that ship
with Perl::Critic have a "core" theme. Since use of "grep"
without blocks often leads to bugs, we include a "bugs" theme. And
since this Policy comes directly from
PBP, this Policy should be a
member of the "pbp" theme.
sub default_themes { return qw( core bugs pbp ) }
As a Policy author, you can assign any themes you want to the Policy. If you're
publishing a suite of custom Policies, we suggest that you create a unique
theme that covers all the Policies in the distribution. That way, users can
easily enable or disable all of your policies at once. For example, Policies
in the Perl::Critic::More distribution all have a "more" theme.
Next, we indicate what elements of the code this Policy will analyze, like
statements or variables or conditionals or POD. These elements are specified
as PPI classes such as PPI::Statement, PPI::Token::Symbol,
PPI::Structure::Conditional or PPI::Token::Pod respectively. The
"applies_to()" method returns a list of PPI package names. (You can
get that list of available package names via "perldoc PPI".) As
Perl::Critic traverses the document, it will call the "violates()"
method from this module whenever it encounters one of the PPI types that are
given here. In this case, we just want to test calls to "grep".
Since the token "grep" is a PPI::Token::Word, we return that package
name from the "applies_to()" method.
sub applies_to { return 'PPI::Token::Word' }
If your Policy needs to analyze several different types of elements, the
"applies_to" method may return the name of several PPI packages. If
your Policy needs to examine the file as a whole, then the
"applies_to" method should return PPI::Document. Since there is only
one PPI::Document element, your Policy would only be invoked once per file.
Now comes the interesting part. The "violates()" method does all the
work. It is always called with 2 arguments: a reference to the current PPI
element that Perl::Critic is traversing, and a reference to the entire PPI
document. [And since this is an object method, there will be an additional
argument that is a reference to this object ($self), but you already knew
that!] Since this Policy does not need access to the document as a whole, we
ignore the last parameter by assigning to "undef".
sub violates {
my ( $self, $elem, undef ) = @_;
The "violates()" method then often performs some tests to make sure we
have the right "type" of element. In our example, we know that the
element will be a PPI::Token::Word because that's what we declared back in the
"applies_to()" method. However, we didn't specify exactly which
"word" we were looking for. Evaluating a PPI element in a string
context returns the literal form of the code. (You can also use the
"content()" method.) So we make sure that this
"PPI::Token::Word" is, in fact, "grep". If it's not, then
we don't need to bother examining it.
return if $elem ne 'grep';
The "PPI::Token::Word" class is also used for barewords and methods
called on object references. It is possible for someone to declare a bareword
hash key as "%hash = ( grep => 'foo')". We don't want to test
those types of elements because they don't represent function calls to
"grep". So we use one of handy utility functions from
Perl::Critic::Utils to make sure that this "grep" is actually in the
right context. (The "is_function_call()" subroutine is brought in
via the ":classification" tag.)
return if ! is_function_call($elem);
Now that we know this element is a call to the "grep" function, we can
look at the nearby elements to see what kind of arguments are being passed to
it. In the following paragraphs, we discuss how to do this manually in order
to explore PPI; after that, we'll show how this Policy actually uses
facilities provided by Perl::Critic::Utils to get this done.
Every PPI element is linked to its siblings, parent, and children (if it has
any). Since those siblings could just be whitespace, we use the
"snext_sibling()" to get the next code-sibling (the "s" in
"snext_sibling" stands for "significant").
my $sib = $elem->snext_sibling() or return;
In Perl, the parenthesis around argument lists are usually optional, and PPI
packs the elements into a PPI::Structure::List object when parentheses are
used. So if the sibling is a "PPI::Structure::List", we pull out the
first (significant) child of that list. This child will be the first argument
to "grep". If parentheses were not used, then the sibling itself is
the first argument.
my $arg = $sib->isa('PPI::Structure::List') ? $sib->schild(0) : $sib;
In actuality, this sort of function argument lookup is common, so there is a
"first_arg" in Perl::Critic::Utils subroutine available via the
":ppi" tag. So we use that instead.
my $arg = first_arg($elem);
Finally, we now have a reference to the first argument to "grep". If
that argument is a block (i.e. something in curly braces), then it will be a
PPI::Structure::Block, in which case our Policy is satisfied and we just
return nothing.
return if !$arg;
return if $arg->isa('PPI::Structure::Block');
But if it is not a PPI::Structure::Block, then we know that this call to
"grep" must be using the expression form, and that violates our
Policy. So we create and return a new Perl::Critic::Violation object via the
"violation" in Perl::Critic::Policy method, passing in the
description, explanation, and a reference to the PPI element that caused the
violation. And that's all there is to it!
return $self->violation( $DESC, $EXPL, $elem );
}
1;
One last thing -- people are going to need to understand what is wrong with the
code when your Policy finds a problem. It isn't reasonable to include all the
details in your violation description or explanation. So please include a
DESCRIPTION section in the POD for your Policy. It should succinctly describe
the behavior and motivation for your Policy and include a few examples of both
good and bad code. Here's an example:
=pod
=head1 NAME
Perl::Critic::Policy::BuiltinFunctions::RequireBlockGrep
=head1 DESCRIPTION
The expression forms of C<grep> and C<map> are awkward and hard to read.
Use the block forms instead.
@matches = grep /pattern/, @list; #not ok
@matches = grep { /pattern/ } @list; #ok
@mapped = map transform($_), @list; #not ok
@mapped = map { transform($_) } @list; #ok
=cut
When your policy has a section like this, users can invoke perlcritic with a
"--verbose" parameter of 10 or 11 or with a "%d" escape to
see it along with the rest of the output for violations of your policy.
MAKING YOUR POLICY CONFIGURABLE¶
Perl::Critic takes care of gathering configuration information for your Policy,
from whatever source the user specifies. (See "CONFIGURATION" in
Perl::Critic for the details of how a user specifies the values you're going
to receive.) What your Policy ends up receiving for the value of a parameter
is a string with leading and trailing whitespace removed. By default, you will
need to handle conversion of that string to a useful form yourself. However,
if you provide some metadata about your parameters, the parameter handling
will be taken care of for you. (Additionally, tools that deal with Policies
themselves can use this information to enhance their functionality. See the
perlcritic "--profile-proto" option for an example.)
You can look at Perl::Critic::Policy::ControlStructures::ProhibitCascadingIfElse
for a simple example of a configurable Policy and
Perl::Critic::Policy::Documentation::RequirePodSections for a more complex
one.
Do It All Yourself¶
The "initialize_if_enabled()" method for a Policy receives one
argument: an instance of Perl::Critic::PolicyConfig. This method is only
called if the user's configuration has enabled the policy. It returns a
boolean stating whether the Policy should continue to be enabled. Generally,
the only reason to return $FALSE is when some external requirement is missing.
For example, Perl::Critic::Policy::CodeLayout::RequireTidyCode used to disable
itself if Perl::Tidy was not installed (that is until we made it no longer
optional for the Perl-Critic distribution).
A basic, do-nothing implementation of "initialize_if_enabled()" would
be:
use Perl::Critic::Utils qw< :booleans >;
...
sub initialize_if_enabled {
my ( $self, $config ) = @_;
return $TRUE;
}
As stated above, what you get in $config are trimmed strings. For example, if
the user's
.perlcritic contains
[Your::Policy]
foo = bar baz
factor = 5.52
selections = 2 78 92
then $config will contain the equivalent of
my $config = {
foo => 'bar baz',
factor => '5.52',
selections => '2 78 92',
};
To make this available to the "violates()" method, the values are
usually put into $self under the name of the configuration item prefixed with
an underscore. E.g.
sub initialize_if_enabled {
my ( $self, $config ) = @_;
$self->{_foo} = $config->get{foo};
$self->{_factor} = $config->get{factor};
$self->{_selections} = $config->get{selections};
return $TRUE;
}
Often, you'll want to convert the configuration values into something more
useful. In this example, "selections" is supposed to be a list of
integers. Perl::Critic::Utils contains a number of functions that can help you
with this. Assuming that "violates()" wants to have
"selections" as an array, you'll want to have something like this:
use Perl::Critic::Utils qw{ :booleans :characters :data_conversion };
sub initialize_if_enabled {
my ( $self, $config ) = @_;
$self->{_foo} = $config->get{foo};
$self->{_factor} = $config->get{factor};
my $selections = $config->get{selections};
$selections = defined $selections ? $selections : $EMPTY_STRING;
$self->{_selections} = [ words_from_string($selections) ];
return $TRUE;
}
Since "selections" contains numbers, it may be desirable to change the
assignment to look like
$self->{_selections} = [ map { $_ + 0 } words_from_string($selections) ];
If "violates()" needs to quickly determine whether a particular value
is in "selections", you would want to use a hash instead of an
array, like this:
$self->{_selections} = { hashify( words_from_string($selections) ) };
For an example of a Policy that has some simple, but non-standard configuration
handling, see Perl::Critic::Policy::CodeLayout::RequireTidyCode.
Note On Constructors¶
It used to be the case that Policies handled configuration by implementing a
constructor. However, there was no requirement to call the base constructor;
as long as the Policy ended up being a blessed hash reference, everything was
fine. Unfortunately, this meant that Policies would be loaded and their
prerequisites would be "use"d, even if the Policy wasn't enabled,
slowing things down. Also, this severely restricted the core of Perl::Critic's
ability to enhance things. Use of constructors is deprecated and is
incompatible with "supported_parameters()" metadata below. Kindly
use "initialize_if_enabled()", instead, to do any sort of set up
that you need.
As minimum for a well behaved Policy, you should implement
"supported_parameters()" in order to tell the rest of
"Perl::Critic" what configuration values the Policy looks for, even
if it is only to say that the Policy is not configurable. In the simple form,
this function returns a list of the names of the parameters the Policy
supports. So, for an non-configurable Policy, as in the
"RequireBlockGrep" example above, this looked like
sub supported_parameters { return () }
For the example being used in the "initialize_if_enabled()" section
above, this would be
sub supported_parameters { return qw< foo factor selections >; }
Given this information, "Perl::Critic" can tell the user when they
have specified a parameter for a Policy which isn't valid, e.g. when they've
misspelled the name of the parameter, and can emit the parameter as part of a
.perlcriticrc prototype.
You can provide even more information about your Policy's configuration by
giving each parameter a description and a string representation of the default
value for the parameter. You do this by having the values in the list returned
by "supported_parameters()" be hash references instead of strings,
with keys of "name", "description", and
"default_string". For example,
sub supported_parameters {
return (
{
name => 'allowed_values',
description =>
'Individual and ranges of values to allow, and/or "all_integers".',
default_string => '0 1 2',
},
{
name => 'allowed_types',
description => 'Kind of literals to allow.',
default_string => 'Float',
},
);
}
Note that use of constructors is incompatible with specifying parameters in this
way.
Using "supported_parameters()" to Get It Done For
You¶
The "supported_parameters()" discussion above showed how you could
help others with your Policy, but didn't do anything to make your life as a
Policy author easier; you still need to implement
"initialize_if_enabled()" to access any configuration that the user
has specified. To have the configuration automatically handled for you, you
need to declare how your parameters act by specifying a value for their
"behavior". For example, the following declares that a parameter
allows the user to choose from five specific values and that the user can
select any combination of them:
sub supported_parameters {
return (
{
name => 'allowed_types',
description => 'Kind of literals to allow.',
default_string => 'Float',
behavior => 'enumeration',
enumeration_values => [ qw{ Binary Exp Float Hex Octal } ],
enumeration_allow_multiple_values => 1,
},
);
}
When you specify a behavior, parsing and validation of the user-specified and
default values is done for you and your "violates()" method can
retrieve the value under the key of the parameter name prefixed with an
underscore, e.g., for the above declaration, the parsed and validated value
can be accessed via "$self->{_allowed_types}".
The behaviors provide additional functionality to "Perl::Critic"; for
more on this, see Perl::Critic::PolicyParameter and
Perl::Critic::PolicyParameter::Behavior.
The following discusses each of the supported behaviors and the options they
support. For the full details of a behavior, see the documentation for the
implementing class.
"string"
Implemented in Perl::Critic::PolicyParameter::Behavior::String.
The most basic of behaviors, the value of the parameter will be stored in the
Policy as a string.
This behavior is not configurable.
"supported_parameters()" example
sub supported_parameters {
return (
{
name => 'a_string',
description => 'An example string.',
default_string => 'blah blah blah',
behavior => 'string',
},
);
}
Access example
sub violates {
my ($self, $element, $document) = @_;
...
my $string = $self->{_a_string};
...
}
"boolean"
Implemented in Perl::Critic::PolicyParameter::Behavior::Boolean.
The value of the parameter will be either $TRUE or $FALSE.
This behavior is not configurable.
"supported_parameters()" example
sub supported_parameters {
return (
{
name => 'a_boolean',
description => 'An example boolean.',
default_string => '1',
behavior => 'boolean',
},
);
}
Access example
sub violates {
my ($self, $element, $document) = @_;
...
my $is_whatever = $self->{_a_boolean};
if ($is_whatever) {
...
}
...
}
"integer"
Implemented in Perl::Critic::PolicyParameter::Behavior::Integer.
The value is validated against "m/ \A [-+]? [1-9] [\d_]* \z /xms"
(with an special check for "0"). Notice that this means that
underscores are allowed in input values as with Perl numeric literals.
This takes two options, "integer_minimum" and
"integer_maximum", which specify endpoints of an inclusive range to
restrict the value to. Either, neither, or both may be specified.
"supported_parameters()" example
sub supported_parameters {
return (
{
name => 'an_integer',
description => 'An example integer.',
default_string => '5',
behavior => 'integer',
integer_minimum => 0,
integer_maximum => 10,
},
);
}
Access example
sub violates {
my ($self, $element, $document) = @_;
...
my $integer = $self->{_an_integer};
if ($integer > $TURNING_POINT) {
...
}
...
}
"string list"
Implemented in Perl::Critic::PolicyParameter::Behavior::StringList.
The values will be derived by splitting the input string on blanks. (See
"words_from_string" in Perl::Critic::Utils.) The parameter will be
stored as a reference to a hash, with the values being the keys.
This takes one optional option, "list_always_present_values", of a
reference to an array of strings that will always be included in the parameter
value, e.g. if the value of this option is "[ qw{ a b c } ]" and the
user specifies a value of 'c d e', then the value of the parameter will
contain 'a', 'b', 'c', 'd', and 'e'.
"supported_parameters()" example
sub supported_parameters {
return (
{
name => 'a_string_list',
description => 'An example list.',
default_string => 'red pink blue',
behavior => 'string list',
list_always_present_values => [ qw{ green purple} ],
},
);
}
Access example
sub violates {
my ($self, $element, $document) = @_;
...
my $list = $self->{_a_string_list};
my @list = keys %{$list};
...
return if not $list->{ $element->content() };
...
}
"enumeration"
Implemented in Perl::Critic::PolicyParameter::Behavior::Enumeration.
The values will be derived by splitting the input string on blanks. (See
"words_from_string" in Perl::Critic::Utils.) Depending upon the
value of the "enumeration_allow_multiple_values" option, the
parameter will be stored as a string or a reference to a hash, with the values
being the keys.
This behavior takes one required option and one optional one. A value for
"enumeration_values" of a reference to an array of valid strings is
required. A true value can be specified for
"enumeration_allow_multiple_values" to allow the user to pick more
than one value, but this defaults to false.
"supported_parameters()" example
use Perl::Critic::Utils qw{ :characters };
sub supported_parameters {
return (
{
name => 'a_single_valued_enumeration',
description =>
'An example enumeration that can only have a single value.',
default_string => $EMPTY,
behavior => 'enumeration',
enumeration_values => [ qw{ block statement pod operator } ],
enumeration_allow_multiple_values => 0,
},
{
name => 'a_multi_valued_enumeration',
description =>
'An example enumeration that can have multiple values.',
default_string => 'fe',
behavior => 'enumeration',
enumeration_values => [ qw{ fe fi fo fum } ],
enumeration_allow_multiple_values => 1,
},
);
}
Access example
sub violates {
my ($self, $element, $document) = @_;
...
my $single_value = $self->{_a_single_valued_enumeration};
...
my $multi_value = $self->{_a_multi_valued_enumeration};
if ( $multi_value->{fum} ) {
...
}
...
}
Using a Custom Parser¶
If none of the behaviors does exactly what you want it to, you can provide your
own parser for a parameter. The reason for doing this as opposed to using an
implementation of "initialize_if_enabled()" is that it allows you to
use a behavior to provide its extra functionality and it provides a means for
a "Perl::Critic" configuration program, e.g. an IDE that integrates
"Perl::Critic", to validate your parameter as the user modifies its
value.
The way you declare that you have a custom parser is to include a reference to
it in the parameter specification with the "parser" key. For
example:
sub supported_parameters {
return (
{
name => 'file_name',
description => 'A file for to read a list of values from.',
default_string => undef,
behavior => 'string',
parser => \&_parse_file_name,
},
);
}
A parser is a method on a subclass of Perl::Critic::Policy that takes two
parameters: the Perl::Critic::PolicyParameter that is being specified and the
value string provided by the user. The method is responsible for dealing with
any default value and for saving the parsed value for later use by the
"violates()" method.
An example parser (without enough error handling) for the above example
declaration:
use File::Slurp qw< slurp >;
use Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue
qw{ throw_policy_value };
sub _parse_file_name {
my ($self, $parameter, $config_string) = @_;
my @thingies;
if ($config_string) {
if (not -r $config_string) {
throw_policy_value
policy => $self->get_short_name(),
option_name => $parameter->get_name(),
option_value => $config_string,
message_suffix => 'is not readable.';
}
@thingies = slurp $config_string;
}
$self->{_thingies} = \@thingies;
return;
}
Note that, if the value for the parameter is not valid, an instance of
Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue is
thrown. This allows "Perl::Critic" to include that problem along
with any other problems found with the user's configuration in a single error
message.
Using Both "supported_parameters()" and
"initialize_if_enabled()"¶
There are cases where a Policy needs additional initialization beyond
configuration or where the way it acts depends upon the combination of
multiple parameters. In such situations, you will need to create an
implementation of "initialize_if_enabled()". If you want to take
advantage of the supplied parameter handling from within implementation of
"initialize_if_enabled()", note that the information from
"supported_parameters()" will already have been used, with
user-supplied parameter values validated and placed into the Policy by the
time "initialize_if_enabled()" has been called. It is likely that
you will not need to refer the contents of the $config parameter; just pull
the information you need out of $self. In fact, any value for the parameter
values will be gone.
Summary of permitted hash keys in
"supported_parameters()".¶
All types
- - "name" (mandatory)
- - "description" (optional)
- - "behavior" (optional)
- Currently, one of:
- "boolean"
- "enumeration"
- "integer"
- "string"
- "string list"
- - "default_string" (optional)
- A string representation of the default value of the
parameter.
- - "parser" (optional)
- A code ref to a custom parser for the parameter.
Enumerations
- - "enumeration_values" (mandatory)
- A mandatory reference to an array of strings.
- - "enumeration_allow_multiple_values"
(optional)
- Boolean indicating whether or not the user is restricted to
a single value.
Integers
- - "integer_minimum" (optional)
- Minimum allowed value, inclusive.
- - "integer_maximum" (optional)
- Maximum allowed value, inclusive.
String lists
- - "list_always_present_values" (optional)
- A reference to an array of values that should always be
included in the value of the parameter.
ADDITIONAL FEATURES¶
"default_maximum_violations_per_document()"¶
Certain problems that a Policy detects can be endemic to a particular file; if
there's one violation, there's likely to be many. A good example of this is
Perl::Critic::Policy::TestingAndDebugging::RequireUseStrict; if there's one
line before "use strict", there's a good chance that the entire file
is missing "use strict". In such cases, it's not much help to the
user to report every single violation. If you've got such a policy, you should
override
default_maximum_violations_per_document() method to provide a
limit. The user can override this value with a value for
"maximum_violations_per_document" in their
.perlcriticrc.
See the source code for
Perl::Critic::Policy::ValuesAndExpressions::ProhibitMagicNumbers and
Perl::Critic::Policy::TestingAndDebugging::RequireUseWarnings for examples.
"is_safe()"¶
Most Perl::Critic Policies are purely
static. In other words, they never
compile or execute any of the source code that they analyze. However it is
possible to write
dynamic Policies that do compile or execute code,
which may result in unsafe operations (see Perl::Critic::Dynamic for an
example). So the "is_safe()" method is used to indicate whether a
Policy can be trusted to not cause mischief. By default, "is_safe()"
returns true. But if you are writing a Policy that will compile or execute any
of the source code that it analyzes, then you should override the
"is_safe()" method to return false.
DISTRIBUTING YOUR POLICIES¶
Create a Distribution¶
You need to come up with a name for your set of policies. Sets of add-on
policies are generally named "Perl::Critic::
something", e.g.
Perl::Critic::More.
The module representing the distribution will not actually have any
functionality; it's just documentation and a name for users to use when
installing via CPAN/CPANPLUS. The important part is that this will include a
list of the included policies, with descriptions of each.
A typical implementation will look like:
package Perl::Critic::Example;
use strict;
use warnings;
our $VERSION = '1.000000';
1; # Magic true value required at end of module
__END__
=head1 NAME
Perl::Critic::Example - Policies for Perl::Critic that act as an example.
=head1 AFFILIATION
This module has no functionality, but instead contains documentation
for this distribution and acts as a means of pulling other modules
into a bundle. All of the Policy modules contained herein will have
an "AFFILIATION" section announcing their participation in this
grouping.
=head1 SYNOPSIS
Some L<Perl::Critic|Perl::Critic> policies that will help you keep your
code nice and compliant.
=head1 DESCRIPTION
The included policies are:
=over
=item L<Perl::Critic::Policy::Documentation::Example|Perl::Critic::Policy::Documentation::Example>
Complains about some example documentation issues. [Default severity: 3]
=item L<Perl::Critic::Policy::Variables::Example|Perl::Critic::Policy::Variables::Example>
All modules must have at least one variable. [Default severity: 3]
=back
=head1 CONFIGURATION AND ENVIRONMENT
All policies included are in the "example" theme. See the
L<Perl::Critic|Perl::Critic> documentation for how to make use of this.
Themes¶
Users can choose which policies to enable using themes. You should implement
"default_themes()" so that users can take advantage of this. In
particular, you should use a theme named after your distribution in all your
policies; this should match the value listed in the "CONFIGURATION AND
ENVIRONMENT" POD section as shown above.
default_themes { return qw< example math > }
If you're looking for ideas of what themes to use, have a look at the output of
"perlcritic --list-themes".
Documentation¶
AFFILIATION
Since all policies have to go somewhere under the
"Perl::Critic::Policy::" namespace, it isn't always clear what
distribution a policy came from when browsing through their documentation. For
this reason, you should include an "AFFILIATION" section in the POD
for all of your policies that state where the policy comes from. For example:
=head1 AFFILIATION
This policy is part of L<Perl::Critic::Example|Perl::Critic::Example>.
CONFIGURATION
In order to make it clear what can be done with a policy, you should always
include a "CONFIGURATION" section in your POD, even if it's only to
say:
=head1 CONFIGURATION
This Policy is not configurable except for the standard options.
TESTING YOUR POLICY¶
The Perl::Critic distribution also contains a framework for testing your Policy.
See Test::Perl::Critic::Policy for the details.
HINT¶
When you're trying to figure out what PPI is going to hand you for a chunk of
code, there is a
tools/ppidump program in the Perl::Critic distribution
that will help you. For example, when developing the above RequireBlockGrep
example, you might want to try
tools/ppidump '@matches = grep /pattern/, @list;'
and
tools/ppidump '@matches = grep { /pattern/ } @list;'
to see the differences between the two cases.
Alternatively, see the "ppi_dumper" documentation at
http://search.cpan.org/dist/App-PPI-Dumper/script/ppi_dumper
<
http://search.cpan.org/dist/App-PPI-Dumper/script/ppi_dumper> and the
"PPI::Tester" documentation at
http://search.cpan.org/dist/PPI-Tester/lib/PPI/Tester.pm
<
http://search.cpan.org/dist/PPI-Tester/lib/PPI/Tester.pm>.
VERSION¶
This is part of Perl::Critic version 1.116.
SEE ALSO¶
Chas. Owens has a blog post about developing in-house policies at
http://svok.blogspot.com/2009/09/adding-house-policies-to-perlcritic.html
<
http://svok.blogspot.com/2009/09/adding-house-policies-to-perlcritic.html>.
AUTHOR¶
Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
COPYRIGHT¶
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.