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