NAME¶
Perl::Critic::Utils - General utility subroutines and constants for Perl::Critic
and derivative distributions.
DESCRIPTION¶
This module provides 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.
INTERFACE SUPPORT¶
This is considered to be a public module. Any changes to its interface will go
through a deprecation cycle.
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 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, PPI::Statement::Sub, 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 PPI::Token::Word, PPI::Statement::Sub, 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 PPI::Token::Word, 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 PPI::Token::Word, PPI::Statement::Sub, 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
)"
- Given a PPI::Token::Word, PPI::Statement::Sub, or string,
returns true if that token represents a call to any of the builtin
functions defined in Perl 5.8.8 that can take multiple
arguments.
- "is_perl_builtin_with_no_arguments( $element
)"
- Given a PPI::Token::Word, PPI::Statement::Sub, or string,
returns true if that token represents a call to any of the builtin
functions defined in Perl 5.8.8 that cannot take any
arguments.
- "is_perl_builtin_with_one_argument( $element
)"
- Given a PPI::Token::Word, PPI::Statement::Sub, or string,
returns true if that token represents a call to any of the builtin
functions defined in Perl 5.8.8 that takes one and only one
argument.
- "is_perl_builtin_with_optional_argument( $element
)"
- Given a PPI::Token::Word, PPI::Statement::Sub, or string,
returns true if that token represents a call to any of the builtin
functions defined in Perl 5.8.8 that takes no more than one
argument.
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 )"
- Given a PPI::Token::Word, PPI::Statement::Sub, or string,
returns true if that token represents a call to any of the builtin
functions defined in Perl 5.8.8 that takes no and/or one argument.
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, PPI::Token::Word, or PPI::Token::Symbol,
answers whether it has a module component, i.e. contains
"::".
- "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
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 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);
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 PPI::Token::Word, 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 PPI::Token::Word, 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 PPI::Token::Word, 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 PPI::Token::Word, 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 PPI::Token::Word, returns true if the element is
the name of a package that is being declared.
- "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",
"is_subroutine_name", "is_included_module_name",
"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 PPI::Element that is presumed to be a function call
(which is usually a PPI::Token::Word), 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 PPI::Structure::List instance.
- "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 parentheses 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 )"
- This subroutine is deprecated and will be removed in a
future release. You should use the " is_program()" in
Perl::Critic::Document method instead.
- "is_in_void_context( $token )"
- Given a PPI::Token, 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 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. 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 PPI::Document, 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 PPI::Element, 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
- $EQUAL
- $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 Perl::Critic::Policy. 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.
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 Perl::Critic::Utils::PPI.
- ":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 Perl::Critic::Utils::PPI.
- ":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"
SEE ALSO¶
Perl::Critic::Utils::Constants, Perl::Critic::Utils::McCabe,
Perl::Critic::Utils::PPI,
AUTHOR¶
Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
COPYRIGHT¶
Copyright (c) 2005-2011 Imaginative Software Systems. 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.