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