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