1PPIx::QuoteLike::Utils(U3s)er Contributed Perl DocumentatPiPoInx::QuoteLike::Utils(3)
2
3
4

NAME

6       PPIx::QuoteLike::Utils - Utility subroutines for PPIx::QuoteLike;
7

SYNOPSIS

9        use PPIx::QuoteLike::Utils qw{ __variables };
10
11        say for __variables( PPI::Document->new( \'$foo' );
12

DESCRIPTION

14       This Perl module holds code for PPIx::QuoteLike that did not seem to
15       fit anywhere else.
16

SUBROUTINES

18       This module supports the following public subroutines:
19
20   column_number
21       This subroutine/method returns the column number of the first character
22       in the element, or "undef" if that can not be determined.
23
24   is_ppi_quotelike_element
25       This subroutine returns true if its argument is a PPI::Element that
26       this package is capable of dealing with. That is, one of the following:
27
28           PPI::Token::Quote
29           PPI::Token::QuoteLike::Backtick
30           PPI::Token::QuoteLike::Command
31           PPI::Token::QuoteLike::Readline
32           PPI::Token::HereDoc
33
34       It returns false for unblessed references and for non-references.
35
36   line_number
37       This subroutine/method returns the line number of the first character
38       in the element, or "undef" if that can not be determined.
39
40   logical_filename
41       This subroutine/method returns the logical file name (taking "#line"
42       directives into account) of the file containing first character in the
43       element, or "undef" if that can not be determined.
44
45   logical_line_number
46       This subroutine/method returns the logical line number (taking "#line"
47       directives into account) of the first character in the element, or
48       "undef" if that can not be determined.
49
50   __normalize_interpolation_for_ppi
51       Despite the leading underscores, this exportable subroutine is public
52       and supported. The underscores are so it will not appear to be public
53       code to various tools when imported into other code.
54
55       This subroutine takes as its argument a string representing an
56       interpolation. It removes such things as braces around variable names
57       to make it into more normal Perl -- which is to say Perl that produces
58       a more normal PPI parse. Sample transformations are:
59
60        '${foo}'        => '$foo'
61        '@{[ foo() ]}'  => 'foo()'
62        '${\( foo() )}' => 'foo()'
63
64       NOTE that this is not intended for general code cleanup.  Specifically,
65       it assumes that its argument is an interpolation and only an
66       interpolation. Feeding it anything else is unsupported, and probably
67       will not return anything useful.
68
69   statement
70       This subroutine/method returns the PPI::Statement that contains this
71       element, or nothing if the statement can not be determined.
72
73       In general this method will return something only under the following
74       conditions:
75
76       •   The element is contained in a PPIx::Regexp object;
77
78       •   That object was initialized from a PPI::Element;
79
80       •   The PPI::Element is contained in a statement.
81
82   visual_column_number
83       This subroutine/method returns the visual column number (taking tabs
84       into account) of the first character in the element, or "undef" if that
85       can not be determined.
86
87   __variables
88        say for __variables( PPI::Document->new( \'$foo' );
89
90       NOTE that this subroutine is discouraged, and may well be deprecated
91       and removed. I have two problems with it. The first is that it returns
92       variable names rather than PPI::Element objects, leaving you no idea
93       how the variables are used. The second is that it does not properly
94       handle things like "${^CAPTURE[0]}", and it seems infeasible to make it
95       do so. It was originally written for the benefit of
96       Perl::Critic::Policy::Variables::ProhibitUnusedVarsStricter, but has
97       proven inadequate to that policy's needs.
98
99       Despite the leading underscores, this exportable subroutine is public
100       and supported. The underscores are so it will not appear to be public
101       code to various tools when imported into other code.
102
103       This subroutine takes as its only argument a PPI::Element, and returns
104       the names of all variables found in that element, in no particular
105       order. Scope is not taken into account.
106
107       In addition to reporting variables parsed as such by PPI, and various
108       corner cases such as "${]}" where PPI is blind to the use of the
109       variable, this subroutine looks inside the following PPI classes:
110
111           PPI::Token::Quote
112           PPI::Token::QuoteLike::Backtick
113           PPI::Token::QuoteLike::Command
114           PPI::Token::QuoteLike::Readline
115           PPI::Token::HereDoc
116
117       If PPIx::Regexp is installed, it will also look inside
118
119           PPI::Token::QuoteLike::Regexp
120           PPI::Token::Regexp::Match
121           PPI::Token::Regexp::Substitute
122
123       Unfortunately I can not make "PPIx::Regexp" a requirement for this
124       module, because of the possibility of a circular dependency.
125

SUPPORT

127       Support is by the author. Please file bug reports at
128       <https://rt.cpan.org/Public/Dist/Display.html?Name=PPIx-QuoteLike>,
129       <https://github.com/trwyant/perl-PPIx-QuoteLike/issues>, or in
130       electronic mail to the author.
131

AUTHOR

133       Thomas R. Wyant, III wyant at cpan dot org
134
136       Copyright (C) 2016-2022 by Thomas R. Wyant, III
137
138       This program is free software; you can redistribute it and/or modify it
139       under the same terms as Perl 5.10.0. For more details, see the full
140       text of the licenses in the directory LICENSES.
141
142       This program is distributed in the hope that it will be useful, but
143       without any warranty; without even the implied warranty of
144       merchantability or fitness for a particular purpose.
145
146
147
148perl v5.38.0                      2023-07-21         PPIx::QuoteLike::Utils(3)
Impressum