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