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