Debian Codegraph @

upstream/debian-unstable/man3/B.3perl

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