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