This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
More POD corrections
[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 {
4082acab 18 $B::VERSION = '1.28';
744aaba0
NC
19
20 @B::EXPORT_OK = qw(minus_c ppname save_BEGINs
21 class peekop cast_I32 cstring cchar hash threadsv_names
22 main_root main_start main_cv svref_2object opnumber
23 sub_generation amagic_generation perlstring
24 walkoptree_slow walkoptree walkoptree_exec walksymtable
25 parents comppadlist sv_undef compile_stats timing_info
26 begin_av init_av check_av end_av regex_padav dowarn
27 defstash curstash warnhook diehook inc_gv @optype
28 @specialsv_name
29 );
30 push @B::EXPORT_OK, qw(unitcheck_av) if $] > 5.009;
31
32 # All the above in this BEGIN, because our BOOT code needs $VERSION set,
33 # and will append to @EXPORT_OK. And we need to run the BOOT code before
34 # we see OPf_KIDS below.
35 require XSLoader;
36 XSLoader::load();
37}
38
a798dbf2
MB
39@B::SV::ISA = 'B::OBJECT';
40@B::NULL::ISA = 'B::SV';
41@B::PV::ISA = 'B::SV';
42@B::IV::ISA = 'B::SV';
4edc9001 43@B::NV::ISA = 'B::SV';
4df7f6af 44# RV is eliminated with 5.11.0, but effectively is a specialisation of IV now.
3ce3ed55 45@B::RV::ISA = $] >= 5.011 ? 'B::IV' : 'B::SV';
a798dbf2 46@B::PVIV::ISA = qw(B::PV B::IV);
4edc9001 47@B::PVNV::ISA = qw(B::PVIV B::NV);
a798dbf2 48@B::PVMG::ISA = 'B::PVNV';
5c35adbb 49@B::REGEXP::ISA = 'B::PVMG' if $] >= 5.011;
a01b8a53 50# Change in the inheritance hierarchy post 5.9.0
f5ba1307 51@B::PVLV::ISA = $] > 5.009 ? 'B::GV' : 'B::PVMG';
6822775c
NC
52# BM is eliminated post 5.9.5, but effectively is a specialisation of GV now.
53@B::BM::ISA = $] > 5.009005 ? 'B::GV' : 'B::PVMG';
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
RH
87sub B::GV::SAFENAME {
88 my $name = (shift())->NAME;
d9963e60
RH
89
90 # The regex below corresponds to the isCONTROLVAR macro
91 # from toke.c
92
7a9b44b9
RH
93 $name =~ s/^([\cA-\cZ\c\\c[\c]\c?\c_\c^])/"^".
94 chr( utf8::unicode_to_native( 64 ^ ord($1) ))/e;
95
96 # When we say unicode_to_native we really mean ascii_to_native,
97 # which matters iff this is a non-ASCII platform (EBCDIC).
98
002b978b
RH
99 return $name;
100}
101
d9963e60
RH
102sub B::IV::int_value {
103 my ($self) = @_;
104 return (($self->FLAGS() & SVf_IVisUV()) ? $self->UVX : $self->IV);
105}
106
f3402b25 107sub B::NULL::as_string() {""}
0e4a84de
NC
108*B::IV::as_string = \&B::IV::int_value;
109*B::PV::as_string = \&B::PV::PV;
f3402b25 110
ff1a9fc0
NC
111# The input typemap checking makes no distinction between different SV types,
112# so the XS body will generate the same C code, despite the different XS
113# "types". So there is no change in behaviour from doing "newXS" like this,
114# compared with the old approach of having a (near) duplicate XS body.
115# We should fix the typemap checking.
116*B::IV::RV = \&B::PV::RV if $] > 5.012;
117
a798dbf2
MB
118my $debug;
119my $op_count = 0;
120my @parents = ();
121
122sub debug {
123 my ($class, $value) = @_;
124 $debug = $value;
125 walkoptree_debug($value);
126}
127
a798dbf2
MB
128sub class {
129 my $obj = shift;
130 my $name = ref $obj;
131 $name =~ s/^.*:://;
132 return $name;
133}
134
135sub parents { \@parents }
136
137# For debugging
138sub peekop {
139 my $op = shift;
3f872cb9 140 return sprintf("%s (0x%x) %s", class($op), $$op, $op->name);
a798dbf2
MB
141}
142
b2590c4e 143sub walkoptree_slow {
a798dbf2
MB
144 my($op, $method, $level) = @_;
145 $op_count++; # just for statistics
146 $level ||= 0;
147 warn(sprintf("walkoptree: %d. %s\n", $level, peekop($op))) if $debug;
156f89f0 148 $op->$method($level) if $op->can($method);
a798dbf2
MB
149 if ($$op && ($op->flags & OPf_KIDS)) {
150 my $kid;
151 unshift(@parents, $op);
152 for ($kid = $op->first; $$kid; $kid = $kid->sibling) {
b2590c4e 153 walkoptree_slow($kid, $method, $level + 1);
a798dbf2
MB
154 }
155 shift @parents;
156 }
156f89f0
JJ
157 if (class($op) eq 'PMOP'
158 && ref($op->pmreplroot)
159 && ${$op->pmreplroot}
160 && $op->pmreplroot->isa( 'B::OP' ))
161 {
0091380b
RGS
162 unshift(@parents, $op);
163 walkoptree_slow($op->pmreplroot, $method, $level + 1);
164 shift @parents;
165 }
a798dbf2
MB
166}
167
168sub compile_stats {
169 return "Total number of OPs processed: $op_count\n";
170}
171
172sub timing_info {
173 my ($sec, $min, $hr) = localtime;
174 my ($user, $sys) = times;
175 sprintf("%02d:%02d:%02d user=$user sys=$sys",
176 $hr, $min, $sec, $user, $sys);
177}
178
179my %symtable;
2b8dc4d2
DM
180
181sub clearsym {
182 %symtable = ();
183}
184
a798dbf2
MB
185sub savesym {
186 my ($obj, $value) = @_;
187# warn(sprintf("savesym: sym_%x => %s\n", $$obj, $value)); # debug
188 $symtable{sprintf("sym_%x", $$obj)} = $value;
189}
190
191sub objsym {
192 my $obj = shift;
193 return $symtable{sprintf("sym_%x", $$obj)};
194}
195
196sub walkoptree_exec {
197 my ($op, $method, $level) = @_;
244826eb 198 $level ||= 0;
a798dbf2
MB
199 my ($sym, $ppname);
200 my $prefix = " " x $level;
201 for (; $$op; $op = $op->next) {
202 $sym = objsym($op);
203 if (defined($sym)) {
204 print $prefix, "goto $sym\n";
205 return;
206 }
207 savesym($op, sprintf("%s (0x%lx)", class($op), $$op));
208 $op->$method($level);
3f872cb9 209 $ppname = $op->name;
1a67a97c 210 if ($ppname =~
62e36f8a 211 /^(d?or(assign)?|and(assign)?|mapwhile|grepwhile|entertry|range|cond_expr)$/)
1a67a97c 212 {
a798dbf2
MB
213 print $prefix, uc($1), " => {\n";
214 walkoptree_exec($op->other, $method, $level + 1);
215 print $prefix, "}\n";
3f872cb9 216 } elsif ($ppname eq "match" || $ppname eq "subst") {
a798dbf2
MB
217 my $pmreplstart = $op->pmreplstart;
218 if ($$pmreplstart) {
219 print $prefix, "PMREPLSTART => {\n";
220 walkoptree_exec($pmreplstart, $method, $level + 1);
221 print $prefix, "}\n";
222 }
3f872cb9 223 } elsif ($ppname eq "substcont") {
a798dbf2
MB
224 print $prefix, "SUBSTCONT => {\n";
225 walkoptree_exec($op->other->pmreplstart, $method, $level + 1);
226 print $prefix, "}\n";
227 $op = $op->other;
3f872cb9 228 } elsif ($ppname eq "enterloop") {
a798dbf2
MB
229 print $prefix, "REDO => {\n";
230 walkoptree_exec($op->redoop, $method, $level + 1);
231 print $prefix, "}\n", $prefix, "NEXT => {\n";
232 walkoptree_exec($op->nextop, $method, $level + 1);
233 print $prefix, "}\n", $prefix, "LAST => {\n";
234 walkoptree_exec($op->lastop, $method, $level + 1);
235 print $prefix, "}\n";
3f872cb9 236 } elsif ($ppname eq "subst") {
a798dbf2
MB
237 my $replstart = $op->pmreplstart;
238 if ($$replstart) {
239 print $prefix, "SUBST => {\n";
240 walkoptree_exec($replstart, $method, $level + 1);
241 print $prefix, "}\n";
242 }
243 }
244 }
245}
246
247sub walksymtable {
248 my ($symref, $method, $recurse, $prefix) = @_;
249 my $sym;
0cc1d052 250 my $ref;
b6b0fb7b
MB
251 my $fullname;
252 no strict 'refs';
0cc1d052
NIS
253 $prefix = '' unless defined $prefix;
254 while (($sym, $ref) = each %$symref) {
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
MB
347The C<B> module supplies classes which allow a Perl program to delve
348into its own innards. It is the module used to implement the
349"backends" of the Perl compiler. Usage of the compiler does not
350require knowledge of this module: see the F<O> module for the
351user-visible part. The C<B> module is of use to those who want to
352write new compiler backends. This documentation assumes that the
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
395class. Apart from functions such as C<main_root>, this is the primary
396way to get an initial "handle" on an internal perl data structure
397which can then be followed with the other access methods.
398
f31c3107
SM
399The returned object will only be valid as long as the underlying OPs
400and SVs continue to exist. Do not attempt to use the object after the
401underlying structures are freed.
402
85cf7f2e
MJD
403=item amagic_generation
404
405Returns the SV object corresponding to the C variable C<amagic_generation>.
406
e13efe3c 407=item init_av
85cf7f2e
MJD
408
409Returns the AV object (i.e. in class B::AV) representing INIT blocks.
410
ece599bd
RGS
411=item check_av
412
413Returns the AV object (i.e. in class B::AV) representing CHECK blocks.
414
676456c2
AG
415=item unitcheck_av
416
417Returns the AV object (i.e. in class B::AV) representing UNITCHECK blocks.
418
85cf7f2e
MJD
419=item begin_av
420
421Returns the AV object (i.e. in class B::AV) representing BEGIN blocks.
422
423=item end_av
424
425Returns the AV object (i.e. in class B::AV) representing END blocks.
426
427=item comppadlist
428
429Returns the AV object (i.e. in class B::AV) of the global comppadlist.
430
431=item regex_padav
432
433Only when perl was compiled with ithreads.
434
e13efe3c 435=item main_cv
85cf7f2e
MJD
436
437Return the (faked) CV corresponding to the main part of the Perl
438program.
439
440=back
441
442=head2 Functions for Examining the Symbol Table
443
444=over 4
445
446=item walksymtable(SYMREF, METHOD, RECURSE, PREFIX)
447
448Walk the symbol table starting at SYMREF and call METHOD on each
449symbol (a B::GV object) visited. When the walk reaches package
450symbols (such as "Foo::") it invokes RECURSE, passing in the symbol
451name, and only recurses into the package if that sub returns true.
452
453PREFIX is the name of the SYMREF you're walking.
454
455For example:
456
457 # Walk CGI's symbol table calling print_subs on each symbol.
458 # Recurse only into CGI::Util::
459 walksymtable(\%CGI::, 'print_subs', sub { $_[0] eq 'CGI::Util::' },
460 'CGI::');
461
462print_subs() is a B::GV method you have declared. Also see L<"B::GV
463Methods">, below.
464
465=back
466
467=head2 Functions Returning C<B::OP> objects or for walking op trees
468
3d036c2b 469For descriptions of the class hierarchy of these objects and the
85cf7f2e
MJD
470methods that can be called on them, see below, L<"OVERVIEW OF
471CLASSES"> and L<"OP-RELATED CLASSES">.
472
473=over 4
474
475=item main_root
476
477Returns the root op (i.e. an object in the appropriate B::OP-derived
478class) of the main part of the Perl program.
479
480=item main_start
481
482Returns the starting op of the main part of the Perl program.
483
484=item walkoptree(OP, METHOD)
485
486Does a tree-walk of the syntax tree based at OP and calls METHOD on
487each op it visits. Each node is visited before its children. If
488C<walkoptree_debug> (see below) has been called to turn debugging on then
489the method C<walkoptree_debug> is called on each op before METHOD is
490called.
491
492=item walkoptree_debug(DEBUG)
493
494Returns the current debugging flag for C<walkoptree>. If the optional
495DEBUG argument is non-zero, it sets the debugging flag to that. See
496the description of C<walkoptree> above for what the debugging flag
497does.
498
499=back
500
501=head2 Miscellaneous Utility Functions
502
503=over 4
504
505=item ppname(OPNUM)
506
507Return the PP function name (e.g. "pp_add") of op number OPNUM.
508
509=item hash(STR)
510
511Returns a string in the form "0x..." representing the value of the
512internal hash function used by perl on string STR.
513
514=item cast_I32(I)
515
516Casts I to the internal I32 type used by that perl.
517
518=item minus_c
519
520Does the equivalent of the C<-c> command-line option. Obviously, this
521is only useful in a BEGIN block or else the flag is set too late.
522
523=item cstring(STR)
524
525Returns a double-quote-surrounded escaped version of STR which can
526be used as a string in C source code.
527
528=item perlstring(STR)
529
530Returns a double-quote-surrounded escaped version of STR which can
531be used as a string in Perl source code.
532
533=item class(OBJ)
534
535Returns the class of an object without the part of the classname
536preceding the first C<"::">. This is used to turn C<"B::UNOP"> into
537C<"UNOP"> for example.
538
539=item threadsv_names
540
541In a perl compiled for threads, this returns a list of the special
542per-thread threadsv variables.
543
544=back
545
4082acab 546=head2 Exported utility variables
baccf54f
NC
547
548=over 4
549
550=item @optype
551
552 my $op_type = $optype[$op_type_num];
85cf7f2e 553
baccf54f
NC
554A simple mapping of the op type number to its type (like 'COP' or 'BINOP').
555
556=item @specialsv_name
557
558 my $sv_name = $specialsv_name[$sv_index];
559
560Certain SV types are considered 'special'. They're represented by
561B::SPECIAL and are referred to by a number from the specialsv_list.
562This array maps that number back to the name of the SV (like 'Nullsv'
563or '&PL_sv_undef').
564
565=back
85cf7f2e
MJD
566
567
1a52ab62
MB
568=head1 OVERVIEW OF CLASSES
569
570The C structures used by Perl's internals to hold SV and OP
571information (PVIV, AV, HV, ..., OP, SVOP, UNOP, ...) are modelled on a
572class hierarchy and the C<B> module gives access to them via a true
573object hierarchy. Structure fields which point to other objects
574(whether types of SV or types of OP) are represented by the C<B>
85cf7f2e
MJD
575module as Perl objects of the appropriate class.
576
577The bulk of the C<B> module is the methods for accessing fields of
578these structures.
579
580Note that all access is read-only. You cannot modify the internals by
f31c3107
SM
581using this module. Also, note that the B::OP and B::SV objects created
582by this module are only valid for as long as the underlying objects
583exist; their creation doesn't increase the reference counts of the
584underlying objects. Trying to access the fields of a freed object will
585give incomprehensible results, or worse.
1a52ab62
MB
586
587=head2 SV-RELATED CLASSES
588
6822775c
NC
589B::IV, B::NV, B::RV, B::PV, B::PVIV, B::PVNV, B::PVMG, B::BM (5.9.5 and
590earlier), B::PVLV, B::AV, B::HV, B::CV, B::GV, B::FM, B::IO. These classes
591correspond in the obvious way to the underlying C structures of similar names.
4df7f6af 592The inheritance hierarchy mimics the underlying C "inheritance". For the
dda36756 5935.10.x branch, (I<ie> 5.10.0, 5.10.1 I<etc>) this is:
85cf7f2e 594
6822775c
NC
595 B::SV
596 |
597 +------------+------------+------------+
598 | | | |
599 B::PV B::IV B::NV B::RV
600 \ / /
601 \ / /
602 B::PVIV /
b591c46e
NC
603 \ /
604 \ /
605 \ /
606 B::PVNV
607 |
608 |
609 B::PVMG
610 |
6822775c
NC
611 +-----+-----+-----+-----+
612 | | | | |
613 B::AV B::GV B::HV B::CV B::IO
614 | |
615 | |
616 B::PVLV B::FM
617
6822775c
NC
618For 5.9.0 and earlier, PVLV is a direct subclass of PVMG, and BM is still
619present as a distinct type, so the base of this diagram is
620
621
622 |
623 |
624 B::PVMG
625 |
626 +------+-----+-----+-----+-----+-----+
627 | | | | | | |
628 B::PVLV B::BM B::AV B::GV B::HV B::CV B::IO
629 |
630 |
631 B::FM
f5ba1307 632
dda36756
NC
633For 5.11.0 and later, B::RV is abolished, and IVs can be used to store
634references, and a new type B::REGEXP is introduced, giving this structure:
635
636 B::SV
637 |
638 +------------+------------+
639 | | |
640 B::PV B::IV B::NV
641 \ / /
642 \ / /
643 B::PVIV /
644 \ /
645 \ /
646 \ /
647 B::PVNV
648 |
649 |
650 B::PVMG
651 |
652 +-------+-------+---+---+-------+-------+
653 | | | | | |
654 B::AV B::GV B::HV B::CV B::IO B::REGEXP
655 | |
656 | |
657 B::PVLV B::FM
658
f5ba1307 659
85cf7f2e 660Access methods correspond to the underlying C macros for field access,
1a52ab62
MB
661usually with the leading "class indication" prefix removed (Sv, Av,
662Hv, ...). The leading prefix is only left in cases where its removal
663would cause a clash in method name. For example, C<GvREFCNT> stays
664as-is since its abbreviation would clash with the "superclass" method
665C<REFCNT> (corresponding to the C function C<SvREFCNT>).
666
85cf7f2e 667=head2 B::SV Methods
1a52ab62
MB
668
669=over 4
670
671=item REFCNT
672
673=item FLAGS
674
429a5ce7
SM
675=item object_2svref
676
677Returns a reference to the regular scalar corresponding to this
678B::SV object. In other words, this method is the inverse operation
679to the svref_2object() subroutine. This scalar and other data it points
680at should be considered read-only: modifying them is neither safe nor
681guaranteed to have a sensible effect.
682
1a52ab62
MB
683=back
684
85cf7f2e 685=head2 B::IV Methods
1a52ab62
MB
686
687=over 4
688
689=item IV
690
d9963e60
RH
691Returns the value of the IV, I<interpreted as
692a signed integer>. This will be misleading
693if C<FLAGS & SVf_IVisUV>. Perhaps you want the
694C<int_value> method instead?
695
1a52ab62
MB
696=item IVX
697
d9963e60
RH
698=item UVX
699
700=item int_value
701
702This method returns the value of the IV as an integer.
703It differs from C<IV> in that it returns the correct
704value regardless of whether it's stored signed or
705unsigned.
706
1a52ab62
MB
707=item needs64bits
708
709=item packiv
710
711=back
712
85cf7f2e 713=head2 B::NV Methods
1a52ab62
MB
714
715=over 4
716
717=item NV
718
719=item NVX
720
721=back
722
85cf7f2e 723=head2 B::RV Methods
1a52ab62
MB
724
725=over 4
726
727=item RV
728
729=back
730
85cf7f2e 731=head2 B::PV Methods
1a52ab62
MB
732
733=over 4
734
735=item PV
736
76ef7183
JH
737This method is the one you usually want. It constructs a
738string using the length and offset information in the struct:
739for ordinary scalars it will return the string that you'd see
740from Perl, even if it contains null characters.
741
9d2bbe64
MB
742=item RV
743
744Same as B::RV::RV, except that it will die() if the PV isn't
745a reference.
746
0b40bd6d
RH
747=item PVX
748
76ef7183
JH
749This method is less often useful. It assumes that the string
750stored in the struct is null-terminated, and disregards the
751length information.
752
753It is the appropriate method to use if you need to get the name
754of a lexical variable from a padname array. Lexical variable names
755are always stored with a null terminator, and the length field
756(SvCUR) is overloaded for other purposes and can't be relied on here.
757
1a52ab62
MB
758=back
759
85cf7f2e 760=head2 B::PVMG Methods
1a52ab62
MB
761
762=over 4
763
764=item MAGIC
765
766=item SvSTASH
767
768=back
769
85cf7f2e 770=head2 B::MAGIC Methods
1a52ab62
MB
771
772=over 4
773
774=item MOREMAGIC
775
9d2bbe64
MB
776=item precomp
777
778Only valid on r-magic, returns the string that generated the regexp.
779
1a52ab62
MB
780=item PRIVATE
781
782=item TYPE
783
784=item FLAGS
785
786=item OBJ
787
9d2bbe64
MB
788Will die() if called on r-magic.
789
1a52ab62
MB
790=item PTR
791
9d2bbe64
MB
792=item REGEX
793
794Only valid on r-magic, returns the integer value of the REGEX stored
795in the MAGIC.
796
1a52ab62
MB
797=back
798
85cf7f2e 799=head2 B::PVLV Methods
1a52ab62
MB
800
801=over 4
802
803=item TARGOFF
804
805=item TARGLEN
806
807=item TYPE
808
809=item TARG
810
811=back
812
85cf7f2e 813=head2 B::BM Methods
1a52ab62
MB
814
815=over 4
816
817=item USEFUL
818
819=item PREVIOUS
820
821=item RARE
822
823=item TABLE
824
825=back
826
85cf7f2e 827=head2 B::GV Methods
1a52ab62
MB
828
829=over 4
830
87d7fd28
GS
831=item is_empty
832
833This method returns TRUE if the GP field of the GV is NULL.
834
1a52ab62
MB
835=item NAME
836
002b978b
RH
837=item SAFENAME
838
839This method returns the name of the glob, but if the first
840character of the name is a control character, then it converts
841it to ^X first, so that *^G would return "^G" rather than "\cG".
842
843It's useful if you want to print out the name of a variable.
844If you restrict yourself to globs which exist at compile-time
845then the result ought to be unambiguous, because code like
846C<${"^G"} = 1> is compiled as two ops - a constant string and
847a dereference (rv2gv) - so that the glob is created at runtime.
848
849If you're working with globs at runtime, and need to disambiguate
850*^G from *{"^G"}, then you should use the raw NAME method.
851
1a52ab62
MB
852=item STASH
853
854=item SV
855
856=item IO
857
858=item FORM
859
860=item AV
861
862=item HV
863
864=item EGV
865
866=item CV
867
868=item CVGEN
869
870=item LINE
871
b195d487
GS
872=item FILE
873
1a52ab62
MB
874=item FILEGV
875
876=item GvREFCNT
877
878=item FLAGS
879
880=back
881
85cf7f2e 882=head2 B::IO Methods
1a52ab62
MB
883
884=over 4
885
886=item LINES
887
888=item PAGE
889
890=item PAGE_LEN
891
892=item LINES_LEFT
893
894=item TOP_NAME
895
896=item TOP_GV
897
898=item FMT_NAME
899
900=item FMT_GV
901
902=item BOTTOM_NAME
903
904=item BOTTOM_GV
905
906=item SUBPROCESS
907
908=item IoTYPE
909
910=item IoFLAGS
911
9d2bbe64
MB
912=item IsSTD
913
914Takes one arguments ( 'stdin' | 'stdout' | 'stderr' ) and returns true
915if the IoIFP of the object is equal to the handle whose name was
916passed as argument ( i.e. $io->IsSTD('stderr') is true if
917IoIFP($io) == PerlIO_stdin() ).
918
1a52ab62
MB
919=back
920
85cf7f2e 921=head2 B::AV Methods
1a52ab62
MB
922
923=over 4
924
925=item FILL
926
927=item MAX
928
1a52ab62
MB
929=item ARRAY
930
429a5ce7
SM
931=item ARRAYelt
932
933Like C<ARRAY>, but takes an index as an argument to get only one element,
934rather than a list of all of them.
935
edcc7c74
NC
936=item OFF
937
938This method is deprecated if running under Perl 5.8, and is no longer present
939if running under Perl 5.9
940
941=item AvFLAGS
942
943This method returns the AV specific flags. In Perl 5.9 these are now stored
944in with the main SV flags, so this method is no longer present.
945
1a52ab62
MB
946=back
947
85cf7f2e 948=head2 B::CV Methods
1a52ab62
MB
949
950=over 4
951
952=item STASH
953
954=item START
955
956=item ROOT
957
958=item GV
959
57843af0
GS
960=item FILE
961
1a52ab62
MB
962=item DEPTH
963
964=item PADLIST
965
966=item OUTSIDE
967
a3985cdc
DM
968=item OUTSIDE_SEQ
969
1a52ab62
MB
970=item XSUB
971
972=item XSUBANY
973
9d2bbe64
MB
974For constant subroutines, returns the constant SV returned by the subroutine.
975
5cfd8ad4
VB
976=item CvFLAGS
977
de3f1649
JT
978=item const_sv
979
1a52ab62
MB
980=back
981
85cf7f2e 982=head2 B::HV Methods
1a52ab62
MB
983
984=over 4
985
986=item FILL
987
988=item MAX
989
990=item KEYS
991
992=item RITER
993
994=item NAME
995
1a52ab62
MB
996=item ARRAY
997
edcc7c74
NC
998=item PMROOT
999
1000This method is not present if running under Perl 5.9, as the PMROOT
1001information is no longer stored directly in the hash.
1002
1a52ab62
MB
1003=back
1004
1005=head2 OP-RELATED CLASSES
1006
85cf7f2e 1007C<B::OP>, C<B::UNOP>, C<B::BINOP>, C<B::LOGOP>, C<B::LISTOP>, C<B::PMOP>,
651aa52e 1008C<B::SVOP>, C<B::PADOP>, C<B::PVOP>, C<B::LOOP>, C<B::COP>.
85cf7f2e
MJD
1009
1010These classes correspond in the obvious way to the underlying C
1011structures of similar names. The inheritance hierarchy mimics the
1012underlying C "inheritance":
1013
1014 B::OP
1015 |
5ce57cc0
JJ
1016 +---------------+--------+--------+-------+
1017 | | | | |
1018 B::UNOP B::SVOP B::PADOP B::COP B::PVOP
85cf7f2e
MJD
1019 ,' `-.
1020 / `--.
1021 B::BINOP B::LOGOP
1022 |
1023 |
1024 B::LISTOP
1025 ,' `.
1026 / \
1027 B::LOOP B::PMOP
1028
1029Access methods correspond to the underlying C structre field names,
1030with the leading "class indication" prefix (C<"op_">) removed.
1031
1032=head2 B::OP Methods
1a52ab62 1033
a60ba18b
JC
1034These methods get the values of similarly named fields within the OP
1035data structure. See top of C<op.h> for more info.
1036
1a52ab62
MB
1037=over 4
1038
1039=item next
1040
1041=item sibling
1042
3f872cb9
GS
1043=item name
1044
1045This returns the op name as a string (e.g. "add", "rv2av").
1046
1a52ab62
MB
1047=item ppaddr
1048
dc333d64
GS
1049This returns the function name as a string (e.g. "PL_ppaddr[OP_ADD]",
1050"PL_ppaddr[OP_RV2AV]").
1a52ab62
MB
1051
1052=item desc
1053
4369b173 1054This returns the op description from the global C PL_op_desc array
1a52ab62
MB
1055(e.g. "addition" "array deref").
1056
1057=item targ
1058
1059=item type
1060
a60ba18b
JC
1061=item opt
1062
1a52ab62
MB
1063=item flags
1064
1065=item private
1066
a60ba18b
JC
1067=item spare
1068
1a52ab62
MB
1069=back
1070
1071=head2 B::UNOP METHOD
1072
1073=over 4
1074
1075=item first
1076
1077=back
1078
1079=head2 B::BINOP METHOD
1080
1081=over 4
1082
1083=item last
1084
1085=back
1086
1087=head2 B::LOGOP METHOD
1088
1089=over 4
1090
1091=item other
1092
1093=back
1094
1a52ab62
MB
1095=head2 B::LISTOP METHOD
1096
1097=over 4
1098
1099=item children
1100
1101=back
1102
85cf7f2e 1103=head2 B::PMOP Methods
1a52ab62
MB
1104
1105=over 4
1106
1107=item pmreplroot
1108
1109=item pmreplstart
1110
1111=item pmnext
1112
196d796c
RU
1113Only up to Perl 5.9.4
1114
1a52ab62
MB
1115=item pmflags
1116
c737faaf 1117=item extflags
1a52ab62 1118
196d796c
RU
1119Since Perl 5.9.5
1120
1a52ab62
MB
1121=item precomp
1122
651aa52e 1123=item pmoffset
9d2bbe64
MB
1124
1125Only when perl was compiled with ithreads.
1126
1a52ab62
MB
1127=back
1128
1129=head2 B::SVOP METHOD
1130
1131=over 4
1132
1133=item sv
1134
065a1863
GS
1135=item gv
1136
1a52ab62
MB
1137=back
1138
7934575e 1139=head2 B::PADOP METHOD
1a52ab62
MB
1140
1141=over 4
1142
7934575e 1143=item padix
1a52ab62
MB
1144
1145=back
1146
1147=head2 B::PVOP METHOD
1148
1149=over 4
1150
1151=item pv
1152
1153=back
1154
85cf7f2e 1155=head2 B::LOOP Methods
1a52ab62
MB
1156
1157=over 4
1158
1159=item redoop
1160
1161=item nextop
1162
1163=item lastop
1164
1165=back
1166
85cf7f2e 1167=head2 B::COP Methods
1a52ab62
MB
1168
1169=over 4
1170
1171=item label
1172
1173=item stash
1174
6e6a1aef
RGS
1175=item stashpv
1176
57843af0 1177=item file
1a52ab62
MB
1178
1179=item cop_seq
1180
1181=item arybase
1182
1183=item line
1184
6e6a1aef
RGS
1185=item warnings
1186
1187=item io
1188
d5ec2987
NC
1189=item hints
1190
b47e7f93
RGS
1191=item hints_hash
1192
1a52ab62
MB
1193=back
1194
7f20e9dd
GS
1195
1196=head1 AUTHOR
1197
1198Malcolm Beattie, C<mbeattie@sable.ox.ac.uk>
1199
1200=cut