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