NAME

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

DESCRIPTION

This module 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 )

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.

Given a 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_perl_global( $element )

Given a PPI::Token::Symbol or a string, returns true if that token represents one of the global variables provided by the English module, or one of the builtin global variables like %SIG, %ENV, or @ARGV. The sigil on the symbol is ignored, so things like $ARGV or $ENV will still return true.

is_perl_builtin( $element )

Given a PPI::Token::Word or a string, returns true if that token represents a call to any of the builtin functions defined in Perl 5.8.8

precedence_of( $element )

Given a PPI::Token::Operator or a string, returns the precedence of the operator, where 1 is the highest precedence. Returns undef if the precedence can't be determined (which is usually because it is not an operator).

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. Basically, it just looks to see if the preceding operator is "->". This is useful for distinguishing static function calls from object method calls.

is_subroutine_name( $element )

Given a PPI::Token::Word, returns true if the element is the name of a subroutine declaration. This is useful for distinguishing barewords and from function calls from subroutine declarations.

is_function_call( $element )

Given a PPI::Token::Word returns true if the element appears to be call to a static function. Specifically, this function returns true if is_hash_key, is_method_call, and is_subroutine_name all return false for the given element.

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

is_script( $document )

Given a PPI::Document, test if it starts with /#!.*perl/. If so, it is judged to be a script instead of a module.

all_perl_files( @directories )

Given a list of directories, recursively searches through all the directories (depth first) and returns a list of paths for all the files that are Perl code files. Any administrative files for CVS or Subversion are skipped, as are things that look like temporary or backup files.

A Perl code file is:

• Any file that ends in .PL, .pl, .pm, or .t

• Any file that has a first line with a shebang containing 'perl'

verbosity_to_format( $verbosity_level )

Given a verbosity level between 1 and 10, returns the corresponding predefined format string. These formats are suitable for passing to the set_format method in Perl::Critic::Violation. See the perlcritic documentation for a listing of the predefined formats.

hashify( @list )

Given @list, return a hash where @list is in the keys and each value is 1.

EXPORTED VARIABLES

@BUILTINS

DEPRECATED: Use is_perl_builtin() instead.

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.

@GLOBALS

DEPRECATED: Use is_perl_global() instead.

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

$FATCOMMA

$COLON

$SCOLON

$QUOTE

$DQUOTE

$PERIOD

$PIPE

$EMPTY

$SPACE

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

$SEVERITY_HIGHEST

$SEVERITY_HIGH

$SEVERITY_MEDIUM

$SEVERITY_LOW

$SEVERITY_LOWEST

These numeric constants define the relative severity of violating each Perl::Critic::Policy. The get_severity and default_severity methods of every Policy subclass must return one of these values.

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