This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Clarify the definition of the 'w' pack format, as suggested by
[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
4edc9001 10our $VERSION = '1.08';
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
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
851=item OFF
852
853=item ARRAY
854
429a5ce7
SM
855=item ARRAYelt
856
857Like C<ARRAY>, but takes an index as an argument to get only one element,
858rather than a list of all of them.
859
1a52ab62
MB
860=item AvFLAGS
861
862=back
863
85cf7f2e 864=head2 B::CV Methods
1a52ab62
MB
865
866=over 4
867
868=item STASH
869
870=item START
871
872=item ROOT
873
874=item GV
875
57843af0
GS
876=item FILE
877
1a52ab62
MB
878=item DEPTH
879
880=item PADLIST
881
882=item OUTSIDE
883
a3985cdc
DM
884=item OUTSIDE_SEQ
885
1a52ab62
MB
886=item XSUB
887
888=item XSUBANY
889
9d2bbe64
MB
890For constant subroutines, returns the constant SV returned by the subroutine.
891
5cfd8ad4
VB
892=item CvFLAGS
893
de3f1649
JT
894=item const_sv
895
1a52ab62
MB
896=back
897
85cf7f2e 898=head2 B::HV Methods
1a52ab62
MB
899
900=over 4
901
902=item FILL
903
904=item MAX
905
906=item KEYS
907
908=item RITER
909
910=item NAME
911
912=item PMROOT
913
914=item ARRAY
915
916=back
917
918=head2 OP-RELATED CLASSES
919
85cf7f2e 920C<B::OP>, C<B::UNOP>, C<B::BINOP>, C<B::LOGOP>, C<B::LISTOP>, C<B::PMOP>,
651aa52e 921C<B::SVOP>, C<B::PADOP>, C<B::PVOP>, C<B::LOOP>, C<B::COP>.
85cf7f2e
MJD
922
923These classes correspond in the obvious way to the underlying C
924structures of similar names. The inheritance hierarchy mimics the
925underlying C "inheritance":
926
927 B::OP
928 |
651aa52e
AE
929 +---------------+--------+--------+
930 | | | |
931 B::UNOP B::SVOP B::PADOP B::COP
85cf7f2e
MJD
932 ,' `-.
933 / `--.
934 B::BINOP B::LOGOP
935 |
936 |
937 B::LISTOP
938 ,' `.
939 / \
940 B::LOOP B::PMOP
941
942Access methods correspond to the underlying C structre field names,
943with the leading "class indication" prefix (C<"op_">) removed.
944
945=head2 B::OP Methods
1a52ab62 946
a60ba18b
JC
947These methods get the values of similarly named fields within the OP
948data structure. See top of C<op.h> for more info.
949
1a52ab62
MB
950=over 4
951
952=item next
953
954=item sibling
955
3f872cb9
GS
956=item name
957
958This returns the op name as a string (e.g. "add", "rv2av").
959
1a52ab62
MB
960=item ppaddr
961
dc333d64
GS
962This returns the function name as a string (e.g. "PL_ppaddr[OP_ADD]",
963"PL_ppaddr[OP_RV2AV]").
1a52ab62
MB
964
965=item desc
966
4369b173 967This returns the op description from the global C PL_op_desc array
1a52ab62
MB
968(e.g. "addition" "array deref").
969
970=item targ
971
972=item type
973
a60ba18b
JC
974=item opt
975
976=item static
1a52ab62
MB
977
978=item flags
979
980=item private
981
a60ba18b
JC
982=item spare
983
1a52ab62
MB
984=back
985
986=head2 B::UNOP METHOD
987
988=over 4
989
990=item first
991
992=back
993
994=head2 B::BINOP METHOD
995
996=over 4
997
998=item last
999
1000=back
1001
1002=head2 B::LOGOP METHOD
1003
1004=over 4
1005
1006=item other
1007
1008=back
1009
1a52ab62
MB
1010=head2 B::LISTOP METHOD
1011
1012=over 4
1013
1014=item children
1015
1016=back
1017
85cf7f2e 1018=head2 B::PMOP Methods
1a52ab62
MB
1019
1020=over 4
1021
1022=item pmreplroot
1023
1024=item pmreplstart
1025
1026=item pmnext
1027
1028=item pmregexp
1029
1030=item pmflags
1031
9d2bbe64
MB
1032=item pmdynflags
1033
1a52ab62
MB
1034=item pmpermflags
1035
1036=item precomp
1037
651aa52e 1038=item pmoffset
9d2bbe64
MB
1039
1040Only when perl was compiled with ithreads.
1041
1a52ab62
MB
1042=back
1043
1044=head2 B::SVOP METHOD
1045
1046=over 4
1047
1048=item sv
1049
065a1863
GS
1050=item gv
1051
1a52ab62
MB
1052=back
1053
7934575e 1054=head2 B::PADOP METHOD
1a52ab62
MB
1055
1056=over 4
1057
7934575e 1058=item padix
1a52ab62
MB
1059
1060=back
1061
1062=head2 B::PVOP METHOD
1063
1064=over 4
1065
1066=item pv
1067
1068=back
1069
85cf7f2e 1070=head2 B::LOOP Methods
1a52ab62
MB
1071
1072=over 4
1073
1074=item redoop
1075
1076=item nextop
1077
1078=item lastop
1079
1080=back
1081
85cf7f2e 1082=head2 B::COP Methods
1a52ab62
MB
1083
1084=over 4
1085
1086=item label
1087
1088=item stash
1089
6e6a1aef
RGS
1090=item stashpv
1091
57843af0 1092=item file
1a52ab62
MB
1093
1094=item cop_seq
1095
1096=item arybase
1097
1098=item line
1099
6e6a1aef
RGS
1100=item warnings
1101
1102=item io
1103
1a52ab62
MB
1104=back
1105
7f20e9dd
GS
1106
1107=head1 AUTHOR
1108
1109Malcolm Beattie, C<mbeattie@sable.ox.ac.uk>
1110
1111=cut