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::ORANGE::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