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