PPIx::Utils::Classification(3pm)

1PPIx::Utils::ClassificaUtsieorn(C3o)ntributed Perl DocumPePnItxa:t:iUotnils::Classification(3)
2
3
4

NAME

6       PPIx::Utils::Classification - Utility functions for classification of
7       PPI elements
8

SYNOPSIS

10           use PPIx::Utils::Classification ':all';
11

DESCRIPTION

13       This package is a component of PPIx::Utils that contains functions for
14       classification of PPI elements.
15

FUNCTIONS

17       All functions can be imported by name, or with the tag ":all".
18
19   is_assignment_operator
20           my $bool = is_assignment_operator($element);
21
22       Given a PPI::Token::Operator or a string, returns true if that token
23       represents one of the assignment operators (e.g.  "= &&= ||= //= += -="
24       etc.).
25
26   is_perl_global
27           my $bool = is_perl_global($element);
28
29       Given a PPI::Token::Symbol or a string, returns true if that token
30       represents one of the global variables provided by the English module,
31       or one of the builtin global variables like %SIG, %ENV, or @ARGV.  The
32       sigil on the symbol is ignored, so things like $ARGV or $ENV will still
33       return true.
34
35   is_perl_builtin
36           my $bool = is_perl_builtin($element);
37
38       Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns true
39       if that token represents a call to any of the builtin functions defined
40       in Perl 5.8.8.
41
42   is_perl_bareword
43           my $bool = is_perl_bareword($element);
44
45       Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns true
46       if that token represents a bareword (e.g. "if", "else", "sub",
47       "package") defined in Perl 5.8.8.
48
49   is_perl_filehandle
50           my $bool = is_perl_filehandle($element);
51
52       Given a PPI::Token::Word, or string, returns true if that token
53       represents one of the global filehandles (e.g. "STDIN", "STDERR",
54       "STDOUT", "ARGV") that are defined in Perl 5.8.8.  Note that this
55       function will return false if given a filehandle that is represented as
56       a typeglob (e.g. *STDIN)
57
58   is_perl_builtin_with_list_context
59           my $bool = is_perl_builtin_with_list_context($element);
60
61       Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns true
62       if that token represents a call to any of the builtin functions defined
63       in Perl 5.8.8 that provide a list context to the following tokens.
64
65   is_perl_builtin_with_multiple_arguments
66           my $bool = is_perl_builtin_with_multiple_arguments($element);
67
68       Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns true
69       if that token represents a call to any of the builtin functions defined
70       in Perl 5.8.8 that can take multiple arguments.
71
72   is_perl_builtin_with_no_arguments
73           my $bool = is_perl_builtin_with_no_arguments($element);
74
75       Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns true
76       if that token represents a call to any of the builtin functions defined
77       in Perl 5.8.8 that cannot take any arguments.
78
79   is_perl_builtin_with_one_argument
80           my $bool = is_perl_builtin_with_one_argument($element);
81
82       Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns true
83       if that token represents a call to any of the builtin functions defined
84       in Perl 5.8.8 that takes one and only one argument.
85
86   is_perl_builtin_with_optional_argument
87           my $bool = is_perl_builtin_with_optional_argument($element);
88
89       Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns true
90       if that token represents a call to any of the builtin functions defined
91       in Perl 5.8.8 that takes no more than one argument.
92
93       The sets of values for which "is_perl_builtin_with_multiple_arguments",
94       "is_perl_builtin_with_no_arguments",
95       "is_perl_builtin_with_one_argument", and
96       "is_perl_builtin_with_optional_argument" return true are disjoint and
97       their union is precisely the set of values that "is_perl_builtin" will
98       return true for.
99
100   is_perl_builtin_with_zero_and_or_one_arguments
101           my $bool = is_perl_builtin_with_zero_and_or_one_arguments($element);
102
103       Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns true
104       if that token represents a call to any of the builtin functions defined
105       in Perl 5.8.8 that takes no and/or one argument.
106
107       Returns true if any of "is_perl_builtin_with_no_arguments",
108       "is_perl_builtin_with_one_argument", and
109       "is_perl_builtin_with_optional_argument" returns true.
110
111   is_qualified_name
112           my $bool = is_qualified_name($name);
113
114       Given a string, PPI::Token::Word, or PPI::Token::Symbol, answers
115       whether it has a module component, i.e. contains "::".
116
117   is_hash_key
118           my $bool = is_hash_key($element);
119
120       Given a PPI::Element, returns true if the element is a literal hash
121       key.  PPI doesn't distinguish between regular barewords (like keywords
122       or subroutine calls) and barewords in hash subscripts (which are
123       considered literal).  So this subroutine is useful if your Policy is
124       searching for PPI::Token::Word elements and you want to filter out the
125       hash subscript variety.  In both of the following examples, "foo" is
126       considered a hash key:
127
128           $hash1{foo} = 1;
129           %hash2 = (foo => 1);
130
131       But if the bareword is followed by an argument list, then perl treats
132       it as a function call.  So in these examples, "foo" is not considered a
133       hash key:
134
135           $hash1{ foo() } = 1;
136           &hash2 = (foo() => 1);
137
138   is_included_module_name
139           my $bool = is_included_module_name($element);
140
141       Given a PPI::Token::Word, returns true if the element is the name of a
142       module that is being included via "use", "require", or "no".
143
144   is_integer
145           my $bool = is_integer($value);
146
147       Answers whether the parameter, as a string, looks like an integral
148       value.
149
150   is_class_name
151           my $bool = is_class_name($element);
152
153       Given a PPI::Token::Word, returns true if the element that immediately
154       follows this element is the dereference operator "->".  When a bareword
155       has a "->" on the right side, it usually means that it is the name of
156       the class (from which a method is being called).
157
158   is_label_pointer
159           my $bool = is_label_pointer($element);
160
161       Given a PPI::Token::Word, returns true if the element is the label in a
162       "next", "last", "redo", or "goto" statement.  Note this is not the same
163       thing as the label declaration.
164
165   is_method_call
166           my $bool = is_method_call($element);
167
168       Given a PPI::Token::Word, returns true if the element that immediately
169       precedes this element is the dereference operator "->".  When a
170       bareword has a "->" on the left side, it usually means that it is the
171       name of a method (that is being called from a class).
172
173   is_package_declaration
174           my $bool = is_package_declaration($element);
175
176       Given a PPI::Token::Word, returns true if the element is the name of a
177       package that is being declared.
178
179   is_subroutine_name
180           my $bool = is_subroutine_name($element);
181
182       Given a PPI::Token::Word, returns true if the element is the name of a
183       subroutine declaration.  This is useful for distinguishing barewords
184       and from function calls from subroutine declarations.
185
186   is_function_call
187           my $bool = is_function_call($element);
188
189       Given a PPI::Token::Word returns true if the element appears to be call
190       to a static function.  Specifically, this function returns true if
191       "is_hash_key", "is_method_call", "is_subroutine_name",
192       "is_included_module_name", "is_package_declaration",
193       "is_perl_bareword", "is_perl_filehandle", "is_label_pointer" and
194       "is_subroutine_name" all return false for the given element.
195
196   is_in_void_context
197           my $bool = is_in_void_context($token);
198
199       Given a PPI::Token, answer whether it appears to be in a void context.
200
201   is_unchecked_call
202           my $bool = is_unchecked_call($element);
203
204       Given a PPI::Element, test to see if it contains a function call whose
205       return value is not checked.
206
207   is_ppi_expression_or_generic_statement
208           my $bool = is_ppi_expression_or_generic_statement($element);
209
210       Answers whether the parameter is an expression or an undifferentiated
211       statement.  I.e. the parameter either is a PPI::Statement::Expression
212       or the class of the parameter is PPI::Statement and not one of its
213       subclasses other than "Expression".
214
215   is_ppi_generic_statement
216           my $bool = is_ppi_generic_statement($element);
217
218       Answers whether the parameter is an undifferentiated statement, i.e.
219       the parameter is a PPI::Statement but not one of its subclasses.
220
221   is_ppi_statement_subclass
222           my $bool = is_ppi_statement_subclass($element);
223
224       Answers whether the parameter is a specialized statement, i.e. the
225       parameter is a PPI::Statement but the class of the parameter is not
226       PPI::Statement.
227
228   is_ppi_simple_statement
229           my $bool = is_ppi_simple_statement($element);
230
231       Answers whether the parameter represents a simple statement, i.e.
232       whether the parameter is a PPI::Statement, PPI::Statement::Break,
233       PPI::Statement::Include, PPI::Statement::Null, PPI::Statement::Package,
234       or PPI::Statement::Variable.
235
236   is_ppi_constant_element
237           my $bool = is_ppi_constant_element($element);
238
239       Answers whether the parameter represents a constant value, i.e. whether
240       the parameter is a PPI::Token::Number, PPI::Token::Quote::Literal,
241       PPI::Token::Quote::Single, or PPI::Token::QuoteLike::Words, or is a
242       PPI::Token::Quote::Double or PPI::Token::Quote::Interpolate which does
243       not in fact contain any interpolated variables.
244
245       This subroutine does not interpret any form of here document as a
246       constant value, and may not until PPI::Token::HereDoc acquires the
247       relevant portions of the PPI::Token::Quote interface.
248
249       This subroutine also does not interpret entities created by the
250       ReadonlyX module (or similar) or the constant pragma as constants.
251
252   is_subroutine_declaration
253           my $bool = is_subroutine_declaration($element);
254
255       Is the parameter a subroutine declaration, named or not?
256
257   is_in_subroutine
258           my $bool = is_in_subroutine($element);
259
260       Is the parameter a subroutine or inside one?
261

BUGS

263       Report any issues on the public bugtracker.
264

AUTHOR

266       Dan Book <dbook@cpan.org>
267
268       Code originally from Perl::Critic::Utils by Jeffrey Ryan Thalhammer
269       <jeff@imaginative-software.com> and Perl::Critic::Utils::PPI by Elliot
270       Shank <perl@galumph.com>
271

COPYRIGHT AND LICENSE

273       This software is copyright (c) 2005-2011 Imaginative Software Systems,
274       2007-2011 Elliot Shank, 2017 Dan Book.
275
276       This is free software; you can redistribute it and/or modify it under
277       the same terms as the Perl 5 programming language system itself.
278