NAME

Perl::Critic::Utils - Utility subs and vars for Perl::Critic

DESCRIPTION

This module has exports several static subs and variables that are useful for developing Perl::Critic::Policy subclasses. Unless you are writing Policy modules, you probably don't care about this package.

EXPORTED SUBS

find_keywords( $doc, $keyword );

This function is deprecated! Since version 0.11, every Policy is evaluated at each element of the document. So you shouldn't need to go looking for a particular keyword. I've left this function in place just in case you come across a particular need for it.

Given PPI::Document as $doc, returns a reference to an array containing all the PPI::Token::Word elements that match $keyword. This can be used to find any built-in function, method call, bareword, or reserved keyword. It will not match variables, subroutine names, literal strings, numbers, or symbols. If the document doesn't contain any matches, returns undef.

is_hash_key( $element )

Given a PPI::Element, returns true if the element is a hash key. PPI doesn't distinguish between regular barewords (like keywords or subroutine calls) and barewords in hash subscripts (which are considered literal). So this subroutine is useful if your Policy is searching for PPI::Token::Word elements and you want to filter out the hash subscript variety. In both of the following examples, 'foo' is considered a hash key:

  $hash1{foo} = 1;
  %hash2 = (foo => 1);

is_method_call( $element )

Given a PPI::Element that is presumed to be a function call (which is usually a PPI::Token::Word, returns true if the function is a method being called on some reference. Baically, it just looks to see if the preceding operator is "->". This is usefull for distinguishing static from object methods.

parse_arg_list( $element )

Given a PPI::Element that is presumed to be a function call (which is usually a PPI::Token::Word), splits the argument expressions into arrays of tokens. Returns a list containing references to each of those arrays. This is useful because parens are optional when calling a function, and PPI parses them very differently. So this method is a poor-man's parse tree of PPI nodes. It's not bullet-proof because it doesn't respect precedence. In general, I don't like the way this function works, so don't count on it to be stable (or even present).

EXPORTED VARIABLES

@BUILTINS

This is a list of all the built-in functions provided by Perl 5.8. I imagine this is useful for distinguishing native and non-native function calls. In the future, I'm thinking of adding a hash that maps each built-in function to the maximal number of arguments that it accepts. I think this will help facilitate the lexing the children of PPI::Expression objects.

@GLOBALS

This is a list of all the magic global variables provided by the English module. Also includes commonly-used global like %SIG, %ENV, and @ARGV. The list contains only the variable name, without the sigil.

$COMMA

$COLON

$SCOLON

$QUOTE

$DQUOTE

$PERIOD

$PIPE

$EMPTY

These give clear names to commonly-used strings that can be hard to read when surrounded by quotes.

$TRUE

$FALSE

These are simple booleans. 1 and 0 respectively. Be mindful of using these with string equality. $FALSE ne $EMPTY.

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.