lib:B

See the current Perl documentation for lib:B.

Here is our local, out-dated (pre-5.6) version:

B - The Perl Compiler

        use B;

The 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 require knowledge of this module: see the O module for the user-visible part. The 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.

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 B module gives access to them via a true object hierarchy. Structure fields which point to other objects (whether types of SV or types of OP) are represented by the B module as Perl objects of the appropriate class. The bulk of the B module is the methods for accessing fields of these structures. Note that all access is read-only: you cannot modify the internals by using this module.

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''. 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, GvREFCNT stays as-is since its abbreviation would clash with the ``superclass'' method REFCNT (corresponding to the C function perlguts).

B::SV METHODS

REFCNT
FLAGS

B::IV METHODS

IV
IVX
needs64bits
packiv

B::NV METHODS

NV
NVX

B::RV METHODS

RV

B::PV METHODS

PV

B::PVMG METHODS

MAGIC
SvSTASH

B::MAGIC METHODS

MOREMAGIC
PRIVATE
TYPE
FLAGS
OBJ
PTR

B::PVLV METHODS

TARGOFF
TARGLEN
TYPE
TARG

B::BM METHODS

USEFUL
PREVIOUS
RARE
TABLE

B::GV METHODS

NAME
STASH
SV
IO
FORM
AV
HV
EGV
CV
CVGEN
LINE
FILEGV
GvREFCNT
FLAGS

B::IO METHODS

LINES
PAGE
PAGE_LEN
LINES_LEFT
TOP_NAME
TOP_GV
FMT_NAME
FMT_GV
BOTTOM_NAME
BOTTOM_GV
SUBPROCESS
IoTYPE
IoFLAGS

B::AV METHODS

FILL
MAX
OFF
ARRAY
AvFLAGS

B::CV METHODS

STASH
START
ROOT
GV
FILEGV
DEPTH
PADLIST
OUTSIDE
XSUB
XSUBANY

B::HV METHODS

FILL
MAX
KEYS
RITER
NAME
PMROOT
ARRAY

OP-RELATED CLASSES

B::OP, B::UNOP, B::BINOP, B::LOGOP, B::CONDOP, B::LISTOP, B::PMOP, B::SVOP, B::GVOP, B::PVOP, B::CVOP, B::LOOP, B::COP. These classes correspond in the obvious way to the underlying C structures of similar names. The inheritance hierarchy mimics the underlying C ``inheritance''. Access methods correspond to the underlying C structre field names, with the leading ``class indication'' prefix removed (op_).

B::OP METHODS

next
sibling
ppaddr: This returns the function name as a string (e.g. pp_add, pp_rv2av).
desc: This returns the op description from the global C op_desc array (e.g. ``addition'' ``array deref'').
targ
type
seq
flags
private

B::UNOP METHOD

first

B::BINOP METHOD

last

B::LOGOP METHOD

other

B::CONDOP METHODS

true
false

B::LISTOP METHOD

children

B::PMOP METHODS

pmreplroot
pmreplstart
pmnext
pmregexp
pmflags
pmpermflags
precomp

B::SVOP METHOD

sv

B::GVOP METHOD

gv

B::PVOP METHOD

pv

B::LOOP METHODS

redoop
nextop
lastop

B::COP METHODS

label
stash
filegv
cop_seq
arybase
line

FUNCTIONS EXPORTED BY `B`

The B module exports a variety of functions: some are simple utility functions, others provide a Perl program with a way to get an initial ``handle'' on an internal object.

main_cv: Return the (faked) CV corresponding to the main part of the Perl program.
main_root: Returns the root op (i.e. an object in the appropriate B::OP-derived class) of the main part of the Perl program.
main_start: Returns the starting op of the main part of the Perl program.
comppadlist: Returns the AV object (i.e. in class B::AV) of the global comppadlist.
sv_undef: Returns the SV object corresponding to the C variable sv_undef.
sv_yes: Returns the SV object corresponding to the C variable sv_yes.
sv_no: Returns the SV object corresponding to the C variable sv_no.
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 walkoptree_debug (q.v.) has been called to turn debugging on then the method walkoptree_debug is called on each op before METHOD is called.
walkoptree_debug(DEBUG): Returns the current debugging flag for walkoptree. If the optional DEBUG argument is non-zero, it sets the debugging flag to that. See the description of walkoptree above for what the debugging flag does.
walksymtable(SYMREF, METHOD, RECURSE): Walk the symbol table starting at SYMREF and call METHOD on each symbol visited. When the walk reached package symbols ``Foo::'' it invokes RECURSE and only recurses into the package if that sub returns true.
svref_2object(SV): Takes any Perl variable and turns it into an object in the appropriate B::OP-derived or B::SV-derived class. Apart from functions such as main_root, this is the primary way to get an initial ``handle'' on a internal perl data structure which can then be followed with the other access methods.
ppname(OPNUM): Return the PP function name (e.g. ``pp_add'') of op number OPNUM.
hash(STR): Returns a string in the form ``0x...'' representing the value of the internal hash function used by perl on string STR.
cast_I32(I): Casts I to the internal I32 type used by that perl.
minus_c: Does the equivalent of the -c command-line option. Obviously, this is only useful in a BEGIN block or else the flag is set too late.
cstring(STR): Returns a double-quote-surrounded escaped version of STR which can be used as a string in C source code.
class(OBJ): Returns the class of an object without the part of the classname preceding the first ``::''. This is used to turn ``B::UNOP'' into ``UNOP'' for example.
threadsv_names: In a perl compiled for threads, this returns a list of the special per-thread threadsv variables.
byteload_fh(FILEHANDLE): Load the contents of FILEHANDLE as bytecode. See documentation for the Bytecode module in B::Backend for how to generate bytecode.

AUTHOR

Malcolm Beattie, mbeattie@sable.ox.ac.uk