1Perl::Critic::Utils(3)User Contributed Perl DocumentationPerl::Critic::Utils(3)
2
6 Perl::Critic::Utils - Utility subs and vars for Perl::Critic
7
9 This module provides several static subs and variables that are useful
10 for developing Perl::Critic::Policy subclasses. Unless you are writing
11 Policy modules, you probably don't care about this package.
12
14 "find_keywords( $doc, $keyword )"
15 DEPRECATED: Since version 0.11, every Policy is evaluated at
16 each element of the document. So you shouldn't need to go
17 looking for a particular keyword. If you do want to use this,
18 please import it via the ":deprecated" tag, rather than
19 directly, to mark the module as needing updating.
20 Given a PPI::Document as $doc, returns a reference to an array
22 containing all the PPI::Token::Word elements that match $key‐
23 word. This can be used to find any built-in function, method
24 call, bareword, or reserved keyword. It will not match vari‐
25 ables, subroutine names, literal strings, numbers, or symbols.
26 If the document doesn't contain any matches, returns undef.
27 "is_perl_global( $element )"
29 Given a PPI::Token::Symbol or a string, returns true if that
30 token represents one of the global variables provided by the
31 English module, or one of the builtin global variables like
32 %SIG, %ENV, or @ARGV. The sigil on the symbol is ignored, so
33 things like $ARGV or $ENV will still return true.
34 "is_perl_builtin( $element )"
36 Given a PPI::Token::Word, PPI::Statement::Sub, or string,
37 returns true if that token represents a call to any of the
38 builtin functions defined in Perl 5.8.8.
39 "is_perl_builtin_with_list_context( $element )"
41 Given a PPI::Token::Word, PPI::Statement::Sub, or string,
42 returns true if that token represents a call to any of the
43 builtin functions defined in Perl 5.8.8 that provide a list
44 context to the following tokens.
45 "is_perl_builtin_with_multiple_arguments( $element )"
47 Given a PPI::Token::Word, PPI::Statement::Sub, or string,
48 returns true if that token represents a call to any of the
49 builtin functions defined in Perl 5.8.8 that can take multiple
50 arguments.
51 "is_perl_builtin_with_no_arguments( $element )"
53 Given a PPI::Token::Word, PPI::Statement::Sub, or string,
54 returns true if that token represents a call to any of the
55 builtin functions defined in Perl 5.8.8 that cannot take any
56 arguments.
57 "is_perl_builtin_with_one_argument( $element )"
59 Given a PPI::Token::Word, PPI::Statement::Sub, or string,
60 returns true if that token represents a call to any of the
61 builtin functions defined in Perl 5.8.8 that takes one and only
62 one argument.
63 "is_perl_builtin_with_optional_argument( $element )"
65 Given a PPI::Token::Word, PPI::Statement::Sub, or string,
66 returns true if that token represents a call to any of the
67 builtin functions defined in Perl 5.8.8 that takes no more than
68 one argument.
69 The sets of values for which "is_perl_builtin_with_multi‐
71 ple_arguments()", "is_perl_builtin_with_no_arguments()",
72 "is_perl_builtin_with_one_argument()", and
73 "is_perl_builtin_with_optional_argument()" return true are dis‐
74 joint and their union is precisely the set of values that
75 "is_perl_builtin()" will return true for.
76 "is_perl_builtin_with_zero_and_or_one_arguments( $element )"
78 Given a PPI::Token::Word, PPI::Statement::Sub, or string,
79 returns true if that token represents a call to any of the
80 builtin functions defined in Perl 5.8.8 that takes no and/or
81 one argument.
82 Returns true if any of "is_perl_builtin_with_no_arguments()",
84 "is_perl_builtin_with_one_argument()", and
85 "is_perl_builtin_with_optional_argument()" returns true.
86 "precedence_of( $element )"
88 Given a PPI::Token::Operator or a string, returns the prece‐
89 dence of the operator, where 1 is the highest precedence.
90 Returns undef if the precedence can't be determined (which is
91 usually because it is not an operator).
92 "is_hash_key( $element )"
94 Given a PPI::Element, returns true if the element is a hash
95 key. PPI doesn't distinguish between regular barewords (like
96 keywords or subroutine calls) and barewords in hash subscripts
97 (which are considered literal). So this subroutine is useful
98 if your Policy is searching for PPI::Token::Word elements and
99 you want to filter out the hash subscript variety. In both of
100 the following examples, 'foo' is considered a hash key:
101 $hash1{foo} = 1;
103 %hash2 = (foo => 1);
104 "is_method_call( $element )"
106 Given a PPI::Element that is presumed to be a function call
107 (which is usually a PPI::Token::Word), returns true if the
108 function is a method being called on some reference. Basi‐
109 cally, it just looks to see if the preceding operator is "->".
110 This is useful for distinguishing static function calls from
111 object method calls.
112 "is_subroutine_name( $element )"
114 Given a PPI::Token::Word, returns true if the element is the
115 name of a subroutine declaration. This is useful for distin‐
116 guishing barewords and from function calls from subroutine dec‐
117 larations.
118 "is_function_call( $element )"
120 Given a PPI::Token::Word returns true if the element appears to
121 be call to a static function. Specifically, this function
122 returns true if "is_hash_key", "is_method_call", and "is_sub‐
123 routine_name" all return false for the given element.
124 "first_arg( $element )"
126 Given a PPI::Element that is presumed to be a function call
127 (which is usually a PPI::Token::Word), return the first argu‐
128 ment. This is similar of "parse_arg_list()" and follows the
129 same logic. Note that for the code:
130 int($x + 0.5)
132 this function will return just the $x, not the whole expres‐
134 sion. This is different from the behavior of
135 "parse_arg_list()". Another caveat is:
136 int(($x + $y) + 0.5)
138 which returns "($x + $y)" as a PPI::Structure::List instance.
140 "parse_arg_list( $element )"
142 Given a PPI::Element that is presumed to be a function call
143 (which is usually a PPI::Token::Word), splits the argument
144 expressions into arrays of tokens. Returns a list containing
145 references to each of those arrays. This is useful because
146 parens are optional when calling a function, and PPI parses
147 them very differently. So this method is a poor-man's parse
148 tree of PPI nodes. It's not bullet-proof because it doesn't
149 respect precedence. In general, I don't like the way this
150 function works, so don't count on it to be stable (or even
151 present).
152 "is_script( $document )"
154 Given a PPI::Document, test if it starts with "/#!.*/". If so,
155 it is judged to be a script instead of a module. See "she‐
156 bang_line()".
157 " policy_long_name( $policy_name ) "
159 Given a policy class name in long or short form, return the
160 long form.
161 " policy_short_name( $policy_name ) "
163 Given a policy class name in long or short form, return the
164 short form.
165 "all_perl_files( @directories )"
167 Given a list of directories, recursively searches through all
168 the directories (depth first) and returns a list of paths for
169 all the files that are Perl code files. Any administrative
170 files for CVS or Subversion are skipped, as are things that
171 look like temporary or backup files.
172 A Perl code file is:
174 * Any file that ends in .PL, .pl, .pm, or .t
176 * Any file that has a first line with a shebang containing
177 'perl'
178 "severity_to_number( $severity )"
179 If $severity is given as an integer, this function returns
180 $severity but normalized to lie between $SEVERITY_LOWEST and
181 $SEVERITY_HIGHEST. If $severity is given as a string, this
182 function returns the corresponding severity number. If the
183 string doesn't have a corresponding number, this function will
184 throw an exception.
185 "verbosity_to_format( $verbosity_level )"
187 Given a verbosity level between 1 and 10, returns the corre‐
188 sponding predefined format string. These formats are suitable
189 for passing to the "set_format" method in Perl::Critic::Viola‐
190 tion. See the perlcritic documentation for a listing of the
191 predefined formats.
192 "hashify( @list )"
194 Given @list, return a hash where @list is in the keys and each
195 value is 1. Duplicate values in @list are silently squished.
196 "interpolate( $literal )"
198 Given a $literal string that may contain control characters
199 (e.g.. '\t' '\n'), this function does a double interpolation on
200 the string and returns it as if it had been declared in double
201 quotes. For example:
202 'foo \t bar \n' ...becomes... "foo \t bar \n"
204 "shebang_line( $document )"
206 Given a PPI::Document, test if it starts with "#!". If so,
207 return that line. Otherwise return undef.
208 "words_from_string( $str )"
210 Given config string $str, return all the words from the string.
211 This is safer than splitting on whitespace.
212 "is_unchecked_call( $element )"
214 Given a PPI::Element, test to see if it contains a function
215 call whose return value is not checked.
216
218 $COMMA
219 $FATCOMMA
220 $COLON
221 $SCOLON
222 $QUOTE
223 $DQUOTE
224 $PERIOD
225 $PIPE
226 $EMPTY
227 $SPACE
228 $SLASH
229 $BSLASH
230 $LEFT_PAREN
231 $RIGHT_PAREN
232 These character constants give clear names to commonly-used
233 strings that can be hard to read when surrounded by quotes and
234 other punctuation. Can be imported in one go via the ":charac‐
235 ters" tag.
236 $SEVERITY_HIGHEST
238 $SEVERITY_HIGH
239 $SEVERITY_MEDIUM
240 $SEVERITY_LOW
241 $SEVERITY_LOWEST
242 These numeric constants define the relative severity of violat‐
243 ing each Perl::Critic::Policy. The "get_severity" and
244 "default_severity" methods of every Policy subclass must return
245 one of these values. Can be imported via the ":severities" tag.
246 $TRUE
248 $FALSE These are simple booleans. 1 and 0 respectively. Be mindful of
249 using these with string equality. "$FALSE ne $EMPTY". Can be
250 imported via the ":booleans" tag.
251
253 The following groups of functions and constants are available as param‐
254 eters to a "use Perl::Critic::Util" statement.
255 ":all"
257 The lot.
258 ":booleans"
260 Includes: $TRUE, $FALSE
261 ":severities"
263 Includes: $SEVERITY_HIGHEST, $SEVERITY_HIGH, $SEVERITY_MEDIUM,
264 $SEVERITY_LOW, $SEVERITY_LOWEST, @SEVERITY_NAMES
265 ":characters"
267 Includes: $COLON, $COMMA, $DQUOTE, $EMPTY, $FATCOMMA, $PERIOD,
268 $PIPE, $QUOTE, $SCOLON, $SPACE, $SLASH, $BSLASH $LEFT_PAREN
269 $RIGHT_PAREN
270 ":classification"
272 Includes: &is_function_call, &is_hash_key, &is_method_call,
273 &is_perl_builtin, &is_perl_global, &is_script, &is_subroutine_name,
274 &is_unchecked_call
275 ":data_conversion"
277 Generic manipulation, not having anything specific to do with
278 Perl::Critic.
279 Includes: &hashify, &words_from_string, &interpolate
281 ":ppi"
283 Things for dealing with PPI, other than classification.
284 Includes: &first_arg, &parse_arg_list
286 ":internal_lookup"
288 Translations between internal representations.
289 Includes: &severity_to_number, &verbosity_to_format
291 ":language"
293 Information about Perl not programmatically available elsewhere.
294 Includes: &precedence_of
296 ":deprecated"
298 Not surprisingly, things that are deprecated. It is preferred to
299 use this tag to get to these functions, rather than the function
300 names themselves, so as to mark any module using them as needing
301 cleanup.
302 Includes: &find_keywords
304
306 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
307
309 Copyright (c) 2005-2007 Jeffrey Ryan Thalhammer. All rights reserved.
310 This program is free software; you can redistribute it and/or modify it
312 under the same terms as Perl itself. The full text of this license can
313 be found in the LICENSE file included with this module.
314perl v5.8.8 2007-03-20 Perl::Critic::Utils(3)