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