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