Welcome to the new Tigris! There have been some changes to the administration of mail lists. Project and list owners should check out the Discussion Services release notes.
Perl::Critic::DEVELOPER - How to make new Perl::Critic::Policy modules.
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.
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.
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::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 c<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 Perl::Critic::Utils/"first_arg" 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
Perl::Critic::Policy/"violation" 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 to see it along with the rest of the output for violations of
your policy.
Perl::Critic takes care of gathering configuration
information for your Policy, from whatever source the user specifies.
(See Perl::Critic/"CONFIGURATION" 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.
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
disables itself if Perl::Tidy is not installed.
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.
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 used,
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 .perlcritic 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.
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.
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.
sub supported_parameters {
return (
{
name => 'a_string',
description => 'An example string.',
default_string => 'blah blah blah',
behavior => 'string',
},
);
}
sub violates {
my ($self, $element, $document) = @_;
...
my $string = $self->{_a_string};
...
}
Implemented in
Perl::Critic::PolicyParameter::Behavior::Boolean.
The value of the parameter will be either Perl::Critic::Utils/$TRUE
or Perl::Critic::Utils/$FALSE.
This behavior is not configurable.
sub supported_parameters {
return (
{
name => 'a_boolean',
description => 'An example boolean.',
default_string => '1',
behavior => 'boolean',
},
);
}
sub violates {
my ($self, $element, $document) = @_;
...
my $is_whatever = $self->{_a_boolean};
if ($is_whatever) {
...
}
...
}
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.
sub supported_parameters {
return (
{
name => 'an_integer',
description => 'An example integer.',
default_string => '5',
behavior => 'integer',
integer_minimum => 0,
integer_maximum => 10,
},
);
}
sub violates {
my ($self, $element, $document) = @_;
...
my $integer = $self->{_an_integer};
if ($integer > $TURNING_POINT) {
...
}
...
}
Implemented in
Perl::Critic::PolicyParameter::Behavior::StringList.
The values will be derived by splitting the input string on blanks.
(See Perl::Critic::Utils/"words_from_string".) The parameter will
be stored as a reference to a hash, with the values being the keys.
This takes one optional option, 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'.
sub supported_parameters {
return (
{
name => 'a_string_list',
description => 'An example list.',
default_string => 'red pink blue',
behavior => 'string list',
always_present_values => [ qw{ green purple} ],
},
);
}
sub violates {
my ($self, $element, $document) = @_;
...
my $list = $self->{_a_string_list};
my @list = keys %{$list};
...
return if not $list->{ $element->content() };
...
}
Implemented in
Perl::Critic::PolicyParameter::Behavior::Enumeration.
The values will be derived by splitting the input string on blanks.
(See Perl::Critic::Utils/"words_from_string".) 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.
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,
},
);
}
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} ) {
...
}
...
}
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.
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.
- - "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.
- - "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.
- - "integer_minimum" (optional)
-
Minimum allowed value, inclusive.
- - "integer_maximum" (optional)
-
Maximum allowed value, inclusive.
- - "list_always_present_values" (optional)
-
A reference to an array of values that should always be included in
the value of the parameter.
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.
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. [Severity: 3]
=item L<Perl::Critic::Policy::Variables::Example|Perl::Critic::Policy::Variables::Example>
All modules must have at least one variable. [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.
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 do, have a look at the
output of perlcritic --list-themes.
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>.
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.
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.
This is part of Perl::Critic version 1.088.
Jeffrey Ryan Thalhammer <thaljef@cpan.org>
Copyright (c) 2005-2008 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.
