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