1Perl::Critic::Utils(3)User Contributed Perl DocumentationPerl::Critic::Utils(3)
2
3
4

NAME

6       Perl::Critic::Utils - General utility subroutines and constants for
7       Perl::Critic and derivative distributions.
8

DESCRIPTION

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

INTERFACE SUPPORT

15       This is considered to be a public module.  Any changes to its interface
16       will go through a deprecation cycle.
17

IMPORTABLE SUBS

19       "find_keywords( $doc, $keyword )"
20           DEPRECATED: Since version 0.11, every Policy is evaluated at each
21           element of the document.  So you shouldn't need to go looking for a
22           particular keyword.  If you do want to use this, please import it
23           via the ":deprecated" tag, rather than directly, to mark the module
24           as needing updating.
25
26           Given a PPI::Document as $doc, returns a reference to an array
27           containing all the PPI::Token::Word elements that match $keyword.
28           This can be used to find any built-in function, method call,
29           bareword, or reserved keyword.  It will not match variables,
30           subroutine names, literal strings, numbers, or symbols.  If the
31           document doesn't contain any matches, returns undef.
32
33       is_assignment_operator( $element )
34           Given a PPI::Token::Operator or a string, returns true if that
35           token represents one of the assignment operators (e.g. "= &&= ||=
36           //= += -=" etc.).
37
38       is_perl_global( $element )
39           Given a PPI::Token::Symbol or a string, returns true if that token
40           represents one of the global variables provided by the English
41           module, or one of the builtin global variables like %SIG, %ENV, or
42           @ARGV.  The sigil on the symbol is ignored, so things like $ARGV or
43           $ENV will still return true.
44
45       is_perl_builtin( $element )
46           Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
47           true if that token represents a call to any of the builtin
48           functions.
49
50       is_perl_bareword( $element )
51           Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
52           true if that token represents a bareword (e.g. "if", "else", "sub",
53           "package").
54
55       is_perl_filehandle( $element )
56           Given a PPI::Token::Word, or string, returns true if that token
57           represents one of the global filehandles (e.g. "STDIN", "STDERR",
58           "STDOUT", "ARGV").  Note that this function will return false if
59           given a filehandle that is represented as a typeglob (e.g. *STDIN)
60
61       is_perl_builtin_with_list_context( $element )
62           Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
63           true if that token represents a call to any of the builtin
64           functions that provide a list context to the following tokens.
65
66       is_perl_builtin_with_multiple_arguments( $element )
67           Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
68           true if that token represents a call to any of the builtin
69           functions that can take multiple arguments.
70
71       is_perl_builtin_with_no_arguments( $element )
72           Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
73           true if that token represents a call to any of the builtin
74           functions that cannot take any arguments.
75
76       is_perl_builtin_with_one_argument( $element )
77           Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
78           true if that token represents a call to any of the builtin
79           functions that takes one and only one argument.
80
81       is_perl_builtin_with_optional_argument( $element )
82           Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
83           true if that token represents a call to any of the builtin
84           functions that takes no more than one argument.
85
86           The sets of values for which
87           is_perl_builtin_with_multiple_arguments(),
88           is_perl_builtin_with_no_arguments(),
89           is_perl_builtin_with_one_argument(), and
90           is_perl_builtin_with_optional_argument() return true are disjoint
91           and their union is precisely the set of values that
92           is_perl_builtin() will return true for.
93
94       is_perl_builtin_with_zero_and_or_one_arguments( $element )
95           Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
96           true if that token represents a call to any of the builtin
97           functions that takes no and/or one argument.
98
99           Returns true if any of is_perl_builtin_with_no_arguments(),
100           is_perl_builtin_with_one_argument(), and
101           is_perl_builtin_with_optional_argument() returns true.
102
103       is_qualified_name( $name )
104           Given a string, PPI::Token::Word, or PPI::Token::Symbol, answers
105           whether it has a module component, i.e. contains "::".
106
107       precedence_of( $element )
108           Given a PPI::Token::Operator or a string, returns the precedence of
109           the operator, where 1 is the highest precedence.  Returns undef if
110           the precedence can't be determined (which is usually because it is
111           not an operator).
112
113       is_hash_key( $element )
114           Given a PPI::Element, returns true if the element is a literal hash
115           key.  PPI doesn't distinguish between regular barewords (like
116           keywords or subroutine calls) and barewords in hash subscripts
117           (which are considered literal).  So this subroutine is useful if
118           your Policy is searching for PPI::Token::Word elements and you want
119           to filter out the hash subscript variety.  In both of the following
120           examples, "foo" is considered a hash key:
121
122               $hash1{foo} = 1;
123               %hash2 = (foo => 1);
124
125           But if the bareword is followed by an argument list, then perl
126           treats it as a function call.  So in these examples, "foo" is not
127           considered a hash key:
128
129               $hash1{ foo() } = 1;
130               &hash2 = (foo() => 1);
131
132       is_included_module_name( $element )
133           Given a PPI::Token::Word, returns true if the element is the name
134           of a module that is being included via "use", "require", or "no".
135
136       is_integer( $value )
137           Answers whether the parameter, as a string, looks like an integral
138           value.
139
140       is_class_name( $element )
141           Given a PPI::Token::Word, returns true if the element that
142           immediately follows this element is the dereference operator "->".
143           When a bareword has a "->" on the right side, it usually means that
144           it is the name of the class (from which a method is being called).
145
146       is_label_pointer( $element )
147           Given a PPI::Token::Word, returns true if the element is the label
148           in a "next", "last", "redo", or "goto" statement.  Note this is not
149           the same thing as the label declaration.
150
151       is_method_call( $element )
152           Given a PPI::Token::Word, returns true if the element that
153           immediately precedes this element is the dereference operator "->".
154           When a bareword has a "->" on the left side, it usually means that
155           it is the name of a method (that is being called from a class).
156
157       is_package_declaration( $element )
158           Given a PPI::Token::Word, returns true if the element is the name
159           of a package that is being declared.
160
161       is_subroutine_name( $element )
162           Given a PPI::Token::Word, returns true if the element is the name
163           of a subroutine declaration.  This is useful for distinguishing
164           barewords and from function calls from subroutine declarations.
165
166       is_function_call( $element )
167           Given a PPI::Token::Word returns true if the element appears to be
168           call to a static function.  Specifically, this function returns
169           true if "is_hash_key", "is_method_call", "is_subroutine_name",
170           "is_included_module_name", "is_package_declaration",
171           "is_perl_bareword", "is_perl_filehandle", "is_label_pointer" and
172           "is_subroutine_name" all return false for the given element.
173
174       first_arg( $element )
175           Given a PPI::Element that is presumed to be a function call (which
176           is usually a PPI::Token::Word), return the first argument.  This is
177           similar of parse_arg_list() and follows the same logic.  Note that
178           for the code:
179
180               int($x + 0.5)
181
182           this function will return just the $x, not the whole expression.
183           This is different from the behavior of parse_arg_list().  Another
184           caveat is:
185
186               int(($x + $y) + 0.5)
187
188           which returns "($x + $y)" as a PPI::Structure::List instance.
189
190       parse_arg_list( $element )
191           Given a PPI::Element that is presumed to be a function call (which
192           is usually a PPI::Token::Word), splits the argument expressions
193           into arrays of tokens.  Returns a list containing references to
194           each of those arrays.  This is useful because parentheses are
195           optional when calling a function, and PPI parses them very
196           differently.  So this method is a poor-man's parse tree of PPI
197           nodes.  It's not bullet-proof because it doesn't respect
198           precedence.  In general, I don't like the way this function works,
199           so don't count on it to be stable (or even present).
200
201       split_nodes_on_comma( @nodes )
202           This has the same return type as parse_arg_list() but expects to be
203           passed the nodes that represent the interior of a list, like:
204
205               'foo', 1, 2, 'bar'
206
207       is_script( $document )
208           This subroutine is deprecated and will be removed in a future
209           release. You should use the "is_program()" in
210           Perl::Critic::Document method instead.
211
212       is_in_void_context( $token )
213           Given a PPI::Token, answer whether it appears to be in a void
214           context.
215
216       policy_long_name( $policy_name )
217           Given a policy class name in long or short form, return the long
218           form.
219
220       policy_short_name( $policy_name )
221           Given a policy class name in long or short form, return the short
222           form.
223
224       all_perl_files( @directories )
225           Given a list of directories, recursively searches through all the
226           directories (depth first) and returns a list of paths for all the
227           files that are Perl code files.  Any administrative files for CVS
228           or Subversion are skipped, as are things that look like temporary
229           or backup files.
230
231           A Perl code file is:
232
233           •   Any file that ends in .PL, .pl, .pm, .psgi, or .t
234
235           •   Any file that has a first line with a shebang containing 'perl'
236
237       severity_to_number( $severity )
238           If $severity is given as an integer, this function returns
239           $severity but normalized to lie between $SEVERITY_LOWEST and
240           $SEVERITY_HIGHEST.  If $severity is given as a string, this
241           function returns the corresponding severity number.  If the string
242           doesn't have a corresponding number, this function will throw an
243           exception.
244
245       is_valid_numeric_verbosity( $severity )
246           Answers whether the argument has a translation to a Violation
247           format.
248
249       verbosity_to_format( $verbosity_level )
250           Given a verbosity level between 1 and 10, returns the corresponding
251           predefined format string.  These formats are suitable for passing
252           to the "set_format" method in Perl::Critic::Violation.  See the
253           perlcritic documentation for a listing of the predefined formats.
254
255       hashify( @list )
256           Given @list, return a hash where @list is in the keys and each
257           value is 1.  Duplicate values in @list are silently squished.
258
259       interpolate( $literal )
260           Given a $literal string that may contain control characters (e.g..
261           '\t' '\n'), this function does a double interpolation on the string
262           and returns it as if it had been declared in double quotes.  For
263           example:
264
265               'foo \t bar \n' ...becomes... "foo \t bar \n"
266
267       shebang_line( $document )
268           Given a PPI::Document, test if it starts with "#!".  If so, return
269           that line.  Otherwise return undef.
270
271       words_from_string( $str )
272           Given config string $str, return all the words from the string.
273           This is safer than splitting on whitespace.
274
275       "is_unchecked_call( $element, $autodie_modules )"
276           Given a PPI::Element, test to see if it contains a function call
277           whose return value is not checked. The second argument is an array
278           reference of module names which export "autodie". The "autodie"
279           module is always included in this list by default.
280

