1PPIx::QuoteLike(3)    User Contributed Perl Documentation   PPIx::QuoteLike(3)
2
3
4

NAME

6       PPIx::QuoteLike - Parse Perl string literals and string-literal-like
7       things.
8

SYNOPSIS

10        use PPIx::QuoteLike;
11
12        my $str = PPIx::QuoteLike->new( q<"fu$bar"> );
13        say $str->interpolates() ?
14           'interpolates' :
15           'does not interpolate';
16

DESCRIPTION

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

INHERITANCE

23       "PPIx::QuoteLike" is not descended from any other class.
24
25       "PPIx::QuoteLike" has no descendants.
26

METHODS

28       This class supports the following public methods:
29
30   new
31        my $str = PPIx::QuoteLike->new( $source, %arg );
32
33       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
37       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
44       "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
49       Additional optional arguments can be passed as name/value pairs.
50       Supported arguments are:
51
52       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
57           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
61       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
69            local $PPIx::QuoteLike::DEFAULT_POSTDEREF = 0;
70
71       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
78       All other arguments are unsupported and reserved to the author.
79
80   child
81        my $kid = $str->child( 0 );
82
83       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
88   children
89        my @kids = $str->children();
90
91       This method returns all child elements. Children do not include the
92       type(), or the start() or finish() delimiters.
93
94   content
95        say $str->content();
96
97       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
101   delimiters
102        say $str->delimiters();
103
104       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
109   elements
110        my @elem = $str->elements();
111
112       This method returns all elements of the object. This includes type(),
113       start(), children(), and finish(), in that order.
114
115   failures
116        say $str->failures();
117
118       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
123   find
124        for ( @{[ $str->find( $criteria ) || [] } ) {
125            ...
126        }
127
128       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
132       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
137   finish
138        say map { $_->content() } $str->finish();
139
140       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
147       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
151   handles
152        say PPIx::QuoteLike->handles( $string ) ?
153            "We can handle $string" :
154            "We can not handle $string";
155
156       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
160   interpolates
161        say $str->interpolates() ?
162            'The string interpolates' :
163            'The string does not interpolate';
164
165       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
170   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
177   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
184   schild
185        my $skid = $str->schild( 0 );
186
187       This method returns the significant child elements whose index is given
188       by the argument. Negative indices are interpreted in the usual way.
189
190   schildren
191        my @skids = $str->schildren();
192
193       This method returns the significant children.
194
195   source
196        my $source = $str->source();
197
198       This method returns the $source argument to new(), whatever it was.
199
200   start
201        say map { $_->content() } $str->start();
202
203       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
210       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
214   type
215        my $type = $str->type();
216
217       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
223       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
229   variables
230        say "Interpolates $_" for $str->variables();
231
232       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

RESTRICTIONS

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
242   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
248        $ perl -le 'print "Foo\FBar"'
249
250       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
254   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
259       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
264   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
270       Acme::PerlML, which renders Perl as XML.
271
272       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
277       Filter::Trigraph, which recognizes ANSI C trigraphs, allowing Perl to
278       be written in the ISO 646 character set.
279
280       Perl6::Pugs. Enough said.
281

SUPPORT

283       Support is by the author. Please file bug reports at
284       <http://rt.cpan.org>, or in electronic mail to the author.
285

AUTHOR

287       Thomas R. Wyant, III wyant at cpan dot org
288
290       Copyright (C) 2016-2019 by Thomas R. Wyant, III
291
292       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
296       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.
299
300
301
302perl v5.28.2                      2019-05-31                PPIx::QuoteLike(3)
Impressum