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