IMPORTABLE VARIABLES

282       $COMMA
283       $FATCOMMA
284       $COLON
285       $SCOLON
286       $QUOTE
287       $DQUOTE
288       $BACKTICK
289       $PERIOD
290       $PIPE
291       $EMPTY
292       $EQUAL
293       $SPACE
294       $SLASH
295       $BSLASH
296       $LEFT_PAREN
297       $RIGHT_PAREN
298           These character constants give clear names to commonly-used strings
299           that can be hard to read when surrounded by quotes and other
300           punctuation.  Can be imported in one go via the ":characters" tag.
301
302       $SEVERITY_HIGHEST
303       $SEVERITY_HIGH
304       $SEVERITY_MEDIUM
305       $SEVERITY_LOW
306       $SEVERITY_LOWEST
307           These numeric constants define the relative severity of violating
308           each Perl::Critic::Policy.  The "get_severity" and
309           "default_severity" methods of every Policy subclass must return one
310           of these values. Can be imported via the ":severities" tag.
311
312       $DEFAULT_VERBOSITY
313           The default numeric verbosity.
314
315       $DEFAULT_VERBOSITY_WITH_FILE_NAME
316           The numeric verbosity that corresponds to the format indicated by
317           $DEFAULT_VERBOSITY, but with the file name prefixed to it.
318
319       $TRUE
320       $FALSE
321           These are simple booleans. 1 and 0 respectively.  Be mindful of
322           using these with string equality.  "$FALSE ne $EMPTY".  Can be
323           imported via the ":booleans" tag.
324

