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