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