Debian Codegraph @

upstream/opensuse-tumbleweed/man3/B.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "B 3pm"
61 .TH B 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 B \- The Perl Compiler Backend
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use B;
72 .Ve
73 .SH DESCRIPTION
74 .IX Header "DESCRIPTION"
75 The \f(CW\*(C`B\*(C'\fR module supplies classes which allow a Perl program to delve
76 into its own innards. It is the module used to implement the
77 "backends" of the Perl compiler. Usage of the compiler does not
78 require knowledge of this module: see the O module for the
79 user\-visible part. The \f(CW\*(C`B\*(C'\fR module is of use to those who want to
80 write new compiler backends. This documentation assumes that the
81 reader knows a fair amount about perl\*(Aqs internals including such
82 things as SVs, OPs and the internal symbol table and syntax tree
83 of a program.
84 .SH OVERVIEW
85 .IX Header "OVERVIEW"
86 The \f(CW\*(C`B\*(C'\fR module contains a set of utility functions for querying the
87 current state of the Perl interpreter; typically these functions
88 return objects from the B::SV and B::OP classes, or their derived
89 classes. These classes in turn define methods for querying the
90 resulting objects about their own internal state.
91 .SH "Utility Functions"
92 .IX Header "Utility Functions"
93 The \f(CW\*(C`B\*(C'\fR module exports a variety of functions: some are simple
94 utility functions, others provide a Perl program with a way to
95 get an initial "handle" on an internal object.
96 .ie n .SS "Functions Returning ""B::SV"", ""B::AV"", ""B::HV"", and ""B::CV"" objects"
97 .el .SS "Functions Returning \f(CWB::SV\fP, \f(CWB::AV\fP, \f(CWB::HV\fP, and \f(CWB::CV\fP objects"
98 .IX Subsection "Functions Returning B::SV, B::AV, B::HV, and B::CV objects"
99 For descriptions of the class hierarchy of these objects and the
100 methods that can be called on them, see below, "OVERVIEW OF
101 CLASSES" and "SV\-RELATED CLASSES".
102 .IP sv_undef 4
103 .IX Item "sv_undef"
104 Returns the SV object corresponding to the C variable \f(CW\*(C`sv_undef\*(C'\fR.
105 .IP sv_yes 4
106 .IX Item "sv_yes"
107 Returns the SV object corresponding to the C variable \f(CW\*(C`sv_yes\*(C'\fR.
108 .IP sv_no 4
109 .IX Item "sv_no"
110 Returns the SV object corresponding to the C variable \f(CW\*(C`sv_no\*(C'\fR.
111 .IP svref_2object(SVREF) 4
112 .IX Item "svref_2object(SVREF)"
113 Takes a reference to any Perl value, and turns the referred\-to value
114 into an object in the appropriate B::OP\-derived or B::SV\-derived
115 class. Apart from functions such as \f(CW\*(C`main_root\*(C'\fR, this is the primary
116 way to get an initial "handle" on an internal perl data structure
117 which can then be followed with the other access methods.
118 .Sp
119 The returned object will only be valid as long as the underlying OPs
120 and SVs continue to exist. Do not attempt to use the object after the
121 underlying structures are freed.
122 .IP amagic_generation 4
123 .IX Item "amagic_generation"
124 Returns the SV object corresponding to the C variable \f(CW\*(C`amagic_generation\*(C'\fR.
125 As of Perl 5.18, this is just an alias to \f(CW\*(C`PL_na\*(C'\fR, so its value is
126 meaningless.
127 .IP init_av 4
128 .IX Item "init_av"
129 Returns the AV object (i.e. in class B::AV) representing INIT blocks.
130 .IP check_av 4
131 .IX Item "check_av"
132 Returns the AV object (i.e. in class B::AV) representing CHECK blocks.
133 .IP unitcheck_av 4
134 .IX Item "unitcheck_av"
135 Returns the AV object (i.e. in class B::AV) representing UNITCHECK blocks.
136 .IP begin_av 4
137 .IX Item "begin_av"
138 Returns the AV object (i.e. in class B::AV) representing BEGIN blocks.
139 .IP end_av 4
140 .IX Item "end_av"
141 Returns the AV object (i.e. in class B::AV) representing END blocks.
142 .IP comppadlist 4
143 .IX Item "comppadlist"
144 Returns the PADLIST object (i.e. in class B::PADLIST) of the global
145 comppadlist. In Perl 5.16 and earlier it returns an AV object (class
146 B::AV).
147 .IP regex_padav 4
148 .IX Item "regex_padav"
149 Only when perl was compiled with ithreads.
150 .IP main_cv 4
151 .IX Item "main_cv"
152 Return the (faked) CV corresponding to the main part of the Perl
153 program.
154 .SS "Functions for Examining the Symbol Table"
155 .IX Subsection "Functions for Examining the Symbol Table"
156 .IP "walksymtable(SYMREF, METHOD, RECURSE, PREFIX)" 4
157 .IX Item "walksymtable(SYMREF, METHOD, RECURSE, PREFIX)"
158 Walk the symbol table starting at SYMREF and call METHOD on each
159 symbol (a B::GV object) visited. When the walk reaches package
160 symbols (such as "Foo::") it invokes RECURSE, passing in the symbol
161 name, and only recurses into the package if that sub returns true.
162 .Sp
163 PREFIX is the name of the SYMREF you\*(Aqre walking.
164 .Sp
165 For example:
166 .Sp
167 .Vb 4
168 \& # Walk CGI\*(Aqs symbol table calling print_subs on each symbol.
169 \& # Recurse only into CGI::Util::
170 \& walksymtable(\e%CGI::, \*(Aqprint_subs\*(Aq,
171 \& sub { $_[0] eq \*(AqCGI::Util::\*(Aq }, \*(AqCGI::\*(Aq);
172 .Ve
173 .Sp
174 \&\fBprint_subs()\fR is a B::GV method you have declared. Also see "B::GV
175 Methods", below.
176 .ie n .SS "Functions Returning ""B::OP"" objects or for walking op trees"
177 .el .SS "Functions Returning \f(CWB::OP\fP objects or for walking op trees"
178 .IX Subsection "Functions Returning B::OP objects or for walking op trees"
179 For descriptions of the class hierarchy of these objects and the
180 methods that can be called on them, see below, "OVERVIEW OF
181 CLASSES" and "OP\-RELATED CLASSES".
182 .IP main_root 4
183 .IX Item "main_root"
184 Returns the root op (i.e. an object in the appropriate B::OP\-derived
185 class) of the main part of the Perl program.
186 .IP main_start 4
187 .IX Item "main_start"
188 Returns the starting op of the main part of the Perl program.
189 .IP "walkoptree(OP, METHOD)" 4
190 .IX Item "walkoptree(OP, METHOD)"
191 Does a tree\-walk of the syntax tree based at OP and calls METHOD on
192 each op it visits. Each node is visited before its children. If
193 \&\f(CW\*(C`walkoptree_debug\*(C'\fR (see below) has been called to turn debugging on then
194 the method \f(CW\*(C`walkoptree_debug\*(C'\fR is called on each op before METHOD is
195 called.
196 .IP walkoptree_debug(DEBUG) 4
197 .IX Item "walkoptree_debug(DEBUG)"
198 Returns the current debugging flag for \f(CW\*(C`walkoptree\*(C'\fR. If the optional
199 DEBUG argument is non\-zero, it sets the debugging flag to that. See
200 the description of \f(CW\*(C`walkoptree\*(C'\fR above for what the debugging flag
201 does.
202 .SS "Miscellaneous Utility Functions"
203 .IX Subsection "Miscellaneous Utility Functions"
204 .IP ppname(OPNUM) 4
205 .IX Item "ppname(OPNUM)"
206 Return the PP function name (e.g. "pp_add") of op number OPNUM.
207 .IP hash(STR) 4
208 .IX Item "hash(STR)"
209 Returns a string in the form "0x..." representing the value of the
210 internal hash function used by perl on string STR.
211 .IP cast_I32(I) 4
212 .IX Item "cast_I32(I)"
213 Casts I to the internal I32 type used by that perl.
214 .IP minus_c 4
215 .IX Item "minus_c"
216 Does the equivalent of the \f(CW\*(C`\-c\*(C'\fR command\-line option. Obviously, this
217 is only useful in a BEGIN block or else the flag is set too late.
218 .IP cstring(STR) 4
219 .IX Item "cstring(STR)"
220 Returns a double\-quote\-surrounded escaped version of STR which can
221 be used as a string in C source code.
222 .IP perlstring(STR) 4
223 .IX Item "perlstring(STR)"
224 Returns a double\-quote\-surrounded escaped version of STR which can
225 be used as a string in Perl source code.
226 .IP safename(STR) 4
227 .IX Item "safename(STR)"
228 This function returns the string with the first character modified if it
229 is a control character. It converts it to ^X format first, so that "\ecG"
230 becomes "^G". This is used internally by B::GV::SAFENAME, but
231 you can call it directly.
232 .IP class(OBJ) 4
233 .IX Item "class(OBJ)"
234 Returns the class of an object without the part of the classname
235 preceding the first \f(CW"::"\fR. This is used to turn \f(CW"B::UNOP"\fR into
236 \&\f(CW"UNOP"\fR for example.
237 .IP threadsv_names 4
238 .IX Item "threadsv_names"
239 This used to provide support for the old 5.005 threading module. It now
240 does nothing.
241 .SS "Exported utility variables"
242 .IX Subsection "Exported utility variables"
243 .ie n .IP @optype 4
244 .el .IP \f(CW@optype\fR 4
245 .IX Item "@optype"
246 .Vb 1
247 \& my $op_type = $optype[$op_type_num];
248 .Ve
249 .Sp
250 A simple mapping of the op type number to its type (like \*(AqCOP\*(Aq or \*(AqBINOP\*(Aq).
251 .ie n .IP @specialsv_name 4
252 .el .IP \f(CW@specialsv_name\fR 4
253 .IX Item "@specialsv_name"
254 .Vb 1
255 \& my $sv_name = $specialsv_name[$sv_index];
256 .Ve
257 .Sp
258 Certain SV types are considered \*(Aqspecial\*(Aq. They\*(Aqre represented by
259 B::SPECIAL and are referred to by a number from the specialsv_list.
260 This array maps that number back to the name of the SV (like \*(AqNullsv\*(Aq
261 or \*(Aq&PL_sv_undef\*(Aq).
262 .SH "OVERVIEW OF CLASSES"
263 .IX Header "OVERVIEW OF CLASSES"
264 The C structures used by Perl\*(Aqs internals to hold SV and OP
265 information (PVIV, AV, HV, ..., OP, SVOP, UNOP, ...) are modelled on a
266 class hierarchy and the \f(CW\*(C`B\*(C'\fR module gives access to them via a true
267 object hierarchy. Structure fields which point to other objects
268 (whether types of SV or types of OP) are represented by the \f(CW\*(C`B\*(C'\fR
269 module as Perl objects of the appropriate class.
270 .PP
271 The bulk of the \f(CW\*(C`B\*(C'\fR module is the methods for accessing fields of
272 these structures.
273 .PP
274 Note that all access is read\-only. You cannot modify the internals by
275 using this module. Also, note that the B::OP and B::SV objects created
276 by this module are only valid for as long as the underlying objects
277 exist; their creation doesn\*(Aqt increase the reference counts of the
278 underlying objects. Trying to access the fields of a freed object will
279 give incomprehensible results, or worse.
280 .SS "SV\-RELATED CLASSES"
281 .IX Subsection "SV-RELATED CLASSES"
282 B::IV, B::NV, B::PV, B::PVIV, B::PVNV, B::PVMG,
283 B::PVLV, B::AV, B::HV, B::CV, B::GV, B::FM, B::IO. These classes
284 correspond in the obvious way to the underlying C structures of similar names.
285 The inheritance hierarchy mimics the underlying C "inheritance":
286 .PP
287 .Vb 10
288 \& B::SV
289 \& |
290 \& +\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+
291 \& | | |
292 \& B::PV B::IV B::NV
293 \& / \e / /
294 \& / \e / /
295 \& B::INVLIST B::PVIV /
296 \& \e /
297 \& \e /
298 \& \e /
299 \& B::PVNV
300 \& |
301 \& |
302 \& B::PVMG
303 \& |
304 \& +\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-+\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+
305 \& | | | | | |
306 \& B::AV B::GV B::HV B::CV B::IO B::REGEXP
307 \& | |
308 \& | |
309 \& B::PVLV B::FM
310 .Ve
311 .PP
312 Access methods correspond to the underlying C macros for field access,
313 usually with the leading "class indication" prefix removed (Sv, Av,
314 Hv, ...). The leading prefix is only left in cases where its removal
315 would cause a clash in method name. For example, \f(CW\*(C`GvREFCNT\*(C'\fR stays
316 as\-is since its abbreviation would clash with the "superclass" method
317 \&\f(CW\*(C`REFCNT\*(C'\fR (corresponding to the C function \f(CW\*(C`SvREFCNT\*(C'\fR).
318 .SS "B::SV Methods"
319 .IX Subsection "B::SV Methods"
320 .IP REFCNT 4
321 .IX Item "REFCNT"
322 .PD 0
323 .IP FLAGS 4
324 .IX Item "FLAGS"
325 .IP IsBOOL 4
326 .IX Item "IsBOOL"
327 .PD
328 Returns true if the SV is a boolean (true or false).
329 You can then use \f(CW\*(C`TRUE\*(C'\fR to check if the value is true or false.
330 .Sp
331 .Vb 5
332 \& my $something = ( 1 == 1 ) # boolean true
333 \& || ( 1 == 0 ) # boolean false
334 \& || 42 # IV true
335 \& || 0; # IV false
336 \& my $sv = B::svref_2object(\e$something);
337 \&
338 \& say q[Not a boolean value]
339 \& if ! $sv\->IsBOOL;
340 \&
341 \& say q[This is a boolean with value: true]
342 \& if $sv\->IsBOOL && $sv\->TRUE_nomg;
343 \&
344 \& say q[This is a boolean with value: false]
345 \& if $sv\->IsBOOL && ! $sv\->TRUE_nomg;
346 .Ve
347 .IP object_2svref 4
348 .IX Item "object_2svref"
349 Returns a reference to the regular scalar corresponding to this
350 B::SV object. In other words, this method is the inverse operation
351 to the \fBsvref_2object()\fR subroutine. This scalar and other data it points
352 at should be considered read\-only: modifying them is neither safe nor
353 guaranteed to have a sensible effect.
354 .IP TRUE 4
355 .IX Item "TRUE"
356 Returns a boolean indicating hether Perl would evaluate the SV as true or
357 false.
358 .Sp
359 \&\fBWarning\fR this call performs \*(Aqget\*(Aq magic. If you only want to check the
360 nature of this SV use \f(CW\*(C`TRUE_nomg\*(C'\fR helper.
361 .Sp
362 This is an alias for \f(CWSvTRUE($sv)\fR.
363 .IP TRUE_nomg 4
364 .IX Item "TRUE_nomg"
365 Check if the value is true (do not perform \*(Aqget\*(Aq magic).
366 Returns a boolean indicating whether Perl would evaluate the SV as true or
367 false.
368 .Sp
369 This is an alias for \f(CWSvTRUE_nomg($sv)\fR.
370 .SS "B::IV Methods"
371 .IX Subsection "B::IV Methods"
372 .IP IV 4
373 .IX Item "IV"
374 Returns the value of the IV, \fIinterpreted as
375 a signed integer\fR. This will be misleading
376 if \f(CW\*(C`FLAGS & SVf_IVisUV\*(C'\fR. Perhaps you want the
377 \&\f(CW\*(C`int_value\*(C'\fR method instead?
378 .IP IVX 4
379 .IX Item "IVX"
380 .PD 0
381 .IP UVX 4
382 .IX Item "UVX"
383 .IP int_value 4
384 .IX Item "int_value"
385 .PD
386 This method returns the value of the IV as an integer.
387 It differs from \f(CW\*(C`IV\*(C'\fR in that it returns the correct
388 value regardless of whether it\*(Aqs stored signed or
389 unsigned.
390 .IP needs64bits 4
391 .IX Item "needs64bits"
392 .PD 0
393 .IP packiv 4
394 .IX Item "packiv"
395 .PD
396 .SS "B::NV Methods"
397 .IX Subsection "B::NV Methods"
398 .IP NV 4
399 .IX Item "NV"
400 .PD 0
401 .IP NVX 4
402 .IX Item "NVX"
403 .IP COP_SEQ_RANGE_LOW 4
404 .IX Item "COP_SEQ_RANGE_LOW"
405 .IP COP_SEQ_RANGE_HIGH 4
406 .IX Item "COP_SEQ_RANGE_HIGH"
407 .PD
408 These last two are only valid for pad name SVs. They only existed in the
409 B::NV class before Perl 5.22. In 5.22 they were moved to the B::PADNAME
410 class.
411 .SS "B::RV Methods"
412 .IX Subsection "B::RV Methods"
413 .IP RV 4
414 .IX Item "RV"
415 .SS "B::PV Methods"
416 .IX Subsection "B::PV Methods"
417 .IP PV 4
418 .IX Item "PV"
419 This method is the one you usually want. It constructs a
420 string using the length and offset information in the struct:
421 for ordinary scalars it will return the string that you\*(Aqd see
422 from Perl, even if it contains null characters.
423 .IP RV 4
424 .IX Item "RV"
425 Same as B::RV::RV, except that it will \fBdie()\fR if the PV isn\*(Aqt
426 a reference.
427 .IP PVX 4
428 .IX Item "PVX"
429 This method is less often useful. It assumes that the string
430 stored in the struct is null\-terminated, and disregards the
431 length information.
432 .Sp
433 It is the appropriate method to use if you need to get the name
434 of a lexical variable from a padname array. Lexical variable names
435 are always stored with a null terminator, and the length field
436 (CUR) is overloaded for other purposes and can\*(Aqt be relied on here.
437 .IP CUR 4
438 .IX Item "CUR"
439 This method returns the internal length field, which consists of the number
440 of internal bytes, not necessarily the number of logical characters.
441 .IP LEN 4
442 .IX Item "LEN"
443 This method returns the number of bytes allocated (via malloc) for storing
444 the string. This is 0 if the scalar does not "own" the string.
445 .SS "B::PVMG Methods"
446 .IX Subsection "B::PVMG Methods"
447 .IP MAGIC 4
448 .IX Item "MAGIC"
449 .PD 0
450 .IP SvSTASH 4
451 .IX Item "SvSTASH"
452 .PD
453 .SS "B::MAGIC Methods"
454 .IX Subsection "B::MAGIC Methods"
455 .IP MOREMAGIC 4
456 .IX Item "MOREMAGIC"
457 .PD 0
458 .IP precomp 4
459 .IX Item "precomp"
460 .PD
461 Only valid on r\-magic, returns the string that generated the regexp.
462 .IP PRIVATE 4
463 .IX Item "PRIVATE"
464 .PD 0
465 .IP TYPE 4
466 .IX Item "TYPE"
467 .IP FLAGS 4
468 .IX Item "FLAGS"
469 .IP OBJ 4
470 .IX Item "OBJ"
471 .PD
472 Will \fBdie()\fR if called on r\-magic.
473 .IP PTR 4
474 .IX Item "PTR"
475 .PD 0
476 .IP REGEX 4
477 .IX Item "REGEX"
478 .PD
479 Only valid on r\-magic, returns the integer value of the REGEX stored
480 in the MAGIC.
481 .SS "B::INVLIST Methods"
482 .IX Subsection "B::INVLIST Methods"
483 .IP prev_index 4
484 .IX Item "prev_index"
485 Returns the cache result of previous \fBinvlist_search()\fR (internal usage)
486 .IP is_offset 4
487 .IX Item "is_offset"
488 Returns a boolean value (0 or 1) to know if the invlist is using an offset.
489 When false the list begins with the code point U+0000.
490 When true the list begins with the following elements.
491 .IP array_len 4
492 .IX Item "array_len"
493 Returns an integer with the size of the array used to define the invlist.
494 .IP get_invlist_array 4
495 .IX Item "get_invlist_array"
496 This method returns a list of integers representing the array used by the
497 invlist.
498 Note: this cannot be used while in middle of iterating on an invlist and croaks.
499 .SS "B::PVLV Methods"
500 .IX Subsection "B::PVLV Methods"
501 .IP TARGOFF 4
502 .IX Item "TARGOFF"
503 .PD 0
504 .IP TARGLEN 4
505 .IX Item "TARGLEN"
506 .IP TYPE 4
507 .IX Item "TYPE"
508 .IP TARG 4
509 .IX Item "TARG"
510 .PD
511 .SS "B::BM Methods"
512 .IX Subsection "B::BM Methods"
513 .IP USEFUL 4
514 .IX Item "USEFUL"
515 .PD 0
516 .IP PREVIOUS 4
517 .IX Item "PREVIOUS"
518 .IP RARE 4
519 .IX Item "RARE"
520 .IP TABLE 4
521 .IX Item "TABLE"
522 .PD
523 .SS "B::REGEXP Methods"
524 .IX Subsection "B::REGEXP Methods"
525 .IP REGEX 4
526 .IX Item "REGEX"
527 .PD 0
528 .IP precomp 4
529 .IX Item "precomp"
530 .IP qr_anoncv 4
531 .IX Item "qr_anoncv"
532 .IP compflags 4
533 .IX Item "compflags"
534 .PD
535 The last two were added in Perl 5.22.
536 .SS "B::GV Methods"
537 .IX Subsection "B::GV Methods"
538 .IP is_empty 4
539 .IX Item "is_empty"
540 This method returns TRUE if the GP field of the GV is NULL.
541 .IP NAME 4
542 .IX Item "NAME"
543 .PD 0
544 .IP SAFENAME 4
545 .IX Item "SAFENAME"
546 .PD
547 This method returns the name of the glob, but if the first
548 character of the name is a control character, then it converts
549 it to ^X first, so that *^G would return "^G" rather than "\ecG".
550 .Sp
551 It\*(Aqs useful if you want to print out the name of a variable.
552 If you restrict yourself to globs which exist at compile\-time
553 then the result ought to be unambiguous, because code like
554 \&\f(CW\*(C`${"^G"} = 1\*(C'\fR is compiled as two ops \- a constant string and
555 a dereference (rv2gv) \- so that the glob is created at runtime.
556 .Sp
557 If you\*(Aqre working with globs at runtime, and need to disambiguate
558 *^G from *{"^G"}, then you should use the raw NAME method.
559 .IP STASH 4
560 .IX Item "STASH"
561 .PD 0
562 .IP SV 4
563 .IX Item "SV"
564 .IP IO 4
565 .IX Item "IO"
566 .IP FORM 4
567 .IX Item "FORM"
568 .IP AV 4
569 .IX Item "AV"
570 .IP HV 4
571 .IX Item "HV"
572 .IP EGV 4
573 .IX Item "EGV"
574 .IP CV 4
575 .IX Item "CV"
576 .IP CVGEN 4
577 .IX Item "CVGEN"
578 .IP LINE 4
579 .IX Item "LINE"
580 .IP FILE 4
581 .IX Item "FILE"
582 .IP FILEGV 4
583 .IX Item "FILEGV"
584 .IP GvREFCNT 4
585 .IX Item "GvREFCNT"
586 .IP FLAGS 4
587 .IX Item "FLAGS"
588 .IP GPFLAGS 4
589 .IX Item "GPFLAGS"
590 .PD
591 This last one is present only in perl 5.22.0 and higher.
592 .SS "B::IO Methods"
593 .IX Subsection "B::IO Methods"
594 B::IO objects derive from IO objects and you will get more information from
595 the IO object itself.
596 .PP
597 For example:
598 .PP
599 .Vb 3
600 \& $gvio = B::svref_2object(\e*main::stdin)\->IO;
601 \& $IO = $gvio\->object_2svref();
602 \& $fd = $IO\->fileno();
603 .Ve
604 .IP LINES 4
605 .IX Item "LINES"
606 .PD 0
607 .IP PAGE 4
608 .IX Item "PAGE"
609 .IP PAGE_LEN 4
610 .IX Item "PAGE_LEN"
611 .IP LINES_LEFT 4
612 .IX Item "LINES_LEFT"
613 .IP TOP_NAME 4
614 .IX Item "TOP_NAME"
615 .IP TOP_GV 4
616 .IX Item "TOP_GV"
617 .IP FMT_NAME 4
618 .IX Item "FMT_NAME"
619 .IP FMT_GV 4
620 .IX Item "FMT_GV"
621 .IP BOTTOM_NAME 4
622 .IX Item "BOTTOM_NAME"
623 .IP BOTTOM_GV 4
624 .IX Item "BOTTOM_GV"
625 .IP SUBPROCESS 4
626 .IX Item "SUBPROCESS"
627 .IP IoTYPE 4
628 .IX Item "IoTYPE"
629 .PD
630 A character symbolizing the type of IO Handle.
631 .Sp
632 .Vb 12
633 \& \- STDIN/OUT
634 \& I STDIN/OUT/ERR
635 \& < read\-only
636 \& > write\-only
637 \& a append
638 \& + read and write
639 \& s socket
640 \& | pipe
641 \& I IMPLICIT
642 \& # NUMERIC
643 \& space closed handle
644 \& \e0 closed internal handle
645 .Ve
646 .IP IoFLAGS 4
647 .IX Item "IoFLAGS"
648 .PD 0
649 .IP IsSTD 4
650 .IX Item "IsSTD"
651 .PD
652 Takes one argument ( \*(Aqstdin\*(Aq | \*(Aqstdout\*(Aq | \*(Aqstderr\*(Aq ) and returns true
653 if the IoIFP of the object is equal to the handle whose name was
654 passed as argument; i.e., \f(CW$io\fR\->IsSTD(\*(Aqstderr\*(Aq) is true if
655 IoIFP($io) == \fBPerlIO_stderr()\fR.
656 .SS "B::AV Methods"
657 .IX Subsection "B::AV Methods"
658 .IP FILL 4
659 .IX Item "FILL"
660 .PD 0
661 .IP MAX 4
662 .IX Item "MAX"
663 .IP ARRAY 4
664 .IX Item "ARRAY"
665 .IP ARRAYelt 4
666 .IX Item "ARRAYelt"
667 .PD
668 Like \f(CW\*(C`ARRAY\*(C'\fR, but takes an index as an argument to get only one element,
669 rather than a list of all of them.
670 .SS "B::CV Methods"
671 .IX Subsection "B::CV Methods"
672 .IP STASH 4
673 .IX Item "STASH"
674 .PD 0
675 .IP START 4
676 .IX Item "START"
677 .IP ROOT 4
678 .IX Item "ROOT"
679 .IP GV 4
680 .IX Item "GV"
681 .IP FILE 4
682 .IX Item "FILE"
683 .IP DEPTH 4
684 .IX Item "DEPTH"
685 .IP PADLIST 4
686 .IX Item "PADLIST"
687 .PD
688 Returns a B::PADLIST object.
689 .IP OUTSIDE 4
690 .IX Item "OUTSIDE"
691 .PD 0
692 .IP OUTSIDE_SEQ 4
693 .IX Item "OUTSIDE_SEQ"
694 .IP XSUB 4
695 .IX Item "XSUB"
696 .IP XSUBANY 4
697 .IX Item "XSUBANY"
698 .PD
699 For constant subroutines, returns the constant SV returned by the subroutine.
700 .IP CvFLAGS 4
701 .IX Item "CvFLAGS"
702 .PD 0
703 .IP const_sv 4
704 .IX Item "const_sv"
705 .IP NAME_HEK 4
706 .IX Item "NAME_HEK"
707 .PD
708 Returns the name of a lexical sub, otherwise \f(CW\*(C`undef\*(C'\fR.
709 .SS "B::HV Methods"
710 .IX Subsection "B::HV Methods"
711 .IP FILL 4
712 .IX Item "FILL"
713 .PD 0
714 .IP MAX 4
715 .IX Item "MAX"
716 .IP KEYS 4
717 .IX Item "KEYS"
718 .IP RITER 4
719 .IX Item "RITER"
720 .IP NAME 4
721 .IX Item "NAME"
722 .IP ARRAY 4
723 .IX Item "ARRAY"
724 .PD
725 .SS "OP\-RELATED CLASSES"
726 .IX Subsection "OP-RELATED CLASSES"
727 \&\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,
728 \&\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,
729 \&\f(CW\*(C`B::COP\*(C'\fR, \f(CW\*(C`B::METHOP\*(C'\fR.
730 .PP
731 These classes correspond in the obvious way to the underlying C
732 structures of similar names. The inheritance hierarchy mimics the
733 underlying C "inheritance":
734 .PP
735 .Vb 10
736 \& B::OP
737 \& |
738 \& +\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+
739 \& | | | | | |
740 \& B::UNOP B::SVOP B::PADOP B::COP B::PVOP B::METHOP
741 \& |
742 \& +\-\-\-+\-\-\-+\-\-\-\-\-\-\-\-\-+
743 \& | | |
744 \& B::BINOP B::LOGOP B::UNOP_AUX
745 \& |
746 \& |
747 \& B::LISTOP
748 \& |
749 \& +\-\-\-+\-\-\-+
750 \& | |
751 \& B::LOOP B::PMOP
752 .Ve
753 .PP
754 Access methods correspond to the underlying C structure field names,
755 with the leading "class indication" prefix (\f(CW"op_"\fR) removed.
756 .SS "B::OP Methods"
757 .IX Subsection "B::OP Methods"
758 These methods get the values of similarly named fields within the OP
759 data structure. See top of \f(CW\*(C`op.h\*(C'\fR for more info.
760 .IP next 4
761 .IX Item "next"
762 .PD 0
763 .IP sibling 4
764 .IX Item "sibling"
765 .IP parent 4
766 .IX Item "parent"
767 .PD
768 Returns the OP\*(Aqs parent. If it has no parent, or if your perl wasn\*(Aqt built
769 with \f(CW\*(C`\-DPERL_OP_PARENT\*(C'\fR, returns NULL.
770 .Sp
771 Note that the global variable \f(CW$B::OP::does_parent\fR is undefined on older
772 perls that don\*(Aqt support the \f(CW\*(C`parent\*(C'\fR method, is defined but false on
773 perls that support the method but were built without \f(CW\*(C`\-DPERL_OP_PARENT\*(C'\fR,
774 and is true otherwise.
775 .IP name 4
776 .IX Item "name"
777 This returns the op name as a string (e.g. "add", "rv2av").
778 .IP ppaddr 4
779 .IX Item "ppaddr"
780 This returns the function name as a string (e.g. "PL_ppaddr[OP_ADD]",
781 "PL_ppaddr[OP_RV2AV]").
782 .IP desc 4
783 .IX Item "desc"
784 This returns the op description from the global C PL_op_desc array
785 (e.g. "addition" "array deref").
786 .IP targ 4
787 .IX Item "targ"
788 .PD 0
789 .IP type 4
790 .IX Item "type"
791 .IP opt 4
792 .IX Item "opt"
793 .IP flags 4
794 .IX Item "flags"
795 .IP private 4
796 .IX Item "private"
797 .IP spare 4
798 .IX Item "spare"
799 .PD
800 .SS "B::UNOP Method"
801 .IX Subsection "B::UNOP Method"
802 .IP first 4
803 .IX Item "first"
804 .SS "B::UNOP_AUX Methods (since 5.22)"
805 .IX Subsection "B::UNOP_AUX Methods (since 5.22)"
806 .IP aux_list(cv) 4
807 .IX Item "aux_list(cv)"
808 This returns a list of the elements of the op\*(Aqs aux data structure,
809 or a null list if there is no aux. What will be returned depends on the
810 object\*(Aqs type, but will typically be a collection of \f(CW\*(C`B::IV\*(C'\fR, \f(CW\*(C`B::GV\*(C'\fR,
811 etc. objects. \f(CW\*(C`cv\*(C'\fR is the \f(CW\*(C`B::CV\*(C'\fR object representing the sub that the
812 op is contained within.
813 .IP string(cv) 4
814 .IX Item "string(cv)"
815 This returns a textual representation of the object (likely to b useful
816 for deparsing and debugging), or an empty string if the op type doesn\*(Aqt
817 support this. \f(CW\*(C`cv\*(C'\fR is the \f(CW\*(C`B::CV\*(C'\fR object representing the sub that the
818 op is contained within.
819 .SS "B::BINOP Method"
820 .IX Subsection "B::BINOP Method"
821 .IP last 4
822 .IX Item "last"
823 .SS "B::LOGOP Method"
824 .IX Subsection "B::LOGOP Method"
825 .IP other 4
826 .IX Item "other"
827 .SS "B::LISTOP Method"
828 .IX Subsection "B::LISTOP Method"
829 .IP children 4
830 .IX Item "children"
831 .SS "B::PMOP Methods"
832 .IX Subsection "B::PMOP Methods"
833 .IP pmreplroot 4
834 .IX Item "pmreplroot"
835 .PD 0
836 .IP pmreplstart 4
837 .IX Item "pmreplstart"
838 .IP pmflags 4
839 .IX Item "pmflags"
840 .IP precomp 4
841 .IX Item "precomp"
842 .IP pmoffset 4
843 .IX Item "pmoffset"
844 .PD
845 Only when perl was compiled with ithreads.
846 .IP code_list 4
847 .IX Item "code_list"
848 Since perl 5.17.1
849 .IP pmregexp 4
850 .IX Item "pmregexp"
851 Added in perl 5.22, this method returns the B::REGEXP associated with the
852 op. While PMOPs do not actually have \f(CW\*(C`pmregexp\*(C'\fR fields under threaded
853 builds, this method returns the regexp under threads nonetheless, for
854 convenience.
855 .SS "B::SVOP Methods"
856 .IX Subsection "B::SVOP Methods"
857 .IP sv 4
858 .IX Item "sv"
859 .PD 0
860 .IP gv 4
861 .IX Item "gv"
862 .PD
863 .SS "B::PADOP Method"
864 .IX Subsection "B::PADOP Method"
865 .IP padix 4
866 .IX Item "padix"
867 .SS "B::PVOP Method"
868 .IX Subsection "B::PVOP Method"
869 .IP pv 4
870 .IX Item "pv"
871 .SS "B::LOOP Methods"
872 .IX Subsection "B::LOOP Methods"
873 .IP redoop 4
874 .IX Item "redoop"
875 .PD 0
876 .IP nextop 4
877 .IX Item "nextop"
878 .IP lastop 4
879 .IX Item "lastop"
880 .PD
881 .SS "B::COP Methods"
882 .IX Subsection "B::COP Methods"
883 The \f(CW\*(C`B::COP\*(C'\fR class is used for "nextstate" and "dbstate" ops. As of Perl
884 5.22, it is also used for "null" ops that started out as COPs.
885 .IP label 4
886 .IX Item "label"
887 .PD 0
888 .IP stash 4
889 .IX Item "stash"
890 .IP stashpv 4
891 .IX Item "stashpv"
892 .IP "stashoff (threaded only)" 4
893 .IX Item "stashoff (threaded only)"
894 .IP file 4
895 .IX Item "file"
896 .IP cop_seq 4
897 .IX Item "cop_seq"
898 .IP line 4
899 .IX Item "line"
900 .IP warnings 4
901 .IX Item "warnings"
902 .IP io 4
903 .IX Item "io"
904 .IP hints 4
905 .IX Item "hints"
906 .IP hints_hash 4
907 .IX Item "hints_hash"
908 .PD
909 .SS "B::METHOP Methods (Since Perl 5.22)"
910 .IX Subsection "B::METHOP Methods (Since Perl 5.22)"
911 .IP first 4
912 .IX Item "first"
913 .PD 0
914 .IP meth_sv 4
915 .IX Item "meth_sv"
916 .PD
917 .SS "PAD\-RELATED CLASSES"
918 .IX Subsection "PAD-RELATED CLASSES"
919 Perl 5.18 introduced a new class, B::PADLIST, returned by B::CV\*(Aqs
920 \&\f(CW\*(C`PADLIST\*(C'\fR method.
921 .PP
922 Perl 5.22 introduced the B::PADNAMELIST and B::PADNAME classes.
923 .SS "B::PADLIST Methods"
924 .IX Subsection "B::PADLIST Methods"
925 .IP MAX 4
926 .IX Item "MAX"
927 .PD 0
928 .IP ARRAY 4
929 .IX Item "ARRAY"
930 .PD
931 A list of pads. The first one is a B::PADNAMELIST containing the names.
932 The rest are currently B::AV objects, but that could
933 change in future versions.
934 .IP ARRAYelt 4
935 .IX Item "ARRAYelt"
936 Like \f(CW\*(C`ARRAY\*(C'\fR, but takes an index as an argument to get only one element,
937 rather than a list of all of them.
938 .IP NAMES 4
939 .IX Item "NAMES"
940 This method, introduced in 5.22, returns the B::PADNAMELIST. It is
941 equivalent to \f(CW\*(C`ARRAYelt\*(C'\fR with a 0 argument.
942 .IP REFCNT 4
943 .IX Item "REFCNT"
944 .PD 0
945 .IP id 4
946 .IX Item "id"
947 .PD
948 This method, introduced in 5.22, returns an ID shared by clones of the same
949 padlist.
950 .IP outid 4
951 .IX Item "outid"
952 This method, also added in 5.22, returns the ID of the outer padlist.
953 .SS "B::PADNAMELIST Methods"
954 .IX Subsection "B::PADNAMELIST Methods"
955 .IP MAX 4
956 .IX Item "MAX"
957 .PD 0
958 .IP ARRAY 4
959 .IX Item "ARRAY"
960 .IP ARRAYelt 4
961 .IX Item "ARRAYelt"
962 .PD
963 These two methods return the pad names, using B::SPECIAL objects for null
964 pointers and B::PADNAME objects otherwise.
965 .IP REFCNT 4
966 .IX Item "REFCNT"
967 .SS "B::PADNAME Methods"
968 .IX Subsection "B::PADNAME Methods"
969 .IP PV 4
970 .IX Item "PV"
971 .PD 0
972 .IP PVX 4
973 .IX Item "PVX"
974 .IP LEN 4
975 .IX Item "LEN"
976 .IP REFCNT 4
977 .IX Item "REFCNT"
978 .IP GEN 4
979 .IX Item "GEN"
980 .IP FLAGS 4
981 .IX Item "FLAGS"
982 .PD
983 For backward\-compatibility, if the PADNAMEt_OUTER flag is set, the FLAGS
984 method adds the SVf_FAKE flag, too.
985 .IP TYPE 4
986 .IX Item "TYPE"
987 A B::HV object representing the stash for a typed lexical.
988 .IP SvSTASH 4
989 .IX Item "SvSTASH"
990 A backward\-compatibility alias for TYPE.
991 .IP OURSTASH 4
992 .IX Item "OURSTASH"
993 A B::HV object representing the stash for \*(Aqour\*(Aq variables.
994 .IP PROTOCV 4
995 .IX Item "PROTOCV"
996 The prototype CV for a \*(Aqmy\*(Aq sub.
997 .IP COP_SEQ_RANGE_LOW 4
998 .IX Item "COP_SEQ_RANGE_LOW"
999 .PD 0
1000 .IP COP_SEQ_RANGE_HIGH 4
1001 .IX Item "COP_SEQ_RANGE_HIGH"
1002 .PD
1003 Sequence numbers representing the scope within which a lexical is visible.
1004 Meaningless if PADNAMEt_OUTER is set.
1005 .IP PARENT_PAD_INDEX 4
1006 .IX Item "PARENT_PAD_INDEX"
1007 Only meaningful if PADNAMEt_OUTER is set.
1008 .IP PARENT_FAKELEX_FLAGS 4
1009 .IX Item "PARENT_FAKELEX_FLAGS"
1010 Only meaningful if PADNAMEt_OUTER is set.
1011 .IP IsUndef 4
1012 .IX Item "IsUndef"
1013 Returns a boolean value to check if the padname is PL_padname_undef.
1014 .ie n .SS $B::overlay
1015 .el .SS \f(CW$B::overlay\fP
1016 .IX Subsection "$B::overlay"
1017 Although the optree is read\-only, there is an overlay facility that allows
1018 you to override what values the various B::*OP methods return for a
1019 particular op. \f(CW$B::overlay\fR should be set to reference a two\-deep hash:
1020 indexed by OP address, then method name. Whenever a an op method is
1021 called, the value in the hash is returned if it exists. This facility is
1022 used by B::Deparse to "undo" some optimisations. For example:
1023 .PP
1024 .Vb 11
1025 \& local $B::overlay = {};
1026 \& ...
1027 \& if ($op\->name eq "foo") {
1028 \& $B::overlay\->{$$op} = {
1029 \& name => \*(Aqbar\*(Aq,
1030 \& next => $op\->next\->next,
1031 \& };
1032 \& }
1033 \& ...
1034 \& $op\->name # returns "bar"
1035 \& $op\->next # returns the next op but one
1036 .Ve
1037 .SH AUTHOR
1038 .IX Header "AUTHOR"
1039 Malcolm Beattie, \f(CW\*(C`[email protected]\*(C'\fR