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