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