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