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