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