This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
B::walksymtable: clear cached methods
[perl5.git] / ext / B / B.pm
CommitLineData
a798dbf2
MB
1# B.pm
2#
1a52ab62 3# Copyright (c) 1996, 1997, 1998 Malcolm Beattie
a798dbf2
MB
4#
5# You may distribute under the terms of either the GNU General Public
6# License or the Artistic License, as specified in the README file.
7#
8package B;
744aaba0 9use strict;
28b605d8 10
a798dbf2 11require Exporter;
744aaba0 12@B::ISA = qw(Exporter);
b2590c4e 13
f72d64f0
DC
14# walkoptree_slow comes from B.pm (you are there),
15# walkoptree comes from B.xs
744aaba0
NC
16
17BEGIN {
951698f8 18 $B::VERSION = '1.70';
4aa23ba6 19 @B::EXPORT_OK = ();
744aaba0 20
4aa23ba6
NC
21 # Our BOOT code needs $VERSION set, and will append to @EXPORT_OK.
22 # Want our constants loaded before the compiler meets OPf_KIDS below, as
23 # the combination of having the constant stay a Proxy Constant Subroutine
24 # and its value being inlined saves a little over .5K
744aaba0 25
744aaba0
NC
26 require XSLoader;
27 XSLoader::load();
28}
29
4aa23ba6
NC
30push @B::EXPORT_OK, (qw(minus_c ppname save_BEGINs
31 class peekop cast_I32 cstring cchar hash threadsv_names
32 main_root main_start main_cv svref_2object opnumber
33 sub_generation amagic_generation perlstring
34 walkoptree_slow walkoptree walkoptree_exec walksymtable
35 parents comppadlist sv_undef compile_stats timing_info
36 begin_av init_av check_av end_av regex_padav dowarn
37 defstash curstash warnhook diehook inc_gv @optype
d9cd2aeb 38 @specialsv_name unitcheck_av safename));
4aa23ba6 39
a798dbf2
MB
40@B::SV::ISA = 'B::OBJECT';
41@B::NULL::ISA = 'B::SV';
42@B::PV::ISA = 'B::SV';
43@B::IV::ISA = 'B::SV';
4edc9001 44@B::NV::ISA = 'B::SV';
4df7f6af 45# RV is eliminated with 5.11.0, but effectively is a specialisation of IV now.
3ce3ed55 46@B::RV::ISA = $] >= 5.011 ? 'B::IV' : 'B::SV';
a798dbf2 47@B::PVIV::ISA = qw(B::PV B::IV);
4edc9001 48@B::PVNV::ISA = qw(B::PVIV B::NV);
a798dbf2 49@B::PVMG::ISA = 'B::PVNV';
5c35adbb 50@B::REGEXP::ISA = 'B::PVMG' if $] >= 5.011;
38d2280f 51@B::INVLIST::ISA = 'B::PV' if $] >= 5.019;
35633035
DM
52@B::PVLV::ISA = 'B::GV';
53@B::BM::ISA = 'B::GV';
a798dbf2
MB
54@B::AV::ISA = 'B::PVMG';
55@B::GV::ISA = 'B::PVMG';
56@B::HV::ISA = 'B::PVMG';
57@B::CV::ISA = 'B::PVMG';
276493cb
SM
58@B::IO::ISA = 'B::PVMG';
59@B::FM::ISA = 'B::CV';
a798dbf2
MB
60
61@B::OP::ISA = 'B::OBJECT';
62@B::UNOP::ISA = 'B::OP';
2f7c6295 63@B::UNOP_AUX::ISA = 'B::UNOP';
a798dbf2
MB
64@B::BINOP::ISA = 'B::UNOP';
65@B::LOGOP::ISA = 'B::UNOP';
a798dbf2
MB
66@B::LISTOP::ISA = 'B::BINOP';
67@B::SVOP::ISA = 'B::OP';
7934575e 68@B::PADOP::ISA = 'B::OP';
a798dbf2 69@B::PVOP::ISA = 'B::OP';
a798dbf2
MB
70@B::LOOP::ISA = 'B::LISTOP';
71@B::PMOP::ISA = 'B::LISTOP';
72@B::COP::ISA = 'B::OP';
b46e009d 73@B::METHOP::ISA = 'B::OP';
a798dbf2
MB
74
75@B::SPECIAL::ISA = 'B::OBJECT';
76
2f7c6295
DM
77@B::optype = qw(OP UNOP BINOP LOGOP LISTOP PMOP SVOP PADOP PVOP LOOP COP
78 METHOP UNOP_AUX);
baccf54f
NC
79# bytecode.pl contained the following comment:
80# Nullsv *must* come first in the following so that the condition
81# ($$sv == 0) can continue to be used to test (sv == Nullsv).
82@B::specialsv_name = qw(Nullsv &PL_sv_undef &PL_sv_yes &PL_sv_no
b043c4bf
DM
83 (SV*)pWARN_ALL (SV*)pWARN_NONE (SV*)pWARN_STD
84 &PL_sv_zero);
baccf54f 85
a798dbf2
MB
86{
87 # Stop "-w" from complaining about the lack of a real B::OBJECT class
88 package B::OBJECT;
89}
90
002b978b 91sub B::GV::SAFENAME {
d9cd2aeb
FC
92 safename(shift()->NAME);
93}
94
95sub safename {
96 my $name = shift;
d9963e60
RH
97
98 # The regex below corresponds to the isCONTROLVAR macro
99 # from toke.c
100
2bd1cbf6
KW
101 $name =~ s/^\c?/^?/
102 or $name =~ s/^([\cA-\cZ\c\\c[\c]\c_\c^])/
103 "^" . chr( utf8::unicode_to_native( 64 ^ ord($1) ))/e;
7a9b44b9
RH
104
105 # When we say unicode_to_native we really mean ascii_to_native,
2bd1cbf6
KW
106 # which matters iff this is a non-ASCII platform (EBCDIC). '\c?' would
107 # not have to be special cased, except for non-ASCII.
7a9b44b9 108
002b978b
RH
109 return $name;
110}
111
d9963e60
RH
112sub B::IV::int_value {
113 my ($self) = @_;
114 return (($self->FLAGS() & SVf_IVisUV()) ? $self->UVX : $self->IV);
115}
116
f3402b25 117sub B::NULL::as_string() {""}
88ecb8a6
NC
118*B::IV::as_string = \*B::IV::int_value;
119*B::PV::as_string = \*B::PV::PV;
f3402b25 120
ff1a9fc0
NC
121# The input typemap checking makes no distinction between different SV types,
122# so the XS body will generate the same C code, despite the different XS
123# "types". So there is no change in behaviour from doing "newXS" like this,
124# compared with the old approach of having a (near) duplicate XS body.
125# We should fix the typemap checking.
88ecb8a6 126*B::IV::RV = \*B::PV::RV if $] > 5.012;
ff1a9fc0 127
a798dbf2
MB
128my $debug;
129my $op_count = 0;
130my @parents = ();
131
132sub debug {
133 my ($class, $value) = @_;
134 $debug = $value;
135 walkoptree_debug($value);
136}
137
a798dbf2
MB
138sub class {
139 my $obj = shift;
140 my $name = ref $obj;
141 $name =~ s/^.*:://;
142 return $name;
143}
144
145sub parents { \@parents }
146
147# For debugging
148sub peekop {
149 my $op = shift;
3f872cb9 150 return sprintf("%s (0x%x) %s", class($op), $$op, $op->name);
a798dbf2
MB
151}
152
b2590c4e 153sub walkoptree_slow {
a798dbf2
MB
154 my($op, $method, $level) = @_;
155 $op_count++; # just for statistics
156 $level ||= 0;
157 warn(sprintf("walkoptree: %d. %s\n", $level, peekop($op))) if $debug;
156f89f0 158 $op->$method($level) if $op->can($method);
a798dbf2
MB
159 if ($$op && ($op->flags & OPf_KIDS)) {
160 my $kid;
161 unshift(@parents, $op);
162 for ($kid = $op->first; $$kid; $kid = $kid->sibling) {
b2590c4e 163 walkoptree_slow($kid, $method, $level + 1);
a798dbf2
MB
164 }
165 shift @parents;
166 }
156f89f0
JJ
167 if (class($op) eq 'PMOP'
168 && ref($op->pmreplroot)
169 && ${$op->pmreplroot}
170 && $op->pmreplroot->isa( 'B::OP' ))
171 {
0091380b
RGS
172 unshift(@parents, $op);
173 walkoptree_slow($op->pmreplroot, $method, $level + 1);
174 shift @parents;
175 }
a798dbf2
MB
176}
177
178sub compile_stats {
179 return "Total number of OPs processed: $op_count\n";
180}
181
182sub timing_info {
183 my ($sec, $min, $hr) = localtime;
184 my ($user, $sys) = times;
185 sprintf("%02d:%02d:%02d user=$user sys=$sys",
186 $hr, $min, $sec, $user, $sys);
187}
188
189my %symtable;
2b8dc4d2
DM
190
191sub clearsym {
192 %symtable = ();
193}
194
a798dbf2
MB
195sub savesym {
196 my ($obj, $value) = @_;
197# warn(sprintf("savesym: sym_%x => %s\n", $$obj, $value)); # debug
198 $symtable{sprintf("sym_%x", $$obj)} = $value;
199}
200
201sub objsym {
202 my $obj = shift;
203 return $symtable{sprintf("sym_%x", $$obj)};
204}
205
206sub walkoptree_exec {
207 my ($op, $method, $level) = @_;
244826eb 208 $level ||= 0;
a798dbf2
MB
209 my ($sym, $ppname);
210 my $prefix = " " x $level;
211 for (; $$op; $op = $op->next) {
212 $sym = objsym($op);
213 if (defined($sym)) {
214 print $prefix, "goto $sym\n";
215 return;
216 }
217 savesym($op, sprintf("%s (0x%lx)", class($op), $$op));
218 $op->$method($level);
3f872cb9 219 $ppname = $op->name;
1a67a97c 220 if ($ppname =~
62e36f8a 221 /^(d?or(assign)?|and(assign)?|mapwhile|grepwhile|entertry|range|cond_expr)$/)
1a67a97c 222 {
a798dbf2
MB
223 print $prefix, uc($1), " => {\n";
224 walkoptree_exec($op->other, $method, $level + 1);
225 print $prefix, "}\n";
3f872cb9 226 } elsif ($ppname eq "match" || $ppname eq "subst") {
a798dbf2
MB
227 my $pmreplstart = $op->pmreplstart;
228 if ($$pmreplstart) {
229 print $prefix, "PMREPLSTART => {\n";
230 walkoptree_exec($pmreplstart, $method, $level + 1);
231 print $prefix, "}\n";
232 }
3f872cb9 233 } elsif ($ppname eq "substcont") {
a798dbf2
MB
234 print $prefix, "SUBSTCONT => {\n";
235 walkoptree_exec($op->other->pmreplstart, $method, $level + 1);
236 print $prefix, "}\n";
237 $op = $op->other;
3f872cb9 238 } elsif ($ppname eq "enterloop") {
a798dbf2
MB
239 print $prefix, "REDO => {\n";
240 walkoptree_exec($op->redoop, $method, $level + 1);
241 print $prefix, "}\n", $prefix, "NEXT => {\n";
242 walkoptree_exec($op->nextop, $method, $level + 1);
243 print $prefix, "}\n", $prefix, "LAST => {\n";
244 walkoptree_exec($op->lastop, $method, $level + 1);
245 print $prefix, "}\n";
3f872cb9 246 } elsif ($ppname eq "subst") {
a798dbf2
MB
247 my $replstart = $op->pmreplstart;
248 if ($$replstart) {
249 print $prefix, "SUBST => {\n";
250 walkoptree_exec($replstart, $method, $level + 1);
251 print $prefix, "}\n";
252 }
253 }
254 }
255}
256
257sub walksymtable {
258 my ($symref, $method, $recurse, $prefix) = @_;
259 my $sym;
b6b0fb7b
MB
260 my $fullname;
261 no strict 'refs';
0cc1d052 262 $prefix = '' unless defined $prefix;
5cc8528c 263 foreach my $sym ( sort keys %$symref ) {
f4a37198
FC
264 my $dummy = $symref->{$sym}; # Copying the glob and incrementing
265 # the GPs refcnt clears cached methods
b6b0fb7b 266 $fullname = "*main::".$prefix.$sym;
a798dbf2
MB
267 if ($sym =~ /::$/) {
268 $sym = $prefix . $sym;
7834d9fb 269 if (svref_2object(\*$sym)->NAME ne "main::" && $sym ne "<none>::" && &$recurse($sym)) {
b6b0fb7b 270 walksymtable(\%$fullname, $method, $recurse, $sym);
a798dbf2
MB
271 }
272 } else {
b6b0fb7b 273 svref_2object(\*$fullname)->$method();
a798dbf2
MB
274 }
275 }
276}
277
a798dbf2 2781;
7f20e9dd
GS
279
280__END__
281
282=head1 NAME
283
4b661dd3 284B - The Perl Compiler Backend
7f20e9dd
GS
285
286=head1 SYNOPSIS
287
288 use B;
289
290=head1 DESCRIPTION
291
1a52ab62 292The C<B> module supplies classes which allow a Perl program to delve
130592f5
FC
293into its own innards. It is the module used to implement the
294"backends" of the Perl compiler. Usage of the compiler does not
1a52ab62 295require knowledge of this module: see the F<O> module for the
130592f5
FC
296user-visible part. The C<B> module is of use to those who want to
297write new compiler backends. This documentation assumes that the
1a52ab62
MB
298reader knows a fair amount about perl's internals including such
299things as SVs, OPs and the internal symbol table and syntax tree
300of a program.
301
85cf7f2e
MJD
302=head1 OVERVIEW
303
304The C<B> module contains a set of utility functions for querying the
305current state of the Perl interpreter; typically these functions
306return objects from the B::SV and B::OP classes, or their derived
307classes. These classes in turn define methods for querying the
308resulting objects about their own internal state.
309
310=head1 Utility Functions
311
312The C<B> module exports a variety of functions: some are simple
313utility functions, others provide a Perl program with a way to
314get an initial "handle" on an internal object.
315
316=head2 Functions Returning C<B::SV>, C<B::AV>, C<B::HV>, and C<B::CV> objects
317
3d036c2b 318For descriptions of the class hierarchy of these objects and the
85cf7f2e
MJD
319methods that can be called on them, see below, L<"OVERVIEW OF
320CLASSES"> and L<"SV-RELATED CLASSES">.
321
322=over 4
323
324=item sv_undef
325
326Returns the SV object corresponding to the C variable C<sv_undef>.
327
328=item sv_yes
329
330Returns the SV object corresponding to the C variable C<sv_yes>.
331
332=item sv_no
333
334Returns the SV object corresponding to the C variable C<sv_no>.
335
336=item svref_2object(SVREF)
337
338Takes a reference to any Perl value, and turns the referred-to value
339into an object in the appropriate B::OP-derived or B::SV-derived
130592f5 340class. Apart from functions such as C<main_root>, this is the primary
85cf7f2e
MJD
341way to get an initial "handle" on an internal perl data structure
342which can then be followed with the other access methods.
343
f31c3107 344The returned object will only be valid as long as the underlying OPs
130592f5 345and SVs continue to exist. Do not attempt to use the object after the
f31c3107
SM
346underlying structures are freed.
347
85cf7f2e
MJD
348=item amagic_generation
349
350Returns the SV object corresponding to the C variable C<amagic_generation>.
66978156
FC
351As of Perl 5.18, this is just an alias to C<PL_na>, so its value is
352meaningless.
85cf7f2e 353
e13efe3c 354=item init_av
85cf7f2e
MJD
355
356Returns the AV object (i.e. in class B::AV) representing INIT blocks.
357
ece599bd
RGS
358=item check_av
359
360Returns the AV object (i.e. in class B::AV) representing CHECK blocks.
361
676456c2
AG
362=item unitcheck_av
363
364Returns the AV object (i.e. in class B::AV) representing UNITCHECK blocks.
365
85cf7f2e
MJD
366=item begin_av
367
368Returns the AV object (i.e. in class B::AV) representing BEGIN blocks.
369
370=item end_av
371
372Returns the AV object (i.e. in class B::AV) representing END blocks.
373
374=item comppadlist
375
3a910aa0
FC
376Returns the PADLIST object (i.e. in class B::PADLIST) of the global
377comppadlist. In Perl 5.16 and earlier it returns an AV object (class
378B::AV).
85cf7f2e
MJD
379
380=item regex_padav
381
382Only when perl was compiled with ithreads.
383
e13efe3c 384=item main_cv
85cf7f2e
MJD
385
386Return the (faked) CV corresponding to the main part of the Perl
387program.
388
389=back
390
391=head2 Functions for Examining the Symbol Table
392
393=over 4
394
395=item walksymtable(SYMREF, METHOD, RECURSE, PREFIX)
396
397Walk the symbol table starting at SYMREF and call METHOD on each
398symbol (a B::GV object) visited. When the walk reaches package
399symbols (such as "Foo::") it invokes RECURSE, passing in the symbol
400name, and only recurses into the package if that sub returns true.
401
402PREFIX is the name of the SYMREF you're walking.
403
404For example:
405
406 # Walk CGI's symbol table calling print_subs on each symbol.
407 # Recurse only into CGI::Util::
26d2adad
FC
408 walksymtable(\%CGI::, 'print_subs',
409 sub { $_[0] eq 'CGI::Util::' }, 'CGI::');
85cf7f2e 410
130592f5 411print_subs() is a B::GV method you have declared. Also see L<"B::GV
85cf7f2e
MJD
412Methods">, below.
413
414=back
415
416=head2 Functions Returning C<B::OP> objects or for walking op trees
417
3d036c2b 418For descriptions of the class hierarchy of these objects and the
85cf7f2e
MJD
419methods that can be called on them, see below, L<"OVERVIEW OF
420CLASSES"> and L<"OP-RELATED CLASSES">.
421
422=over 4
423
424=item main_root
425
426Returns the root op (i.e. an object in the appropriate B::OP-derived
427class) of the main part of the Perl program.
428
429=item main_start
430
431Returns the starting op of the main part of the Perl program.
432
433=item walkoptree(OP, METHOD)
434
435Does a tree-walk of the syntax tree based at OP and calls METHOD on
130592f5 436each op it visits. Each node is visited before its children. If
85cf7f2e
MJD
437C<walkoptree_debug> (see below) has been called to turn debugging on then
438the method C<walkoptree_debug> is called on each op before METHOD is
439called.
440
441=item walkoptree_debug(DEBUG)
442
130592f5
FC
443Returns the current debugging flag for C<walkoptree>. If the optional
444DEBUG argument is non-zero, it sets the debugging flag to that. See
85cf7f2e
MJD
445the description of C<walkoptree> above for what the debugging flag
446does.
447
448=back
449
450=head2 Miscellaneous Utility Functions
451
452=over 4
453
454=item ppname(OPNUM)
455
456Return the PP function name (e.g. "pp_add") of op number OPNUM.
457
458=item hash(STR)
459
460Returns a string in the form "0x..." representing the value of the
461internal hash function used by perl on string STR.
462
463=item cast_I32(I)
464
465Casts I to the internal I32 type used by that perl.
466
467=item minus_c
468
130592f5 469Does the equivalent of the C<-c> command-line option. Obviously, this
85cf7f2e
MJD
470is only useful in a BEGIN block or else the flag is set too late.
471
472=item cstring(STR)
473
474Returns a double-quote-surrounded escaped version of STR which can
475be used as a string in C source code.
476
477=item perlstring(STR)
478
479Returns a double-quote-surrounded escaped version of STR which can
480be used as a string in Perl source code.
481
d9cd2aeb
FC
482=item safename(STR)
483
484This function returns the string with the first character modified if it
485is a control character. It converts it to ^X format first, so that "\cG"
486becomes "^G". This is used internally by L<B::GV::SAFENAME|/SAFENAME>, but
487you can call it directly.
488
85cf7f2e
MJD
489=item class(OBJ)
490
491Returns the class of an object without the part of the classname
130592f5 492preceding the first C<"::">. This is used to turn C<"B::UNOP"> into
85cf7f2e
MJD
493C<"UNOP"> for example.
494
495=item threadsv_names
496
dacd2ca7
DM
497This used to provide support for the old 5.005 threading module. It now
498does nothing.
85cf7f2e
MJD
499
500=back
501
4082acab 502=head2 Exported utility variables
baccf54f
NC
503
504=over 4
505
506=item @optype
507
508 my $op_type = $optype[$op_type_num];
85cf7f2e 509
baccf54f
NC
510A simple mapping of the op type number to its type (like 'COP' or 'BINOP').
511
512=item @specialsv_name
513
514 my $sv_name = $specialsv_name[$sv_index];
515
516Certain SV types are considered 'special'. They're represented by
517B::SPECIAL and are referred to by a number from the specialsv_list.
518This array maps that number back to the name of the SV (like 'Nullsv'
519or '&PL_sv_undef').
520
521=back
85cf7f2e
MJD
522
523
1a52ab62
MB
524=head1 OVERVIEW OF CLASSES
525
526The C structures used by Perl's internals to hold SV and OP
527information (PVIV, AV, HV, ..., OP, SVOP, UNOP, ...) are modelled on a
528class hierarchy and the C<B> module gives access to them via a true
130592f5 529object hierarchy. Structure fields which point to other objects
1a52ab62 530(whether types of SV or types of OP) are represented by the C<B>
85cf7f2e
MJD
531module as Perl objects of the appropriate class.
532
533The bulk of the C<B> module is the methods for accessing fields of
534these structures.
535
536Note that all access is read-only. You cannot modify the internals by
130592f5 537using this module. Also, note that the B::OP and B::SV objects created
f31c3107
SM
538by this module are only valid for as long as the underlying objects
539exist; their creation doesn't increase the reference counts of the
130592f5 540underlying objects. Trying to access the fields of a freed object will
f31c3107 541give incomprehensible results, or worse.
1a52ab62
MB
542
543=head2 SV-RELATED CLASSES
544
6822775c 545B::IV, B::NV, B::RV, B::PV, B::PVIV, B::PVNV, B::PVMG, B::BM (5.9.5 and
130592f5 546earlier), B::PVLV, B::AV, B::HV, B::CV, B::GV, B::FM, B::IO. These classes
6822775c 547correspond in the obvious way to the underlying C structures of similar names.
130592f5 548The inheritance hierarchy mimics the underlying C "inheritance". For the
dda36756 5495.10.x branch, (I<ie> 5.10.0, 5.10.1 I<etc>) this is:
85cf7f2e 550
6822775c
NC
551 B::SV
552 |
553 +------------+------------+------------+
554 | | | |
555 B::PV B::IV B::NV B::RV
556 \ / /
557 \ / /
558 B::PVIV /
b591c46e
NC
559 \ /
560 \ /
561 \ /
562 B::PVNV
563 |
564 |
565 B::PVMG
566 |
6822775c
NC
567 +-----+-----+-----+-----+
568 | | | | |
569 B::AV B::GV B::HV B::CV B::IO
570 | |
571 | |
572 B::PVLV B::FM
573
6822775c
NC
574For 5.9.0 and earlier, PVLV is a direct subclass of PVMG, and BM is still
575present as a distinct type, so the base of this diagram is
576
577
578 |
579 |
580 B::PVMG
581 |
582 +------+-----+-----+-----+-----+-----+
583 | | | | | | |
584 B::PVLV B::BM B::AV B::GV B::HV B::CV B::IO
585 |
586 |
587 B::FM
f5ba1307 588
dda36756
NC
589For 5.11.0 and later, B::RV is abolished, and IVs can be used to store
590references, and a new type B::REGEXP is introduced, giving this structure:
591
592 B::SV
593 |
594 +------------+------------+
595 | | |
596 B::PV B::IV B::NV
597 \ / /
598 \ / /
599 B::PVIV /
600 \ /
601 \ /
602 \ /
603 B::PVNV
604 |
605 |
606 B::PVMG
607 |
608 +-------+-------+---+---+-------+-------+
609 | | | | | |
610 B::AV B::GV B::HV B::CV B::IO B::REGEXP
611 | |
612 | |
613 B::PVLV B::FM
614
f5ba1307 615
85cf7f2e 616Access methods correspond to the underlying C macros for field access,
1a52ab62 617usually with the leading "class indication" prefix removed (Sv, Av,
130592f5
FC
618Hv, ...). The leading prefix is only left in cases where its removal
619would cause a clash in method name. For example, C<GvREFCNT> stays
1a52ab62
MB
620as-is since its abbreviation would clash with the "superclass" method
621C<REFCNT> (corresponding to the C function C<SvREFCNT>).
622
85cf7f2e 623=head2 B::SV Methods
1a52ab62
MB
624
625=over 4
626
627=item REFCNT
628
629=item FLAGS
630
429a5ce7
SM
631=item object_2svref
632
633Returns a reference to the regular scalar corresponding to this
130592f5
FC
634B::SV object. In other words, this method is the inverse operation
635to the svref_2object() subroutine. This scalar and other data it points
429a5ce7
SM
636at should be considered read-only: modifying them is neither safe nor
637guaranteed to have a sensible effect.
638
1a52ab62
MB
639=back
640
85cf7f2e 641=head2 B::IV Methods
1a52ab62
MB
642
643=over 4
644
645=item IV
646
d9963e60 647Returns the value of the IV, I<interpreted as
130592f5
FC
648a signed integer>. This will be misleading
649if C<FLAGS & SVf_IVisUV>. Perhaps you want the
d9963e60
RH
650C<int_value> method instead?
651
1a52ab62
MB
652=item IVX
653
d9963e60
RH
654=item UVX
655
656=item int_value
657
658This method returns the value of the IV as an integer.
659It differs from C<IV> in that it returns the correct
660value regardless of whether it's stored signed or
661unsigned.
662
1a52ab62
MB
663=item needs64bits
664
665=item packiv
666
667=back
668
85cf7f2e 669=head2 B::NV Methods
1a52ab62
MB
670
671=over 4
672
673=item NV
674
675=item NVX
676
43e81a9a
FC
677=item COP_SEQ_RANGE_LOW
678
679=item COP_SEQ_RANGE_HIGH
680
dbac5ffe
FC
681These last two are only valid for pad name SVs. They only existed in the
682B::NV class before Perl 5.22. In 5.22 they were moved to the B::PADNAME
683class.
43e81a9a 684
1a52ab62
MB
685=back
686
85cf7f2e 687=head2 B::RV Methods
1a52ab62
MB
688
689=over 4
690
691=item RV
692
693=back
694
85cf7f2e 695=head2 B::PV Methods
1a52ab62
MB
696
697=over 4
698
699=item PV
700
130592f5 701This method is the one you usually want. It constructs a
76ef7183
JH
702string using the length and offset information in the struct:
703for ordinary scalars it will return the string that you'd see
704from Perl, even if it contains null characters.
705
9d2bbe64
MB
706=item RV
707
708Same as B::RV::RV, except that it will die() if the PV isn't
709a reference.
710
0b40bd6d
RH
711=item PVX
712
130592f5 713This method is less often useful. It assumes that the string
76ef7183
JH
714stored in the struct is null-terminated, and disregards the
715length information.
716
717It is the appropriate method to use if you need to get the name
130592f5 718of a lexical variable from a padname array. Lexical variable names
76ef7183 719are always stored with a null terminator, and the length field
5c140421
FC
720(CUR) is overloaded for other purposes and can't be relied on here.
721
722=item CUR
723
724This method returns the internal length field, which consists of the number
725of internal bytes, not necessarily the number of logical characters.
726
727=item LEN
728
729This method returns the number of bytes allocated (via malloc) for storing
730the string. This is 0 if the scalar does not "own" the string.
76ef7183 731
1a52ab62
MB
732=back
733
85cf7f2e 734=head2 B::PVMG Methods
1a52ab62
MB
735
736=over 4
737
738=item MAGIC
739
740=item SvSTASH
741
742=back
743
85cf7f2e 744=head2 B::MAGIC Methods
1a52ab62
MB
745
746=over 4
747
748=item MOREMAGIC
749
9d2bbe64
MB
750=item precomp
751
752Only valid on r-magic, returns the string that generated the regexp.
753
1a52ab62
MB
754=item PRIVATE
755
756=item TYPE
757
758=item FLAGS
759
760=item OBJ
761
9d2bbe64
MB
762Will die() if called on r-magic.
763
1a52ab62
MB
764=item PTR
765
9d2bbe64
MB
766=item REGEX
767
768Only valid on r-magic, returns the integer value of the REGEX stored
769in the MAGIC.
770
1a52ab62
MB
771=back
772
85cf7f2e 773=head2 B::PVLV Methods
1a52ab62
MB
774
775=over 4
776
777=item TARGOFF
778
779=item TARGLEN
780
781=item TYPE
782
783=item TARG
784
785=back
786
85cf7f2e 787=head2 B::BM Methods
1a52ab62
MB
788
789=over 4
790
791=item USEFUL
792
793=item PREVIOUS
794
795=item RARE
796
797=item TABLE
798
799=back
800
3f03baed
FC
801=head2 B::REGEXP Methods
802
803=over 4
804
805=item REGEX
806
807=item precomp
808
6190dd99
FC
809=item qr_anoncv
810
1f306347
FC
811=item compflags
812
813The last two were added in Perl 5.22.
814
3f03baed
FC
815=back
816
85cf7f2e 817=head2 B::GV Methods
1a52ab62
MB
818
819=over 4
820
87d7fd28
GS
821=item is_empty
822
823This method returns TRUE if the GP field of the GV is NULL.
824
1a52ab62
MB
825=item NAME
826
002b978b
RH
827=item SAFENAME
828
829This method returns the name of the glob, but if the first
830character of the name is a control character, then it converts
831it to ^X first, so that *^G would return "^G" rather than "\cG".
832
833It's useful if you want to print out the name of a variable.
834If you restrict yourself to globs which exist at compile-time
835then the result ought to be unambiguous, because code like
836C<${"^G"} = 1> is compiled as two ops - a constant string and
837a dereference (rv2gv) - so that the glob is created at runtime.
838
839If you're working with globs at runtime, and need to disambiguate
840*^G from *{"^G"}, then you should use the raw NAME method.
841
1a52ab62
MB
842=item STASH
843
844=item SV
845
846=item IO
847
848=item FORM
849
850=item AV
851
852=item HV
853
854=item EGV
855
856=item CV
857
858=item CVGEN
859
860=item LINE
861
b195d487
GS
862=item FILE
863
1a52ab62
MB
864=item FILEGV
865
866=item GvREFCNT
867
868=item FLAGS
869
8f4983af
FC
870=item GPFLAGS
871
872This last one is present only in perl 5.22.0 and higher.
873
1a52ab62
MB
874=back
875
85cf7f2e 876=head2 B::IO Methods
1a52ab62 877
8b858c71
FC
878B::IO objects derive from IO objects and you will get more information from
879the IO object itself.
44f7f2d5
RU
880
881For example:
882
883 $gvio = B::svref_2object(\*main::stdin)->IO;
884 $IO = $gvio->object_2svref();
885 $fd = $IO->fileno();
886
1a52ab62
MB
887=over 4
888
889=item LINES
890
891=item PAGE
892
893=item PAGE_LEN
894
895=item LINES_LEFT
896
897=item TOP_NAME
898
899=item TOP_GV
900
901=item FMT_NAME
902
903=item FMT_GV
904
905=item BOTTOM_NAME
906
907=item BOTTOM_GV
908
909=item SUBPROCESS
910
911=item IoTYPE
912
44f7f2d5
RU
913A character symbolizing the type of IO Handle.
914
915 - STDIN/OUT
916 I STDIN/OUT/ERR
917 < read-only
918 > write-only
919 a append
920 + read and write
921 s socket
922 | pipe
923 I IMPLICIT
924 # NUMERIC
925 space closed handle
926 \0 closed internal handle
927
1a52ab62
MB
928=item IoFLAGS
929
9d2bbe64
MB
930=item IsSTD
931
44f7f2d5 932Takes one argument ( 'stdin' | 'stdout' | 'stderr' ) and returns true
9d2bbe64 933if the IoIFP of the object is equal to the handle whose name was
8b858c71 934passed as argument; i.e., $io->IsSTD('stderr') is true if
44f7f2d5 935IoIFP($io) == PerlIO_stderr().
9d2bbe64 936
1a52ab62
MB
937=back
938
85cf7f2e 939=head2 B::AV Methods
1a52ab62
MB
940
941=over 4
942
943=item FILL
944
945=item MAX
946
1a52ab62
MB
947=item ARRAY
948
429a5ce7
SM
949=item ARRAYelt
950
951Like C<ARRAY>, but takes an index as an argument to get only one element,
952rather than a list of all of them.
953
edcc7c74
NC
954=item OFF
955
956This method is deprecated if running under Perl 5.8, and is no longer present
957if running under Perl 5.9
958
959=item AvFLAGS
960
130592f5
FC
961This method returns the AV specific
962flags. In Perl 5.9 these are now stored
edcc7c74
NC
963in with the main SV flags, so this method is no longer present.
964
1a52ab62
MB
965=back
966
85cf7f2e 967=head2 B::CV Methods
1a52ab62
MB
968
969=over 4
970
971=item STASH
972
973=item START
974
975=item ROOT
976
977=item GV
978
57843af0
GS
979=item FILE
980
1a52ab62
MB
981=item DEPTH
982
983=item PADLIST
984
3a910aa0
FC
985Returns a B::PADLIST object under Perl 5.18 or higher, or a B::AV in
986earlier versions.
987
1a52ab62
MB
988=item OUTSIDE
989
a3985cdc
DM
990=item OUTSIDE_SEQ
991
1a52ab62
MB
992=item XSUB
993
994=item XSUBANY
995
9d2bbe64
MB
996For constant subroutines, returns the constant SV returned by the subroutine.
997
5cfd8ad4
VB
998=item CvFLAGS
999
de3f1649
JT
1000=item const_sv
1001
486b1e7f
TC
1002=item NAME_HEK
1003
1004Returns the name of a lexical sub, otherwise C<undef>.
1005
1a52ab62
MB
1006=back
1007
85cf7f2e 1008=head2 B::HV Methods
1a52ab62
MB
1009
1010=over 4
1011
1012=item FILL
1013
1014=item MAX
1015
1016=item KEYS
1017
1018=item RITER
1019
1020=item NAME
1021
1a52ab62
MB
1022=item ARRAY
1023
edcc7c74
NC
1024=item PMROOT
1025
1026This method is not present if running under Perl 5.9, as the PMROOT
1027information is no longer stored directly in the hash.
1028
1a52ab62
MB
1029=back
1030
1031=head2 OP-RELATED CLASSES
1032
2f7c6295
DM
1033C<B::OP>, C<B::UNOP>, C<B::UNOP_AUX>, C<B::BINOP>, C<B::LOGOP>,
1034C<B::LISTOP>, C<B::PMOP>, C<B::SVOP>, C<B::PADOP>, C<B::PVOP>, C<B::LOOP>,
1035C<B::COP>, C<B::METHOP>.
85cf7f2e
MJD
1036
1037These classes correspond in the obvious way to the underlying C
130592f5 1038structures of similar names. The inheritance hierarchy mimics the
85cf7f2e
MJD
1039underlying C "inheritance":
1040
1041 B::OP
1042 |
b46e009d 1043 +----------+---------+--------+-------+---------+
1044 | | | | | |
1045 B::UNOP B::SVOP B::PADOP B::COP B::PVOP B::METHOP
2f7c6295
DM
1046 |
1047 +---+---+---------+
1048 | | |
1049 B::BINOP B::LOGOP B::UNOP_AUX
85cf7f2e
MJD
1050 |
1051 |
1052 B::LISTOP
2f7c6295
DM
1053 |
1054 +---+---+
1055 | |
1056 B::LOOP B::PMOP
85cf7f2e 1057
b84c7839 1058Access methods correspond to the underlying C structure field names,
85cf7f2e
MJD
1059with the leading "class indication" prefix (C<"op_">) removed.
1060
1061=head2 B::OP Methods
1a52ab62 1062
a60ba18b
JC
1063These methods get the values of similarly named fields within the OP
1064data structure. See top of C<op.h> for more info.
1065
1a52ab62
MB
1066=over 4
1067
1068=item next
1069
1070=item sibling
1071
29e61fd9
DM
1072=item parent
1073
1074Returns the OP's parent. If it has no parent, or if your perl wasn't built
1075with C<-DPERL_OP_PARENT>, returns NULL.
1076
c3890f9c
DM
1077Note that the global variable C<$B::OP::does_parent> is undefined on older
1078perls that don't support the C<parent> method, is defined but false on
1079perls that support the method but were built without C<-DPERL_OP_PARENT>,
1080and is true otherwise.
1081
3f872cb9
GS
1082=item name
1083
1084This returns the op name as a string (e.g. "add", "rv2av").
1085
1a52ab62
MB
1086=item ppaddr
1087
dc333d64
GS
1088This returns the function name as a string (e.g. "PL_ppaddr[OP_ADD]",
1089"PL_ppaddr[OP_RV2AV]").
1a52ab62
MB
1090
1091=item desc
1092
4369b173 1093This returns the op description from the global C PL_op_desc array
1a52ab62
MB
1094(e.g. "addition" "array deref").
1095
1096=item targ
1097
1098=item type
1099
a60ba18b
JC
1100=item opt
1101
1a52ab62
MB
1102=item flags
1103
1104=item private
1105
a60ba18b
JC
1106=item spare
1107
1a52ab62
MB
1108=back
1109
18aceeb0 1110=head2 B::UNOP Method
1a52ab62
MB
1111
1112=over 4
1113
1114=item first
1115
1116=back
1117
18aceeb0 1118=head2 B::UNOP_AUX Methods (since 5.22)
2f7c6295
DM
1119
1120=over 4
1121
1122=item aux_list(cv)
1123
1124This returns a list of the elements of the op's aux data structure,
1125or a null list if there is no aux. What will be returned depends on the
1126object's type, but will typically be a collection of C<B::IV>, C<B::GV>,
1127etc. objects. C<cv> is the C<B::CV> object representing the sub that the
1128op is contained within.
1129
1130=item string(cv)
1131
1132This returns a textual representation of the object (likely to b useful
1133for deparsing and debugging), or an empty string if the op type doesn't
1134support this. C<cv> is the C<B::CV> object representing the sub that the
1135op is contained within.
1136
1137=back
1138
18aceeb0 1139=head2 B::BINOP Method
1a52ab62
MB
1140
1141=over 4
1142
1143=item last
1144
1145=back
1146
18aceeb0 1147=head2 B::LOGOP Method
1a52ab62
MB
1148
1149=over 4
1150
1151=item other
1152
1153=back
1154
18aceeb0 1155=head2 B::LISTOP Method
1a52ab62
MB
1156
1157=over 4
1158
1159=item children
1160
1161=back
1162
85cf7f2e 1163=head2 B::PMOP Methods
1a52ab62
MB
1164
1165=over 4
1166
1167=item pmreplroot
1168
1169=item pmreplstart
1170
1171=item pmnext
1172
196d796c
RU
1173Only up to Perl 5.9.4
1174
1a52ab62
MB
1175=item pmflags
1176
c737faaf 1177=item extflags
1a52ab62 1178
196d796c
RU
1179Since Perl 5.9.5
1180
1a52ab62
MB
1181=item precomp
1182
651aa52e 1183=item pmoffset
9d2bbe64
MB
1184
1185Only when perl was compiled with ithreads.
1186
e07bb516
DM
1187=item code_list
1188
1189Since perl 5.17.1
1190
429ba3b2
FC
1191=item pmregexp
1192
1193Added in perl 5.22, this method returns the B::REGEXP associated with the
1194op. While PMOPs do not actually have C<pmregexp> fields under threaded
1195builds, this method returns the regexp under threads nonetheless, for
1196convenience.
1197
1a52ab62
MB
1198=back
1199
18aceeb0 1200=head2 B::SVOP Methods
1a52ab62
MB
1201
1202=over 4
1203
1204=item sv
1205
065a1863
GS
1206=item gv
1207
1a52ab62
MB
1208=back
1209
18aceeb0 1210=head2 B::PADOP Method
1a52ab62
MB
1211
1212=over 4
1213
7934575e 1214=item padix
1a52ab62
MB
1215
1216=back
1217
18aceeb0 1218=head2 B::PVOP Method
1a52ab62
MB
1219
1220=over 4
1221
1222=item pv
1223
1224=back
1225
85cf7f2e 1226=head2 B::LOOP Methods
1a52ab62
MB
1227
1228=over 4
1229
1230=item redoop
1231
1232=item nextop
1233
1234=item lastop
1235
1236=back
1237
85cf7f2e 1238=head2 B::COP Methods
1a52ab62 1239
a379c8cb
FC
1240The C<B::COP> class is used for "nextstate" and "dbstate" ops. As of Perl
12415.22, it is also used for "null" ops that started out as COPs.
1242
1a52ab62
MB
1243=over 4
1244
1245=item label
1246
1247=item stash
1248
6e6a1aef
RGS
1249=item stashpv
1250
a60c099b 1251=item stashoff (threaded only)
8df2993f 1252
57843af0 1253=item file
1a52ab62
MB
1254
1255=item cop_seq
1256
1257=item arybase
1258
1259=item line
1260
6e6a1aef
RGS
1261=item warnings
1262
1263=item io
1264
d5ec2987
NC
1265=item hints
1266
b47e7f93
RGS
1267=item hints_hash
1268
1a52ab62
MB
1269=back
1270
b46e009d 1271=head2 B::METHOP Methods (Since Perl 5.22)
1272
1273=over 4
1274
1275=item first
1276
1277=item meth_sv
1278
1279=back
1280
9b7476d7 1281=head2 PAD-RELATED CLASSES
3a910aa0 1282
9b7476d7 1283Perl 5.18 introduced a new class, B::PADLIST, returned by B::CV's
3a910aa0
FC
1284C<PADLIST> method.
1285
9b7476d7
FC
1286Perl 5.22 introduced the B::PADNAMELIST and B::PADNAME classes.
1287
3a910aa0
FC
1288=head2 B::PADLIST Methods
1289
1290=over 4
1291
1292=item MAX
1293
1294=item ARRAY
1295
9b7476d7
FC
1296A list of pads. The first one contains the names.
1297
1298The first one is a B::PADNAMELIST under Perl 5.22, and a B::AV under
1299earlier versions. The rest are currently B::AV objects, but that could
1300change in future versions.
3a910aa0
FC
1301
1302=item ARRAYelt
1303
1304Like C<ARRAY>, but takes an index as an argument to get only one element,
1305rather than a list of all of them.
1306
9b7476d7
FC
1307=item NAMES
1308
1309This method, introduced in 5.22, returns the B::PADNAMELIST. It is
1310equivalent to C<ARRAYelt> with a 0 argument.
1311
1312=item REFCNT
1313
58480c3b
FC
1314=item id
1315
1316This method, introduced in 5.22, returns an ID shared by clones of the same
1317padlist.
1318
1319=item outid
1320
1321This method, also added in 5.22, returns the ID of the outer padlist.
1322
9b7476d7
FC
1323=back
1324
1325=head2 B::PADNAMELIST Methods
1326
1327=over 4
1328
1329=item MAX
1330
1331=item ARRAY
1332
1333=item ARRAYelt
1334
aa572f37
FC
1335These two methods return the pad names, using B::SPECIAL objects for null
1336pointers and B::PADNAME objects otherwise.
1337
3a910aa0
FC
1338=item REFCNT
1339
1340=back
7f20e9dd 1341
dbac5ffe
FC
1342=head2 B::PADNAME Methods
1343
1344=over 4
1345
1346=item PV
1347
1348=item PVX
1349
1350=item LEN
1351
1352=item REFCNT
1353
1354=item FLAGS
1355
1356For backward-compatibility, if the PADNAMEt_OUTER flag is set, the FLAGS
1357method adds the SVf_FAKE flag, too.
1358
1359=item TYPE
1360
1361A B::HV object representing the stash for a typed lexical.
1362
1363=item SvSTASH
1364
1365A backward-compatibility alias for TYPE.
1366
1367=item OURSTASH
1368
1369A B::HV object representing the stash for 'our' variables.
1370
1371=item PROTOCV
1372
1373The prototype CV for a 'my' sub.
1374
1375=item COP_SEQ_RANGE_LOW
1376
1377=item COP_SEQ_RANGE_HIGH
1378
1379Sequence numbers representing the scope within which a lexical is visible.
1380Meaningless if PADNAMEt_OUTER is set.
1381
1382=item PARENT_PAD_INDEX
1383
1384Only meaningful if PADNAMEt_OUTER is set.
1385
1386=item PARENT_FAKELEX_FLAGS
1387
1388Only meaningful if PADNAMEt_OUTER is set.
1389
1390=back
1391
71324a3b
DM
1392=head2 $B::overlay
1393
1394Although the optree is read-only, there is an overlay facility that allows
1395you to override what values the various B::*OP methods return for a
1396particular op. C<$B::overlay> should be set to reference a two-deep hash:
1397indexed by OP address, then method name. Whenever a an op method is
1398called, the value in the hash is returned if it exists. This facility is
1399used by B::Deparse to "undo" some optimisations. For example:
1400
1401
1402 local $B::overlay = {};
1403 ...
1404 if ($op->name eq "foo") {
1405 $B::overlay->{$$op} = {
1406 name => 'bar',
1407 next => $op->next->next,
1408 };
1409 }
1410 ...
1411 $op->name # returns "bar"
1412 $op->next # returns the next op but one
1413
1414
7f20e9dd
GS
1415=head1 AUTHOR
1416
1417Malcolm Beattie, C<mbeattie@sable.ox.ac.uk>
1418
1419=cut