diff options
Diffstat (limited to 'upstream/archlinux/man3/B.3perl')
| -rw-r--r-- | upstream/archlinux/man3/B.3perl | 1044 |
1 files changed, 1044 insertions, 0 deletions
diff --git a/upstream/archlinux/man3/B.3perl b/upstream/archlinux/man3/B.3perl new file mode 100644 index 00000000..628613d8 --- /dev/null +++ b/upstream/archlinux/man3/B.3perl @@ -0,0 +1,1044 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "B 3perl" +.TH B 3perl 2024-02-11 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +B \- The Perl Compiler Backend +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& use B; +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \f(CW\*(C`B\*(C'\fR 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 \f(CW\*(C`B\*(C'\fR 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. +.SH OVERVIEW +.IX Header "OVERVIEW" +The \f(CW\*(C`B\*(C'\fR module contains a set of utility functions for querying the +current state of the Perl interpreter; typically these functions +return objects from the B::SV and B::OP classes, or their derived +classes. These classes in turn define methods for querying the +resulting objects about their own internal state. +.SH "Utility Functions" +.IX Header "Utility Functions" +The \f(CW\*(C`B\*(C'\fR 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. +.ie n .SS "Functions Returning ""B::SV"", ""B::AV"", ""B::HV"", and ""B::CV"" objects" +.el .SS "Functions Returning \f(CWB::SV\fP, \f(CWB::AV\fP, \f(CWB::HV\fP, and \f(CWB::CV\fP objects" +.IX Subsection "Functions Returning B::SV, B::AV, B::HV, and B::CV objects" +For descriptions of the class hierarchy of these objects and the +methods that can be called on them, see below, "OVERVIEW OF +CLASSES" and "SV-RELATED CLASSES". +.IP sv_undef 4 +.IX Item "sv_undef" +Returns the SV object corresponding to the C variable \f(CW\*(C`sv_undef\*(C'\fR. +.IP sv_yes 4 +.IX Item "sv_yes" +Returns the SV object corresponding to the C variable \f(CW\*(C`sv_yes\*(C'\fR. +.IP sv_no 4 +.IX Item "sv_no" +Returns the SV object corresponding to the C variable \f(CW\*(C`sv_no\*(C'\fR. +.IP svref_2object(SVREF) 4 +.IX Item "svref_2object(SVREF)" +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 \f(CW\*(C`main_root\*(C'\fR, 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. +.Sp +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. +.IP amagic_generation 4 +.IX Item "amagic_generation" +Returns the SV object corresponding to the C variable \f(CW\*(C`amagic_generation\*(C'\fR. +As of Perl 5.18, this is just an alias to \f(CW\*(C`PL_na\*(C'\fR, so its value is +meaningless. +.IP init_av 4 +.IX Item "init_av" +Returns the AV object (i.e. in class B::AV) representing INIT blocks. +.IP check_av 4 +.IX Item "check_av" +Returns the AV object (i.e. in class B::AV) representing CHECK blocks. +.IP unitcheck_av 4 +.IX Item "unitcheck_av" +Returns the AV object (i.e. in class B::AV) representing UNITCHECK blocks. +.IP begin_av 4 +.IX Item "begin_av" +Returns the AV object (i.e. in class B::AV) representing BEGIN blocks. +.IP end_av 4 +.IX Item "end_av" +Returns the AV object (i.e. in class B::AV) representing END blocks. +.IP comppadlist 4 +.IX Item "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). +.IP regex_padav 4 +.IX Item "regex_padav" +Only when perl was compiled with ithreads. +.IP main_cv 4 +.IX Item "main_cv" +Return the (faked) CV corresponding to the main part of the Perl +program. +.SS "Functions for Examining the Symbol Table" +.IX Subsection "Functions for Examining the Symbol Table" +.IP "walksymtable(SYMREF, METHOD, RECURSE, PREFIX)" 4 +.IX Item "walksymtable(SYMREF, METHOD, RECURSE, PREFIX)" +Walk the symbol table starting at SYMREF and call METHOD on each +symbol (a B::GV object) visited. When the walk reaches package +symbols (such as "Foo::") it invokes RECURSE, passing in the symbol +name, and only recurses into the package if that sub returns true. +.Sp +PREFIX is the name of the SYMREF you're walking. +.Sp +For example: +.Sp +.Vb 4 +\& # Walk CGI\*(Aqs symbol table calling print_subs on each symbol. +\& # Recurse only into CGI::Util:: +\& walksymtable(\e%CGI::, \*(Aqprint_subs\*(Aq, +\& sub { $_[0] eq \*(AqCGI::Util::\*(Aq }, \*(AqCGI::\*(Aq); +.Ve +.Sp +\&\fBprint_subs()\fR is a B::GV method you have declared. Also see "B::GV +Methods", below. +.ie n .SS "Functions Returning ""B::OP"" objects or for walking op trees" +.el .SS "Functions Returning \f(CWB::OP\fP objects or for walking op trees" +.IX Subsection "Functions Returning B::OP objects or for walking op trees" +For descriptions of the class hierarchy of these objects and the +methods that can be called on them, see below, "OVERVIEW OF +CLASSES" and "OP-RELATED CLASSES". +.IP main_root 4 +.IX Item "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. +.IP main_start 4 +.IX Item "main_start" +Returns the starting op of the main part of the Perl program. +.IP "walkoptree(OP, METHOD)" 4 +.IX 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 +\&\f(CW\*(C`walkoptree_debug\*(C'\fR (see below) has been called to turn debugging on then +the method \f(CW\*(C`walkoptree_debug\*(C'\fR is called on each op before METHOD is +called. +.IP walkoptree_debug(DEBUG) 4 +.IX Item "walkoptree_debug(DEBUG)" +Returns the current debugging flag for \f(CW\*(C`walkoptree\*(C'\fR. If the optional +DEBUG argument is non-zero, it sets the debugging flag to that. See +the description of \f(CW\*(C`walkoptree\*(C'\fR above for what the debugging flag +does. +.SS "Miscellaneous Utility Functions" +.IX Subsection "Miscellaneous Utility Functions" +.IP ppname(OPNUM) 4 +.IX Item "ppname(OPNUM)" +Return the PP function name (e.g. "pp_add") of op number OPNUM. +.IP hash(STR) 4 +.IX Item "hash(STR)" +Returns a string in the form "0x..." representing the value of the +internal hash function used by perl on string STR. +.IP cast_I32(I) 4 +.IX Item "cast_I32(I)" +Casts I to the internal I32 type used by that perl. +.IP minus_c 4 +.IX Item "minus_c" +Does the equivalent of the \f(CW\*(C`\-c\*(C'\fR command-line option. Obviously, this +is only useful in a BEGIN block or else the flag is set too late. +.IP cstring(STR) 4 +.IX Item "cstring(STR)" +Returns a double-quote-surrounded escaped version of STR which can +be used as a string in C source code. +.IP perlstring(STR) 4 +.IX Item "perlstring(STR)" +Returns a double-quote-surrounded escaped version of STR which can +be used as a string in Perl source code. +.IP safename(STR) 4 +.IX 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 "\ecG" +becomes "^G". This is used internally by B::GV::SAFENAME, but +you can call it directly. +.IP class(OBJ) 4 +.IX Item "class(OBJ)" +Returns the class of an object without the part of the classname +preceding the first \f(CW"::"\fR. This is used to turn \f(CW"B::UNOP"\fR into +\&\f(CW"UNOP"\fR for example. +.IP threadsv_names 4 +.IX Item "threadsv_names" +This used to provide support for the old 5.005 threading module. It now +does nothing. +.SS "Exported utility variables" +.IX Subsection "Exported utility variables" +.ie n .IP @optype 4 +.el .IP \f(CW@optype\fR 4 +.IX Item "@optype" +.Vb 1 +\& my $op_type = $optype[$op_type_num]; +.Ve +.Sp +A simple mapping of the op type number to its type (like 'COP' or 'BINOP'). +.ie n .IP @specialsv_name 4 +.el .IP \f(CW@specialsv_name\fR 4 +.IX Item "@specialsv_name" +.Vb 1 +\& my $sv_name = $specialsv_name[$sv_index]; +.Ve +.Sp +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'). +.SH "OVERVIEW OF CLASSES" +.IX Header "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 \f(CW\*(C`B\*(C'\fR 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 \f(CW\*(C`B\*(C'\fR +module as Perl objects of the appropriate class. +.PP +The bulk of the \f(CW\*(C`B\*(C'\fR module is the methods for accessing fields of +these structures. +.PP +Note that all access is read-only. You cannot modify the internals by +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. +.SS "SV-RELATED CLASSES" +.IX Subsection "SV-RELATED CLASSES" +B::IV, B::NV, B::PV, B::PVIV, B::PVNV, B::PVMG, +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": +.PP +.Vb 10 +\& B::SV +\& | +\& +\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+ +\& | | | +\& B::PV B::IV B::NV +\& / \e / / +\& / \e / / +\& B::INVLIST B::PVIV / +\& \e / +\& \e / +\& \e / +\& B::PVNV +\& | +\& | +\& B::PVMG +\& | +\& +\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-+\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+ +\& | | | | | | +\& B::AV B::GV B::HV B::CV B::IO B::REGEXP +\& | | +\& | | +\& B::PVLV B::FM +.Ve +.PP +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, \f(CW\*(C`GvREFCNT\*(C'\fR stays +as-is since its abbreviation would clash with the "superclass" method +\&\f(CW\*(C`REFCNT\*(C'\fR (corresponding to the C function \f(CW\*(C`SvREFCNT\*(C'\fR). +.SS "B::SV Methods" +.IX Subsection "B::SV Methods" +.IP REFCNT 4 +.IX Item "REFCNT" +.PD 0 +.IP FLAGS 4 +.IX Item "FLAGS" +.IP IsBOOL 4 +.IX Item "IsBOOL" +.PD +Returns true if the SV is a boolean (true or false). +You can then use \f(CW\*(C`TRUE\*(C'\fR to check if the value is true or false. +.Sp +.Vb 5 +\& my $something = ( 1 == 1 ) # boolean true +\& || ( 1 == 0 ) # boolean false +\& || 42 # IV true +\& || 0; # IV false +\& my $sv = B::svref_2object(\e$something); +\& +\& say q[Not a boolean value] +\& if ! $sv\->IsBOOL; +\& +\& say q[This is a boolean with value: true] +\& if $sv\->IsBOOL && $sv\->TRUE_nomg; +\& +\& say q[This is a boolean with value: false] +\& if $sv\->IsBOOL && ! $sv\->TRUE_nomg; +.Ve +.IP object_2svref 4 +.IX 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 \fBsvref_2object()\fR 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. +.IP TRUE 4 +.IX Item "TRUE" +Returns a boolean indicating hether Perl would evaluate the SV as true or +false. +.Sp +\&\fBWarning\fR this call performs 'get' magic. If you only want to check the +nature of this SV use \f(CW\*(C`TRUE_nomg\*(C'\fR helper. +.Sp +This is an alias for \f(CWSvTRUE($sv)\fR. +.IP TRUE_nomg 4 +.IX Item "TRUE_nomg" +Check if the value is true (do not perform 'get' magic). +Returns a boolean indicating whether Perl would evaluate the SV as true or +false. +.Sp +This is an alias for \f(CWSvTRUE_nomg($sv)\fR. +.SS "B::IV Methods" +.IX Subsection "B::IV Methods" +.IP IV 4 +.IX Item "IV" +Returns the value of the IV, \fIinterpreted as +a signed integer\fR. This will be misleading +if \f(CW\*(C`FLAGS & SVf_IVisUV\*(C'\fR. Perhaps you want the +\&\f(CW\*(C`int_value\*(C'\fR method instead? +.IP IVX 4 +.IX Item "IVX" +.PD 0 +.IP UVX 4 +.IX Item "UVX" +.IP int_value 4 +.IX Item "int_value" +.PD +This method returns the value of the IV as an integer. +It differs from \f(CW\*(C`IV\*(C'\fR in that it returns the correct +value regardless of whether it's stored signed or +unsigned. +.IP needs64bits 4 +.IX Item "needs64bits" +.PD 0 +.IP packiv 4 +.IX Item "packiv" +.PD +.SS "B::NV Methods" +.IX Subsection "B::NV Methods" +.IP NV 4 +.IX Item "NV" +.PD 0 +.IP NVX 4 +.IX Item "NVX" +.IP COP_SEQ_RANGE_LOW 4 +.IX Item "COP_SEQ_RANGE_LOW" +.IP COP_SEQ_RANGE_HIGH 4 +.IX Item "COP_SEQ_RANGE_HIGH" +.PD +These last two are only valid for pad name SVs. They only existed in the +B::NV class before Perl 5.22. In 5.22 they were moved to the B::PADNAME +class. +.SS "B::RV Methods" +.IX Subsection "B::RV Methods" +.IP RV 4 +.IX Item "RV" +.SS "B::PV Methods" +.IX Subsection "B::PV Methods" +.PD 0 +.IP PV 4 +.IX Item "PV" +.PD +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. +.IP RV 4 +.IX Item "RV" +Same as B::RV::RV, except that it will \fBdie()\fR if the PV isn't +a reference. +.IP PVX 4 +.IX Item "PVX" +This method is less often useful. It assumes that the string +stored in the struct is null-terminated, and disregards the +length information. +.Sp +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 +are always stored with a null terminator, and the length field +(CUR) is overloaded for other purposes and can't be relied on here. +.IP CUR 4 +.IX Item "CUR" +This method returns the internal length field, which consists of the number +of internal bytes, not necessarily the number of logical characters. +.IP LEN 4 +.IX 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. +.SS "B::PVMG Methods" +.IX Subsection "B::PVMG Methods" +.IP MAGIC 4 +.IX Item "MAGIC" +.PD 0 +.IP SvSTASH 4 +.IX Item "SvSTASH" +.PD +.SS "B::MAGIC Methods" +.IX Subsection "B::MAGIC Methods" +.IP MOREMAGIC 4 +.IX Item "MOREMAGIC" +.PD 0 +.IP precomp 4 +.IX Item "precomp" +.PD +Only valid on r\-magic, returns the string that generated the regexp. +.IP PRIVATE 4 +.IX Item "PRIVATE" +.PD 0 +.IP TYPE 4 +.IX Item "TYPE" +.IP FLAGS 4 +.IX Item "FLAGS" +.IP OBJ 4 +.IX Item "OBJ" +.PD +Will \fBdie()\fR if called on r\-magic. +.IP PTR 4 +.IX Item "PTR" +.PD 0 +.IP REGEX 4 +.IX Item "REGEX" +.PD +Only valid on r\-magic, returns the integer value of the REGEX stored +in the MAGIC. +.SS "B::INVLIST Methods" +.IX Subsection "B::INVLIST Methods" +.IP prev_index 4 +.IX Item "prev_index" +Returns the cache result of previous \fBinvlist_search()\fR (internal usage) +.IP is_offset 4 +.IX Item "is_offset" +Returns a boolean value (0 or 1) to know if the invlist is using an offset. +When false the list begins with the code point U+0000. +When true the list begins with the following elements. +.IP array_len 4 +.IX Item "array_len" +Returns an integer with the size of the array used to define the invlist. +.IP get_invlist_array 4 +.IX Item "get_invlist_array" +This method returns a list of integers representing the array used by the +invlist. +Note: this cannot be used while in middle of iterating on an invlist and croaks. +.SS "B::PVLV Methods" +.IX Subsection "B::PVLV Methods" +.IP TARGOFF 4 +.IX Item "TARGOFF" +.PD 0 +.IP TARGLEN 4 +.IX Item "TARGLEN" +.IP TYPE 4 +.IX Item "TYPE" +.IP TARG 4 +.IX Item "TARG" +.PD +.SS "B::BM Methods" +.IX Subsection "B::BM Methods" +.IP USEFUL 4 +.IX Item "USEFUL" +.PD 0 +.IP PREVIOUS 4 +.IX Item "PREVIOUS" +.IP RARE 4 +.IX Item "RARE" +.IP TABLE 4 +.IX Item "TABLE" +.PD +.SS "B::REGEXP Methods" +.IX Subsection "B::REGEXP Methods" +.IP REGEX 4 +.IX Item "REGEX" +.PD 0 +.IP precomp 4 +.IX Item "precomp" +.IP qr_anoncv 4 +.IX Item "qr_anoncv" +.IP compflags 4 +.IX Item "compflags" +.PD +The last two were added in Perl 5.22. +.SS "B::GV Methods" +.IX Subsection "B::GV Methods" +.IP is_empty 4 +.IX Item "is_empty" +This method returns TRUE if the GP field of the GV is NULL. +.IP NAME 4 +.IX Item "NAME" +.PD 0 +.IP SAFENAME 4 +.IX Item "SAFENAME" +.PD +This method returns the name of the glob, but if the first +character of the name is a control character, then it converts +it to ^X first, so that *^G would return "^G" rather than "\ecG". +.Sp +It's useful if you want to print out the name of a variable. +If you restrict yourself to globs which exist at compile-time +then the result ought to be unambiguous, because code like +\&\f(CW\*(C`${"^G"} = 1\*(C'\fR is compiled as two ops \- a constant string and +a dereference (rv2gv) \- so that the glob is created at runtime. +.Sp +If you're working with globs at runtime, and need to disambiguate +*^G from *{"^G"}, then you should use the raw NAME method. +.IP STASH 4 +.IX Item "STASH" +.PD 0 +.IP SV 4 +.IX Item "SV" +.IP IO 4 +.IX Item "IO" +.IP FORM 4 +.IX Item "FORM" +.IP AV 4 +.IX Item "AV" +.IP HV 4 +.IX Item "HV" +.IP EGV 4 +.IX Item "EGV" +.IP CV 4 +.IX Item "CV" +.IP CVGEN 4 +.IX Item "CVGEN" +.IP LINE 4 +.IX Item "LINE" +.IP FILE 4 +.IX Item "FILE" +.IP FILEGV 4 +.IX Item "FILEGV" +.IP GvREFCNT 4 +.IX Item "GvREFCNT" +.IP FLAGS 4 +.IX Item "FLAGS" +.IP GPFLAGS 4 +.IX Item "GPFLAGS" +.PD +This last one is present only in perl 5.22.0 and higher. +.SS "B::IO Methods" +.IX Subsection "B::IO Methods" +B::IO objects derive from IO objects and you will get more information from +the IO object itself. +.PP +For example: +.PP +.Vb 3 +\& $gvio = B::svref_2object(\e*main::stdin)\->IO; +\& $IO = $gvio\->object_2svref(); +\& $fd = $IO\->fileno(); +.Ve +.IP LINES 4 +.IX Item "LINES" +.PD 0 +.IP PAGE 4 +.IX Item "PAGE" +.IP PAGE_LEN 4 +.IX Item "PAGE_LEN" +.IP LINES_LEFT 4 +.IX Item "LINES_LEFT" +.IP TOP_NAME 4 +.IX Item "TOP_NAME" +.IP TOP_GV 4 +.IX Item "TOP_GV" +.IP FMT_NAME 4 +.IX Item "FMT_NAME" +.IP FMT_GV 4 +.IX Item "FMT_GV" +.IP BOTTOM_NAME 4 +.IX Item "BOTTOM_NAME" +.IP BOTTOM_GV 4 +.IX Item "BOTTOM_GV" +.IP SUBPROCESS 4 +.IX Item "SUBPROCESS" +.IP IoTYPE 4 +.IX Item "IoTYPE" +.PD +A character symbolizing the type of IO Handle. +.Sp +.Vb 12 +\& \- STDIN/OUT +\& I STDIN/OUT/ERR +\& < read\-only +\& > write\-only +\& a append +\& + read and write +\& s socket +\& | pipe +\& I IMPLICIT +\& # NUMERIC +\& space closed handle +\& \e0 closed internal handle +.Ve +.IP IoFLAGS 4 +.IX Item "IoFLAGS" +.PD 0 +.IP IsSTD 4 +.IX Item "IsSTD" +.PD +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., \f(CW$io\fR\->IsSTD('stderr') is true if +IoIFP($io) == \fBPerlIO_stderr()\fR. +.SS "B::AV Methods" +.IX Subsection "B::AV Methods" +.IP FILL 4 +.IX Item "FILL" +.PD 0 +.IP MAX 4 +.IX Item "MAX" +.IP ARRAY 4 +.IX Item "ARRAY" +.IP ARRAYelt 4 +.IX Item "ARRAYelt" +.PD +Like \f(CW\*(C`ARRAY\*(C'\fR, but takes an index as an argument to get only one element, +rather than a list of all of them. +.SS "B::CV Methods" +.IX Subsection "B::CV Methods" +.IP STASH 4 +.IX Item "STASH" +.PD 0 +.IP START 4 +.IX Item "START" +.IP ROOT 4 +.IX Item "ROOT" +.IP GV 4 +.IX Item "GV" +.IP FILE 4 +.IX Item "FILE" +.IP DEPTH 4 +.IX Item "DEPTH" +.IP PADLIST 4 +.IX Item "PADLIST" +.PD +Returns a B::PADLIST object. +.IP OUTSIDE 4 +.IX Item "OUTSIDE" +.PD 0 +.IP OUTSIDE_SEQ 4 +.IX Item "OUTSIDE_SEQ" +.IP XSUB 4 +.IX Item "XSUB" +.IP XSUBANY 4 +.IX Item "XSUBANY" +.PD +For constant subroutines, returns the constant SV returned by the subroutine. +.IP CvFLAGS 4 +.IX Item "CvFLAGS" +.PD 0 +.IP const_sv 4 +.IX Item "const_sv" +.IP NAME_HEK 4 +.IX Item "NAME_HEK" +.PD +Returns the name of a lexical sub, otherwise \f(CW\*(C`undef\*(C'\fR. +.SS "B::HV Methods" +.IX Subsection "B::HV Methods" +.IP FILL 4 +.IX Item "FILL" +.PD 0 +.IP MAX 4 +.IX Item "MAX" +.IP KEYS 4 +.IX Item "KEYS" +.IP RITER 4 +.IX Item "RITER" +.IP NAME 4 +.IX Item "NAME" +.IP ARRAY 4 +.IX Item "ARRAY" +.PD +.SS "OP-RELATED CLASSES" +.IX Subsection "OP-RELATED CLASSES" +\&\f(CW\*(C`B::OP\*(C'\fR, \f(CW\*(C`B::UNOP\*(C'\fR, \f(CW\*(C`B::UNOP_AUX\*(C'\fR, \f(CW\*(C`B::BINOP\*(C'\fR, \f(CW\*(C`B::LOGOP\*(C'\fR, +\&\f(CW\*(C`B::LISTOP\*(C'\fR, \f(CW\*(C`B::PMOP\*(C'\fR, \f(CW\*(C`B::SVOP\*(C'\fR, \f(CW\*(C`B::PADOP\*(C'\fR, \f(CW\*(C`B::PVOP\*(C'\fR, \f(CW\*(C`B::LOOP\*(C'\fR, +\&\f(CW\*(C`B::COP\*(C'\fR, \f(CW\*(C`B::METHOP\*(C'\fR. +.PP +These classes correspond in the obvious way to the underlying C +structures of similar names. The inheritance hierarchy mimics the +underlying C "inheritance": +.PP +.Vb 10 +\& B::OP +\& | +\& +\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+ +\& | | | | | | +\& B::UNOP B::SVOP B::PADOP B::COP B::PVOP B::METHOP +\& | +\& +\-\-\-+\-\-\-+\-\-\-\-\-\-\-\-\-+ +\& | | | +\& B::BINOP B::LOGOP B::UNOP_AUX +\& | +\& | +\& B::LISTOP +\& | +\& +\-\-\-+\-\-\-+ +\& | | +\& B::LOOP B::PMOP +.Ve +.PP +Access methods correspond to the underlying C structure field names, +with the leading "class indication" prefix (\f(CW"op_"\fR) removed. +.SS "B::OP Methods" +.IX Subsection "B::OP Methods" +These methods get the values of similarly named fields within the OP +data structure. See top of \f(CW\*(C`op.h\*(C'\fR for more info. +.IP next 4 +.IX Item "next" +.PD 0 +.IP sibling 4 +.IX Item "sibling" +.IP parent 4 +.IX Item "parent" +.PD +Returns the OP's parent. If it has no parent, or if your perl wasn't built +with \f(CW\*(C`\-DPERL_OP_PARENT\*(C'\fR, returns NULL. +.Sp +Note that the global variable \f(CW$B::OP::does_parent\fR is undefined on older +perls that don't support the \f(CW\*(C`parent\*(C'\fR method, is defined but false on +perls that support the method but were built without \f(CW\*(C`\-DPERL_OP_PARENT\*(C'\fR, +and is true otherwise. +.IP name 4 +.IX Item "name" +This returns the op name as a string (e.g. "add", "rv2av"). +.IP ppaddr 4 +.IX Item "ppaddr" +This returns the function name as a string (e.g. "PL_ppaddr[OP_ADD]", +"PL_ppaddr[OP_RV2AV]"). +.IP desc 4 +.IX Item "desc" +This returns the op description from the global C PL_op_desc array +(e.g. "addition" "array deref"). +.IP targ 4 +.IX Item "targ" +.PD 0 +.IP type 4 +.IX Item "type" +.IP opt 4 +.IX Item "opt" +.IP flags 4 +.IX Item "flags" +.IP private 4 +.IX Item "private" +.IP spare 4 +.IX Item "spare" +.PD +.SS "B::UNOP Method" +.IX Subsection "B::UNOP Method" +.IP first 4 +.IX Item "first" +.SS "B::UNOP_AUX Methods (since 5.22)" +.IX Subsection "B::UNOP_AUX Methods (since 5.22)" +.PD 0 +.IP aux_list(cv) 4 +.IX Item "aux_list(cv)" +.PD +This returns a list of the elements of the op's aux data structure, +or a null list if there is no aux. What will be returned depends on the +object's type, but will typically be a collection of \f(CW\*(C`B::IV\*(C'\fR, \f(CW\*(C`B::GV\*(C'\fR, +etc. objects. \f(CW\*(C`cv\*(C'\fR is the \f(CW\*(C`B::CV\*(C'\fR object representing the sub that the +op is contained within. +.IP string(cv) 4 +.IX Item "string(cv)" +This returns a textual representation of the object (likely to b useful +for deparsing and debugging), or an empty string if the op type doesn't +support this. \f(CW\*(C`cv\*(C'\fR is the \f(CW\*(C`B::CV\*(C'\fR object representing the sub that the +op is contained within. +.SS "B::BINOP Method" +.IX Subsection "B::BINOP Method" +.IP last 4 +.IX Item "last" +.SS "B::LOGOP Method" +.IX Subsection "B::LOGOP Method" +.PD 0 +.IP other 4 +.IX Item "other" +.PD +.SS "B::LISTOP Method" +.IX Subsection "B::LISTOP Method" +.IP children 4 +.IX Item "children" +.SS "B::PMOP Methods" +.IX Subsection "B::PMOP Methods" +.PD 0 +.IP pmreplroot 4 +.IX Item "pmreplroot" +.IP pmreplstart 4 +.IX Item "pmreplstart" +.IP pmflags 4 +.IX Item "pmflags" +.IP precomp 4 +.IX Item "precomp" +.IP pmoffset 4 +.IX Item "pmoffset" +.PD +Only when perl was compiled with ithreads. +.IP code_list 4 +.IX Item "code_list" +Since perl 5.17.1 +.IP pmregexp 4 +.IX Item "pmregexp" +Added in perl 5.22, this method returns the B::REGEXP associated with the +op. While PMOPs do not actually have \f(CW\*(C`pmregexp\*(C'\fR fields under threaded +builds, this method returns the regexp under threads nonetheless, for +convenience. +.SS "B::SVOP Methods" +.IX Subsection "B::SVOP Methods" +.IP sv 4 +.IX Item "sv" +.PD 0 +.IP gv 4 +.IX Item "gv" +.PD +.SS "B::PADOP Method" +.IX Subsection "B::PADOP Method" +.IP padix 4 +.IX Item "padix" +.SS "B::PVOP Method" +.IX Subsection "B::PVOP Method" +.PD 0 +.IP pv 4 +.IX Item "pv" +.PD +.SS "B::LOOP Methods" +.IX Subsection "B::LOOP Methods" +.IP redoop 4 +.IX Item "redoop" +.PD 0 +.IP nextop 4 +.IX Item "nextop" +.IP lastop 4 +.IX Item "lastop" +.PD +.SS "B::COP Methods" +.IX Subsection "B::COP Methods" +The \f(CW\*(C`B::COP\*(C'\fR class is used for "nextstate" and "dbstate" ops. As of Perl +5.22, it is also used for "null" ops that started out as COPs. +.IP label 4 +.IX Item "label" +.PD 0 +.IP stash 4 +.IX Item "stash" +.IP stashpv 4 +.IX Item "stashpv" +.IP "stashoff (threaded only)" 4 +.IX Item "stashoff (threaded only)" +.IP file 4 +.IX Item "file" +.IP cop_seq 4 +.IX Item "cop_seq" +.IP line 4 +.IX Item "line" +.IP warnings 4 +.IX Item "warnings" +.IP io 4 +.IX Item "io" +.IP hints 4 +.IX Item "hints" +.IP hints_hash 4 +.IX Item "hints_hash" +.PD +.SS "B::METHOP Methods (Since Perl 5.22)" +.IX Subsection "B::METHOP Methods (Since Perl 5.22)" +.IP first 4 +.IX Item "first" +.PD 0 +.IP meth_sv 4 +.IX Item "meth_sv" +.PD +.SS "PAD-RELATED CLASSES" +.IX Subsection "PAD-RELATED CLASSES" +Perl 5.18 introduced a new class, B::PADLIST, returned by B::CV's +\&\f(CW\*(C`PADLIST\*(C'\fR method. +.PP +Perl 5.22 introduced the B::PADNAMELIST and B::PADNAME classes. +.SS "B::PADLIST Methods" +.IX Subsection "B::PADLIST Methods" +.IP MAX 4 +.IX Item "MAX" +.PD 0 +.IP ARRAY 4 +.IX Item "ARRAY" +.PD +A list of pads. The first one is a B::PADNAMELIST containing the names. +The rest are currently B::AV objects, but that could +change in future versions. +.IP ARRAYelt 4 +.IX Item "ARRAYelt" +Like \f(CW\*(C`ARRAY\*(C'\fR, but takes an index as an argument to get only one element, +rather than a list of all of them. +.IP NAMES 4 +.IX Item "NAMES" +This method, introduced in 5.22, returns the B::PADNAMELIST. It is +equivalent to \f(CW\*(C`ARRAYelt\*(C'\fR with a 0 argument. +.IP REFCNT 4 +.IX Item "REFCNT" +.PD 0 +.IP id 4 +.IX Item "id" +.PD +This method, introduced in 5.22, returns an ID shared by clones of the same +padlist. +.IP outid 4 +.IX Item "outid" +This method, also added in 5.22, returns the ID of the outer padlist. +.SS "B::PADNAMELIST Methods" +.IX Subsection "B::PADNAMELIST Methods" +.IP MAX 4 +.IX Item "MAX" +.PD 0 +.IP ARRAY 4 +.IX Item "ARRAY" +.IP ARRAYelt 4 +.IX Item "ARRAYelt" +.PD +These two methods return the pad names, using B::SPECIAL objects for null +pointers and B::PADNAME objects otherwise. +.IP REFCNT 4 +.IX Item "REFCNT" +.SS "B::PADNAME Methods" +.IX Subsection "B::PADNAME Methods" +.PD 0 +.IP PV 4 +.IX Item "PV" +.IP PVX 4 +.IX Item "PVX" +.IP LEN 4 +.IX Item "LEN" +.IP REFCNT 4 +.IX Item "REFCNT" +.IP GEN 4 +.IX Item "GEN" +.IP FLAGS 4 +.IX Item "FLAGS" +.PD +For backward-compatibility, if the PADNAMEt_OUTER flag is set, the FLAGS +method adds the SVf_FAKE flag, too. +.IP TYPE 4 +.IX Item "TYPE" +A B::HV object representing the stash for a typed lexical. +.IP SvSTASH 4 +.IX Item "SvSTASH" +A backward-compatibility alias for TYPE. +.IP OURSTASH 4 +.IX Item "OURSTASH" +A B::HV object representing the stash for 'our' variables. +.IP PROTOCV 4 +.IX Item "PROTOCV" +The prototype CV for a 'my' sub. +.IP COP_SEQ_RANGE_LOW 4 +.IX Item "COP_SEQ_RANGE_LOW" +.PD 0 +.IP COP_SEQ_RANGE_HIGH 4 +.IX Item "COP_SEQ_RANGE_HIGH" +.PD +Sequence numbers representing the scope within which a lexical is visible. +Meaningless if PADNAMEt_OUTER is set. +.IP PARENT_PAD_INDEX 4 +.IX Item "PARENT_PAD_INDEX" +Only meaningful if PADNAMEt_OUTER is set. +.IP PARENT_FAKELEX_FLAGS 4 +.IX Item "PARENT_FAKELEX_FLAGS" +Only meaningful if PADNAMEt_OUTER is set. +.IP IsUndef 4 +.IX Item "IsUndef" +Returns a boolean value to check if the padname is PL_padname_undef. +.ie n .SS $B::overlay +.el .SS \f(CW$B::overlay\fP +.IX Subsection "$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. \f(CW$B::overlay\fR 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: +.PP +.Vb 11 +\& local $B::overlay = {}; +\& ... +\& if ($op\->name eq "foo") { +\& $B::overlay\->{$$op} = { +\& name => \*(Aqbar\*(Aq, +\& next => $op\->next\->next, +\& }; +\& } +\& ... +\& $op\->name # returns "bar" +\& $op\->next # returns the next op but one +.Ve +.SH AUTHOR +.IX Header "AUTHOR" +Malcolm Beattie, \f(CW\*(C`mbeattie@sable.ox.ac.uk\*(C'\fR |