Debian Codegraph @

upstream/opensuse-tumbleweed/man3/B::Deparse.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::Deparse 3pm"
61 .TH B::Deparse 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::Deparse \- Perl compiler backend to produce perl code
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 \&\fBperl\fR \fB\-MO=Deparse\fR[\fB,\-d\fR][\fB,\-f\fR\fIFILE\fR][\fB,\-p\fR][\fB,\-q\fR][\fB,\-l\fR]
71 [\fB,\-s\fR\fILETTERS\fR][\fB,\-x\fR\fILEVEL\fR] \fIprog.pl\fR
72 .SH DESCRIPTION
73 .IX Header "DESCRIPTION"
74 B::Deparse is a backend module for the Perl compiler that generates
75 perl source code, based on the internal compiled structure that perl
76 itself creates after parsing a program. The output of B::Deparse won\*(Aqt
77 be exactly the same as the original source, since perl doesn\*(Aqt keep
78 track of comments or whitespace, and there isn\*(Aqt a one\-to\-one
79 correspondence between perl\*(Aqs syntactical constructions and their
80 compiled form, but it will often be close. When you use the \fB\-p\fR
81 option, the output also includes parentheses even when they are not
82 required by precedence, which can make it easy to see if perl is
83 parsing your expressions the way you intended.
84 .PP
85 While B::Deparse goes to some lengths to try to figure out what your
86 original program was doing, some parts of the language can still trip
87 it up; it still fails even on some parts of Perl\*(Aqs own test suite. If
88 you encounter a failure other than the most common ones described in
89 the BUGS section below, you can help contribute to B::Deparse\*(Aqs
90 ongoing development by submitting a bug report with a small
91 example.
92 .SH OPTIONS
93 .IX Header "OPTIONS"
94 As with all compiler backend options, these must follow directly after
95 the \*(Aq\-MO=Deparse\*(Aq, separated by a comma but not any white space.
96 .IP \fB\-d\fR 4
97 .IX Item "-d"
98 Output data values (when they appear as constants) using Data::Dumper.
99 Without this option, B::Deparse will use some simple routines of its
100 own for the same purpose. Currently, Data::Dumper is better for some
101 kinds of data (such as complex structures with sharing and
102 self\-reference) while the built\-in routines are better for others
103 (such as odd floating\-point values).
104 .IP \fB\-f\fR\fIFILE\fR 4
105 .IX Item "-fFILE"
106 Normally, B::Deparse deparses the main code of a program, and all the subs
107 defined in the same file. To include subs defined in
108 other files, pass the \fB\-f\fR option with the filename.
109 You can pass the \fB\-f\fR option several times, to
110 include more than one secondary file. (Most of the time you don\*(Aqt want to
111 use it at all.) You can also use this option to include subs which are
112 defined in the scope of a \fB#line\fR directive with two parameters.
113 .IP \fB\-l\fR 4
114 .IX Item "-l"
115 Add \*(Aq#line\*(Aq declarations to the output based on the line and file
116 locations of the original code.
117 .IP \fB\-p\fR 4
118 .IX Item "-p"
119 Print extra parentheses. Without this option, B::Deparse includes
120 parentheses in its output only when they are needed, based on the
121 structure of your program. With \fB\-p\fR, it uses parentheses (almost)
122 whenever they would be legal. This can be useful if you are used to
123 LISP, or if you want to see how perl parses your input. If you say
124 .Sp
125 .Vb 3
126 \& if ($var & 0x7f == 65) {print "Gimme an A!"}
127 \& print ($which ? $a : $b), "\en";
128 \& $name = $ENV{USER} or "Bob";
129 .Ve
130 .Sp
131 \&\f(CW\*(C`B::Deparse,\-p\*(C'\fR will print
132 .Sp
133 .Vb 5
134 \& if (($var & 0)) {
135 \& print(\*(AqGimme an A!\*(Aq)
136 \& };
137 \& (print(($which ? $a : $b)), \*(Aq???\*(Aq);
138 \& (($name = $ENV{\*(AqUSER\*(Aq}) or \*(Aq???\*(Aq)
139 .Ve
140 .Sp
141 which probably isn\*(Aqt what you intended (the \f(CW\*(Aq???\*(Aq\fR is a sign that
142 perl optimized away a constant value).
143 .IP \fB\-P\fR 4
144 .IX Item "-P"
145 Disable prototype checking. With this option, all function calls are
146 deparsed as if no prototype was defined for them. In other words,
147 .Sp
148 .Vb 1
149 \& perl \-MO=Deparse,\-P \-e \*(Aqsub foo (\e@) { 1 } foo @x\*(Aq
150 .Ve
151 .Sp
152 will print
153 .Sp
154 .Vb 4
155 \& sub foo (\e@) {
156 \& 1;
157 \& }
158 \& &foo(\e@x);
159 .Ve
160 .Sp
161 making clear how the parameters are actually passed to \f(CW\*(C`foo\*(C'\fR.
162 .IP \fB\-q\fR 4
163 .IX Item "-q"
164 Expand double\-quoted strings into the corresponding combinations of
165 concatenation, uc, ucfirst, lc, lcfirst, quotemeta, and join. For
166 instance, print
167 .Sp
168 .Vb 1
169 \& print "Hello, $world, @ladies, \eu$gentlemen\eE, \eu\eL$me!";
170 .Ve
171 .Sp
172 as
173 .Sp
174 .Vb 2
175 \& print \*(AqHello, \*(Aq . $world . \*(Aq, \*(Aq . join($", @ladies) . \*(Aq, \*(Aq
176 \& . ucfirst($gentlemen) . \*(Aq, \*(Aq . ucfirst(lc $me . \*(Aq!\*(Aq);
177 .Ve
178 .Sp
179 Note that the expanded form represents the way perl handles such
180 constructions internally \-\- this option actually turns off the reverse
181 translation that B::Deparse usually does. On the other hand, note that
182 \&\f(CW\*(C`$x = "$y"\*(C'\fR is not the same as \f(CW\*(C`$x = $y\*(C'\fR: the former makes the value
183 of \f(CW$y\fR into a string before doing the assignment.
184 .IP \fB\-s\fR\fILETTERS\fR 4
185 .IX Item "-sLETTERS"
186 Tweak the style of B::Deparse\*(Aqs output. The letters should follow
187 directly after the \*(Aqs\*(Aq, with no space or punctuation. The following
188 options are available:
189 .RS 4
190 .IP \fBC\fR 4
191 .IX Item "C"
192 Cuddle \f(CW\*(C`elsif\*(C'\fR, \f(CW\*(C`else\*(C'\fR, and \f(CW\*(C`continue\*(C'\fR blocks. For example, print
193 .Sp
194 .Vb 5
195 \& if (...) {
196 \& ...
197 \& } else {
198 \& ...
199 \& }
200 .Ve
201 .Sp
202 instead of
203 .Sp
204 .Vb 6
205 \& if (...) {
206 \& ...
207 \& }
208 \& else {
209 \& ...
210 \& }
211 .Ve
212 .Sp
213 The default is not to cuddle.
214 .IP \fBi\fR\fINUMBER\fR 4
215 .IX Item "iNUMBER"
216 Indent lines by multiples of \fINUMBER\fR columns. The default is 4 columns.
217 .IP \fBT\fR 4
218 .IX Item "T"
219 Use tabs for each 8 columns of indent. The default is to use only spaces.
220 For instance, if the style options are \fB\-si4T\fR, a line that\*(Aqs indented
221 3 times will be preceded by one tab and four spaces; if the options were
222 \&\fB\-si8T\fR, the same line would be preceded by three tabs.
223 .IP \fBv\fR\fISTRING\fR\fB.\fR 4
224 .IX Item "vSTRING."
225 Print \fISTRING\fR for the value of a constant that can\*(Aqt be determined
226 because it was optimized away (mnemonic: this happens when a constant
227 is used in \fBv\fRoid context). The end of the string is marked by a period.
228 The string should be a valid perl expression, generally a constant.
229 Note that unless it\*(Aqs a number, it probably needs to be quoted, and on
230 a command line quotes need to be protected from the shell. Some
231 conventional values include 0, 1, 42, \*(Aq\*(Aq, \*(Aqfoo\*(Aq, and
232 \&\*(AqUseless use of constant omitted\*(Aq (which may need to be
233 \&\fB\-sv"\*(AqUseless use of constant omitted\*(Aq."\fR
234 or something similar depending on your shell). The default is \*(Aq???\*(Aq.
235 If you\*(Aqre using B::Deparse on a module or other file that\*(Aqs require\*(Aqd,
236 you shouldn\*(Aqt use a value that evaluates to false, since the customary
237 true constant at the end of a module will be in void context when the
238 file is compiled as a main program.
239 .RE
240 .RS 4
241 .RE
242 .IP \fB\-x\fR\fILEVEL\fR 4
243 .IX Item "-xLEVEL"
244 Expand conventional syntax constructions into equivalent ones that expose
245 their internal operation. \fILEVEL\fR should be a digit, with higher values
246 meaning more expansion. As with \fB\-q\fR, this actually involves turning off
247 special cases in B::Deparse\*(Aqs normal operations.
248 .Sp
249 If \fILEVEL\fR is at least 3, \f(CW\*(C`for\*(C'\fR loops will be translated into equivalent
250 while loops with continue blocks; for instance
251 .Sp
252 .Vb 3
253 \& for ($i = 0; $i < 10; ++$i) {
254 \& print $i;
255 \& }
256 .Ve
257 .Sp
258 turns into
259 .Sp
260 .Vb 6
261 \& $i = 0;
262 \& while ($i < 10) {
263 \& print $i;
264 \& } continue {
265 \& ++$i
266 \& }
267 .Ve
268 .Sp
269 Note that in a few cases this translation can\*(Aqt be perfectly carried back
270 into the source code \-\- if the loop\*(Aqs initializer declares a my variable,
271 for instance, it won\*(Aqt have the correct scope outside of the loop.
272 .Sp
273 If \fILEVEL\fR is at least 5, \f(CW\*(C`use\*(C'\fR declarations will be translated into
274 \&\f(CW\*(C`BEGIN\*(C'\fR blocks containing calls to \f(CW\*(C`require\*(C'\fR and \f(CW\*(C`import\*(C'\fR; for
275 instance,
276 .Sp
277 .Vb 1
278 \& use strict \*(Aqrefs\*(Aq;
279 .Ve
280 .Sp
281 turns into
282 .Sp
283 .Vb 6
284 \& sub BEGIN {
285 \& require strict;
286 \& do {
287 \& \*(Aqstrict\*(Aq\->import(\*(Aqrefs\*(Aq)
288 \& };
289 \& }
290 .Ve
291 .Sp
292 If \fILEVEL\fR is at least 7, \f(CW\*(C`if\*(C'\fR statements will be translated into
293 equivalent expressions using \f(CW\*(C`&&\*(C'\fR, \f(CW\*(C`?:\*(C'\fR and \f(CW\*(C`do {}\*(C'\fR; for instance
294 .Sp
295 .Vb 9
296 \& print \*(Aqhi\*(Aq if $nice;
297 \& if ($nice) {
298 \& print \*(Aqhi\*(Aq;
299 \& }
300 \& if ($nice) {
301 \& print \*(Aqhi\*(Aq;
302 \& } else {
303 \& print \*(Aqbye\*(Aq;
304 \& }
305 .Ve
306 .Sp
307 turns into
308 .Sp
309 .Vb 3
310 \& $nice and print \*(Aqhi\*(Aq;
311 \& $nice and do { print \*(Aqhi\*(Aq };
312 \& $nice ? do { print \*(Aqhi\*(Aq } : do { print \*(Aqbye\*(Aq };
313 .Ve
314 .Sp
315 Long sequences of elsifs will turn into nested ternary operators, which
316 B::Deparse doesn\*(Aqt know how to indent nicely.
317 .SH "USING B::Deparse AS A MODULE"
318 .IX Header "USING B::Deparse AS A MODULE"
319 .SS Synopsis
320 .IX Subsection "Synopsis"
321 .Vb 4
322 \& use B::Deparse;
323 \& $deparse = B::Deparse\->new("\-p", "\-sC");
324 \& $body = $deparse\->coderef2text(\e&func);
325 \& eval "sub func $body"; # the inverse operation
326 .Ve
327 .SS Description
328 .IX Subsection "Description"
329 B::Deparse can also be used on a sub\-by\-sub basis from other perl
330 programs.
331 .SS new
332 .IX Subsection "new"
333 .Vb 1
334 \& $deparse = B::Deparse\->new(OPTIONS)
335 .Ve
336 .PP
337 Create an object to store the state of a deparsing operation and any
338 options. The options are the same as those that can be given on the
339 command line (see "OPTIONS"); options that are separated by commas
340 after \fB\-MO=Deparse\fR should be given as separate strings.
341 .SS ambient_pragmas
342 .IX Subsection "ambient_pragmas"
343 .Vb 1
344 \& $deparse\->ambient_pragmas(strict => \*(Aqall\*(Aq, \*(Aq$[\*(Aq => $[);
345 .Ve
346 .PP
347 The compilation of a subroutine can be affected by a few compiler
348 directives, \fBpragmas\fR. These are:
349 .IP \(bu 4
350 use strict;
351 .IP \(bu 4
352 use warnings;
353 .IP \(bu 4
354 Assigning to the special variable $[
355 .IP \(bu 4
356 use integer;
357 .IP \(bu 4
358 use bytes;
359 .IP \(bu 4
360 use utf8;
361 .IP \(bu 4
362 use re;
363 .PP
364 Ordinarily, if you use B::Deparse on a subroutine which has
365 been compiled in the presence of one or more of these pragmas,
366 the output will include statements to turn on the appropriate
367 directives. So if you then compile the code returned by coderef2text,
368 it will behave the same way as the subroutine which you deparsed.
369 .PP
370 However, you may know that you intend to use the results in a
371 particular context, where some pragmas are already in scope. In
372 this case, you use the \fBambient_pragmas\fR method to describe the
373 assumptions you wish to make.
374 .PP
375 Not all of the options currently have any useful effect. See
376 "BUGS" for more details.
377 .PP
378 The parameters it accepts are:
379 .IP strict 4
380 .IX Item "strict"
381 Takes a string, possibly containing several values separated
382 by whitespace. The special values "all" and "none" mean what you\*(Aqd
383 expect.
384 .Sp
385 .Vb 1
386 \& $deparse\->ambient_pragmas(strict => \*(Aqsubs refs\*(Aq);
387 .Ve
388 .IP $[ 4
389 Takes a number, the value of the array base $[.
390 Obsolete: cannot be non\-zero.
391 .IP bytes 4
392 .IX Item "bytes"
393 .PD 0
394 .IP utf8 4
395 .IX Item "utf8"
396 .IP integer 4
397 .IX Item "integer"
398 .PD
399 If the value is true, then the appropriate pragma is assumed to
400 be in the ambient scope, otherwise not.
401 .IP re 4
402 .IX Item "re"
403 Takes a string, possibly containing a whitespace\-separated list of
404 values. The values "all" and "none" are special. It\*(Aqs also permissible
405 to pass an array reference here.
406 .Sp
407 .Vb 1
408 \& $deparser\->ambient_pragmas(re => \*(Aqeval\*(Aq);
409 .Ve
410 .IP warnings 4
411 .IX Item "warnings"
412 Takes a string, possibly containing a whitespace\-separated list of
413 values. The values "all" and "none" are special, again. It\*(Aqs also
414 permissible to pass an array reference here.
415 .Sp
416 .Vb 1
417 \& $deparser\->ambient_pragmas(warnings => [qw[void io]]);
418 .Ve
419 .Sp
420 If one of the values is the string "FATAL", then all the warnings
421 in that list will be considered fatal, just as with the \fBwarnings\fR
422 pragma itself. Should you need to specify that some warnings are
423 fatal, and others are merely enabled, you can pass the \fBwarnings\fR
424 parameter twice:
425 .Sp
426 .Vb 4
427 \& $deparser\->ambient_pragmas(
428 \& warnings => \*(Aqall\*(Aq,
429 \& warnings => [FATAL => qw/void io/],
430 \& );
431 .Ve
432 .Sp
433 See warnings for more information about lexical warnings.
434 .IP hint_bits 4
435 .IX Item "hint_bits"
436 .PD 0
437 .IP warning_bits 4
438 .IX Item "warning_bits"
439 .PD
440 These two parameters are used to specify the ambient pragmas in
441 the format used by the special variables $^H and ${^WARNING_BITS}.
442 .Sp
443 They exist principally so that you can write code like:
444 .Sp
445 .Vb 7
446 \& { my ($hint_bits, $warning_bits);
447 \& BEGIN {($hint_bits, $warning_bits) = ($^H, ${^WARNING_BITS})}
448 \& $deparser\->ambient_pragmas (
449 \& hint_bits => $hint_bits,
450 \& warning_bits => $warning_bits,
451 \& \*(Aq$[\*(Aq => 0 + $[
452 \& ); }
453 .Ve
454 .Sp
455 which specifies that the ambient pragmas are exactly those which
456 are in scope at the point of calling.
457 .IP %^H 4
458 .IX Item "%^H"
459 This parameter is used to specify the ambient pragmas which are
460 stored in the special hash %^H.
461 .SS coderef2text
462 .IX Subsection "coderef2text"
463 .Vb 2
464 \& $body = $deparse\->coderef2text(\e&func)
465 \& $body = $deparse\->coderef2text(sub ($$) { ... })
466 .Ve
467 .PP
468 Return source code for the body of a subroutine (a block, optionally
469 preceded by a prototype in parens), given a reference to the
470 sub. Because a subroutine can have no names, or more than one name,
471 this method doesn\*(Aqt return a complete subroutine definition \-\- if you
472 want to eval the result, you should prepend "sub subname ", or "sub "
473 for an anonymous function constructor. Unless the sub was defined in
474 the main:: package, the code will include a package declaration.
475 .SH BUGS
476 .IX Header "BUGS"
477 .IP \(bu 4
478 The only pragmas to
479 be completely supported are: \f(CW\*(C`use warnings\*(C'\fR,
480 \&\f(CW\*(C`use strict\*(C'\fR, \f(CW\*(C`use bytes\*(C'\fR, \f(CW\*(C`use integer\*(C'\fR
481 and \f(CW\*(C`use feature\*(C'\fR.
482 .Sp
483 Excepting those listed above, we\*(Aqre currently unable to guarantee that
484 B::Deparse will produce a pragma at the correct point in the program.
485 (Specifically, pragmas at the beginning of a block often appear right
486 before the start of the block instead.)
487 Since the effects of pragmas are often lexically scoped, this can mean
488 that the pragma holds sway over a different portion of the program
489 than in the input file.
490 .IP \(bu 4
491 In fact, the above is a specific instance of a more general problem:
492 we can\*(Aqt guarantee to produce BEGIN blocks or \f(CW\*(C`use\*(C'\fR declarations in
493 exactly the right place. So if you use a module which affects compilation
494 (such as by over\-riding keywords, overloading constants or whatever)
495 then the output code might not work as intended.
496 .IP \(bu 4
497 Some constants don\*(Aqt print correctly either with or without \fB\-d\fR.
498 For instance, neither B::Deparse nor Data::Dumper know how to print
499 dual\-valued scalars correctly, as in:
500 .Sp
501 .Vb 1
502 \& use constant E2BIG => ($!=7); $y = E2BIG; print $y, 0+$y;
503 \&
504 \& use constant H => { "#" => 1 }; H\->{"#"};
505 .Ve
506 .IP \(bu 4
507 An input file that uses source filtering probably won\*(Aqt be deparsed into
508 runnable code, because it will still include the \fBuse\fR declaration
509 for the source filtering module, even though the code that is
510 produced is already ordinary Perl which shouldn\*(Aqt be filtered again.
511 .IP \(bu 4
512 Optimized\-away statements are rendered as
513 \&\*(Aq???\*(Aq. This includes statements that
514 have a compile\-time side\-effect, such as the obscure
515 .Sp
516 .Vb 1
517 \& my $x if 0;
518 .Ve
519 .Sp
520 which is not, consequently, deparsed correctly.
521 .Sp
522 .Vb 3
523 \& foreach my $i (@_) { 0 }
524 \& =>
525 \& foreach my $i (@_) { \*(Aq???\*(Aq }
526 .Ve
527 .IP \(bu 4
528 Lexical (my) variables declared in scopes external to a subroutine
529 appear in coderef2text output text as package variables. This is a tricky
530 problem, as perl has no native facility for referring to a lexical variable
531 defined within a different scope, although PadWalker is a good start.
532 .Sp
533 See also Data::Dump::Streamer, which combines B::Deparse and
534 PadWalker to serialize closures properly.
535 .IP \(bu 4
536 There are probably many more bugs on non\-ASCII platforms (EBCDIC).
537 .SH AUTHOR
538 .IX Header "AUTHOR"
539 Stephen McCamant <[email protected]>, based on an earlier version
540 by Malcolm Beattie <[email protected]>, with contributions from
541 Gisle Aas, James Duncan, Albert Dvornik, Robin Houston, Dave Mitchell,
542 Hugo van der Sanden, Gurusamy Sarathy, Nick Ing\-Simmons, and Rafael
543 Garcia\-Suarez.