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