ext/B/B.pm

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