This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
3b5933c7d122258b779697c9565ab81f1adcc6c8
[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.36';
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 As of Perl 5.18, this is just an alias to C<PL_na>, so its value is
409 meaningless.
410
411 =item init_av
412
413 Returns the AV object (i.e. in class B::AV) representing INIT blocks.
414
415 =item check_av
416
417 Returns the AV object (i.e. in class B::AV) representing CHECK blocks.
418
419 =item unitcheck_av
420
421 Returns the AV object (i.e. in class B::AV) representing UNITCHECK blocks.
422
423 =item begin_av
424
425 Returns the AV object (i.e. in class B::AV) representing BEGIN blocks.
426
427 =item end_av
428
429 Returns the AV object (i.e. in class B::AV) representing END blocks.
430
431 =item comppadlist
432
433 Returns the AV object (i.e. in class B::AV) of the global comppadlist.
434
435 =item regex_padav
436
437 Only when perl was compiled with ithreads.
438
439 =item main_cv
440
441 Return the (faked) CV corresponding to the main part of the Perl
442 program.
443
444 =back
445
446 =head2 Functions for Examining the Symbol Table
447
448 =over 4
449
450 =item walksymtable(SYMREF, METHOD, RECURSE, PREFIX)
451
452 Walk the symbol table starting at SYMREF and call METHOD on each
453 symbol (a B::GV object) visited.  When the walk reaches package
454 symbols (such as "Foo::") it invokes RECURSE, passing in the symbol
455 name, and only recurses into the package if that sub returns true.
456
457 PREFIX is the name of the SYMREF you're walking.
458
459 For example:
460
461   # Walk CGI's symbol table calling print_subs on each symbol.
462   # Recurse only into CGI::Util::
463   walksymtable(\%CGI::, 'print_subs',
464                sub { $_[0] eq 'CGI::Util::' }, 'CGI::');
465
466 print_subs() is a B::GV method you have declared.  Also see L<"B::GV
467 Methods">, below.
468
469 =back
470
471 =head2 Functions Returning C<B::OP> objects or for walking op trees
472
473 For descriptions of the class hierarchy of these objects and the
474 methods that can be called on them, see below, L<"OVERVIEW OF
475 CLASSES"> and L<"OP-RELATED CLASSES">.
476
477 =over 4
478
479 =item main_root
480
481 Returns the root op (i.e. an object in the appropriate B::OP-derived
482 class) of the main part of the Perl program.
483
484 =item main_start
485
486 Returns the starting op of the main part of the Perl program.
487
488 =item walkoptree(OP, METHOD)
489
490 Does a tree-walk of the syntax tree based at OP and calls METHOD on
491 each op it visits.  Each node is visited before its children.  If
492 C<walkoptree_debug> (see below) has been called to turn debugging on then
493 the method C<walkoptree_debug> is called on each op before METHOD is
494 called.
495
496 =item walkoptree_debug(DEBUG)
497
498 Returns the current debugging flag for C<walkoptree>.  If the optional
499 DEBUG argument is non-zero, it sets the debugging flag to that.  See
500 the description of C<walkoptree> above for what the debugging flag
501 does.
502
503 =back
504
505 =head2 Miscellaneous Utility Functions
506
507 =over 4
508
509 =item ppname(OPNUM)
510
511 Return the PP function name (e.g. "pp_add") of op number OPNUM.
512
513 =item hash(STR)
514
515 Returns a string in the form "0x..." representing the value of the
516 internal hash function used by perl on string STR.
517
518 =item cast_I32(I)
519
520 Casts I to the internal I32 type used by that perl.
521
522 =item minus_c
523
524 Does the equivalent of the C<-c> command-line option.  Obviously, this
525 is only useful in a BEGIN block or else the flag is set too late.
526
527 =item cstring(STR)
528
529 Returns a double-quote-surrounded escaped version of STR which can
530 be used as a string in C source code.
531
532 =item perlstring(STR)
533
534 Returns a double-quote-surrounded escaped version of STR which can
535 be used as a string in Perl source code.
536
537 =item class(OBJ)
538
539 Returns the class of an object without the part of the classname
540 preceding the first C<"::">.  This is used to turn C<"B::UNOP"> into
541 C<"UNOP"> for example.
542
543 =item threadsv_names
544
545 In a perl compiled for threads, this returns a list of the special
546 per-thread threadsv variables.
547
548 =back
549
550 =head2 Exported utility variables
551
552 =over 4
553
554 =item @optype
555
556   my $op_type = $optype[$op_type_num];
557
558 A simple mapping of the op type number to its type (like 'COP' or 'BINOP').
559
560 =item @specialsv_name
561
562   my $sv_name = $specialsv_name[$sv_index];
563
564 Certain SV types are considered 'special'.  They're represented by
565 B::SPECIAL and are referred to by a number from the specialsv_list.
566 This array maps that number back to the name of the SV (like 'Nullsv'
567 or '&PL_sv_undef').
568
569 =back
570
571
572 =head1 OVERVIEW OF CLASSES
573
574 The C structures used by Perl's internals to hold SV and OP
575 information (PVIV, AV, HV, ..., OP, SVOP, UNOP, ...) are modelled on a
576 class hierarchy and the C<B> module gives access to them via a true
577 object hierarchy.  Structure fields which point to other objects
578 (whether types of SV or types of OP) are represented by the C<B>
579 module as Perl objects of the appropriate class.
580
581 The bulk of the C<B> module is the methods for accessing fields of
582 these structures.
583
584 Note that all access is read-only.  You cannot modify the internals by
585 using this module.  Also, note that the B::OP and B::SV objects created
586 by this module are only valid for as long as the underlying objects
587 exist; their creation doesn't increase the reference counts of the
588 underlying objects.  Trying to access the fields of a freed object will
589 give incomprehensible results, or worse.
590
591 =head2 SV-RELATED CLASSES
592
593 B::IV, B::NV, B::RV, B::PV, B::PVIV, B::PVNV, B::PVMG, B::BM (5.9.5 and
594 earlier), B::PVLV, B::AV, B::HV, B::CV, B::GV, B::FM, B::IO.  These classes
595 correspond in the obvious way to the underlying C structures of similar names.
596 The inheritance hierarchy mimics the underlying C "inheritance".  For the
597 5.10.x branch, (I<ie> 5.10.0, 5.10.1 I<etc>) this is:
598
599                            B::SV
600                              |
601                 +------------+------------+------------+
602                 |            |            |            |
603               B::PV        B::IV        B::NV        B::RV
604                   \         /           /
605                    \       /           /
606                     B::PVIV           /
607                          \           /
608                           \         /
609                            \       /
610                             B::PVNV
611                                |
612                                |
613                             B::PVMG
614                                |
615                    +-----+-----+-----+-----+
616                    |     |     |     |     |
617                  B::AV B::GV B::HV B::CV B::IO
618                          |           |
619                          |           |
620                       B::PVLV      B::FM
621
622 For 5.9.0 and earlier, PVLV is a direct subclass of PVMG, and BM is still
623 present as a distinct type, so the base of this diagram is
624
625
626                                |
627                                |
628                             B::PVMG
629                                |
630             +------+-----+-----+-----+-----+-----+
631             |      |     |     |     |     |     |
632          B::PVLV B::BM B::AV B::GV B::HV B::CV B::IO
633                                            |
634                                            |
635                                          B::FM
636
637 For 5.11.0 and later, B::RV is abolished, and IVs can be used to store
638 references, and a new type B::REGEXP is introduced, giving this structure:
639
640                            B::SV
641                              |
642                 +------------+------------+
643                 |            |            |
644               B::PV        B::IV        B::NV
645                   \         /           /
646                    \       /           /
647                     B::PVIV           /
648                          \           /
649                           \         /
650                            \       /
651                             B::PVNV
652                                |
653                                |
654                             B::PVMG
655                                |
656            +-------+-------+---+---+-------+-------+
657            |       |       |       |       |       |
658          B::AV   B::GV   B::HV   B::CV   B::IO B::REGEXP
659                    |               |
660                    |               |
661                 B::PVLV          B::FM
662
663
664 Access methods correspond to the underlying C macros for field access,
665 usually with the leading "class indication" prefix removed (Sv, Av,
666 Hv, ...).  The leading prefix is only left in cases where its removal
667 would cause a clash in method name.  For example, C<GvREFCNT> stays
668 as-is since its abbreviation would clash with the "superclass" method
669 C<REFCNT> (corresponding to the C function C<SvREFCNT>).
670
671 =head2 B::SV Methods
672
673 =over 4
674
675 =item REFCNT
676
677 =item FLAGS
678
679 =item object_2svref
680
681 Returns a reference to the regular scalar corresponding to this
682 B::SV object.  In other words, this method is the inverse operation
683 to the svref_2object() subroutine.  This scalar and other data it points
684 at should be considered read-only: modifying them is neither safe nor
685 guaranteed to have a sensible effect.
686
687 =back
688
689 =head2 B::IV Methods
690
691 =over 4
692
693 =item IV
694
695 Returns the value of the IV, I<interpreted as
696 a signed integer>.  This will be misleading
697 if C<FLAGS & SVf_IVisUV>.  Perhaps you want the
698 C<int_value> method instead?
699
700 =item IVX
701
702 =item UVX
703
704 =item int_value
705
706 This method returns the value of the IV as an integer.
707 It differs from C<IV> in that it returns the correct
708 value regardless of whether it's stored signed or
709 unsigned.
710
711 =item needs64bits
712
713 =item packiv
714
715 =back
716
717 =head2 B::NV Methods
718
719 =over 4
720
721 =item NV
722
723 =item NVX
724
725 =back
726
727 =head2 B::RV Methods
728
729 =over 4
730
731 =item RV
732
733 =back
734
735 =head2 B::PV Methods
736
737 =over 4
738
739 =item PV
740
741 This method is the one you usually want.  It constructs a
742 string using the length and offset information in the struct:
743 for ordinary scalars it will return the string that you'd see
744 from Perl, even if it contains null characters.
745
746 =item RV
747
748 Same as B::RV::RV, except that it will die() if the PV isn't
749 a reference.
750
751 =item PVX
752
753 This method is less often useful.  It assumes that the string
754 stored in the struct is null-terminated, and disregards the
755 length information.
756
757 It is the appropriate method to use if you need to get the name
758 of a lexical variable from a padname array.  Lexical variable names
759 are always stored with a null terminator, and the length field
760 (CUR) is overloaded for other purposes and can't be relied on here.
761
762 =item CUR
763
764 This method returns the internal length field, which consists of the number
765 of internal bytes, not necessarily the number of logical characters.
766
767 =item LEN
768
769 This method returns the number of bytes allocated (via malloc) for storing
770 the string.  This is 0 if the scalar does not "own" the string.
771
772 =back
773
774 =head2 B::PVMG Methods
775
776 =over 4
777
778 =item MAGIC
779
780 =item SvSTASH
781
782 =back
783
784 =head2 B::MAGIC Methods
785
786 =over 4
787
788 =item MOREMAGIC
789
790 =item precomp
791
792 Only valid on r-magic, returns the string that generated the regexp.
793
794 =item PRIVATE
795
796 =item TYPE
797
798 =item FLAGS
799
800 =item OBJ
801
802 Will die() if called on r-magic.
803
804 =item PTR
805
806 =item REGEX
807
808 Only valid on r-magic, returns the integer value of the REGEX stored
809 in the MAGIC.
810
811 =back
812
813 =head2 B::PVLV Methods
814
815 =over 4
816
817 =item TARGOFF
818
819 =item TARGLEN
820
821 =item TYPE
822
823 =item TARG
824
825 =back
826
827 =head2 B::BM Methods
828
829 =over 4
830
831 =item USEFUL
832
833 =item PREVIOUS
834
835 =item RARE
836
837 =item TABLE
838
839 =back
840
841 =head2 B::GV Methods
842
843 =over 4
844
845 =item is_empty
846
847 This method returns TRUE if the GP field of the GV is NULL.
848
849 =item NAME
850
851 =item SAFENAME
852
853 This method returns the name of the glob, but if the first
854 character of the name is a control character, then it converts
855 it to ^X first, so that *^G would return "^G" rather than "\cG".
856
857 It's useful if you want to print out the name of a variable.
858 If you restrict yourself to globs which exist at compile-time
859 then the result ought to be unambiguous, because code like
860 C<${"^G"} = 1> is compiled as two ops - a constant string and
861 a dereference (rv2gv) - so that the glob is created at runtime.
862
863 If you're working with globs at runtime, and need to disambiguate
864 *^G from *{"^G"}, then you should use the raw NAME method.
865
866 =item STASH
867
868 =item SV
869
870 =item IO
871
872 =item FORM
873
874 =item AV
875
876 =item HV
877
878 =item EGV
879
880 =item CV
881
882 =item CVGEN
883
884 =item LINE
885
886 =item FILE
887
888 =item FILEGV
889
890 =item GvREFCNT
891
892 =item FLAGS
893
894 =back
895
896 =head2 B::IO Methods
897
898 B::IO objects derive from IO objects and you will get more information from
899 the IO object itself.
900
901 For example:
902
903   $gvio = B::svref_2object(\*main::stdin)->IO;
904   $IO = $gvio->object_2svref();
905   $fd = $IO->fileno();
906
907 =over 4
908
909 =item LINES
910
911 =item PAGE
912
913 =item PAGE_LEN
914
915 =item LINES_LEFT
916
917 =item TOP_NAME
918
919 =item TOP_GV
920
921 =item FMT_NAME
922
923 =item FMT_GV
924
925 =item BOTTOM_NAME
926
927 =item BOTTOM_GV
928
929 =item SUBPROCESS
930
931 =item IoTYPE
932
933 A character symbolizing the type of IO Handle.
934
935   -     STDIN/OUT
936   I     STDIN/OUT/ERR
937   <     read-only
938   >     write-only
939   a     append
940   +     read and write
941   s     socket
942   |     pipe
943   I     IMPLICIT
944   #     NUMERIC
945   space closed handle
946   \0    closed internal handle
947
948 =item IoFLAGS
949
950 =item IsSTD
951
952 Takes one argument ( 'stdin' | 'stdout' | 'stderr' ) and returns true
953 if the IoIFP of the object is equal to the handle whose name was
954 passed as argument; i.e., $io->IsSTD('stderr') is true if
955 IoIFP($io) == PerlIO_stderr().
956
957 =back
958
959 =head2 B::AV Methods
960
961 =over 4
962
963 =item FILL
964
965 =item MAX
966
967 =item ARRAY
968
969 =item ARRAYelt
970
971 Like C<ARRAY>, but takes an index as an argument to get only one element,
972 rather than a list of all of them.
973
974 =item OFF
975
976 This method is deprecated if running under Perl 5.8, and is no longer present
977 if running under Perl 5.9
978
979 =item AvFLAGS
980
981 This method returns the AV specific
982 flags.  In Perl 5.9 these are now stored
983 in with the main SV flags, so this method is no longer present.
984
985 =back
986
987 =head2 B::CV Methods
988
989 =over 4
990
991 =item STASH
992
993 =item START
994
995 =item ROOT
996
997 =item GV
998
999 =item FILE
1000
1001 =item DEPTH
1002
1003 =item PADLIST
1004
1005 =item OUTSIDE
1006
1007 =item OUTSIDE_SEQ
1008
1009 =item XSUB
1010
1011 =item XSUBANY
1012
1013 For constant subroutines, returns the constant SV returned by the subroutine.
1014
1015 =item CvFLAGS
1016
1017 =item const_sv
1018
1019 =back
1020
1021 =head2 B::HV Methods
1022
1023 =over 4
1024
1025 =item FILL
1026
1027 =item MAX
1028
1029 =item KEYS
1030
1031 =item RITER
1032
1033 =item NAME
1034
1035 =item ARRAY
1036
1037 =item PMROOT
1038
1039 This method is not present if running under Perl 5.9, as the PMROOT
1040 information is no longer stored directly in the hash.
1041
1042 =back
1043
1044 =head2 OP-RELATED CLASSES
1045
1046 C<B::OP>, C<B::UNOP>, C<B::BINOP>, C<B::LOGOP>, C<B::LISTOP>, C<B::PMOP>,
1047 C<B::SVOP>, C<B::PADOP>, C<B::PVOP>, C<B::LOOP>, C<B::COP>.
1048
1049 These classes correspond in the obvious way to the underlying C
1050 structures of similar names.  The inheritance hierarchy mimics the
1051 underlying C "inheritance":
1052
1053                                  B::OP
1054                                    |
1055                    +---------------+--------+--------+-------+
1056                    |               |        |        |       |
1057                 B::UNOP          B::SVOP B::PADOP  B::COP  B::PVOP
1058                  ,'  `-.
1059                 /       `--.
1060            B::BINOP     B::LOGOP
1061                |
1062                |
1063            B::LISTOP
1064              ,' `.
1065             /     \
1066         B::LOOP B::PMOP
1067
1068 Access methods correspond to the underlying C structre field names,
1069 with the leading "class indication" prefix (C<"op_">) removed.
1070
1071 =head2 B::OP Methods
1072
1073 These methods get the values of similarly named fields within the OP
1074 data structure.  See top of C<op.h> for more info.
1075
1076 =over 4
1077
1078 =item next
1079
1080 =item sibling
1081
1082 =item name
1083
1084 This returns the op name as a string (e.g. "add", "rv2av").
1085
1086 =item ppaddr
1087
1088 This returns the function name as a string (e.g. "PL_ppaddr[OP_ADD]",
1089 "PL_ppaddr[OP_RV2AV]").
1090
1091 =item desc
1092
1093 This returns the op description from the global C PL_op_desc array
1094 (e.g. "addition" "array deref").
1095
1096 =item targ
1097
1098 =item type
1099
1100 =item opt
1101
1102 =item flags
1103
1104 =item private
1105
1106 =item spare
1107
1108 =back
1109
1110 =head2 B::UNOP METHOD
1111
1112 =over 4
1113
1114 =item first
1115
1116 =back
1117
1118 =head2 B::BINOP METHOD
1119
1120 =over 4
1121
1122 =item last
1123
1124 =back
1125
1126 =head2 B::LOGOP METHOD
1127
1128 =over 4
1129
1130 =item other
1131
1132 =back
1133
1134 =head2 B::LISTOP METHOD
1135
1136 =over 4
1137
1138 =item children
1139
1140 =back
1141
1142 =head2 B::PMOP Methods
1143
1144 =over 4
1145
1146 =item pmreplroot
1147
1148 =item pmreplstart
1149
1150 =item pmnext
1151
1152 Only up to Perl 5.9.4
1153
1154 =item pmflags
1155
1156 =item extflags
1157
1158 Since Perl 5.9.5
1159
1160 =item precomp
1161
1162 =item pmoffset
1163
1164 Only when perl was compiled with ithreads.
1165
1166 =item code_list
1167
1168 Since perl 5.17.1
1169
1170 =back
1171
1172 =head2 B::SVOP METHOD
1173
1174 =over 4
1175
1176 =item sv
1177
1178 =item gv
1179
1180 =back
1181
1182 =head2 B::PADOP METHOD
1183
1184 =over 4
1185
1186 =item padix
1187
1188 =back
1189
1190 =head2 B::PVOP METHOD
1191
1192 =over 4
1193
1194 =item pv
1195
1196 =back
1197
1198 =head2 B::LOOP Methods
1199
1200 =over 4
1201
1202 =item redoop
1203
1204 =item nextop
1205
1206 =item lastop
1207
1208 =back
1209
1210 =head2 B::COP Methods
1211
1212 =over 4
1213
1214 =item label
1215
1216 =item stash
1217
1218 =item stashpv
1219
1220 =item stashoff (threaded only)
1221
1222 =item file
1223
1224 =item cop_seq
1225
1226 =item arybase
1227
1228 =item line
1229
1230 =item warnings
1231
1232 =item io
1233
1234 =item hints
1235
1236 =item hints_hash
1237
1238 =back
1239
1240
1241 =head1 AUTHOR
1242
1243 Malcolm Beattie, C<mbeattie@sable.ox.ac.uk>
1244
1245 =cut