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