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

IMPORTABLE VARIABLES

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

IMPORT TAGS

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

SEE ALSO

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

AUTHOR

396       Jeffrey Ryan Thalhammer <thaljef@cpan.org>
397
399       Copyright (c) 2005-2009 Jeffrey Ryan Thalhammer.  All rights reserved.
400
401       This program is free software; you can redistribute it and/or modify it
402       under the same terms as Perl itself.  The full text of this license can
403       be found in the LICENSE file included with this module.
404
405
406
407perl v5.12.1                      2010-09-08            Perl::Critic::Utils(3)
Impressum