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