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