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