Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Perl::Critic::Utils(3)User Contributed Perl DocumentatioPerl::Critic::Utils(3)

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_assignment_operator(	$element )"
	   Given a PPI::Token::Operator	or a string, returns true if that
	   token represents one	of the assignment operators (e.g. "= &&= ||=
	   //= += -=" etc.).

       "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:

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

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

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_assignment_operator", "is_class_name",
	   "is_function_call", "is_hash_key", "is_included_module_name",
	   "is_integer", "is_label_pointer", "is_method_call",
	   "is_package_declaration", "is_perl_bareword", "is_perl_builtin",
	   "is_perl_filehandle", "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_qualified_name",	"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.

perl v5.24.1			  2017-07-02		Perl::Critic::Utils(3)

NAME | DESCRIPTION | INTERFACE SUPPORT | IMPORTABLE SUBS | IMPORTABLE VARIABLES | IMPORT TAGS | SEE ALSO | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Perl::Critic::Utils&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help