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

NAME

Developer - How to make new Perl::Critic::Policy modules

DESCRIPTION

This document describes how to create a new Policy module for Perl::Critic. It is intended for developers who wish to extend Perl::Critic to enforce their own custom coding standards. Although the Perl::Critic distribution already includes a number of Policies based on Damian Conway's book "Perl Best Practices", Perl::Critic is not limited to his guidelines and can be used to enforce any practice, preference, or style that you want to follow. In fact, 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, which is a parser and lexer for Perl. PPI transforms a file of Perl source code into a Document Object Model (DOM). Each token in the document is represented by one of the various PPI classes (for example: PPI::Token::Operator, PPI::Token::Word). The tokens are then organized into a hierarchy of structural classes (for example: PPI::Statement::Expression, 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.

So now that we understand the basic organization of PPI and Perl::Critic, lets examine one the existing Policy modules so we can see how this all works. We will pick the RequireBlockGrep.pm policy because it is relatively simple but 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 "Perl Best Practices."

EXAMPLE POLICY

First, the Policy module needs to have a name. Perl::Critic uses Module::Pluggable to automatically discover all modules that are in the Perl::Critic::Policy namespace. Also, we've adopted the convention of grouping Policies into directories according to the table of contents in Conway's book "Perl Best Practices." 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 they are necessary to make Perl::Critic self-compliant. And we don't want Perl::Critic to be a hypocrite, now do we?

  use strict;
  use warnings;
  use Perl::Critic::Utils;
  use Perl::Critic::Violation;
  use base 'Perl::Critic::Policy';

This following is a pretty standard way to declare a version number for you module, and it's also required for self-compliance. But the ProhibitStringyEval policy doesn't approve of using eval in this manner, so we attach the "## no critic" comments to tell Perl::Critic to overlook this line of code.

  our $VERSION = '0.13_01';
  $VERSION = eval $VERSION;    ## no critic

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 the "Perl Best Practices" book.

  my $desc = q{Expression form of 'grep'};
  my $expl = [169];

Here we define the default_severity() method, which should return a scalar value 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 subject and purely cosmetic. The Perl::Critic::Utils package exports several severity constants that you can use here.

  sub default_severity  { return $SEVERITY_HIGH }

Next we define which types of PPI objects this Policy should be invoked on. The applies_to() method returns a list of PPI package names. 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 name from the applies_to() method.

  sub applies_to { return 'PPI::Token::Word' }

Until this point, we've been writing static methods. However, we are writing an object class. Perl::Critic::Policy provides a default constructor that simply returns a blessed hash reference. So in most cases, you don't need to write your own constructor. But if your Policy requires any special parameters, you can write a custom constructor that accepts those parameters.

Now comes the interesting part. The violates() method does all the work. It is always called with 2 arguments: a reference to the current node or "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!]

  sub violates {
      my ( $self, $elem, $doc ) = @_;

Next, we do some tests to make sure we have the right "type" of element. We know it 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. 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 eq '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 some handy utility functions from Perl::Critic::Utils to make sure that this "grep" is actually in the right context.

    return if is_method_call($elem);
    return if is_hash_key($elem);

Now that we know this element is a function call to grep, we can look at the nearby elements to see what kind of arguments are being passed to it. 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' stands for 'significant').

    my $sib = $elem->snext_sibling() || return;

In Perl, the parenthesis around argument lists are usually optional, and PPI packs the elements into a PPI::Structure::List object when parens 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 parens were not used, then the sibling itself is the first argument.

    my $arg = $sib->isa('PPI::Structure::List') ? $sib->schild(0) : $sib;

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 || $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, passing in the description, explanation, and severity of the violation, as well as a reference to the PPI element that caused the violation. And that's all there is to it!

    my $sev = $self->get_severity();
    return Perl::Critic::Violation->new( $desc, $expl, $elem, $sev );
  }

  1;

One last thing -- When you import Perl::Critic::Violation, it extracts the DESCRIPTION section from the POD in your Policy module. That text can displayed in the diagnostic output when the Violations objects are string-ified. 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.

  =pod

  =head1 NAME

  Perl::Critic::Policy::BuiltinFunctions::RequireBlockGrep

  =head1 DESCRIPTION

  The expression form of C<grep> and C<map> is 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

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005 Jeffrey Ryan Thalhammer. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.