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