Provided by: libperl-critic-perl_1.121-1_all bug

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

   Providing Basic Configuration Information Via "supported_parameters()"
       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> and the "PPI::Tester"
       documentation at <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>.

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.