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

NAME

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

DESCRIPTION

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

IMPORTABLE 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. If you do want to use this, please import it via the :deprecated tag, rather than directly, to mark the module as needing updating.

Given a the PPI::Document manpage as $doc, returns a reference to an array containing all the the PPI::Token::Word manpage 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 the PPI::Token::Symbol manpage or a string, returns true if that token represents one of the global variables provided by the the English manpage 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 the PPI::Token::Word manpage, the PPI::Statement::Sub manpage, or string, returns true if that token represents a call to any of the builtin functions defined in Perl 5.8.8.

is_perl_bareword( $element )

Given a the PPI::Token::Word manpage, the PPI::Statement::Sub manpage, or string, returns true if that token represents a bareword (e.g. ``if'', ``else'', ``sub'', ``package'') defined in Perl 5.8.8.

is_perl_filehandle( $element )

Given a the PPI::Token::Word manpage, or string, returns true if that token represents one of the global filehandles (e.g. STDIN, STDERR, STDOUT, ARGV) that are defined in Perl 5.8.8. Note that this function will return false if given a filehandle that is represented as a typeglob (e.g. *STDIN)

is_perl_builtin_with_list_context( $element )

Given a the PPI::Token::Word manpage, the PPI::Statement::Sub manpage, or string, returns true if that token represents a call to any of the builtin functions defined in Perl 5.8.8 that provide a list context to the following tokens.

is_perl_builtin_with_multiple_arguments( $element )

is_perl_builtin_with_no_arguments( $element )

is_perl_builtin_with_one_argument( $element )

is_perl_builtin_with_optional_argument( $element )

The sets of values for which is_perl_builtin_with_multiple_arguments(), is_perl_builtin_with_no_arguments(), is_perl_builtin_with_one_argument(), and is_perl_builtin_with_optional_argument() return true are disjoint and their union is precisely the set of values that is_perl_builtin() will return true for.

is_perl_builtin_with_zero_and_or_one_arguments( $element )

Returns true if any of is_perl_builtin_with_no_arguments(), is_perl_builtin_with_one_argument(), and is_perl_builtin_with_optional_argument() returns true.

is_qualified_name( $name )

Given a string, the PPI::Token::Word manpage, or the PPI::Token::Symbol manpage, answers whether it has a module component, i.e. contains ``::''.

precedence_of( $element )

Given a the PPI::Token::Operator manpage 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 the PPI::Element manpage, returns true if the element is a literal 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 the PPI::Token::Word manpage 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);

But if the bareword is followed by an argument list, then perl treats it as a function call. So in these examples, ``foo'' is not considered a hash key:

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

is_included_module_name( $element )

Given a the PPI::Token::Word manpage, returns true if the element is the name of a module that is being included via use, require, or no.

is_integer( $value )

Answers whether the parameter, as a string, looks like an integral value.

is_class_name( $element )

Given a the PPI::Token::Word manpage, returns true if the element that immediately follows this element is the dereference operator ``->''. When a bareword has a ``->'' on the right side, it usually means that it is the name of the class (from which a method is being called).

is_label_pointer( $element )

Given a the PPI::Token::Word manpage, returns true if the element is the label in a next, last, redo, or goto statement. Note this is not the same thing as the label declaration.

is_method_call( $element )

Given a the PPI::Token::Word manpage, returns true if the element that immediately precedes this element is the dereference operator ``->''. When a bareword has a ``->'' on the left side, it usually means that it is the name of a method (that is being called from a class).

is_package_declaration( $element )

Given a the PPI::Token::Word manpage, returns true if the element is the name of a package that is being declared.

is_subroutine_name( $element )

Given a the PPI::Token::Word manpage, 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 the PPI::Token::Word manpage 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, is_subroutine_name, is_included_module_anme, is_package_declaration, is_perl_bareword, is_perl_filehandle, is_label_pointer and is_subroutine_name all return false for the given element.

first_arg( $element )

Given a the PPI::Element manpage that is presumed to be a function call (which is usually a the PPI::Token::Word manpage), return the first argument. This is similar of parse_arg_list() and follows the same logic. Note that for the code:

  int($x + 0.5)

this function will return just the $x, not the whole expression. This is different from the behavior of parse_arg_list(). Another caveat is:

  int(($x + $y) + 0.5)

which returns ($x + $y) as a the PPI::Structure::List manpage instance.

parse_arg_list( $element )

Given a the PPI::Element manpage that is presumed to be a function call (which is usually a the PPI::Token::Word manpage), 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).

split_nodes_on_comma( @nodes )

This has the same return type as parse_arg_list() but expects to be passed the nodes that represent the interior of a list, like:

  'foo', 1, 2, 'bar'

