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