1PPIx::Regexp::Element(3U)ser Contributed Perl DocumentatiPoPnIx::Regexp::Element(3)
2
6 PPIx::Regexp::Element - Base of the PPIx::Regexp hierarchy.
7
9 No user-serviceable parts inside.
10
12 "PPIx::Regexp::Element" is not descended from any other class.
13 "PPIx::Regexp::Element" is the parent of PPIx::Regexp::Node and
15 PPIx::Regexp::Token.
16
18 This class is the base of the PPIx::Regexp object hierarchy. It
19 provides the same kind of navigational functionality that is provided
20 by PPI::Element.
21
23 This class provides the following public methods. Methods not
24 documented here are private, and unsupported in the sense that the
25 author reserves the right to change or remove them without notice.
26 accepts_perl
28 $token->accepts_perl( '5.020' )
29 and say 'This works under Perl 5.20';
30 This method returns a true value if the token is acceptable under the
32 specified version of Perl, and a false value otherwise. Unless the
33 token (or its contents) have been equivocated on, the result is simply
34 what you would expect based on testing the results of
35 perl_version_introduced() and perl_version_removed() versus the given
36 Perl version number.
37 This method was added in version 0.051_01.
39 ancestor_of
41 This method returns true if the object is an ancestor of the argument,
42 and false otherwise. By the definition of this method, $self is its own
43 ancestor.
44 can_be_quantified
46 $token->can_be_quantified()
47 and print "This element can be quantified.\n";
48 This method returns true if the element can be quantified.
50 class
52 This method returns the class name of the element. It is the same as
53 "ref $self".
54 comment
56 This method returns true if the element is a comment and false
57 otherwise.
58 content
60 This method returns the content of the element.
61 descendant_of
63 This method returns true if the object is a descendant of the argument,
64 and false otherwise. By the definition of this method, $self is its own
65 descendant.
66 explain
68 This method returns a brief explanation of what the element does. The
69 return will be either a string or "undef" in scalar context, but may be
70 multiple values or an empty array in list context.
71 This method should be considered experimental. What it returns may
73 change without notice as my understanding of what all the pieces/parts
74 of a Perl regular expression evolves. The worst case is that it will
75 prove entirely infeasible to implement satisfactorily, in which case it
76 will be put through a deprecation cycle and retracted.
77 error
79 say $token->error();
80 If an element is one of the classes that represents a parse error, this
82 method may return a brief message saying why. Otherwise it will return
83 "undef".
84 in_regex_set
86 This method returns a true value if the invocant is contained in an
87 extended bracketed character class (also known as a regex set), and a
88 false value otherwise. This method returns true if the invocant is a
89 PPIx::Regexp::Structure::RegexSet.
90 is_quantifier
92 $token->is_quantifier()
93 and print "This element is a quantifier.\n";
94 This method returns true if the element is a quantifier. You can not
96 tell this from the element's class, because a right curly bracket may
97 represent a quantifier for the purposes of figuring out whether a
98 greediness token is possible.
99 main_structure
101 This method returns the PPIx::Regexp::Structure::Main that contains the
102 element. In practice this will be a PPIx::Regexp::Structure::Regexp or
103 a PPIx::Regexp::Structure::Replacement,
104 If the element is not contained in any such structure, "undef" is
106 returned. This will happen if the element is a PPIx::Regexp or one of
107 its immediate children.
108 modifier_asserted
110 $token->modifier_asserted( 'i' )
111 and print "Matched without regard to case.\n";
112 This method returns true if the given modifier is in effect for the
114 element, and false otherwise.
115 What it does is to walk backwards from the element until it finds a
117 modifier object that specifies the modifier, whether asserted or
118 negated. and returns the specified value. If nobody specifies the
119 modifier, it returns "undef".
120 This method will not work reliably if called on tokenizer output.
122 next_element
124 This method returns the next element, or nothing if there is none.
125 Unlike next_sibling(), this will cross from the content of a structure
127 into the elements that define the structure, or vice versa.
128 next_sibling
130 This method returns the element's next sibling, or nothing if there is
131 none.
132 parent
134 This method returns the parent of the element, or undef if there is
135 none.
136 perl_version_introduced
138 This method returns the version of Perl in which the element was
139 introduced. This will be at least 5.000. Before 5.006 I am relying on
140 the perldelta, perlre, and perlop documentation, since I have been
141 unable to build earlier Perls. Since I have found no documentation
142 before 5.003, I assume that anything found in 5.003 is also in 5.000.
143 Since this all depends on my ability to read and understand masses of
145 documentation, the results of this method should be viewed with
146 caution, if not downright skepticism.
147 There are also cases which are ambiguous in various ways. For those see
149 the PPIx::Regexp documentation, particularly Changes in Syntax.
150 Very occasionally, a construct will be removed and then added back. If
152 this happens, this method will return the lowest version in which the
153 construct appeared. For the known instances of this, see the
154 PPIx::Regexp documentation, particularly Equivocation.
155 perl_version_removed
157 This method returns the version of Perl in which the element was
158 removed. If the element is still valid the return is "undef".
159 All the caveats to perl_version_introduced() apply here also, though
161 perhaps less severely since although many features have been introduced
162 since 5.0, few have been removed.
163 Very occasionally, a construct will be removed and then added back. If
165 this happens, this method will return the "undef" if the construct is
166 present in the highest-numbered version of Perl (whether production or
167 development), or the version after the highest-numbered version in
168 which it appeared otherwise. For the known instances of this, see the
169 PPIx::Regexp documentation, particularly Equivocation.
170 previous_element
172 This method returns the previous element, or nothing if there is none.
173 Unlike previous_sibling(), this will cross from the content of a
175 structure into the elements that define the structure, or vice versa.
176 previous_sibling
178 This method returns the element's previous sibling, or nothing if there
179 is none.
180 This method is analogous to the same-named PPI::Element method, in that
182 it will not cross from the content of a structure into the elements
183 that define the structure.
184 remove_insignificant
186 This method returns a new object manufactured from the invocant, but
187 containing only elements for which "$elem->significant()" returns a
188 true value.
189 If you call this method on a PPIx::Regexp::Node you will get back a
191 deep clone, but without the insignificant elements.
192 If you call this method on any other PPIx::Regexp class you will get
194 back either the invocant or nothing. This may change to a clone of the
195 invocant or nothing if unforseen problems arise with returning the
196 invocant, or if objects become mutable (unlikely, but not impossible.)
197 requirements_for_perl
199 say $token->requirements_for_perl();
200 This method returns a string representing the Perl requirements for a
202 given module. This should only be used for informational purposes, as
203 the format of the string may be subject to change.
204 At the moment, the returns may be:
206 version <= $]
208 version <= $] < version
209 two or more of the above joined by '||'
210 ! $]
211 The last means that, although all the components of the regular
213 expression can be compiled by some version of Perl, there is no version
214 that will compile all of them.
215 I reiterate: the returned string may be subject to change, maybe
217 without warning.
218 This method was added in version 0.051_01.
220 scontent
222 This method returns the significant content of the element. That is, if
223 called on the parse of '/ f u b a r /x', it returns '/fubar/x'. If the
224 invocant contains no insignificant elements, it is the same as
225 content(). If called on an insignificant element, it returns nothing --
226 that is, "undef" in scalar context, and an empty list in list context.
227 This method was inspired by jb's question on Perl Monks about stripping
229 comments and white space from a regular expression:
230 <http://www.perlmonks.org/?node_id=1207556>
231 This method was added in version 0.053_01
233 significant
235 This method returns true if the element is significant and false
236 otherwise.
237 snext_element
239 This method returns the next significant element, or nothing if there
240 is none.
241 Unlike snext_sibling(), this will cross from the content of a structure
243 into the elements that define the structure, or vice versa.
244 snext_sibling
246 This method returns the element's next significant sibling, or nothing
247 if there is none.
248 This method is analogous to the same-named PPI::Element method, in that
250 it will not cross from the content of a structure into the elements
251 that define the structure.
252 sprevious_element
254 This method returns the previous significant element, or nothing if
255 there is none.
256 Unlike sprevious_sibling(), this will cross from the content of a
258 structure into the elements that define the structure, or vice versa.
259 sprevious_sibling
261 This method returns the element's previous significant sibling, or
262 nothing if there is none.
263 This method is analogous to the same-named PPI::Element method, in that
265 it will not cross from the content of a structure into the elements
266 that define the structure.
267 tokens
269 This method returns all tokens contained in the element.
270 top
272 This method returns the top of the hierarchy.
273 unescaped_content
275 This method returns the content of the element, unescaped.
276 whitespace
278 This method returns true if the element is whitespace and false
279 otherwise.
280 nav
282 This method returns navigation information from the top of the
283 hierarchy to this node. The return is a list of names of methods and
284 references to their argument lists. The idea is that given $elem which
285 is somewhere under $top,
286 my @nav = $elem->nav();
288 my $obj = $top;
289 while ( @nav ) {
290 my $method = shift @nav;
291 my $args = shift @nav;
292 $obj = $obj->$method( @{ $args } ) or die;
293 }
294 # At this point, $obj should contain the same object
295 # as $elem.
296
298 Support is by the author. Please file bug reports at
299 <http://rt.cpan.org>, or in electronic mail to the author.
300
302 Thomas R. Wyant, III wyant at cpan dot org
303
305 Copyright (C) 2009-2019 by Thomas R. Wyant, III
306 This program is free software; you can redistribute it and/or modify it
308 under the same terms as Perl 5.10.0. For more details, see the full
309 text of the licenses in the directory LICENSES.
310 This program is distributed in the hope that it will be useful, but
312 without any warranty; without even the implied warranty of
313 merchantability or fitness for a particular purpose.
314perl v5.30.0 2019-09-02 PPIx::Regexp::Element(3)