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