# License or the Artistic License, as specified in the README file.
#
package B;
+use strict;
-our $VERSION = '1.07';
-
-use XSLoader ();
require Exporter;
-@ISA = qw(Exporter);
+@B::ISA = qw(Exporter);
# walkoptree_slow comes from B.pm (you are there),
# walkoptree comes from B.xs
-@EXPORT_OK = qw(minus_c ppname save_BEGINs
- class peekop cast_I32 cstring cchar hash threadsv_names
- main_root main_start main_cv svref_2object opnumber
- amagic_generation perlstring
- walkoptree_slow walkoptree walkoptree_exec walksymtable
- parents comppadlist sv_undef compile_stats timing_info
- begin_av init_av check_av end_av regex_padav dowarn
- defstash curstash warnhook diehook inc_gv
- );
-
-sub OPf_KIDS ();
-use strict;
+
+BEGIN {
+ $B::VERSION = '1.52';
+ @B::EXPORT_OK = ();
+
+ # Our BOOT code needs $VERSION set, and will append to @EXPORT_OK.
+ # Want our constants loaded before the compiler meets OPf_KIDS below, as
+ # the combination of having the constant stay a Proxy Constant Subroutine
+ # and its value being inlined saves a little over .5K
+
+ require XSLoader;
+ XSLoader::load();
+}
+
+push @B::EXPORT_OK, (qw(minus_c ppname save_BEGINs
+ class peekop cast_I32 cstring cchar hash threadsv_names
+ main_root main_start main_cv svref_2object opnumber
+ sub_generation amagic_generation perlstring
+ walkoptree_slow walkoptree walkoptree_exec walksymtable
+ parents comppadlist sv_undef compile_stats timing_info
+ begin_av init_av check_av end_av regex_padav dowarn
+ defstash curstash warnhook diehook inc_gv @optype
+ @specialsv_name unitcheck_av safename));
+
@B::SV::ISA = 'B::OBJECT';
@B::NULL::ISA = 'B::SV';
@B::PV::ISA = 'B::SV';
@B::IV::ISA = 'B::SV';
-@B::NV::ISA = 'B::IV';
-@B::RV::ISA = 'B::SV';
+@B::NV::ISA = 'B::SV';
+# RV is eliminated with 5.11.0, but effectively is a specialisation of IV now.
+@B::RV::ISA = $] >= 5.011 ? 'B::IV' : 'B::SV';
@B::PVIV::ISA = qw(B::PV B::IV);
-@B::PVNV::ISA = qw(B::PV B::NV);
+@B::PVNV::ISA = qw(B::PVIV B::NV);
@B::PVMG::ISA = 'B::PVNV';
-# Change in the inheritance hierarchy post 5.9.0
-@B::PVLV::ISA = $] > 5.009 ? 'B::GV' : 'B::PVMG';
-@B::BM::ISA = 'B::PVMG';
+@B::REGEXP::ISA = 'B::PVMG' if $] >= 5.011;
+@B::INVLIST::ISA = 'B::PV' if $] >= 5.019;
+@B::PVLV::ISA = 'B::GV';
+@B::BM::ISA = 'B::GV';
@B::AV::ISA = 'B::PVMG';
@B::GV::ISA = 'B::PVMG';
@B::HV::ISA = 'B::PVMG';
@B::LOOP::ISA = 'B::LISTOP';
@B::PMOP::ISA = 'B::LISTOP';
@B::COP::ISA = 'B::OP';
+@B::METHOP::ISA = 'B::OP';
@B::SPECIAL::ISA = 'B::OBJECT';
+@B::optype = qw(OP UNOP BINOP LOGOP LISTOP PMOP SVOP PADOP PVOP LOOP COP METHOP);
+# bytecode.pl contained the following comment:
+# Nullsv *must* come first in the following so that the condition
+# ($$sv == 0) can continue to be used to test (sv == Nullsv).
+@B::specialsv_name = qw(Nullsv &PL_sv_undef &PL_sv_yes &PL_sv_no
+ (SV*)pWARN_ALL (SV*)pWARN_NONE (SV*)pWARN_STD);
+
{
# Stop "-w" from complaining about the lack of a real B::OBJECT class
package B::OBJECT;
}
sub B::GV::SAFENAME {
- my $name = (shift())->NAME;
+ safename(shift()->NAME);
+}
+
+sub safename {
+ my $name = shift;
# The regex below corresponds to the isCONTROLVAR macro
# from toke.c
- $name =~ s/^([\cA-\cZ\c\\c[\c]\c?\c_\c^])/"^".
- chr( utf8::unicode_to_native( 64 ^ ord($1) ))/e;
+ $name =~ s/^\c?/^?/
+ or $name =~ s/^([\cA-\cZ\c\\c[\c]\c_\c^])/
+ "^" . chr( utf8::unicode_to_native( 64 ^ ord($1) ))/e;
# When we say unicode_to_native we really mean ascii_to_native,
- # which matters iff this is a non-ASCII platform (EBCDIC).
+ # which matters iff this is a non-ASCII platform (EBCDIC). '\c?' would
+ # not have to be special cased, except for non-ASCII.
return $name;
}
}
sub B::NULL::as_string() {""}
-sub B::IV::as_string() {goto &B::IV::int_value}
-sub B::PV::as_string() {goto &B::PV::PV}
+*B::IV::as_string = \*B::IV::int_value;
+*B::PV::as_string = \*B::PV::PV;
+
+# The input typemap checking makes no distinction between different SV types,
+# so the XS body will generate the same C code, despite the different XS
+# "types". So there is no change in behaviour from doing "newXS" like this,
+# compared with the old approach of having a (near) duplicate XS body.
+# We should fix the typemap checking.
+*B::IV::RV = \*B::PV::RV if $] > 5.012;
my $debug;
my $op_count = 0;
$op_count++; # just for statistics
$level ||= 0;
warn(sprintf("walkoptree: %d. %s\n", $level, peekop($op))) if $debug;
- $op->$method($level);
+ $op->$method($level) if $op->can($method);
if ($$op && ($op->flags & OPf_KIDS)) {
my $kid;
unshift(@parents, $op);
}
shift @parents;
}
- if (class($op) eq 'PMOP' && ref($op->pmreplroot) && ${$op->pmreplroot}) {
+ if (class($op) eq 'PMOP'
+ && ref($op->pmreplroot)
+ && ${$op->pmreplroot}
+ && $op->pmreplroot->isa( 'B::OP' ))
+ {
unshift(@parents, $op);
walkoptree_slow($op->pmreplroot, $method, $level + 1);
shift @parents;
my $fullname;
no strict 'refs';
$prefix = '' unless defined $prefix;
- while (($sym, $ref) = each %$symref) {
+ foreach my $sym ( sort keys %$symref ) {
+ $ref= $symref->{$sym};
$fullname = "*main::".$prefix.$sym;
if ($sym =~ /::$/) {
$sym = $prefix . $sym;
- if ($sym ne "main::" && $sym ne "<none>::" && &$recurse($sym)) {
+ if (svref_2object(\*$sym)->NAME ne "main::" && $sym ne "<none>::" && &$recurse($sym)) {
walksymtable(\%$fullname, $method, $recurse, $sym);
}
} else {
}
}
-XSLoader::load 'B';
-
1;
__END__
=head1 NAME
-B - The Perl Compiler
+B - The Perl Compiler Backend
=head1 SYNOPSIS
=head1 DESCRIPTION
The C<B> module supplies classes which allow a Perl program to delve
-into its own innards. It is the module used to implement the
-"backends" of the Perl compiler. Usage of the compiler does not
+into its own innards. It is the module used to implement the
+"backends" of the Perl compiler. Usage of the compiler does not
require knowledge of this module: see the F<O> module for the
-user-visible part. The C<B> module is of use to those who want to
-write new compiler backends. This documentation assumes that the
+user-visible part. The C<B> module is of use to those who want to
+write new compiler backends. This documentation assumes that the
reader knows a fair amount about perl's internals including such
things as SVs, OPs and the internal symbol table and syntax tree
of a program.
Takes a reference to any Perl value, and turns the referred-to value
into an object in the appropriate B::OP-derived or B::SV-derived
-class. Apart from functions such as C<main_root>, this is the primary
+class. Apart from functions such as C<main_root>, this is the primary
way to get an initial "handle" on an internal perl data structure
which can then be followed with the other access methods.
+The returned object will only be valid as long as the underlying OPs
+and SVs continue to exist. Do not attempt to use the object after the
+underlying structures are freed.
+
=item amagic_generation
Returns the SV object corresponding to the C variable C<amagic_generation>.
+As of Perl 5.18, this is just an alias to C<PL_na>, so its value is
+meaningless.
=item init_av
Returns the AV object (i.e. in class B::AV) representing CHECK blocks.
+=item unitcheck_av
+
+Returns the AV object (i.e. in class B::AV) representing UNITCHECK blocks.
+
=item begin_av
Returns the AV object (i.e. in class B::AV) representing BEGIN blocks.
=item comppadlist
-Returns the AV object (i.e. in class B::AV) of the global comppadlist.
+Returns the PADLIST object (i.e. in class B::PADLIST) of the global
+comppadlist. In Perl 5.16 and earlier it returns an AV object (class
+B::AV).
=item regex_padav
# Walk CGI's symbol table calling print_subs on each symbol.
# Recurse only into CGI::Util::
- walksymtable(\%CGI::, 'print_subs', sub { $_[0] eq 'CGI::Util::' },
- 'CGI::');
+ walksymtable(\%CGI::, 'print_subs',
+ sub { $_[0] eq 'CGI::Util::' }, 'CGI::');
-print_subs() is a B::GV method you have declared. Also see L<"B::GV
+print_subs() is a B::GV method you have declared. Also see L<"B::GV
Methods">, below.
=back
=item walkoptree(OP, METHOD)
Does a tree-walk of the syntax tree based at OP and calls METHOD on
-each op it visits. Each node is visited before its children. If
+each op it visits. Each node is visited before its children. If
C<walkoptree_debug> (see below) has been called to turn debugging on then
the method C<walkoptree_debug> is called on each op before METHOD is
called.
=item walkoptree_debug(DEBUG)
-Returns the current debugging flag for C<walkoptree>. If the optional
-DEBUG argument is non-zero, it sets the debugging flag to that. See
+Returns the current debugging flag for C<walkoptree>. If the optional
+DEBUG argument is non-zero, it sets the debugging flag to that. See
the description of C<walkoptree> above for what the debugging flag
does.
=item minus_c
-Does the equivalent of the C<-c> command-line option. Obviously, this
+Does the equivalent of the C<-c> command-line option. Obviously, this
is only useful in a BEGIN block or else the flag is set too late.
=item cstring(STR)
Returns a double-quote-surrounded escaped version of STR which can
be used as a string in Perl source code.
+=item safename(STR)
+
+This function returns the string with the first character modified if it
+is a control character. It converts it to ^X format first, so that "\cG"
+becomes "^G". This is used internally by L<B::GV::SAFENAME|/SAFENAME>, but
+you can call it directly.
+
=item class(OBJ)
Returns the class of an object without the part of the classname
-preceding the first C<"::">. This is used to turn C<"B::UNOP"> into
+preceding the first C<"::">. This is used to turn C<"B::UNOP"> into
C<"UNOP"> for example.
=item threadsv_names
-In a perl compiled for threads, this returns a list of the special
-per-thread threadsv variables.
+This used to provide support for the old 5.005 threading module. It now
+does nothing.
=back
+=head2 Exported utility variables
+=over 4
+
+=item @optype
+
+ my $op_type = $optype[$op_type_num];
+
+A simple mapping of the op type number to its type (like 'COP' or 'BINOP').
+
+=item @specialsv_name
+
+ my $sv_name = $specialsv_name[$sv_index];
+
+Certain SV types are considered 'special'. They're represented by
+B::SPECIAL and are referred to by a number from the specialsv_list.
+This array maps that number back to the name of the SV (like 'Nullsv'
+or '&PL_sv_undef').
+
+=back
=head1 OVERVIEW OF CLASSES
The C structures used by Perl's internals to hold SV and OP
information (PVIV, AV, HV, ..., OP, SVOP, UNOP, ...) are modelled on a
class hierarchy and the C<B> module gives access to them via a true
-object hierarchy. Structure fields which point to other objects
+object hierarchy. Structure fields which point to other objects
(whether types of SV or types of OP) are represented by the C<B>
module as Perl objects of the appropriate class.
these structures.
Note that all access is read-only. You cannot modify the internals by
-using this module.
+using this module. Also, note that the B::OP and B::SV objects created
+by this module are only valid for as long as the underlying objects
+exist; their creation doesn't increase the reference counts of the
+underlying objects. Trying to access the fields of a freed object will
+give incomprehensible results, or worse.
=head2 SV-RELATED CLASSES
-B::IV, B::NV, B::RV, B::PV, B::PVIV, B::PVNV, B::PVMG, B::BM, B::PVLV,
-B::AV, B::HV, B::CV, B::GV, B::FM, B::IO. These classes correspond in
-the obvious way to the underlying C structures of similar names. The
-inheritance hierarchy mimics the underlying C "inheritance". For 5.9.1
-and later this is:
+B::IV, B::NV, B::RV, B::PV, B::PVIV, B::PVNV, B::PVMG, B::BM (5.9.5 and
+earlier), B::PVLV, B::AV, B::HV, B::CV, B::GV, B::FM, B::IO. These classes
+correspond in the obvious way to the underlying C structures of similar names.
+The inheritance hierarchy mimics the underlying C "inheritance". For the
+5.10.x branch, (I<ie> 5.10.0, 5.10.1 I<etc>) this is:
+
+ B::SV
+ |
+ +------------+------------+------------+
+ | | | |
+ B::PV B::IV B::NV B::RV
+ \ / /
+ \ / /
+ B::PVIV /
+ \ /
+ \ /
+ \ /
+ B::PVNV
+ |
+ |
+ B::PVMG
+ |
+ +-----+-----+-----+-----+
+ | | | | |
+ B::AV B::GV B::HV B::CV B::IO
+ | |
+ | |
+ B::PVLV B::FM
+
+For 5.9.0 and earlier, PVLV is a direct subclass of PVMG, and BM is still
+present as a distinct type, so the base of this diagram is
+
- B::SV
|
- +--------------+----------------------+
- | | |
- B::PV B::IV B::RV
- | \ / \
- | \ / \
- | B::PVIV B::NV
- \ /
- \____ __/
- \ /
- B::PVNV
- |
- |
- B::PVMG
- |
- +-----+----+------+-----+-----+
- | | | | | |
- B::BM B::AV B::GV B::HV B::CV B::IO
- | |
- B::PVLV |
- B::FM
-
-
-For 5.9.0 and earlier, PVLV is a direct subclass of PVMG, so the base
-of this diagram is
-
- |
- B::PVMG
- |
- +------+-----+----+------+-----+-----+
- | | | | | | |
- B::PVLV B::BM B::AV B::GV B::HV B::CV B::IO
- |
- |
- B::FM
+ |
+ B::PVMG
+ |
+ +------+-----+-----+-----+-----+-----+
+ | | | | | | |
+ B::PVLV B::BM B::AV B::GV B::HV B::CV B::IO
+ |
+ |
+ B::FM
+
+For 5.11.0 and later, B::RV is abolished, and IVs can be used to store
+references, and a new type B::REGEXP is introduced, giving this structure:
+
+ B::SV
+ |
+ +------------+------------+
+ | | |
+ B::PV B::IV B::NV
+ \ / /
+ \ / /
+ B::PVIV /
+ \ /
+ \ /
+ \ /
+ B::PVNV
+ |
+ |
+ B::PVMG
+ |
+ +-------+-------+---+---+-------+-------+
+ | | | | | |
+ B::AV B::GV B::HV B::CV B::IO B::REGEXP
+ | |
+ | |
+ B::PVLV B::FM
Access methods correspond to the underlying C macros for field access,
usually with the leading "class indication" prefix removed (Sv, Av,
-Hv, ...). The leading prefix is only left in cases where its removal
-would cause a clash in method name. For example, C<GvREFCNT> stays
+Hv, ...). The leading prefix is only left in cases where its removal
+would cause a clash in method name. For example, C<GvREFCNT> stays
as-is since its abbreviation would clash with the "superclass" method
C<REFCNT> (corresponding to the C function C<SvREFCNT>).
=item object_2svref
Returns a reference to the regular scalar corresponding to this
-B::SV object. In other words, this method is the inverse operation
-to the svref_2object() subroutine. This scalar and other data it points
+B::SV object. In other words, this method is the inverse operation
+to the svref_2object() subroutine. This scalar and other data it points
at should be considered read-only: modifying them is neither safe nor
guaranteed to have a sensible effect.
=item IV
Returns the value of the IV, I<interpreted as
-a signed integer>. This will be misleading
-if C<FLAGS & SVf_IVisUV>. Perhaps you want the
+a signed integer>. This will be misleading
+if C<FLAGS & SVf_IVisUV>. Perhaps you want the
C<int_value> method instead?
=item IVX
=item PV
-This method is the one you usually want. It constructs a
+This method is the one you usually want. It constructs a
string using the length and offset information in the struct:
for ordinary scalars it will return the string that you'd see
from Perl, even if it contains null characters.
=item PVX
-This method is less often useful. It assumes that the string
+This method is less often useful. It assumes that the string
stored in the struct is null-terminated, and disregards the
length information.
It is the appropriate method to use if you need to get the name
-of a lexical variable from a padname array. Lexical variable names
+of a lexical variable from a padname array. Lexical variable names
are always stored with a null terminator, and the length field
-(SvCUR) is overloaded for other purposes and can't be relied on here.
+(CUR) is overloaded for other purposes and can't be relied on here.
+
+=item CUR
+
+This method returns the internal length field, which consists of the number
+of internal bytes, not necessarily the number of logical characters.
+
+=item LEN
+
+This method returns the number of bytes allocated (via malloc) for storing
+the string. This is 0 if the scalar does not "own" the string.
=back
=item FLAGS
+=item GPFLAGS
+
+This last one is present only in perl 5.22.0 and higher.
+
=back
=head2 B::IO Methods
+B::IO objects derive from IO objects and you will get more information from
+the IO object itself.
+
+For example:
+
+ $gvio = B::svref_2object(\*main::stdin)->IO;
+ $IO = $gvio->object_2svref();
+ $fd = $IO->fileno();
+
=over 4
=item LINES
=item IoTYPE
+A character symbolizing the type of IO Handle.
+
+ - STDIN/OUT
+ I STDIN/OUT/ERR
+ < read-only
+ > write-only
+ a append
+ + read and write
+ s socket
+ | pipe
+ I IMPLICIT
+ # NUMERIC
+ space closed handle
+ \0 closed internal handle
+
=item IoFLAGS
=item IsSTD
-Takes one arguments ( 'stdin' | 'stdout' | 'stderr' ) and returns true
+Takes one argument ( 'stdin' | 'stdout' | 'stderr' ) and returns true
if the IoIFP of the object is equal to the handle whose name was
-passed as argument ( i.e. $io->IsSTD('stderr') is true if
-IoIFP($io) == PerlIO_stdin() ).
+passed as argument; i.e., $io->IsSTD('stderr') is true if
+IoIFP($io) == PerlIO_stderr().
=back
=item MAX
-=item OFF
-
=item ARRAY
=item ARRAYelt
Like C<ARRAY>, but takes an index as an argument to get only one element,
rather than a list of all of them.
+=item OFF
+
+This method is deprecated if running under Perl 5.8, and is no longer present
+if running under Perl 5.9
+
=item AvFLAGS
+This method returns the AV specific
+flags. In Perl 5.9 these are now stored
+in with the main SV flags, so this method is no longer present.
+
=back
=head2 B::CV Methods
=item PADLIST
+Returns a B::PADLIST object under Perl 5.18 or higher, or a B::AV in
+earlier versions.
+
=item OUTSIDE
=item OUTSIDE_SEQ
=item const_sv
+=item NAME_HEK
+
+Returns the name of a lexical sub, otherwise C<undef>.
+
=back
=head2 B::HV Methods
=item NAME
+=item ARRAY
+
=item PMROOT
-=item ARRAY
+This method is not present if running under Perl 5.9, as the PMROOT
+information is no longer stored directly in the hash.
=back
=head2 OP-RELATED CLASSES
C<B::OP>, C<B::UNOP>, C<B::BINOP>, C<B::LOGOP>, C<B::LISTOP>, C<B::PMOP>,
-C<B::SVOP>, C<B::PADOP>, C<B::PVOP>, C<B::LOOP>, C<B::COP>.
+C<B::SVOP>, C<B::PADOP>, C<B::PVOP>, C<B::LOOP>, C<B::COP>, C<B::METHOP>.
These classes correspond in the obvious way to the underlying C
-structures of similar names. The inheritance hierarchy mimics the
+structures of similar names. The inheritance hierarchy mimics the
underlying C "inheritance":
B::OP
|
- +---------------+--------+--------+
- | | | |
- B::UNOP B::SVOP B::PADOP B::COP
+ +----------+---------+--------+-------+---------+
+ | | | | | |
+ B::UNOP B::SVOP B::PADOP B::COP B::PVOP B::METHOP
,' `-.
/ `--.
B::BINOP B::LOGOP
/ \
B::LOOP B::PMOP
-Access methods correspond to the underlying C structre field names,
+Access methods correspond to the underlying C structure field names,
with the leading "class indication" prefix (C<"op_">) removed.
=head2 B::OP Methods
=item sibling
+=item parent
+
+Returns the OP's parent. If it has no parent, or if your perl wasn't built
+with C<-DPERL_OP_PARENT>, returns NULL.
+
=item name
This returns the op name as a string (e.g. "add", "rv2av").
=item opt
-=item static
-
=item flags
=item private
=item pmnext
-=item pmregexp
+Only up to Perl 5.9.4
=item pmflags
-=item pmdynflags
+=item extflags
-=item pmpermflags
+Since Perl 5.9.5
=item precomp
Only when perl was compiled with ithreads.
+=item code_list
+
+Since perl 5.17.1
+
=back
=head2 B::SVOP METHOD
=item stashpv
+=item stashoff (threaded only)
+
=item file
=item cop_seq
=item io
+=item hints
+
+=item hints_hash
+
+=back
+
+=head2 B::METHOP Methods (Since Perl 5.22)
+
+=over 4
+
+=item first
+
+=item meth_sv
+
=back
+=head2 OTHER CLASSES
+
+Perl 5.18 introduces a new class, B::PADLIST, returned by B::CV's
+C<PADLIST> method.
+
+=head2 B::PADLIST Methods
+
+=over 4
+
+=item MAX
+
+=item ARRAY
+
+A list of pads. The first one contains the names. These are currently
+B::AV objects, but that is likely to change in future versions.
+
+=item ARRAYelt
+
+Like C<ARRAY>, but takes an index as an argument to get only one element,
+rather than a list of all of them.
+
+=item REFCNT
+
+=back
+
+=head2 $B::overlay
+
+Although the optree is read-only, there is an overlay facility that allows
+you to override what values the various B::*OP methods return for a
+particular op. C<$B::overlay> should be set to reference a two-deep hash:
+indexed by OP address, then method name. Whenever a an op method is
+called, the value in the hash is returned if it exists. This facility is
+used by B::Deparse to "undo" some optimisations. For example:
+
+
+ local $B::overlay = {};
+ ...
+ if ($op->name eq "foo") {
+ $B::overlay->{$$op} = {
+ name => 'bar',
+ next => $op->next->next,
+ };
+ }
+ ...
+ $op->name # returns "bar"
+ $op->next # returns the next op but one
+
=head1 AUTHOR
https://perl5.git.perl.org / perl5.git / blobdiff