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

IMPORTABLE VARIABLES

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

IMPORT TAGS

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

SEE ALSO

397       Perl::Critic::Utils::Constants, Perl::Critic::Utils::McCabe,
398       Perl::Critic::Utils::PPI,
399

AUTHOR

401       Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
402
404       Copyright (c) 2005-2011 Imaginative Software Systems.  All rights
405       reserved.
406
407       This program is free software; you can redistribute it and/or modify it
408       under the same terms as Perl itself.  The full text of this license can
409       be found in the LICENSE file included with this module.
410
411
412
413perl v5.34.0                      2022-01-21            Perl::Critic::Utils(3)
Impressum