1PPIx::QuoteLike(3) User Contributed Perl Documentation PPIx::QuoteLike(3)
2
6 PPIx::QuoteLike - Parse Perl string literals and string-literal-like
7 things.
8
10 use PPIx::QuoteLike;
11 my $str = PPIx::QuoteLike->new( q<"fu$bar"> );
13 say $str->interpolates() ?
14 'interpolates' :
15 'does not interpolate';
16
18 This Perl class parses Perl string literals and things that are
19 reasonably like string literals. Its real reason for being is to find
20 interpolated variables for Perl::Critic policies and similar code.
21
23 "PPIx::QuoteLike" is not descended from any other class.
24 "PPIx::QuoteLike" has no descendants.
26
28 This class supports the following public methods:
29 new
31 my $str = PPIx::QuoteLike->new( $source, %arg );
32 This static method parses the argument, and returns a new object
34 containing the parse. The $source argument can be either a scalar or an
35 appropriate PPI::Element object.
36 If the $source argument is a scalar, it is presumed to represent a
38 quote-like literal of some sort, provided it begins like one. Otherwise
39 this method will return nothing. The scalar representation of a here
40 document is a multi-line string whose first line consists of the
41 leading " << " and the start delimiter, and whose subsequent lines
42 consist of the content of the here document and the end delimiter.
43 "PPI" classes that can be handled are PPI::Token::Quote,
45 PPI::Token::QuoteLike::Backtick, PPI::Token::QuoteLike::Command,
46 PPI::Token::QuoteLike::Readline, and PPI::Token::HereDoc. Any other
47 object will cause "new()" to return nothing.
48 Additional optional arguments can be passed as name/value pairs.
50 Supported arguments are:
51 encoding
53 This is the encoding of the $source. If this is specified as
54 something other than "undef", the $source will be decoded before
55 processing.
56 If the $source is a "PPI::Element", this encoding is used only if
58 the document that contains the element has neither a byte order
59 mark nor 'use utf8'.
60 postderef
62 This Boolean argument determines whether postfix dereferencing is
63 recognized in interpolation. If unspecified, or specified as
64 "undef", it defaults to the value of
65 $PPIx::QuoteLike::DEFAULT_POSTDEREF. This variable is not exported,
66 and is true by default. If you change the value, the change should
67 be properly localized:
68 local $PPIx::QuoteLike::DEFAULT_POSTDEREF = 0;
70 trace
72 This Boolean argument causes a trace of the parse to be written to
73 standard out. Setting this to a true value is unsupported in the
74 sense that the author makes no representation as to what will
75 happen if you do it, and reserves the right to make changes to the
76 functionality, or retract it completely, without notice.
77 All other arguments are unsupported and reserved to the author.
79 child
81 my $kid = $str->child( 0 );
82 This method returns the child element whose index is given as the
84 argument. Children do not include the type(), or the start() or
85 finish() delimiters. Negative indices are valid, and given the usual
86 Perl interpretation.
87 children
89 my @kids = $str->children();
90 This method returns all child elements. Children do not include the
92 type(), or the start() or finish() delimiters.
93 content
95 say $str->content();
96 This method returns the content of the object. If the original argument
98 was a valid Perl string, this should be the same as the originally-
99 parsed string.
100 delimiters
102 say $str->delimiters();
103 This method returns the delimiters of the object, as a string. This
105 will be two characters unless the argument to new() was a here
106 document, missing its end delimiter, or an invalid string. In the
107 latter case the return might be anything.
108 elements
110 my @elem = $str->elements();
111 This method returns all elements of the object. This includes type(),
113 start(), children(), and finish(), in that order.
114 failures
116 say $str->failures();
117 This method returns the number of parse failures found. These are
119 instances where the parser could not figure out what was going on, and
120 should be the same as the number of PPIx::QuoteLike::Token::Unknown
121 objects returned by elements().
122 find
124 for ( @{[ $str->find( $criteria ) || [] } ) {
125 ...
126 }
127 This method finds and returns a reference to an array of all elements
129 that meet the given criteria. If nothing is found, a false value is
130 returned.
131 The $criteria can be either the name of a PPIx::QuoteLike::Token class,
133 or a code reference. In the latter case, the code is called for each
134 element in elements(), with the element as the only argument. The
135 element is included in the output if the code returns a true value.
136 finish
138 say map { $_->content() } $str->finish();
139 This method returns the finishing elements of the parse. It is actually
141 an array, with the first element being a
142 PPIx::QuoteLike::Token::Delimiter. If the parse is of a here document
143 there will be a second element, which will be a
144 PPIx::QuoteLike::Token::Whitespace containing the trailing new line
145 character.
146 If called in list context you get the whole array. If called in scalar
148 context you get the element whose index is given in the argument, or
149 element zero if no argument is specified.
150 handles
152 say PPIx::QuoteLike->handles( $string ) ?
153 "We can handle $string" :
154 "We can not handle $string";
155 This convenience static method returns a true value if this package can
157 be expected to handle the content of $string (be it scalar or object),
158 and a false value otherwise.
159 interpolates
161 say $str->interpolates() ?
162 'The string interpolates' :
163 'The string does not interpolate';
164 This method returns a true value if the parsed string interpolates, and
166 a false value if it does not. This does not indicate whether any
167 interpolation actually takes place, only whether the string is double-
168 quotish or single-quotish.
169 perl_version_introduced
171 This method returns the maximum value of "perl_version_introduced"
172 returned by any of its elements. In other words, it returns the minimum
173 version of Perl under which this quote-like object is valid. If there
174 are no elements, 5.000 is returned, since that is the minimum value of
175 Perl supported by this package.
176 perl_version_removed
178 This method returns the minimum defined value of "perl_version_removed"
179 returned by any of the quote-like object's elements. In other words, it
180 returns the lowest version of Perl in which this object is "not" valid.
181 If there are no elements, or if no element has a defined
182 "perl_version_removed", "undef" is returned.
183 schild
185 my $skid = $str->schild( 0 );
186 This method returns the significant child elements whose index is given
188 by the argument. Negative indices are interpreted in the usual way.
189 schildren
191 my @skids = $str->schildren();
192 This method returns the significant children.
194 source
196 my $source = $str->source();
197 This method returns the $source argument to new(), whatever it was.
199 start
201 say map { $_->content() } $str->start();
202 This method returns the starting elements of the parse. It is actually
204 an array, with the first element being a
205 PPIx::QuoteLike::Token::Delimiter. If the parse is of a here document
206 there will be a second element, which will be a
207 PPIx::QuoteLike::Token::Whitespace containing the trailing new line
208 character.
209 If called in list context you get the whole array. If called in scalar
211 context you get the element whose index is given in the argument, or
212 element zero if no argument is specified.
213 type
215 my $type = $str->type();
216 This method returns the type object. This will be a
218 PPIx::QuoteLike::Token::Structure if the parse was successful;
219 otherwise it might be "undef". Its contents will be everything up to
220 the start delimiter, and will typically be 'q', 'qq', 'qx', '<<' (for
221 here documents), or '' (for quoted strings).
222 The type data are actually an array. If the second element is present
224 it will be the white space (if any) separating the actual type from the
225 value. If called in list context you get the whole array. If called in
226 scalar context you get the element whose index is given in the
227 argument, or element zero if no argument is specified.
228 variables
230 say "Interpolates $_" for $str->variables();
231 This convenience method returns all interpolated variables. Each is
233 returned only once, and they are returned in no particular order. If
234 the object does not represent a string that interpolates, nothing is
235 returned.
236
238 By the nature of this module, it is never going to get everything
239 right. Many of the known problem areas involve interpolations one way
240 or another.
241 Changes in Syntax
243 Sometimes the introduction of new syntax changes the way a string is
244 parsed. For example, the "\F" (fold case) case control was introduced
245 in Perl 5.15.8. But it did not represent a syntax error prior to that
246 version of Perl, it was simply parsed as "F". So
247 $ perl -le 'print "Foo\FBar"'
249 prints "FooFBar" under Perl 5.14.4, but "Foobar" under 5.16.0.
251 "PPIx::QuoteLike" generally assumes the more modern parse in cases like
252 this.
253 Static Parsing
255 It is well known that Perl can not be statically parsed. That is, you
256 can not completely parse a piece of Perl code without executing that
257 same code.
258 Nevertheless, this class is trying to statically parse quote-like
260 things. I do not have any examples of where the parse of a quote-like
261 thing would change based on what is interpolated, but neither can I
262 rule it out. Caveat user.
263 Non-Standard Syntax
265 There are modules out there that alter the syntax of Perl. If the
266 syntax of a quote-like string is altered, this module has no way to
267 understand that it has been altered, much less to adapt to the
268 alteration. The following modules are known to cause problems:
269 Acme::PerlML, which renders Perl as XML.
271 Data::PostfixDeref, which causes Perl to interpret suffixed empty
273 brackets as dereferencing the thing they suffix, and which is
274 inconsistent with the postfix dereference syntax introduced in 5.19.5
275 and mainstreamed with 5.24.0.
276 Filter::Trigraph, which recognizes ANSI C trigraphs, allowing Perl to
278 be written in the ISO 646 character set.
279 Perl6::Pugs. Enough said.
281
283 Support is by the author. Please file bug reports at
284 <http://rt.cpan.org>, or in electronic mail to the author.
285
287 Thomas R. Wyant, III wyant at cpan dot org
288
290 Copyright (C) 2016-2019 by Thomas R. Wyant, III
291 This program is free software; you can redistribute it and/or modify it
293 under the same terms as Perl 5.10.0. For more details, see the full
294 text of the licenses in the directory LICENSES.
295 This program is distributed in the hope that it will be useful, but
297 without any warranty; without even the implied warranty of
298 merchantability or fitness for a particular purpose.
299perl v5.28.2 2019-05-31 PPIx::QuoteLike(3)