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