Login
Convert L<Some::Module> escapes to
[gknop/Perl-Critic.git] / lib / Perl / Critic / DEVELOPER.pod
1 ##############################################################################
2 #      $URL$
3 #     $Date$
4 #   $Author$
5 # $Revision$
6 ##############################################################################
7
8 =pod
9
10 =for stopwords lookup RequireBlockGrep
11
12 =head1 NAME
13
14 Perl::Critic::DEVELOPER - How to make new Perl::Critic::Policy modules.
15
16
17 =head1 DESCRIPTION
18
19 For developers who want to create custom coding standards, the
20 following tells how to create a Policy module for
21 L<Perl::Critic|Perl::Critic>.  Although the Perl::Critic distribution
22 already includes a number of Policies based on Damian Conway's book
23 I<Perl Best Practices> (which will be referred to via "I<PBP>" from
24 here on), Perl::Critic is not limited to his guidelines and can be
25 used to enforce any practice, preference, or style that you want to
26 follow.  You can even write Policies to enforce contradictory
27 guidelines.  All you need to do is write a corresponding
28 L<Perl::Critic::Policy|Perl::Critic::Policy> subclass, which may
29 require as little as 10 lines of code.
30
31
32 =head1 BACKGROUND
33
34 The heart of Perl::Critic is L<PPI|PPI>, a parser and lexer for Perl.
35 PPI transforms Perl source code into a Document Object Model (DOM).
36 Each token in the document is represented by a PPI class, such as
37 L<PPI::Token::Operator|PPI::Token::Operator> or
38 L<PPI::Token::Word|PPI::Token::Word>, and then organized into
39 structure classes, like
40 L<PPI::Statement::Expression|PPI::Statement::Expression> and
41 L<PPI::Structure::Subroutine|PPI::Structure::Subroutine>. The root
42 node of the hierarchy is the L<PPI::Document|PPI::Document>.
43
44 The L<Perl::Critic|Perl::Critic> engine traverses each node in the
45 L<PPI::Document|PPI::Document> tree and invokes each of the
46 L<Perl::Critic::Policy|Perl::Critic::Policy> subclasses at the
47 appropriate node.  The Policy can inspect the node, look at the
48 surrounding nodes, and do whatever else it wants.  If the Policy
49 decides that that a coding standard has been violated, it returns one
50 or more L<Perl::Critic::Violation|Perl::Critic::Violation> objects.
51 If there are no violations, then the Policy returns nothing.
52
53 Policies are usually written based on existing policies, so let's look
54 at one to see how it works.  The F<RequireBlockGrep.pm> Policy is
55 relatively simple and demonstrates most of the important issues.  The
56 goal of this Policy is to enforce that every call to C<grep> uses a
57 block for the first argument and not an expression.  The reasons for
58 this Policy are discussed in detail in I<PBP>.
59
60
61 =head1 EXAMPLE POLICY
62
63 First, the Policy module needs to have a name.  Perl::Critic uses
64 L<Module::Pluggable|Module::Pluggable> to automatically discover all
65 modules in the C<Perl::Critic::Policy> namespace.  Also, we've adopted
66 the convention of grouping Policies into directories according to the
67 chapters of I<PBP>.  Since the goal of this Policy is to enforce the
68 use of block arguments to C<grep> and it comes from the "Builtin
69 Functions" chapter of I<PBP>, we call it
70 C<"Perl::Critic::Policy::BuiltinFunctions::RequireBlockGrep">.
71
72     package Perl::Critic::Policy::BuiltinFunctions::RequireBlockGrep;
73
74 Next, we set some pragmas and load the modules that we'll need.  All
75 Policy modules inherit from the
76 L<Perl::Critic::Policy|Perl::Critic::Policy> class, which provides
77 no-op implementations of the basic methods.  Our job is to override
78 these methods to make them do something useful.
79
80 Technically, C<use strict> and C<use warnings> are optional, but we
81 don't want Perl::Critic to be a hypocrite, now do we?
82
83     use strict;
84     use warnings;
85
86     use Readonly;
87
88     use Perl::Critic::Utils qw{ :severities :classification :ppi };
89     use base 'Perl::Critic::Policy';
90
91     our $VERSION = '1.05';
92
93 Next, we'll declare a description and explanation for this Policy.
94 The description is always just a string that basically says "this is
95 what's wrong."  The explanation can be either a string with further
96 details, or a reference to an array of integers that correspond to
97 page numbers in I<PBP>.  We make them read-only because they never
98 change.  (See
99 L<Perl::Critic::ValuesAndExpressions::ProhibitConstantPragma|Perl::Critic::ValuesAndExpressions::ProhibitConstantPragma>
100 for why we don't C<use constant>.)
101
102     Readonly::Scalar my $DESC => q{Expression form of "grep"};
103     Readonly::Scalar my $EXPL => [ 169 ];
104
105 Most policies don't need to override the C<initialize_if_enabled()>
106 method provided by L<Perl::Critic::Policy|Perl::Critic::Policy>.
107 However, if your Policy is configurable via F<.perlcriticrc>, you
108 should implement a C<supported_parameters()> method and need to
109 implement C<initialize_if_enabled()> to examine the C<$config> values.
110 Since this Policy isn't configurable, we'll declare that by providing
111 an implementation of C<supported_parameters()> that returns an empty
112 list.
113
114     sub supported_parameters { return ()                  }
115
116 Next, we define the C<default_severity()> method, which must return an
117 integer indicating the severity of violating this Policy.  Severity
118 values range from 1 to 5, where 5 is the "most severe."  In general,
119 level 5 is reserved for things that are frequently misused and/or
120 cause bugs.  Level 1 is for things that are highly subjective or
121 purely cosmetic.  The L<Perl::Critic::Utils|Perl::Critic::Utils>
122 package exports several severity constants that you can use here via
123 the C<:severities> tag.
124
125     sub default_severity     { return $SEVERITY_HIGH      }
126
127 Likewise, the C<default_themes()> method returns a list of theme
128 names.  Themes are intended to be named groups of Policies.  All
129 Policies that ship with Perl::Critic have a C<"core"> theme.  Since
130 use of C<grep> without blocks often leads to bugs, we include a
131 C<"bugs"> theme.  And since this Policy comes directly from I<PBP>,
132 this Policy should be a member of the C<"pbp"> theme.
133
134     sub default_themes       { return qw( core bugs pbp ) }
135
136 As a Policy author, you can assign any themes you want to the Policy.
137 If you're publishing a suite of custom Policies, we suggest that you
138 create a unique theme that covers all the Policies in the
139 distribution.  That way, users can easily enable or disable all of
140 your policies at once.  For example, Policies in the
141 L<Perl::Critic::More|Perl::Critic::More> distribution all have a
142 C<"more"> theme.
143
144 Next, we indicate what elements of the code this Policy will analyze,
145 like statements or variables or conditionals or POD.  These elements
146 are specified as PPI classes such as L<PPI::Statement|PPI::Statement>,
147 L<PPI::Token::Symbol|PPI::Token::Symbol>,
148 L<PPI::Structure::Conditional|PPI::Structure::Conditional> or
149 L<PPI::Token::Pod|PPI::Token::Pod> respectively.  The applies_to()
150 method returns a list of PPI package names.  (You can get that list of
151 available package names via C<perldoc PPI>.)  As Perl::Critic
152 traverses the document, it will call the C<violates()> method from
153 this module whenever it encounters one of the PPI types that are given
154 here.  In this case, we just want to test calls to C<grep>.  Since the
155 token "grep" is a L<PPI::Token::Word|PPI::Token::Word>, we return that
156 package name from the C<applies_to()> method.
157
158     sub applies_to           { return 'PPI::Token::Word'  }
159
160 If your Policy needs to analyze several different types of elements,
161 the C<applies_to> method may return the name of several PPI packages.
162 If your Policy needs to examine the file as a whole, then the
163 C<applies_to> method should return L<PPI::Document|PPI::Document>.
164 Since there is only one PPI::Document element, your Policy would only
165 be invoked once per file.
166
167 Now comes the interesting part.  The C<violates()> method does all the
168 work.  It is always called with 2 arguments: a reference to the
169 current PPI element that Perl::Critic is traversing, and a reference
170 to the entire PPI document. [And since this is an object method, there
171 will be an additional argument that is a reference to this object
172 (C<$self>), but you already knew that!]  Since this Policy does not
173 need access to the document as a whole, we ignore the last parameter
174 by assigning to C<undef>.
175
176     sub violates {
177         my ( $self, $elem, undef ) = @_;
178
179 The violates() method then often performs some tests to make sure we
180 have the right "type" of element.  In our example, we know that the
181 element will be a L<PPI::Token::Word|PPI::Token::Word> because that's
182 what we declared back in the C<applies_to()> method.  However, we
183 didn't specify exactly which "word" we were looking for.  Evaluating a
184 PPI element in a string context returns the literal form of the code.
185 (You can also use the c<content()> method.)  So we make sure that this
186 PPI::Token::Word is, in fact, "grep".  If it's not, then we don't'
187 need to bother examining it.
188
189         return if $elem ne 'grep';
190
191 The C<PPI::Token::Word> class is also used for barewords and methods
192 called on object references.  It is possible for someone to declare a
193 bareword hash key as C<<%hash = ( grep => 'foo' )>>.  We don't want to
194 test those types of elements because they don't represent function
195 calls to C<grep>.  So we use one of handy utility functions from
196 L<Perl::Critic::Utils|Perl::Critic::Utils> to make sure that this
197 "grep" is actually in the right context.  (The C<is_function_call()>
198 subroutine is brought in via the C<:classification> tag.)
199
200         return if ! is_function_call($elem);
201
202 Now that we know this element is a call to the C<grep> function, we
203 can look at the nearby elements to see what kind of arguments are
204 being passed to it.  In the following paragraphs, we discuss how to do
205 this manually in order to explore L<PPI|PPI>; after that, we'll show
206 how this Policy actually uses facilities provided by
207 L<Perl::Critic::Utils|Perl::Critic::Utils> to get this done.
208
209 Every PPI element is linked to its siblings, parent, and children (if
210 it has any).  Since those siblings could just be whitespace, we use
211 the C<snext_sibling()> to get the next code-sibling (the "s" in
212 C<snext_sibling> stands for "significant").
213
214         my $sib = $elem->snext_sibling() or return;
215
216 In Perl, the parenthesis around argument lists are usually optional,
217 and PPI packs the elements into a
218 L<PPI::Structure::List|PPI::Structure::List> object when parentheses
219 are used.  So if the sibling is a PPI::Structure::List, we pull out
220 the first (significant) child of that list.  This child will be the
221 first argument to C<grep>.  If parentheses were not used, then the
222 sibling itself is the first argument.
223
224         my $arg = $sib->isa('PPI::Structure::List') ? $sib->schild(0) : $sib;
225
226 In actuality, this sort of function argument lookup is common, so
227 there is a L<Perl::Critic::Utils/"first_arg"> subroutine available via
228 the C<:ppi> tag.  So we use that instead.
229
230         my $arg = first_arg($elem);
231
232 Finally, we now have a reference to the first argument to C<grep>.  If
233 that argument is a block (i.e. something in curly braces), then it
234 will be a L<PPI::Structure::Block|PPI::Structure::Block>, in which
235 case our Policy is satisfied and we just return nothing.
236
237         return if !$arg;
238         return if $arg->isa('PPI::Structure::Block');
239
240 But if it is not a L<PPI::Structure::Block|PPI::Structure::Block>,
241 then we know that this call to C<grep> must be using the expression
242 form, and that violates our Policy.  So we create and return a new
243 L<Perl::Critic::Violation|Perl::Critic::Violation> object via the
244 L<Perl::Critic::Policy/"violation"> method, passing in the
245 description, explanation, and a reference to the PPI element that
246 caused the violation.  And that's all there is to it!
247
248         return $self->violation( $DESC, $EXPL, $elem );
249     }
250
251     1;
252
253 One last thing -- people are going to need to understand what is wrong
254 with the code when your Policy finds a problem.  It isn't reasonable
255 to include all the details in your violation description or
256 explanation.  So please include a DESCRIPTION section in the POD for
257 your Policy.  It should succinctly describe the behavior and
258 motivation for your Policy and include a few examples of both good and
259 bad code.  Here's an example:
260
261     =pod
262
263     =head1 NAME
264
265     Perl::Critic::Policy::BuiltinFunctions::RequireBlockGrep
266
267
268     =head1 DESCRIPTION
269
270     The expression forms of C<grep> and C<map> are awkward and hard to read.
271     Use the block forms instead.
272
273         @matches = grep  /pattern/,    @list;        #not ok
274         @matches = grep { /pattern/ }  @list;        #ok
275
276         @mapped = map  transform($_),    @list;      #not ok
277         @mapped = map { transform($_) }  @list;      #ok
278
279     =cut
280
281 When your policy has a section like this, users can invoke
282 L<perlcritic|perlcritic> with a C<--verbose> parameter of C<10> or
283 C<11> to see it along with the rest of the output for violations of
284 your policy.
285
286
287 =head1 MAKING YOUR POLICY CONFIGURABLE
288
289 L<Perl::Critic|Perl::Critic> takes care of gathering configuration
290 information for your Policy, from whatever source the user specifies.
291 (See L<Perl::Critic/"CONFIGURATION"> for the details of how a user
292 specifies the values you're going to receive.)  What your Policy ends
293 up receiving for the value of a parameter is a string with leading and
294 trailing whitespace removed.  By default, you will need to handle
295 conversion of that string to a useful form yourself.  However, if you
296 provide some metadata about your parameters, the parameter handling
297 will be taken care of for you.  (Additionally, tools that deal with
298 Policies themselves can use this information to enhance their
299 functionality.  See the L<perlcritic|perlcritic> C<--profile-proto>
300 option for an example.)
301
302 You can look at
303 L<Perl::Critic::Policy::ControlStructures::ProhibitCascadingIfElse|Perl::Critic::Policy::ControlStructures::ProhibitCascadingIfElse>
304 for a simple example of a configurable Policy and
305 L<Perl::Critic::Policy::Documentation::RequirePodSections|Perl::Critic::Policy::Documentation::RequirePodSections>
306 for a more complex one.
307
308 =head2 Do It All Yourself
309
310 The C<initialize_if_enabled()> method for a Policy receives one
311 argument: an instance of
312 L<Perl::Critic::PolicyConfig|Perl::Critic::PolicyConfig>.  This method
313 is only called if the user's configuration has enabled the policy.  It
314 returns a boolean stating whether the Policy should continue to be
315 enabled.  Generally, the only reason to return C<$FALSE> is when some
316 external requirement is missing.  For example,
317 L<Perl::Critic::Policy::CodeLayout::RequireTidyCode|Perl::Critic::Policy::CodeLayout::RequireTidyCode>
318 disables itself if L<Perl::Tidy|Perl::Tidy> is not installed.
319
320 A basic, do-nothing implementation of C<initialize_if_enabled()> would
321 be:
322
323     use Perl::Critic::Utils qw< :booleans >;
324
325     ...
326
327     sub initialize_if_enabled {
328         my ( $self, $config ) = @_;
329
330         return $TRUE;
331     }
332
333 As stated above, what you get in C<$config> are trimmed strings.  For
334 example, if the user's F<.perlcritic> contains
335
336     [Your::Policy]
337     foo          = bar baz
338     factor   =     5.52
339     selections =   2 78 92
340
341 then C<$config> will contain the equivalent of
342
343     my $config = {
344         foo        => 'bar baz',
345         factor     => '5.52',
346         selections => '2 78 92',
347     };
348
349 To make this available to the C<violates()> method, the values are
350 usually put into C<$self> under the name of the configuration item
351 prefixed with an underscore.  E.g.
352
353     sub initialize_if_enabled {
354         my ( $self, $config ) = @_;
355
356         $self->{_foo} = $config->get{foo};
357         $self->{_factor} = $config->get{factor};
358         $self->{_selections} = $config->get{selections};
359
360         return $TRUE;
361     }
362
363 Often, you'll want to convert the configuration values into something
364 more useful.  In this example, C<selections> is supposed to be a list
365 of integers.  L<Perl::Critic::Utils|Perl::Critic::Utils> contains a
366 number of functions that can help you with this.  Assuming that
367 C<violates()> wants to have C<selections> as an array, you'll want to
368 have something like this:
369
370     use Perl::Critic::Utils qw{ :booleans :characters :data_conversion };
371
372     sub initialize_if_enabled {
373         my ( $self, $config ) = @_;
374
375         $self->{_foo} = $config->get{foo};
376         $self->{_factor} = $config->get{factor};
377
378         my $selections = $config->get{selections};
379         $selections = defined $selections ? $selections : $EMPTY_STRING;
380         $self->{_selections} = [ words_from_string($selections) ];
381
382         return $TRUE;
383     }
384
385 Since C<selections> contains numbers, it may be desirable to change
386 the assignment to look like
387
388     $self->{_selections} = [ map { $_ + 0 } words_from_string($selections) ];
389
390 If C<violates()> needs to quickly determine whether a particular value
391 is in C<selections>, you would want to use a hash instead of an array,
392 like this:
393
394     $self->{_selections} = { hashify( words_from_string($selections) ) };
395
396 For an example of a Policy that has some simple, but non-standard
397 configuration handling, see
398 L<Perl::Critic::Policy::CodeLayout::RequireTidyCode|Perl::Critic::Policy::CodeLayout::RequireTidyCode>.
399
400
401 =head2 Note On Constructors
402
403 It used to be the case that Policies handled configuration by
404 implementing a constructor.  However, there was no requirement to call
405 the base constructor; as long as the Policy ended up being a blessed
406 hash reference, everything was fine.  Unfortunately, this meant that
407 Policies would be loaded and their prerequisites would be C<use>d,
408 even if the Policy wasn't enabled, slowing things down.  Also, this
409 severely restricted the core of L<Perl::Critic|Perl::Critic>'s ability
410 to enhance things.  Use of constructors is deprecated and is
411 incompatible with C<supported_parameters()> metadata below.  Kindly
412 use C<initialize_if_enabled()>, instead, to do any sort of set up that
413 you need.
414
415
416
417 =head2 Providing Basic Configuration Information Via C<supported_parameters()>
418
419 As minimum for a well behaved Policy, you should implement
420 C<supported_parameters()> in order to tell the rest of C<Perl::Critic>
421 what configuration values the Policy looks for, even if it is only to
422 say that the Policy is not configurable.  In the simple form, this
423 function returns a list of the names of the parameters the Policy
424 supports.  So, for an non-configurable Policy, as in the
425 C<RequireBlockGrep> example above, this looked like
426
427     sub supported_parameters { return ()                  }
428
429 For the example being used in the C<initialize_if_enabled()> section
430 above, this would be
431
432     sub supported_parameters { return qw< foo factor selections >; }
433
434 Given this information, C<Perl::Critic> can tell the user when they
435 have specified a parameter for a Policy which isn't valid, e.g. when
436 they've misspelled the name of the parameter, and can emit the
437 parameter as part of a F<.perlcritic> prototype.
438
439 You can provide even more information about your Policy's
440 configuration by giving each parameter a description and a string
441 representation of the default value for the parameter.  You do this by
442 having the values in the list returned by C<supported_parameters()> be
443 hash references instead of strings, with keys of C<name>,
444 C<description>, and C<default_string>.  For example,
445
446     sub supported_parameters {
447         return (
448             {
449                 name           => 'allowed_values',
450                 description    =>
451                     'Individual and ranges of values to allow, and/or "all_integers".',
452                 default_string => '0 1 2',
453             },
454             {
455                 name           => 'allowed_types',
456                 description    => 'Kind of literals to allow.',
457                 default_string => 'Float',
458             },
459         );
460     }
461
462 Note that use of constructors is
463 L<incompatible|/"Note On Constructors"> with specifying parameters in
464 this way.
465
466
467 =head2 Using C<supported_parameters()> to Get It Done For You
468
469 The C<supported_parameters()> discussion above showed how you could
470 help others with your Policy, but didn't do anything to make your life
471 as a Policy author easier; you still need to implement
472 C<initialize_if_enabled()> to access any configuration that the user
473 has specified.  To have the configuration automatically handled for
474 you, you need to declare how your parameters act by specifying a value
475 for their C<behavior>.  For example, the following declares that a
476 parameter allows the user to choose from five specific values and that
477 the user can select any combination of them:
478
479     sub supported_parameters {
480         return (
481             {
482                 name               => 'allowed_types',
483                 description        => 'Kind of literals to allow.',
484                 default_string     => 'Float',
485                 behavior           => 'enumeration',
486                 enumeration_values => [ qw{ Binary Exp Float Hex Octal } ],
487                 enumeration_allow_multiple_values => 1,
488             },
489         );
490     }
491
492 When you specify a behavior, parsing and validation of the
493 user-specified and default values is done for you and your
494 C<violates()> method can retrieve the value under the key of the
495 parameter name prefixed with an underscore, e.g., for the above
496 declaration, the parsed and validated value can be accessed via
497 C<<$self->{_allowed_types}>>.
498
499 The behaviors provide additional functionality to C<Perl::Critic>; for
500 more on this, see
501 L<Perl::Critic::PolicyParameter|Perl::Critic::PolicyParameter> and
502 L<Perl::Critic::PolicyParameter::Behavior|Perl::Critic::PolicyParameter::Behavior>.
503
504 The following discusses each of the supported behaviors and the
505 options they support.  For the full details of a behavior, see the
506 documentation for the implementing class.
507
508
509 =head3 "string"
510
511 Implemented in
512 L<Perl::Critic::PolicyParameter::Behavior::String|Perl::Critic::PolicyParameter::Behavior::String>.
513
514 The most basic of behaviors, the value of the parameter will be stored
515 in the Policy as a string.
516
517 This behavior is not configurable.
518
519 =head4 C<supported_parameters()> example
520
521     sub supported_parameters {
522         return (
523             {
524                 name           => 'a_string',
525                 description    => 'An example string.',
526                 default_string => 'blah blah blah',
527                 behavior       => 'string',
528             },
529         );
530     }
531
532
533 =head4 Access example
534
535     sub violates {
536         my ($self, $element, $document) = @_;
537
538         ...
539         my $string = $self->{_a_string};
540         ...
541     }
542
543
544 =head3 "boolean"
545
546 Implemented in
547 L<Perl::Critic::PolicyParameter::Behavior::Boolean|Perl::Critic::PolicyParameter::Behavior::Boolean>.
548
549 The value of the parameter will be either L<Perl::Critic::Utils/$TRUE>
550 or L<Perl::Critic::Utils/$FALSE>.
551
552 This behavior is not configurable.
553
554 =head4 C<supported_parameters()> example
555
556     sub supported_parameters {
557         return (
558             {
559                 name           => 'a_boolean',
560                 description    => 'An example boolean.',
561                 default_string => '1',
562                 behavior       => 'boolean',
563             },
564         );
565     }
566
567
568 =head4 Access example
569
570     sub violates {
571         my ($self, $element, $document) = @_;
572
573         ...
574         my $is_whatever = $self->{_a_boolean};
575         if ($is_whatever) {
576             ...
577         }
578         ...
579     }
580
581
582 =head3 "integer"
583
584 Implemented in
585 L<Perl::Critic::PolicyParameter::Behavior::Integer|Perl::Critic::PolicyParameter::Behavior::Integer>.
586
587 The value is validated against C<m/ \A [-+]? [1-9] [\d_]* \z /xms>
588 (with an special check for "0").  Notice that this means that
589 underscores are allowed in input values as with Perl numeric literals.
590
591 This takes two options, C<integer_minimum> and C<integer_maximum>,
592 which specify endpoints of an inclusive range to restrict the value
593 to.  Either, neither, or both may be specified.
594
595 =head4 C<supported_parameters()> example
596
597     sub supported_parameters {
598         return (
599             {
600                 name            => 'an_integer',
601                 description     => 'An example integer.',
602                 default_string  => '5',
603                 behavior        => 'integer',
604                 integer_minimum => 0,
605                 integer_maximum => 10,
606             },
607         );
608     }
609
610
611 =head4 Access example
612
613     sub violates {
614         my ($self, $element, $document) = @_;
615
616         ...
617         my $integer = $self->{_an_integer};
618         if ($integer > $TURNING_POINT) {
619             ...
620         }
621         ...
622     }
623
624
625 =head3 "string list"
626
627 Implemented in
628 L<Perl::Critic::PolicyParameter::Behavior::StringList|Perl::Critic::PolicyParameter::Behavior::StringList>.
629
630 The values will be derived by splitting the input string on blanks.
631 (See L<Perl::Critic::Utils/"words_from_string">.) The parameter will
632 be stored as a reference to a hash, with the values being the keys.
633
634 This takes one optional option, C<always_present_values>, of a
635 reference to an array of strings that will always be included in the
636 parameter value, e.g. if the value of this option is C<[ qw{ a b c }
637 ]> and the user specifies a value of C<'c d e'>, then the value of the
638 parameter will contain C<'a'>, C<'b'>, C<'c'>, C<'d'>, and C<'e'>.
639
640 =head4 C<supported_parameters()> example
641
642     sub supported_parameters {
643         return (
644             {
645                 name                  => 'a_string_list',
646                 description           => 'An example list.',
647                 default_string        => 'red pink blue',
648                 behavior              => 'string list',
649                 always_present_values => [ qw{ green purple} ],
650             },
651         );
652     }
653
654
655 =head4 Access example
656
657     sub violates {
658         my ($self, $element, $document) = @_;
659
660         ...
661         my $list = $self->{_a_string_list};
662         my @list = keys %{$list};
663         ...
664         return if not $list->{ $element->content() };
665         ...
666     }
667
668
669 =head3 "enumeration"
670
671 Implemented in
672 L<Perl::Critic::PolicyParameter::Behavior::Enumeration|Perl::Critic::PolicyParameter::Behavior::Enumeration>.
673
674 The values will be derived by splitting the input string on blanks.
675 (See L<Perl::Critic::Utils/"words_from_string">.)  Depending upon the
676 value of the C<enumeration_allow_multiple_values> option, the
677 parameter will be stored as a string or a reference to a hash, with
678 the values being the keys.
679
680 This behavior takes one required option and one optional one.  A value
681 for C<enumeration_values> of a reference to an array of valid strings
682 is required.  A true value can be specified for
683 C<enumeration_allow_multiple_values> to allow the user to pick more
684 than one value, but this defaults to false.
685
686 =head4 C<supported_parameters()> example
687
688     use Perl::Critic::Utils qw{ :characters };
689
690     sub supported_parameters {
691         return (
692             {
693                 name               => 'a_single_valued_enumeration',
694                 description        =>
695                     'An example enumeration that can only have a single value.',
696                 default_string     => $EMPTY,
697                 behavior           => 'enumeration',
698                 enumeration_values => [ qw{ block statement pod operator } ],
699                 enumeration_allow_multiple_values => 0,
700             },
701             {
702                 name               => 'a_multi_valued_enumeration',
703                 description        =>
704                     'An example enumeration that can have multiple values.',
705                 default_string     => 'fe',
706                 behavior           => 'enumeration',
707                 enumeration_values => [ qw{ fe fi fo fum } ],
708                 enumeration_allow_multiple_values => 1,
709             },
710         );
711     }
712
713
714 =head4 Access example
715
716     sub violates {
717         my ($self, $element, $document) = @_;
718
719         ...
720         my $single_value = $self->{_a_single_valued_enumeration};
721         ...
722         my $multi_value = $self->{_a_multi_valued_enumeration};
723         if ( $multi_value->{fum} ) {
724             ...
725         }
726         ...
727     }
728
729
730 =head2 Using a Custom Parser
731
732 If none of the behaviors does exactly what you want it to, you can
733 provide your own parser for a parameter.  The reason for doing this as
734 opposed to using an implementation of C<initialize_if_enabled()> is
735 that it allows you to use a behavior to provide its extra
736 functionality and it provides a means for a C<Perl::Critic>
737 configuration program, e.g. an IDE that integrates C<Perl::Critic>, to
738 validate your parameter as the user modifies its value.
739
740 The way you declare that you have a custom parser is to include a
741 reference to it in the parameter specification with the C<parser> key.
742 For example:
743
744     sub supported_parameters {
745         return (
746             {
747                 name           => 'file_name',
748                 description    => 'A file for to read a list of values from.',
749                 default_string => undef,
750                 behavior       => 'string',
751                 parser         => \&_parse_file_name,
752             },
753         );
754     }
755
756 A parser is a method on a subclass of
757 L<Perl::Critic::Policy|Perl::Critic::Policy> that takes two
758 parameters: the
759 L<Perl::Critic::PolicyParameter|Perl::Critic::PolicyParameter> that is
760 being specified and the value string provided by the user.  The method
761 is responsible for dealing with any default value and for saving the
762 parsed value for later use by the C<violates()> method.
763
764 An example parser (without enough error handling) for the above
765 example declaration:
766
767     use File::Slurp qw< slurp >;
768
769     use Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue
770         qw{ throw_policy_value };
771
772     sub _parse_file_name {
773         my ($self, $parameter, $config_string) = @_;
774
775         my @thingies;
776
777         if ($config_string) {
778             if (not -r $config_string) {
779                 throw_policy_value
780                     policy         => $self->get_short_name(),
781                     option_name    => $parameter->get_name(),
782                     option_value   => $config_string,
783                     message_suffix => 'is not readable.';
784             }
785
786             @thingies = slurp $config_string;
787         }
788
789         $self->{_thingies} = \@thingies;
790
791         return;
792     }
793
794 Note that, if the value for the parameter is not valid, an instance of
795 L<Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue|Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue>
796 is thrown.  This allows C<Perl::Critic> to include that problem along
797 with any other problems found with the user's configuration in a
798 single error message.
799
800
801 =head2 Using Both C<supported_parameters()> and C<initialize_if_enabled()>
802
803 There are cases where a Policy needs additional initialization beyond
804 configuration or where the way it acts depends upon the combination of
805 multiple parameters.  In such situations, you will need to create an
806 implementation of C<initialize_if_enabled()>.  If you want to take
807 advantage of the supplied parameter handling from within
808 implementation of C<initialize_if_enabled()>, note that the
809 information from C<supported_parameters()> will already have been
810 used, with user-supplied parameter values validated and placed into
811 the Policy by the time C<initialize_if_enabled()> has been called.  It
812 is likely that you will not need to refer the contents of the
813 C<$config> parameter; just pull the information you need out of
814 C<$self>.  In fact, any value for the parameter values will be gone.
815
816
817
818 =head2 Summary of permitted hash keys in C<supported_parameters()>.
819
820
821 =head3 All types
822
823
824 =over
825
826 =item - "name" (mandatory)
827
828 =item - "description" (optional)
829
830 =item - "behavior" (optional)
831
832 Currently, one of:
833
834 =over
835
836 =item "boolean"
837
838 =item "enumeration"
839
840 =item "integer"
841
842 =item "string"
843
844 =item "string list"
845
846 =back
847
848 =item - "default_string" (optional)
849
850 A string representation of the default value of the parameter.
851
852 =item - "parser" (optional)
853
854 A code ref to a custom parser for the parameter.
855
856 =back
857
858 =head3 Enumerations
859
860 =over
861
862 =item - "enumeration_values" (mandatory)
863
864 A mandatory reference to an array of strings.
865
866 =item - "enumeration_allow_multiple_values" (optional)
867
868 Boolean indicating whether or not the user is restricted to a single
869 value.
870
871 =back
872
873 =head3 Integers
874
875 =over
876
877 =item - "integer_minimum" (optional)
878
879 Minimum allowed value, inclusive.
880
881 =item - "integer_maximum" (optional)
882
883 Maximum allowed value, inclusive.
884
885 =back
886
887 =head3 String lists
888
889 =over
890
891 =item - "list_always_present_values" (optional)
892
893 A reference to an array of values that should always be included in
894 the value of the parameter.
895
896 =back
897
898
899 =head1 ADDITIONAL FEATURES
900
901 =head2 C<default_maximum_violations_per_document()>
902
903 Certain problems that a Policy detects can be endemic to a particular
904 file; if there's one violation, there's likely to be many.  A good
905 example of this is
906 L<Perl::Critic::Policy::TestingAndDebugging::RequireUseStrict|Perl::Critic::Policy::TestingAndDebugging::RequireUseStrict>;
907 if there's one line before L<use strict>, there's a good chance that
908 the entire file is missing L<use strict>.  In such cases, it's not
909 much help to the user to report every single violation.  If you've got
910 such a policy, you should override
911 L<default_maximum_violations_per_document()|Perl::Critic::Policy/"default_maximum_violations_per_document()">
912 method to provide a limit.  The user can override this value with a
913 value for "maximum_violations_per_document" in their F<.perlcriticrc>.
914
915 See the source code for
916 L<Perl::Critic::Policy::ValuesAndExpressions::ProhibitMagicNumbers|Perl::Critic::Policy::ValuesAndExpressions::ProhibitMagicNumbers>
917 and
918 L<Perl::Critic::Policy::TestingAndDebugging::RequireUseWarnings|Perl::Critic::Policy::TestingAndDebugging::RequireUseWarnings>
919 for examples.
920
921
922 =head1 DISTRIBUTING YOUR POLICIES
923
924 =head2 Create a Distribution
925
926 You need to come up with a name for your set of policies.  Sets of
927 add-on policies are generally named C<Perl::Critic::I<something>>,
928 e.g. L<Perl::Critic::More|Perl::Critic::More>.
929
930 The module representing the distribution will not actually have any
931 functionality; it's just documentation and a name for users to use
932 when installing via L<CPAN|CPAN>/L<CPANPLUS|CPANPLUS>.  The important
933 part is that this will include a list of the included policies, with
934 descriptions of each.
935
936 A typical implementation will look like:
937
938     package Perl::Critic::Example;
939
940     use strict;
941     use warnings;
942
943     our $VERSION = '1.000000';
944
945     1; # Magic true value required at end of module
946
947     __END__
948
949     =head1 NAME
950
951     Perl::Critic::Example - Policies for Perl::Critic that act as an example.
952
953     =head1 AFFILIATION
954
955     This module has no functionality, but instead contains documentation
956     for this distribution and acts as a means of pulling other modules
957     into a bundle.  All of the Policy modules contained herein will have
958     an "AFFILIATION" section announcing their participation in this
959     grouping.
960
961
962     =head1 SYNOPSIS
963
964     Some L<Perl::Critic|Perl::Critic> policies that will help you keep your code
965     nice and compliant.
966
967
968     =head1 DESCRIPTION
969
970     The included policies are:
971
972     =over
973
974     =item L<Perl::Critic::Policy::Documentation::Example|Perl::Critic::Policy::Documentation::Example>
975
976     Complains about some example documentation issues.  [Severity: 3]
977
978
979     =item L<Perl::Critic::Policy::Variables::Example|Perl::Critic::Policy::Variables::Example>
980
981     All modules must have at least one variable.  [Severity: 3]
982
983
984     =back
985
986
987     =head1 CONFIGURATION AND ENVIRONMENT
988
989     All policies included are in the "example" theme.  See the
990     L<Perl::Critic|Perl::Critic> documentation for how to make use of this.
991
992
993 =head2 Themes
994
995 Users can choose which policies to enable using themes.  You should
996 implement C<default_themes()> so that users can take advantage of
997 this.  In particular, you should use a theme named after your
998 distribution in all your policies; this should match the value listed
999 in the C<CONFIGURATION AND ENVIRONMENT> POD section as shown above.
1000
1001     default_themes { return qw< example math > }
1002
1003 If you're looking for ideas of what themes to do, have a look at the
1004 output of C<perlcritic --list-themes>.
1005
1006
1007 =head2 Documentation
1008
1009 =head3 AFFILIATION
1010
1011 Since all policies have to go somewhere under the
1012 C<Perl::Critic::Policy::> namespace, it isn't always clear what
1013 distribution a policy came from when browsing through their
1014 documentation.  For this reason, you should include an C<AFFILIATION>
1015 section in the POD for all of your policies that state where the
1016 policy comes from.  For example:
1017
1018     =head1 AFFILIATION
1019
1020     This policy is part of L<Perl::Critic::Example|Perl::Critic::Example>.
1021
1022
1023 =head3 CONFIGURATION
1024
1025 In order to make it clear what can be done with a policy, you should
1026 always include a C<CONFIGURATION> section in your POD, even if it's
1027 only to say:
1028
1029     =head1 CONFIGURATION
1030
1031     This Policy is not configurable except for the standard options.
1032
1033
1034 =head1 HINT
1035
1036 When you're trying to figure out what L<PPI|PPI> is going to hand you
1037 for a chunk of code, there is a F<tools/ppidump> program in the
1038 L<Perl::Critic|Perl::Critic> distribution that will help you.  For
1039 example, when developing the above RequireBlockGrep example, you might
1040 want to try
1041
1042     tools/ppidump '@matches = grep /pattern/, @list;'
1043
1044 and
1045
1046     tools/ppidump '@matches = grep { /pattern/ } @list;'
1047
1048 to see the differences between the two cases.
1049
1050
1051 =head1 VERSION
1052
1053 This is part of L<Perl::Critic|Perl::Critic> version 1.088.
1054
1055
1056 =head1 AUTHOR
1057
1058 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
1059
1060
1061 =head1 COPYRIGHT
1062
1063 Copyright (c) 2005-2008 Jeffrey Ryan Thalhammer.  All rights reserved.
1064
1065 This program is free software; you can redistribute it and/or modify
1066 it under the same terms as Perl itself.  The full text of this license
1067 can be found in the LICENSE file included with this module.
1068
1069 =cut
1070
1071 ##############################################################################
1072 # Local Variables:
1073 #   mode: cperl
1074 #   cperl-indent-level: 4
1075 #   fill-column: 78
1076 #   indent-tabs-mode: nil
1077 #   c-indentation-style: bsd
1078 # End:
1079 # ex: set ts=8 sts=4 sw=4 tw=70 ft=pod expandtab shiftround :