1B::Deparse(3pm) Perl Programmers Reference Guide B::Deparse(3pm)
2
6 B::Deparse - Perl compiler backend to produce perl code
7
9 perl -MO=Deparse[,-d][,-fFILE][,-p][,-q][,-l]
10 [,-sLETTERS][,-xLEVEL] prog.pl
11
13 B::Deparse is a backend module for the Perl compiler that generates
14 perl source code, based on the internal compiled structure that perl
15 itself creates after parsing a program. The output of B::Deparse won't
16 be exactly the same as the original source, since perl doesn't keep
17 track of comments or whitespace, and there isn't a one-to-one
18 correspondence between perl's syntactical constructions and their
19 compiled form, but it will often be close. When you use the -p option,
20 the output also includes parentheses even when they are not required by
21 precedence, which can make it easy to see if perl is parsing your
22 expressions the way you intended.
23 While B::Deparse goes to some lengths to try to figure out what your
25 original program was doing, some parts of the language can still trip
26 it up; it still fails even on some parts of Perl's own test suite. If
27 you encounter a failure other than the most common ones described in
28 the BUGS section below, you can help contribute to B::Deparse's ongoing
29 development by submitting a bug report with a small example.
30
32 As with all compiler backend options, these must follow directly after
33 the '-MO=Deparse', separated by a comma but not any white space.
34 -d Output data values (when they appear as constants) using
36 Data::Dumper. Without this option, B::Deparse will use some simple
37 routines of its own for the same purpose. Currently, Data::Dumper
38 is better for some kinds of data (such as complex structures with
39 sharing and self-reference) while the built-in routines are better
40 for others (such as odd floating-point values).
41 -fFILE
43 Normally, B::Deparse deparses the main code of a program, and all
44 the subs defined in the same file. To include subs defined in
45 other files, pass the -f option with the filename. You can pass
46 the -f option several times, to include more than one secondary
47 file. (Most of the time you don't want to use it at all.) You can
48 also use this option to include subs which are defined in the scope
49 of a #line directive with two parameters.
50 -l Add '#line' declarations to the output based on the line and file
52 locations of the original code.
53 -p Print extra parentheses. Without this option, B::Deparse includes
55 parentheses in its output only when they are needed, based on the
56 structure of your program. With -p, it uses parentheses (almost)
57 whenever they would be legal. This can be useful if you are used
58 to LISP, or if you want to see how perl parses your input. If you
59 say
60 if ($var & 0x7f == 65) {print "Gimme an A!"}
62 print ($which ? $a : $b), "\n";
63 $name = $ENV{USER} or "Bob";
64 "B::Deparse,-p" will print
66 if (($var & 0)) {
68 print('Gimme an A!')
69 };
70 (print(($which ? $a : $b)), '???');
71 (($name = $ENV{'USER'}) or '???')
72 which probably isn't what you intended (the '???' is a sign that
74 perl optimized away a constant value).
75 -P Disable prototype checking. With this option, all function calls
77 are deparsed as if no prototype was defined for them. In other
78 words,
79 perl -MO=Deparse,-P -e 'sub foo (\@) { 1 } foo @x'
81 will print
83 sub foo (\@) {
85 1;
86 }
87 &foo(\@x);
88 making clear how the parameters are actually passed to "foo".
90 -q Expand double-quoted strings into the corresponding combinations of
92 concatenation, uc, ucfirst, lc, lcfirst, quotemeta, and join. For
93 instance, print
94 print "Hello, $world, @ladies, \u$gentlemen\E, \u\L$me!";
96 as
98 print 'Hello, ' . $world . ', ' . join($", @ladies) . ', '
100 . ucfirst($gentlemen) . ', ' . ucfirst(lc $me . '!');
101 Note that the expanded form represents the way perl handles such
103 constructions internally -- this option actually turns off the
104 reverse translation that B::Deparse usually does. On the other
105 hand, note that "$x = "$y"" is not the same as "$x = $y": the
106 former makes the value of $y into a string before doing the
107 assignment.
108 -sLETTERS
110 Tweak the style of B::Deparse's output. The letters should follow
111 directly after the 's', with no space or punctuation. The
112 following options are available:
113 C Cuddle "elsif", "else", and "continue" blocks. For example,
115 print
116 if (...) {
118 ...
119 } else {
120 ...
121 }
122 instead of
124 if (...) {
126 ...
127 }
128 else {
129 ...
130 }
131 The default is not to cuddle.
133 iNUMBER
135 Indent lines by multiples of NUMBER columns. The default is 4
136 columns.
137 T Use tabs for each 8 columns of indent. The default is to use
139 only spaces. For instance, if the style options are -si4T, a
140 line that's indented 3 times will be preceded by one tab and
141 four spaces; if the options were -si8T, the same line would be
142 preceded by three tabs.
143 vSTRING.
145 Print STRING for the value of a constant that can't be
146 determined because it was optimized away (mnemonic: this
147 happens when a constant is used in void context). The end of
148 the string is marked by a period. The string should be a valid
149 perl expression, generally a constant. Note that unless it's a
150 number, it probably needs to be quoted, and on a command line
151 quotes need to be protected from the shell. Some conventional
152 values include 0, 1, 42, '', 'foo', and 'Useless use of
153 constant omitted' (which may need to be -sv"'Useless use of
154 constant omitted'." or something similar depending on your
155 shell). The default is '???'. If you're using B::Deparse on a
156 module or other file that's require'd, you shouldn't use a
157 value that evaluates to false, since the customary true
158 constant at the end of a module will be in void context when
159 the file is compiled as a main program.
160 -xLEVEL
162 Expand conventional syntax constructions into equivalent ones that
163 expose their internal operation. LEVEL should be a digit, with
164 higher values meaning more expansion. As with -q, this actually
165 involves turning off special cases in B::Deparse's normal
166 operations.
167 If LEVEL is at least 3, "for" loops will be translated into
169 equivalent while loops with continue blocks; for instance
170 for ($i = 0; $i < 10; ++$i) {
172 print $i;
173 }
174 turns into
176 $i = 0;
178 while ($i < 10) {
179 print $i;
180 } continue {
181 ++$i
182 }
183 Note that in a few cases this translation can't be perfectly
185 carried back into the source code -- if the loop's initializer
186 declares a my variable, for instance, it won't have the correct
187 scope outside of the loop.
188 If LEVEL is at least 5, "use" declarations will be translated into
190 "BEGIN" blocks containing calls to "require" and "import"; for
191 instance,
192 use strict 'refs';
194 turns into
196 sub BEGIN {
198 require strict;
199 do {
200 'strict'->import('refs')
201 };
202 }
203 If LEVEL is at least 7, "if" statements will be translated into
205 equivalent expressions using "&&", "?:" and "do {}"; for instance
206 print 'hi' if $nice;
208 if ($nice) {
209 print 'hi';
210 }
211 if ($nice) {
212 print 'hi';
213 } else {
214 print 'bye';
215 }
216 turns into
218 $nice and print 'hi';
220 $nice and do { print 'hi' };
221 $nice ? do { print 'hi' } : do { print 'bye' };
222 Long sequences of elsifs will turn into nested ternary operators,
224 which B::Deparse doesn't know how to indent nicely.
225
227 Synopsis
228 use B::Deparse;
229 $deparse = B::Deparse->new("-p", "-sC");
230 $body = $deparse->coderef2text(\&func);
231 eval "sub func $body"; # the inverse operation
232 Description
234 B::Deparse can also be used on a sub-by-sub basis from other perl
235 programs.
236 new
238 $deparse = B::Deparse->new(OPTIONS)
239 Create an object to store the state of a deparsing operation and any
241 options. The options are the same as those that can be given on the
242 command line (see "OPTIONS"); options that are separated by commas
243 after -MO=Deparse should be given as separate strings.
244 ambient_pragmas
246 $deparse->ambient_pragmas(strict => 'all', '$[' => $[);
247 The compilation of a subroutine can be affected by a few compiler
249 directives, pragmas. These are:
250 • use strict;
252 • use warnings;
254 • Assigning to the special variable $[
256 • use integer;
258 • use bytes;
260 • use utf8;
262 • use re;
264 Ordinarily, if you use B::Deparse on a subroutine which has been
266 compiled in the presence of one or more of these pragmas, the output
267 will include statements to turn on the appropriate directives. So if
268 you then compile the code returned by coderef2text, it will behave the
269 same way as the subroutine which you deparsed.
270 However, you may know that you intend to use the results in a
272 particular context, where some pragmas are already in scope. In this
273 case, you use the ambient_pragmas method to describe the assumptions
274 you wish to make.
275 Not all of the options currently have any useful effect. See "BUGS"
277 for more details.
278 The parameters it accepts are:
280 strict
282 Takes a string, possibly containing several values separated by
283 whitespace. The special values "all" and "none" mean what you'd
284 expect.
285 $deparse->ambient_pragmas(strict => 'subs refs');
287 $[ Takes a number, the value of the array base $[. Obsolete: cannot
289 be non-zero.
290 bytes
292 utf8
293 integer
294 If the value is true, then the appropriate pragma is assumed to be
295 in the ambient scope, otherwise not.
296 re Takes a string, possibly containing a whitespace-separated list of
298 values. The values "all" and "none" are special. It's also
299 permissible to pass an array reference here.
300 $deparser->ambient_pragmas(re => 'eval');
302 warnings
304 Takes a string, possibly containing a whitespace-separated list of
305 values. The values "all" and "none" are special, again. It's also
306 permissible to pass an array reference here.
307 $deparser->ambient_pragmas(warnings => [qw[void io]]);
309 If one of the values is the string "FATAL", then all the warnings
311 in that list will be considered fatal, just as with the warnings
312 pragma itself. Should you need to specify that some warnings are
313 fatal, and others are merely enabled, you can pass the warnings
314 parameter twice:
315 $deparser->ambient_pragmas(
317 warnings => 'all',
318 warnings => [FATAL => qw/void io/],
319 );
320 See warnings for more information about lexical warnings.
322 hint_bits
324 warning_bits
325 These two parameters are used to specify the ambient pragmas in the
326 format used by the special variables $^H and ${^WARNING_BITS}.
327 They exist principally so that you can write code like:
329 { my ($hint_bits, $warning_bits);
331 BEGIN {($hint_bits, $warning_bits) = ($^H, ${^WARNING_BITS})}
332 $deparser->ambient_pragmas (
333 hint_bits => $hint_bits,
334 warning_bits => $warning_bits,
335 '$[' => 0 + $[
336 ); }
337 which specifies that the ambient pragmas are exactly those which
339 are in scope at the point of calling.
340 %^H This parameter is used to specify the ambient pragmas which are
342 stored in the special hash %^H.
343 coderef2text
345 $body = $deparse->coderef2text(\&func)
346 $body = $deparse->coderef2text(sub ($$) { ... })
347 Return source code for the body of a subroutine (a block, optionally
349 preceded by a prototype in parens), given a reference to the sub.
350 Because a subroutine can have no names, or more than one name, this
351 method doesn't return a complete subroutine definition -- if you want
352 to eval the result, you should prepend "sub subname ", or "sub " for an
353 anonymous function constructor. Unless the sub was defined in the
354 main:: package, the code will include a package declaration.
355
357 • The only pragmas to be completely supported are: "use warnings",
358 "use strict", "use bytes", "use integer" and "use feature".
359 Excepting those listed above, we're currently unable to guarantee
361 that B::Deparse will produce a pragma at the correct point in the
362 program. (Specifically, pragmas at the beginning of a block often
363 appear right before the start of the block instead.) Since the
364 effects of pragmas are often lexically scoped, this can mean that
365 the pragma holds sway over a different portion of the program than
366 in the input file.
367 • In fact, the above is a specific instance of a more general
369 problem: we can't guarantee to produce BEGIN blocks or "use"
370 declarations in exactly the right place. So if you use a module
371 which affects compilation (such as by over-riding keywords,
372 overloading constants or whatever) then the output code might not
373 work as intended.
374 • Some constants don't print correctly either with or without -d.
376 For instance, neither B::Deparse nor Data::Dumper know how to print
377 dual-valued scalars correctly, as in:
378 use constant E2BIG => ($!=7); $y = E2BIG; print $y, 0+$y;
380 use constant H => { "#" => 1 }; H->{"#"};
382 • An input file that uses source filtering probably won't be deparsed
384 into runnable code, because it will still include the use
385 declaration for the source filtering module, even though the code
386 that is produced is already ordinary Perl which shouldn't be
387 filtered again.
388 • Optimized-away statements are rendered as '???'. This includes
390 statements that have a compile-time side-effect, such as the
391 obscure
392 my $x if 0;
394 which is not, consequently, deparsed correctly.
396 foreach my $i (@_) { 0 }
398 =>
399 foreach my $i (@_) { '???' }
400 • Lexical (my) variables declared in scopes external to a subroutine
402 appear in coderef2text output text as package variables. This is a
403 tricky problem, as perl has no native facility for referring to a
404 lexical variable defined within a different scope, although
405 PadWalker is a good start.
406 See also Data::Dump::Streamer, which combines B::Deparse and
408 PadWalker to serialize closures properly.
409 • There are probably many more bugs on non-ASCII platforms (EBCDIC).
411
413 Stephen McCamant <smcc@CSUA.Berkeley.EDU>, based on an earlier version
414 by Malcolm Beattie <mbeattie@sable.ox.ac.uk>, with contributions from
415 Gisle Aas, James Duncan, Albert Dvornik, Robin Houston, Dave Mitchell,
416 Hugo van der Sanden, Gurusamy Sarathy, Nick Ing-Simmons, and Rafael
417 Garcia-Suarez.
418perl v5.38.2 2023-11-30 B::Deparse(3pm)