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