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. My problem with it is that it returns variable names
92       rather than PPI::Element objects, leaving you no idea how the variables
93       are used. It was originally written for the benefit of
94       Perl::Critic::Policy::Variables::ProhibitUnusedVarsStricter, but has
95       proven inadequate to that policy's needs.
96
97       Despite the leading underscores, this exportable subroutine is public
98       and supported. The underscores are so it will not appear to be public
99       code to various tools when imported into other code.
100
101       This subroutine takes as its only argument a PPI::Element, and returns
102       the names of all variables found in that element, in no particular
103       order. Scope is not taken into account.
104
105       In addition to reporting variables parsed as such by PPI, and various
106       corner cases such as "${]}" where PPI is blind to the use of the
107       variable, this subroutine looks inside the following PPI classes:
108
109           PPI::Token::Quote
110           PPI::Token::QuoteLike::Backtick
111           PPI::Token::QuoteLike::Command
112           PPI::Token::QuoteLike::Readline
113           PPI::Token::HereDoc
114
115       If PPIx::Regexp is installed, it will also look inside
116
117           PPI::Token::QuoteLike::Regexp
118           PPI::Token::Regexp::Match
119           PPI::Token::Regexp::Substitute
120
121       Unfortunately I can not make "PPIx::Regexp" a requirement for this
122       module, because of the possibility of a circular dependency.
123

SUPPORT

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

AUTHOR

131       Thomas R. Wyant, III wyant at cpan dot org
132

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