is_script( $document )

Given a the PPI::Document manpage, test if it starts with /#!.*/. If so, it is judged to be a script instead of a module. See shebang_line().

is_in_void_context( $token )

Given a the PPI::Token manpage, answer whether it appears to be in a void context.

policy_long_name( $policy_name )

Given a policy class name in long or short form, return the long form.

policy_short_name( $policy_name )

Given a policy class name in long or short form, return the short form.

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'

severity_to_number( $severity )

If $severity is given as an integer, this function returns $severity but normalized to lie between $SEVERITY_LOWEST and $SEVERITY_HIGHEST. If $severity is given as a string, this function returns the corresponding severity number. If the string doesn't have a corresponding number, this function will throw an exception.

is_valid_numeric_verbosity( $severity )

Answers whether the argument has a translation to a Violation format.

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 the Perl::Critic::Violation manpage. 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. Duplicate values in @list are silently squished.

interpolate( $literal )

Given a $literal string that may contain control characters (e.g.. '\t' '\n'), this function does a double interpolation on the string and returns it as if it had been declared in double quotes. For example:

  'foo \t bar \n' ...becomes... "foo \t bar \n"

shebang_line( $document )

Given a the PPI::Document manpage, test if it starts with #!. If so, return that line. Otherwise return undef.

words_from_string( $str )

Given config string $str, return all the words from the string. This is safer than splitting on whitespace.

is_unchecked_call( $element )

Given a the PPI::Element manpage, test to see if it contains a function call whose return value is not checked.

IMPORTABLE VARIABLES

$COMMA
$FATCOMMA
$COLON
$SCOLON
$QUOTE
$DQUOTE
$BACKTICK
$PERIOD
$PIPE
$EMPTY
$SPACE
$SLASH
$BSLASH
$LEFT_PAREN
$RIGHT_PAREN: These character constants give clear names to commonly-used strings that can be hard to read when surrounded by quotes and other punctuation. Can be imported in one go via the :characters tag.
$SEVERITY_HIGHEST
$SEVERITY_HIGH
$SEVERITY_MEDIUM
$SEVERITY_LOW
$SEVERITY_LOWEST: These numeric constants define the relative severity of violating each the Perl::Critic::Policy manpage. The get_severity and default_severity methods of every Policy subclass must return one of these values. Can be imported via the :severities tag.
$DEFAULT_VERBOSITY: The default numeric verbosity.
$DEFAULT_VERBOSITY_WITH_FILE_NAME: The numeric verbosity that corresponds to the format indicated by $DEFAULT_VERBOSITY, but with the file name prefixed to it.
$TRUE
$FALSE: These are simple booleans. 1 and 0 respectively. Be mindful of using these with string equality. $FALSE ne $EMPTY. Can be imported via the :booleans tag.

IMPORT TAGS

The following groups of functions and constants are available as parameters to a use Perl::Critic::Util statement.

:all: The lot.
:booleans: Includes: $TRUE, $FALSE
:severities: Includes: $SEVERITY_HIGHEST, $SEVERITY_HIGH, $SEVERITY_MEDIUM, $SEVERITY_LOW, $SEVERITY_LOWEST, @SEVERITY_NAMES
:characters: Includes: $COLON, $COMMA, $DQUOTE, $EMPTY, $FATCOMMA, $PERIOD, $PIPE, $QUOTE, $BACKTICK, $SCOLON, $SPACE, $SLASH, $BSLASH $LEFT_PAREN $RIGHT_PAREN
:classification: Includes: is_function_call, is_hash_key, is_included_module_name, is_integer, is_method_call, is_package_declaration, is_perl_builtin, is_perl_global, is_perl_builtin_with_list_context is_perl_builtin_with_multiple_arguments is_perl_builtin_with_no_arguments is_perl_builtin_with_one_argument is_perl_builtin_with_optional_argument is_perl_builtin_with_zero_and_or_one_arguments is_script, is_subroutine_name, is_unchecked_call is_valid_numeric_verbosity; See also the Perl::Critic::Utils::PPI manpage.
:data_conversion: Generic manipulation, not having anything specific to do with Perl::Critic.; Includes: hashify, words_from_string, interpolate
:ppi: Things for dealing with PPI, other than classification.; Includes: first_arg, parse_arg_list; See also the Perl::Critic::Utils::PPI manpage.
:internal_lookup: Translations between internal representations.; Includes: severity_to_number, verbosity_to_format
:language: Information about Perl not programmatically available elsewhere.; Includes: precedence_of
:deprecated: Not surprisingly, things that are deprecated. It is preferred to use this tag to get to these functions, rather than the function names themselves, so as to mark any module using them as needing cleanup.; Includes: find_keywords

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

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.

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