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