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