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