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