1B::Utils(3)           User Contributed Perl Documentation          B::Utils(3)
2
3
4

NAME

6       B::Utils - Helper functions for op tree manipulation
7

VERSION

9       version 0.27
10

INSTALLATION

12       To install this module, run the following commands:
13
14           perl Makefile.PL
15           make
16           make test
17           make install
18

SYNOPSIS

20         use B::Utils;
21

OP METHODS

23       "$op->oldname"
24           Returns the name of the op, even if it is currently optimized to
25           null.  This helps you understand the structure of the op tree.
26
27       "$op->kids"
28           Returns an array of all this op's non-null children, in order.
29
30       "$op->parent"
31           Returns the parent node in the op tree, if possible. Currently
32           "possible" means "if the tree has already been optimized"; that is,
33           if we're during a "CHECK" block. (and hence, if we have valid
34           "next" pointers.)
35
36           In the future, it may be possible to search for the parent before
37           we have the "next" pointers in place, but it'll take me a while to
38           figure out how to do that.
39
40           Warning: Since 5.21.2 B comes with its own version of B::OP::parent
41           which returns either B::NULL or the real parent when ccflags
42           contains -DPERL_OP_PARENT.  In this case rather use $op->_parent.
43
44       "$op->ancestors"
45           Returns all parents of this node, recursively. The list is ordered
46           from younger/closer parents to older/farther parents.
47
48       "$op->descendants"
49           Returns all children of this node, recursively. The list is
50           unordered.
51
52       "$op->siblings"
53           Returns all younger siblings of this node. The list is ordered from
54           younger/closer siblings to older/farther siblings.
55
56       "$op->previous"
57           Like " $op->next ", but not quite.
58
59       "$op->stringify"
60           Returns a nice stringification of an opcode.
61
62       "$op->as_opgrep_pattern(%options)"
63           From the op tree it is called on, as_opgrep_pattern() generates a
64           data structure suitable for use as a condition pattern for the
65           opgrep() function described below in detail.  Beware: When using
66           such generated patterns, there may be false positives: The pattern
67           will most likely not match only the op tree it was generated from
68           since by default, not all properties of the op are reproduced.
69
70           You can control which properties of the op to include in the
71           pattern by passing named arguments. The default behaviour is as if
72           you passed in the following options:
73
74             my $pattern = $op->as_opgrep_pattern(
75               attributes          => [qw(name flags)],
76               max_recursion_depth => undef,
77             );
78
79           So obviously, you can set "max_recursion_depth" to a number to
80           limit the maximum depth of recursion into the op tree. Setting it
81           to 0 will limit the dump to the current op.
82
83           "attributes" is a list of attributes to include in the produced
84           pattern. The attributes that can be checked against in this way
85           are:
86
87             name targ type seq flags private pmflags pmpermflags.
88

EXPORTABLE FUNCTIONS

