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