This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
CvGV is no longer a simple struct member access
[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.45';
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 PADLIST object (i.e. in class B::PADLIST) of the global
432 comppadlist.  In Perl 5.16 and earlier it returns an AV object (class
433 B::AV).
434
435 =item regex_padav
436
437 Only when perl was compiled with ithreads.
438
439 =item main_cv
440
441 Return the (faked) CV corresponding to the main part of the Perl
442 program.
443
444 =back
445
446 =head2 Functions for Examining the Symbol Table
447
448 =over 4
449
450 =item walksymtable(SYMREF, METHOD, RECURSE, PREFIX)
451
452 Walk the symbol table starting at SYMREF and call METHOD on each
453 symbol (a B::GV object) visited.  When the walk reaches package
454 symbols (such as "Foo::") it invokes RECURSE, passing in the symbol
455 name, and only recurses into the package if that sub returns true.
456
457 PREFIX is the name of the SYMREF you're walking.
458
459 For example:
460
461   # Walk CGI's symbol table calling print_subs on each symbol.
462   # Recurse only into CGI::Util::
463   walksymtable(\%CGI::, 'print_subs',
464                sub { $_[0] eq 'CGI::Util::' }, 'CGI::');
465
466 print_subs() is a B::GV method you have declared.  Also see L<"B::GV
467 Methods">, below.
468
469 =back
470
471 =head2 Functions Returning C<B::OP> objects or for walking op trees
472
473 For descriptions of the class hierarchy of these objects and the
474 methods that can be called on them, see below, L<"OVERVIEW OF
475 CLASSES"> and L<"OP-RELATED CLASSES">.
476
477 =over 4
478
479 =item main_root
480
481 Returns the root op (i.e. an object in the appropriate B::OP-derived
482 class) of the main part of the Perl program.
483
484 =item main_start
485
486 Returns the starting op of the main part of the Perl program.
487
488 =item walkoptree(OP, METHOD)
489
490 Does a tree-walk of the syntax tree based at OP and calls METHOD on
491 each op it visits.  Each node is visited before its children.  If
492 C<walkoptree_debug> (see below) has been called to turn debugging on then
493 the method C<walkoptree_debug> is called on each op before METHOD is
494 called.
495
496 =item walkoptree_debug(DEBUG)
497
498 Returns the current debugging flag for C<walkoptree>.  If the optional
499 DEBUG argument is non-zero, it sets the debugging flag to that.  See
500 the description of C<walkoptree> above for what the debugging flag
501 does.
502
503 =back
504
505 =head2 Miscellaneous Utility Functions
506
507 =over 4
508
509 =item ppname(OPNUM)
510
511 Return the PP function name (e.g. "pp_add") of op number OPNUM.
512
513 =item hash(STR)
514
515 Returns a string in the form "0x..." representing the value of the
516 internal hash function used by perl on string STR.
517
518 =item cast_I32(I)
519
520 Casts I to the internal I32 type used by that perl.
521
522 =item minus_c
523
524 Does the equivalent of the C<-c> command-line option.  Obviously, this
525 is only useful in a BEGIN block or else the flag is set too late.
526
527 =item cstring(STR)
528
529 Returns a double-quote-surrounded escaped version of STR which can
530 be used as a string in C source code.
531
532 =item perlstring(STR)
533
534 Returns a double-quote-surrounded escaped version of STR which can
535 be used as a string in Perl source code.
536
537 =item class(OBJ)
538
539 Returns the class of an object without the part of the classname
540 preceding the first C<"::">.  This is used to turn C<"B::UNOP"> into
541 C<"UNOP"> for example.
542
543 =item threadsv_names
544
545 In a perl compiled for threads, this returns a list of the special
546 per-thread threadsv variables.
547
548 =back
549
550 =head2 Exported utility variables
551
552 =over 4
553
554 =item @optype
555
556   my $op_type = $optype[$op_type_num];
557
558 A simple mapping of the op type number to its type (like 'COP' or 'BINOP').
559
560 =item @specialsv_name
561
562   my $sv_name = $specialsv_name[$sv_index];
563
564 Certain SV types are considered 'special'.  They're represented by
565 B::SPECIAL and are referred to by a number from the specialsv_list.
566 This array maps that number back to the name of the SV (like 'Nullsv'
567 or '&PL_sv_undef').
568
569 =back
570
571
572 =head1 OVERVIEW OF CLASSES
573
574 The C structures used by Perl's internals to hold SV and OP
575 information (PVIV, AV, HV, ..., OP, SVOP, UNOP, ...) are modelled on a
576 class hierarchy and the C<B> module gives access to them via a true
577 object hierarchy.  Structure fields which point to other objects
578 (whether types of SV or types of OP) are represented by the C<B>
579 module as Perl objects of the appropriate class.
580
581 The bulk of the C<B> module is the methods for accessing fields of
582 these structures.
583
584 Note that all access is read-only.  You cannot modify the internals by
585 using this module.  Also, note that the B::OP and B::SV objects created
586 by this module are only valid for as long as the underlying objects
587 exist; their creation doesn't increase the reference counts of the
588 underlying objects.  Trying to access the fields of a freed object will
589 give incomprehensible results, or worse.
590
591 =head2 SV-RELATED CLASSES
592
593 B::IV, B::NV, B::RV, B::PV, B::PVIV, B::PVNV, B::PVMG, B::BM (5.9.5 and
594 earlier), B::PVLV, B::AV, B::HV, B::CV, B::GV, B::FM, B::IO.  These classes
595 correspond in the obvious way to the underlying C structures of similar names.
596 The inheritance hierarchy mimics the underlying C "inheritance".  For the
597 5.10.x branch, (I<ie> 5.10.0, 5.10.1 I<etc>) this is:
598
599                            B::SV
600                              |
601                 +------------+------------+------------+
602                 |            |            |            |
603               B::PV        B::IV        B::NV        B::RV
604                   \         /           /
605                    \       /           /
606                     B::PVIV           /
607                          \           /
608                           \         /
609                            \       /
610                             B::PVNV
611                                |
612                                |
613                             B::PVMG
614                                |
615                    +-----+-----+-----+-----+
616                    |     |     |     |     |
617                  B::AV B::GV B::HV B::CV B::IO
618                          |           |
619                          |           |
620                       B::PVLV      B::FM
621
622 For 5.9.0 and earlier, PVLV is a direct subclass of PVMG, and BM is still
623 present as a distinct type, so the base of this diagram is
624
625
626                                |
627                                |
628                             B::PVMG
629                                |
630             +------+-----+-----+-----+-----+-----+
631             |      |     |     |     |     |     |
632          B::PVLV B::BM B::AV B::GV B::HV B::CV B::IO
633                                            |
634                                            |
635                                          B::FM
636
637 For 5.11.0 and later, B::RV is abolished, and IVs can be used to store
638 references, and a new type B::REGEXP is introduced, giving this structure:
639
640                            B::SV
641                              |
642                 +------------+------------+
643                 |            |            |
644               B::PV        B::IV        B::NV
645                   \         /           /
646                    \       /           /
647                     B::PVIV           /
648                          \           /
649                           \         /
650                            \       /
651                             B::PVNV
652                                |
653                                |
654                             B::PVMG
655                                |
656            +-------+-------+---+---+-------+-------+
657            |       |       |       |       |       |
658          B::AV   B::GV   B::HV   B::CV   B::IO B::REGEXP
659                    |               |
660                    |               |
661                 B::PVLV          B::FM
662
663
664 Access methods correspond to the underlying C macros for field access,
665 usually with the leading "class indication" prefix removed (Sv, Av,
666 Hv, ...).  The leading prefix is only left in cases where its removal
667 would cause a clash in method name.  For example, C<GvREFCNT> stays
668 as-is since its abbreviation would clash with the "superclass" method
669 C<REFCNT> (corresponding to the C function C<SvREFCNT>).
670
671 =head2 B::SV Methods
672
673 =over 4
674
675 =item REFCNT
676
677 =item FLAGS
678
679 =item object_2svref
680
681 Returns a reference to the regular scalar corresponding to this
682 B::SV object.  In other words, this method is the inverse operation
683 to the svref_2object() subroutine.  This scalar and other data it points
684 at should be considered read-only: modifying them is neither safe nor
685 guaranteed to have a sensible effect.
686
687 =back
688
689 =head2 B::IV Methods
690
691 =over 4
692
693 =item IV
694
695 Returns the value of the IV, I<interpreted as
696 a signed integer>.  This will be misleading
697 if C<FLAGS & SVf_IVisUV>.  Perhaps you want the
698 C<int_value> method instead?
699
700 =item IVX
701
702 =item UVX
703
704 =item int_value
705
706 This method returns the value of the IV as an integer.
707 It differs from C<IV> in that it returns the correct
708 value regardless of whether it's stored signed or
709 unsigned.
710
711 =item needs64bits
712
713 =item packiv
714
715 =back
716
717 =head2 B::NV Methods
718
719 =over 4
720
721 =item NV
722
723 =item NVX
724
725 =back
726
727 =head2 B::RV Methods
728
729 =over 4
730
731 =item RV
732
733 =back
734
735 =head2 B::PV Methods
736
737 =over 4
738
739 =item PV
740
741 This method is the one you usually want.  It constructs a
742 string using the length and offset information in the struct:
743 for ordinary scalars it will return the string that you'd see
744 from Perl, even if it contains null characters.
745
746 =item RV
747
748 Same as B::RV::RV, except that it will die() if the PV isn't
749 a reference.
750
751 =item PVX
752
753 This method is less often useful.  It assumes that the string
754 stored in the struct is null-terminated, and disregards the
755 length information.
756
757 It is the appropriate method to use if you need to get the name
758 of a lexical variable from a padname array.  Lexical variable names
759 are always stored with a null terminator, and the length field
760 (CUR) is overloaded for other purposes and can't be relied on here.
761
762 =item CUR
763
764 This method returns the internal length field, which consists of the number
765 of internal bytes, not necessarily the number of logical characters.
766
767 =item LEN
768
769 This method returns the number of bytes allocated (via malloc) for storing
770 the string.  This is 0 if the scalar does not "own" the string.
771
772 =back
773
774 =head2 B::PVMG Methods
775
776 =over 4
777
778 =item MAGIC
779
780 =item SvSTASH
781
782 =back
783
784 =head2 B::MAGIC Methods
785
786 =over 4
787
788 =item MOREMAGIC
789
790 =item precomp
791
792 Only valid on r-magic, returns the string that generated the regexp.
793
794 =item PRIVATE
795
796 =item TYPE
797
798 =item FLAGS
799
800 =item OBJ
801
802 Will die() if called on r-magic.
803
804 =item PTR
805
806 =item REGEX
807
808 Only valid on r-magic, returns the integer value of the REGEX stored
809 in the MAGIC.
810
811 =back
812
813 =head2 B::PVLV Methods
814
815 =over 4
816
817 =item TARGOFF
818
819 =item TARGLEN
820
821 =item TYPE
822
823 =item TARG
824
825 =back
826
827 =head2 B::BM Methods
828
829 =over 4
830
831 =item USEFUL
832
833 =item PREVIOUS
834
835 =item RARE
836
837 =item TABLE
838
839 =back
840
841 =head2 B::GV Methods
842
843 =over 4
844
845 =item is_empty
846
847 This method returns TRUE if the GP field of the GV is NULL.
848
849 =item NAME
850
851 =item SAFENAME
852
853 This method returns the name of the glob, but if the first
854 character of the name is a control character, then it converts
855 it to ^X first, so that *^G would return "^G" rather than "\cG".
856
857 It's useful if you want to print out the name of a variable.
858 If you restrict yourself to globs which exist at compile-time
859 then the result ought to be unambiguous, because code like
860 C<${"^G"} = 1> is compiled as two ops - a constant string and
861 a dereference (rv2gv) - so that the glob is created at runtime.
862
863 If you're working with globs at runtime, and need to disambiguate
864 *^G from *{"^G"}, then you should use the raw NAME method.
865
866 =item STASH
867
868 =item SV
869
870 =item IO
871
872 =item FORM
873
874 =item AV
875
876 =item HV
877
878 =item EGV
879
880 =item CV
881
882 =item CVGEN
883
884 =item LINE
885
886 =item FILE
887
888 =item FILEGV
889
890 =item GvREFCNT
891
892 =item FLAGS
893
894 =back
895
896 =head2 B::IO Methods
897
898 B::IO objects derive from IO objects and you will get more information from
899 the IO object itself.
900
901 For example:
902
903   $gvio = B::svref_2object(\*main::stdin)->IO;
904   $IO = $gvio->object_2svref();
905   $fd = $IO->fileno();
906
907 =over 4
908
909 =item LINES
910
911 =item PAGE
912
913 =item PAGE_LEN
914
915 =item LINES_LEFT
916
917 =item TOP_NAME
918
919 =item TOP_GV
920
921 =item FMT_NAME
922
923 =item FMT_GV
924
925 =item BOTTOM_NAME
926
927 =item BOTTOM_GV
928
929 =item SUBPROCESS
930
931 =item IoTYPE
932
933 A character symbolizing the type of IO Handle.
934
935   -     STDIN/OUT
936   I     STDIN/OUT/ERR
937   <     read-only
938   >     write-only
939   a     append
940   +     read and write
941   s     socket
942   |     pipe
943   I     IMPLICIT
944   #     NUMERIC
945   space closed handle
946   \0    closed internal handle
947
948 =item IoFLAGS
949
950 =item IsSTD
951
952 Takes one argument ( 'stdin' | 'stdout' | 'stderr' ) and returns true
953 if the IoIFP of the object is equal to the handle whose name was
954 passed as argument; i.e., $io->IsSTD('stderr') is true if
955 IoIFP($io) == PerlIO_stderr().
956
957 =back
958
959 =head2 B::AV Methods
960
961 =over 4
962
963 =item FILL
964
965 =item MAX
966
967 =item ARRAY
968
969 =item ARRAYelt
970
971 Like C<ARRAY>, but takes an index as an argument to get only one element,
972 rather than a list of all of them.
973
974 =item OFF
975
976 This method is deprecated if running under Perl 5.8, and is no longer present
977 if running under Perl 5.9
978
979 =item AvFLAGS
980
981 This method returns the AV specific
982 flags.  In Perl 5.9 these are now stored
983 in with the main SV flags, so this method is no longer present.
984
985 =back
986
987 =head2 B::CV Methods
988
989 =over 4
990
991 =item STASH
992
993 =item START
994
995 =item ROOT
996
997 =item GV
998
999 =item FILE
1000
1001 =item DEPTH
1002
1003 =item PADLIST
1004
1005 Returns a B::PADLIST object under Perl 5.18 or higher, or a B::AV in
1006 earlier versions.
1007
1008 =item OUTSIDE
1009
1010 =item OUTSIDE_SEQ
1011
1012 =item XSUB
1013
1014 =item XSUBANY
1015
1016 For constant subroutines, returns the constant SV returned by the subroutine.
1017
1018 =item CvFLAGS
1019
1020 =item const_sv
1021
1022 =item NAME_HEK
1023
1024 Returns the name of a lexical sub, otherwise C<undef>.
1025
1026 =back
1027
1028 =head2 B::HV Methods
1029
1030 =over 4
1031
1032 =item FILL
1033
1034 =item MAX
1035
1036 =item KEYS
1037
1038 =item RITER
1039
1040 =item NAME
1041
1042 =item ARRAY
1043
1044 =item PMROOT
1045
1046 This method is not present if running under Perl 5.9, as the PMROOT
1047 information is no longer stored directly in the hash.
1048
1049 =back
1050
1051 =head2 OP-RELATED CLASSES
1052
1053 C<B::OP>, C<B::UNOP>, C<B::BINOP>, C<B::LOGOP>, C<B::LISTOP>, C<B::PMOP>,
1054 C<B::SVOP>, C<B::PADOP>, C<B::PVOP>, C<B::LOOP>, C<B::COP>.
1055
1056 These classes correspond in the obvious way to the underlying C
1057 structures of similar names.  The inheritance hierarchy mimics the
1058 underlying C "inheritance":
1059
1060                                  B::OP
1061                                    |
1062                    +---------------+--------+--------+-------+
1063                    |               |        |        |       |
1064                 B::UNOP          B::SVOP B::PADOP  B::COP  B::PVOP
1065                  ,'  `-.
1066                 /       `--.
1067            B::BINOP     B::LOGOP
1068                |
1069                |
1070            B::LISTOP
1071              ,' `.
1072             /     \
1073         B::LOOP B::PMOP
1074
1075 Access methods correspond to the underlying C structure field names,
1076 with the leading "class indication" prefix (C<"op_">) removed.
1077
1078 =head2 B::OP Methods
1079
1080 These methods get the values of similarly named fields within the OP
1081 data structure.  See top of C<op.h> for more info.
1082
1083 =over 4
1084
1085 =item next
1086
1087 =item sibling
1088
1089 =item name
1090
1091 This returns the op name as a string (e.g. "add", "rv2av").
1092
1093 =item ppaddr
1094
1095 This returns the function name as a string (e.g. "PL_ppaddr[OP_ADD]",
1096 "PL_ppaddr[OP_RV2AV]").
1097
1098 =item desc
1099
1100 This returns the op description from the global C PL_op_desc array
1101 (e.g. "addition" "array deref").
1102
1103 =item targ
1104
1105 =item type
1106
1107 =item opt
1108
1109 =item flags
1110
1111 =item private
1112
1113 =item spare
1114
1115 =back
1116
1117 =head2 B::UNOP METHOD
1118
1119 =over 4
1120
1121 =item first
1122
1123 =back
1124
1125 =head2 B::BINOP METHOD
1126
1127 =over 4
1128
1129 =item last
1130
1131 =back
1132
1133 =head2 B::LOGOP METHOD
1134
1135 =over 4
1136
1137 =item other
1138
1139 =back
1140
1141 =head2 B::LISTOP METHOD
1142
1143 =over 4
1144
1145 =item children
1146
1147 =back
1148
1149 =head2 B::PMOP Methods
1150
1151 =over 4
1152
1153 =item pmreplroot
1154
1155 =item pmreplstart
1156
1157 =item pmnext
1158
1159 Only up to Perl 5.9.4
1160
1161 =item pmflags
1162
1163 =item extflags
1164
1165 Since Perl 5.9.5
1166
1167 =item precomp
1168
1169 =item pmoffset
1170
1171 Only when perl was compiled with ithreads.
1172
1173 =item code_list
1174
1175 Since perl 5.17.1
1176
1177 =back
1178
1179 =head2 B::SVOP METHOD
1180
1181 =over 4
1182
1183 =item sv
1184
1185 =item gv
1186
1187 =back
1188
1189 =head2 B::PADOP METHOD
1190
1191 =over 4
1192
1193 =item padix
1194
1195 =back
1196
1197 =head2 B::PVOP METHOD
1198
1199 =over 4
1200
1201 =item pv
1202
1203 =back
1204
1205 =head2 B::LOOP Methods
1206
1207 =over 4
1208
1209 =item redoop
1210
1211 =item nextop
1212
1213 =item lastop
1214
1215 =back
1216
1217 =head2 B::COP Methods
1218
1219 =over 4
1220
1221 =item label
1222
1223 =item stash
1224
1225 =item stashpv
1226
1227 =item stashoff (threaded only)
1228
1229 =item file
1230
1231 =item cop_seq
1232
1233 =item arybase
1234
1235 =item line
1236
1237 =item warnings
1238
1239 =item io
1240
1241 =item hints
1242
1243 =item hints_hash
1244
1245 =back
1246
1247 =head2 OTHER CLASSES
1248
1249 Perl 5.18 introduces a new class, B::PADLIST, returned by B::CV's
1250 C<PADLIST> method.
1251
1252 =head2 B::PADLIST Methods
1253
1254 =over 4
1255
1256 =item MAX
1257
1258 =item ARRAY
1259
1260 A list of pads.  The first one contains the names.  These are currently
1261 B::AV objects, but that is likely to change in future versions.
1262
1263 =item ARRAYelt
1264
1265 Like C<ARRAY>, but takes an index as an argument to get only one element,
1266 rather than a list of all of them.
1267
1268 =item REFCNT
1269
1270 =back
1271
1272 =head2 $B::overlay
1273
1274 Although the optree is read-only, there is an overlay facility that allows
1275 you to override what values the various B::*OP methods return for a
1276 particular op. C<$B::overlay> should be set to reference a two-deep hash:
1277 indexed by OP address, then method name. Whenever a an op method is
1278 called, the value in the hash is returned if it exists. This facility is
1279 used by B::Deparse to "undo" some optimisations. For example:
1280
1281
1282     local $B::overlay = {};
1283     ...
1284     if ($op->name eq "foo") {
1285         $B::overlay->{$$op} = {
1286                 name => 'bar',
1287                 next => $op->next->next,
1288         };
1289     }
1290     ...
1291     $op->name # returns "bar"
1292     $op->next # returns the next op but one
1293
1294
1295 =head1 AUTHOR
1296
1297 Malcolm Beattie, C<mbeattie@sable.ox.ac.uk>
1298
1299 =cut