90       "all_starts"
91       "all_roots"
92           Returns a hash of all of the starting ops or root ops of optrees,
93           keyed to subroutine name; the optree for main program is simply
94           keyed to "__MAIN__".
95
96           Note: Certain "dangerous" stashes are not scanned for subroutines:
97           the list of such stashes can be found in @B::Utils::bad_stashes.
98           Feel free to examine and/or modify this to suit your needs. The
99           intention is that a simple program which uses no modules other than
100           "B" and "B::Utils" would show no addition symbols.
101
102           This does not return the details of ops in anonymous subroutines
103           compiled at compile time. For instance, given
104
105               $a = sub { ... };
106
107           the subroutine will not appear in the hash. This is just as well,
108           since they're anonymous... If you want to get at them, use...
109
110       "anon_subs"
111           This returns an array of hash references. Each element has the keys
112           "start" and "root". These are the starting and root ops of all of
113           the anonymous subroutines in the program.
114
115       "recalc_sub_cache"
116           If PL_sub_generation has changed or you have some other reason to
117           want to force the re-examination of the optrees, everywhere, call
118           this function.
119
120       "walkoptree_simple($op, \&callback, [$data])"
121           The "B" module provides various functions to walk the op tree, but
122           they're all rather difficult to use, requiring you to inject
123           methods into the "B::OP" class. This is a very simple op tree
124           walker with more expected semantics.
125
126           All the "walk" functions set $B::Utils::file, $B::Utils::line, and
127           $B::Utils::sub to the appropriate values of file, line number, and
128           sub name in the program being examined.
129
130       "walkoptree_filtered($op, \&filter, \&callback, [$data])"
131           This is much the same as "walkoptree_simple", but will only call
132           the callback if the "filter" returns true. The "filter" is passed
133           the op in question as a parameter; the "opgrep" function is
134           fantastic for building your own filters.
135
136       "walkallops_simple(\&callback, [$data])"
137           This combines "walkoptree_simple" with "all_roots" and "anon_subs"
138           to examine every op in the program. $B::Utils::sub is set to the
139           subroutine name if you're in a subroutine, "__MAIN__" if you're in
140           the main program and "__ANON__" if you're in an anonymous
141           subroutine.
142
143       "walkallops_filtered(\&filter, \&callback, [$data])"
144           Same as above, but filtered.
145
146       "opgrep(\%conditions, @ops)"
147           Returns the ops which meet the given conditions. The conditions
148           should be specified like this:
149
150               @barewords = opgrep(
151                                   { name => "const", private => OPpCONST_BARE },
152                                   @ops
153                                  );
154
155           where the first argument to opgrep() is the condition to be matched
156           against the op structure. We'll henceforth refer to it as an op-
157           pattern.
158
159           You can specify alternation by giving an arrayref of values:
160
161               @svs = opgrep ( { name => ["padsv", "gvsv"] }, @ops)
162
163           And you can specify inversion by making the first element of the
164           arrayref a "!". (Hint: if you want to say "anything", say "not
165           nothing": "["!"]")
166
167           You may also specify the conditions to be matched in nearby ops as
168           nested patterns.
169
170               walkallops_filtered(
171                   sub { opgrep( {name => "exec",
172                                  next => {
173                                            name    => "nextstate",
174                                            sibling => { name => [qw(! exit warn die)] }
175                                          }
176                                 }, @_)},
177                   sub {
178                         carp("Statement unlikely to be reached");
179                         carp("\t(Maybe you meant system() when you said exec()?)\n");
180                   }
181               )
182
183           Get that?
184
185           Here are the things that can be tested in this way:
186
187                   name targ type seq flags private pmflags pmpermflags
188                   first other last sibling next pmreplroot pmreplstart pmnext
189
190           Additionally, you can use the "kids" keyword with an array
191           reference to match the result of a call to "$op->kids()". An
192           example use is given in the documentation for "op_or" below.
193
194           For debugging, you can have many properties of an op that is
195           currently being matched against a given condition dumped to STDERR
196           by specifying "dump =" 1> in the condition's hash reference.
197
198           If you match a complex condition against an op tree, you may want
199           to extract a specific piece of information from the tree if the
200           condition matches.  This normally entails manually walking the tree
201           a second time down to the op you wish to extract, investigate or
202           modify. Since this is tedious duplication of code and information,
203           you can specify a special property in the pattern of the op you
204           wish to extract to capture the sub-op of interest. Example:
205
206             my ($result) = opgrep(
207               { name => "exec",
208                 next => { name    => "nextstate",
209                           sibling => { name => [qw(! exit warn die)]
210                                        capture => "notreached",
211                                      },
212                         }
213               },
214               $root_op
215             );
216
217             if ($result) {
218               my $name = $result->{notreached}->name; # result is *not* the root op
219               carp("Statement unlikely to be reached (op name: $name)");
220               carp("\t(Maybe you meant system() when you said exec()?)\n");
221             }
222
223           While the above is a terribly contrived example, consider the win
224           for a deeply nested pattern or worse yet, a pattern with many
225           disjunctions.  If a "capture" property is found anywhere in the op
226           pattern, opgrep() returns an unblessed hash reference on success
227           instead of the tested op. You can tell them apart using
228           Scalar::Util's blessed(). That hash reference contains all captured
229           ops plus the tested root up as the hash entry "$result->{op}". Note
230           that you cannot use this feature with "walkoptree_filtered" since
231           that function was specifically documented to pass the tested op
232           itself to the callback.
233
234           You cannot capture disjunctions, but that doesn't really make sense
235           anyway.
236
237       "opgrep( \@conditions, @ops )"
238           Same as above, except that you don't have to chain the conditions
239           yourself.  If you pass an array-ref, opgrep will chain the
240           conditions for you using "next".  The conditions can either be
241           strings (taken as op-names), or hash-refs, with the same testable
242           conditions as given above.
243
244       op_or( @conditions )
245           Unlike the chaining of conditions done by "opgrep" itself if there
246           are multiple conditions, this function creates a disjunction
247           ("$cond1 || $cond2 || ...") of the conditions and returns a
248           structure (hash reference) that can be passed to opgrep as a single
249           condition.
250
251           Example:
252
253             my $sub_structure = {
254               name => 'helem',
255               first => { name => 'rv2hv', },
256               'last' => { name => 'const', },
257             };
258
259             my @ops = opgrep( {
260                 name => 'leavesub',
261                 first => {
262                   name => 'lineseq',
263                   kids => [,
264                     { name => 'nextstate', },
265                     op_or(
266                       {
267                         name => 'return',
268                         first => { name => 'pushmark' },
269                         last => $sub_structure,
270                       },
271                       $sub_structure,
272                     ),
273                   ],
274                 },
275             }, $op_obj );
276
277           This example matches the code in a typical simplest-possible
278           accessor method (albeit not down to the last bit):
279
280             sub get_foo { $_[0]->{foo} }
281
282           But by adding an alternation we can also match optional op layers.
283           In this case, we optionally match a return statement, so the
284           following implementation is also recognized:
285
286             sub get_foo { return $_[0]->{foo} }
287
288           Essentially, this is syntactic sugar for the following structure
289           recognized by opgrep():
290
291             { disjunction => [@conditions] }
292
293       carp(@args)
294       croak(@args)
295           Warn and die, respectively, from the perspective of the position of
296           the op in the program. Sounds complicated, but it's exactly the
297           kind of error reporting you expect when you're grovelling through
298           an op tree.
299
300   EXPORT
301       None by default.
302
303   XS EXPORT
304       This modules uses ExtUtils::Depends to export some useful functions for
305       XS modules to use.  To use those, include in your Makefile.PL:
306
307         my $pkg = ExtUtils::Depends->new("Your::XSModule", "B::Utils");
308         WriteMakefile(
309           ... # your normal makefile flags
310           $pkg->get_makefile_vars,
311         );
312
313       Your XS module can now include BUtils.h and BUtils_op.h.  To see
314       document for the functions provided, use:
315
316         perldoc -m B::Utils::Install::BUtils.h
317         perldoc -m B::Utils::Install::BUtils_op.h
318

AUTHOR

320       Originally written by Simon Cozens, "simon@cpan.org" Maintained by
321       Joshua ben Jore, "jjore@cpan.org"
322
323       Contributions from Mattia Barbon, Jim Cromie, Steffen Mueller, and
324       Chia-liang Kao, Alexandr Ciornii, Reini Urban.
325

LICENSE

327       This module is free software; you can redistribute it and/or modify it
328       under the same terms as Perl itself.
329

SEE ALSO

331       B, B::Generate.
332
333
334
335perl v5.38.0                      2023-07-20                       B::Utils(3)
Impressum