IMPORT TAGS

326       The following groups of functions and constants are available as
327       parameters to a "use Perl::Critic::Util" statement.
328
329       ":all"
330           The lot.
331
332       ":booleans"
333           Includes: $TRUE, $FALSE
334
335       ":severities"
336           Includes: $SEVERITY_HIGHEST, $SEVERITY_HIGH, $SEVERITY_MEDIUM,
337           $SEVERITY_LOW, $SEVERITY_LOWEST, @SEVERITY_NAMES
338
339       ":characters"
340           Includes: $COLON, $COMMA, $DQUOTE, $EMPTY, $FATCOMMA, $PERIOD,
341           $PIPE, $QUOTE, $BACKTICK, $SCOLON, $SPACE, $SLASH, $BSLASH
342           $LEFT_PAREN $RIGHT_PAREN
343
344       ":classification"
345           Includes: "is_assignment_operator", "is_class_name",
346           "is_function_call", "is_hash_key", "is_included_module_name",
347           "is_integer", "is_label_pointer", "is_method_call",
348           "is_package_declaration", "is_perl_bareword", "is_perl_builtin",
349           "is_perl_filehandle", "is_perl_global",
350           "is_perl_builtin_with_list_context"
351           "is_perl_builtin_with_multiple_arguments"
352           "is_perl_builtin_with_no_arguments"
353           "is_perl_builtin_with_one_argument"
354           "is_perl_builtin_with_optional_argument"
355           "is_perl_builtin_with_zero_and_or_one_arguments"
356           "is_qualified_name", "is_script", "is_subroutine_name",
357           "is_unchecked_call" "is_valid_numeric_verbosity"
358
359           See also Perl::Critic::Utils::PPI.
360
361       ":data_conversion"
362           Generic manipulation, not having anything specific to do with
363           Perl::Critic.
364
365           Includes: "hashify", "words_from_string", "interpolate"
366
367       ":ppi"
368           Things for dealing with PPI, other than classification.
369
370           Includes: "first_arg", "parse_arg_list"
371
372           See also Perl::Critic::Utils::PPI.
373
374       ":internal_lookup"
375           Translations between internal representations.
376
377           Includes: "severity_to_number", "verbosity_to_format"
378
379       ":language"
380           Information about Perl not programmatically available elsewhere.
381
382           Includes: "precedence_of"
383
384       ":deprecated"
385           Not surprisingly, things that are deprecated.  It is preferred to
386           use this tag to get to these functions, rather than the function
387           names themselves, so as to mark any module using them as needing
388           cleanup.
389
390           Includes: "find_keywords"
391

SEE ALSO

393       Perl::Critic::Utils::Constants, Perl::Critic::Utils::McCabe,
394       Perl::Critic::Utils::PPI,
395

AUTHOR

397       Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
398
400       Copyright (c) 2005-2023 Imaginative Software Systems
401
402       This program is free software; you can redistribute it and/or modify it
403       under the same terms as Perl itself.  The full text of this license can
404       be found in the LICENSE file included with this module.
405
406
407
408perl v5.36.0                      2023-03-05            Perl::Critic::Utils(3)
Impressum