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