Debian Codegraph @

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