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