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 other
45 files, pass the -f option with the filename. You can pass the -f
46 option several times, to include more than one secondary file.
47 (Most of the time you don't want to use it at all.) You can also
48 use this option to include subs which are defined in the scope of a
49 #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 to
58 LISP, or if you want to see how perl parses your input. If you say
59 if ($var & 0x7f == 65) {print "Gimme an A!"}
61 print ($which ? $a : $b), "\n";
62 $name = $ENV{USER} or "Bob";
63 "B::Deparse,-p" will print
65 if (($var & 0)) {
67 print('Gimme an A!')
68 };
69 (print(($which ? $a : $b)), '???');
70 (($name = $ENV{'USER'}) or '???')
71 which probably isn't what you intended (the '???' is a sign that
73 perl optimized away a constant value).
74 -P Disable prototype checking. With this option, all function calls
76 are deparsed as if no prototype was defined for them. In other
77 words,
78 perl -MO=Deparse,-P -e 'sub foo (\@) { 1 } foo @x'
80 will print
82 sub foo (\@) {
84 1;
85 }
86 &foo(\@x);
87 making clear how the parameters are actually passed to "foo".
89 -q Expand double-quoted strings into the corresponding combinations of
91 concatenation, uc, ucfirst, lc, lcfirst, quotemeta, and join. For
92 instance, print
93 print "Hello, $world, @ladies, \u$gentlemen\E, \u\L$me!";
95 as
97 print 'Hello, ' . $world . ', ' . join($", @ladies) . ', '
99 . ucfirst($gentlemen) . ', ' . ucfirst(lc $me . '!');
100 Note that the expanded form represents the way perl handles such
102 constructions internally -- this option actually turns off the
103 reverse translation that B::Deparse usually does. On the other
104 hand, note that "$x = "$y"" is not the same as "$x = $y": the
105 former makes the value of $y into a string before doing the
106 assignment.
107 -sLETTERS
109 Tweak the style of B::Deparse's output. The letters should follow
110 directly after the 's', with no space or punctuation. The following
111 options are available:
112 C Cuddle "elsif", "else", and "continue" blocks. For example,
114 print
115 if (...) {
117 ...
118 } else {
119 ...
120 }
121 instead of
123 if (...) {
125 ...
126 }
127 else {
128 ...
129 }
130 The default is not to cuddle.
132 iNUMBER
134 Indent lines by multiples of NUMBER columns. The default is 4
135 columns.
136 T Use tabs for each 8 columns of indent. The default is to use
138 only spaces. For instance, if the style options are -si4T, a
139 line that's indented 3 times will be preceded by one tab and
140 four spaces; if the options were -si8T, the same line would be
141 preceded by three tabs.
142 vSTRING.
144 Print STRING for the value of a constant that can't be
145 determined because it was optimized away (mnemonic: this
146 happens when a constant is used in void context). The end of
147 the string is marked by a period. The string should be a valid
148 perl expression, generally a constant. Note that unless it's a
149 number, it probably needs to be quoted, and on a command line
150 quotes need to be protected from the shell. Some conventional
151 values include 0, 1, 42, '', 'foo', and 'Useless use of
152 constant omitted' (which may need to be -sv"'Useless use of
153 constant omitted'." or something similar depending on your
154 shell). The default is '???'. If you're using B::Deparse on a
155 module or other file that's require'd, you shouldn't use a
156 value that evaluates to false, since the customary true
157 constant at the end of a module will be in void context when
158 the file is compiled as a main program.
159 -xLEVEL
161 Expand conventional syntax constructions into equivalent ones that
162 expose their internal operation. LEVEL should be a digit, with
163 higher values meaning more expansion. As with -q, this actually
164 involves turning off special cases in B::Deparse's normal
165 operations.
166 If LEVEL is at least 3, "for" loops will be translated into
168 equivalent while loops with continue blocks; for instance
169 for ($i = 0; $i < 10; ++$i) {
171 print $i;
172 }
173 turns into
175 $i = 0;
177 while ($i < 10) {
178 print $i;
179 } continue {
180 ++$i
181 }
182 Note that in a few cases this translation can't be perfectly
184 carried back into the source code -- if the loop's initializer
185 declares a my variable, for instance, it won't have the correct
186 scope outside of the loop.
187 If LEVEL is at least 5, "use" declarations will be translated into
189 "BEGIN" blocks containing calls to "require" and "import"; for
190 instance,
191 use strict 'refs';
193 turns into
195 sub BEGIN {
197 require strict;
198 do {
199 'strict'->import('refs')
200 };
201 }
202 If LEVEL is at least 7, "if" statements will be translated into
204 equivalent expressions using "&&", "?:" and "do {}"; for instance
205 print 'hi' if $nice;
207 if ($nice) {
208 print 'hi';
209 }
210 if ($nice) {
211 print 'hi';
212 } else {
213 print 'bye';
214 }
215 turns into
217 $nice and print 'hi';
219 $nice and do { print 'hi' };
220 $nice ? do { print 'hi' } : do { print 'bye' };
221 Long sequences of elsifs will turn into nested ternary operators,
223 which B::Deparse doesn't know how to indent nicely.
224
226 Synopsis
227 use B::Deparse;
228 $deparse = B::Deparse->new("-p", "-sC");
229 $body = $deparse->coderef2text(\&func);
230 eval "sub func $body"; # the inverse operation
231 Description
233 B::Deparse can also be used on a sub-by-sub basis from other perl
234 programs.
235 new
237 $deparse = B::Deparse->new(OPTIONS)
238 Create an object to store the state of a deparsing operation and any
240 options. The options are the same as those that can be given on the
241 command line (see "OPTIONS"); options that are separated by commas
242 after -MO=Deparse should be given as separate strings.
243 ambient_pragmas
245 $deparse->ambient_pragmas(strict => 'all', '$[' => $[);
246 The compilation of a subroutine can be affected by a few compiler
248 directives, pragmas. These are:
249 · use strict;
251 · use warnings;
253 · Assigning to the special variable $[
255 · use integer;
257 · use bytes;
259 · use utf8;
261 · use re;
263 Ordinarily, if you use B::Deparse on a subroutine which has been
265 compiled in the presence of one or more of these pragmas, the output
266 will include statements to turn on the appropriate directives. So if
267 you then compile the code returned by coderef2text, it will behave the
268 same way as the subroutine which you deparsed.
269 However, you may know that you intend to use the results in a
271 particular context, where some pragmas are already in scope. In this
272 case, you use the ambient_pragmas method to describe the assumptions
273 you wish to make.
274 Not all of the options currently have any useful effect. See "BUGS" for
276 more details.
277 The parameters it accepts are:
279 strict
281 Takes a string, possibly containing several values separated by
282 whitespace. The special values "all" and "none" mean what you'd
283 expect.
284 $deparse->ambient_pragmas(strict => 'subs refs');
286 $[ Takes a number, the value of the array base $[.
288 bytes
290 utf8
291 integer
292 If the value is true, then the appropriate pragma is assumed to be
293 in the ambient scope, otherwise not.
294 re Takes a string, possibly containing a whitespace-separated list of
296 values. The values "all" and "none" are special. It's also
297 permissible to pass an array reference here.
298 $deparser->ambient_pragmas(re => 'eval');
300 warnings
302 Takes a string, possibly containing a whitespace-separated list of
303 values. The values "all" and "none" are special, again. It's also
304 permissible to pass an array reference here.
305 $deparser->ambient_pragmas(warnings => [qw[void io]]);
307 If one of the values is the string "FATAL", then all the warnings
309 in that list will be considered fatal, just as with the warnings
310 pragma itself. Should you need to specify that some warnings are
311 fatal, and others are merely enabled, you can pass the warnings
312 parameter twice:
313 $deparser->ambient_pragmas(
315 warnings => 'all',
316 warnings => [FATAL => qw/void io/],
317 );
318 See perllexwarn for more information about lexical warnings.
320 hint_bits
322 warning_bits
323 These two parameters are used to specify the ambient pragmas in the
324 format used by the special variables $^H and ${^WARNING_BITS}.
325 They exist principally so that you can write code like:
327 { my ($hint_bits, $warning_bits);
329 BEGIN {($hint_bits, $warning_bits) = ($^H, ${^WARNING_BITS})}
330 $deparser->ambient_pragmas (
331 hint_bits => $hint_bits,
332 warning_bits => $warning_bits,
333 '$[' => 0 + $[
334 ); }
335 which specifies that the ambient pragmas are exactly those which
337 are in scope at the point of calling.
338 %^H This parameter is used to specify the ambient pragmas which are
340 stored in the special hash %^H.
341 coderef2text
343 $body = $deparse->coderef2text(\&func)
344 $body = $deparse->coderef2text(sub ($$) { ... })
345 Return source code for the body of a subroutine (a block, optionally
347 preceded by a prototype in parens), given a reference to the sub.
348 Because a subroutine can have no names, or more than one name, this
349 method doesn't return a complete subroutine definition -- if you want
350 to eval the result, you should prepend "sub subname ", or "sub " for an
351 anonymous function constructor. Unless the sub was defined in the
352 main:: package, the code will include a package declaration.
353
355 · The only pragmas to be completely supported are: "use warnings",
356 "use strict 'refs'", "use bytes", and "use integer". ($[, which
357 behaves like a pragma, is also supported.)
358 Excepting those listed above, we're currently unable to guarantee
360 that B::Deparse will produce a pragma at the correct point in the
361 program. (Specifically, pragmas at the beginning of a block often
362 appear right before the start of the block instead.) Since the
363 effects of pragmas are often lexically scoped, this can mean that
364 the pragma holds sway over a different portion of the program than
365 in the input file.
366 · In fact, the above is a specific instance of a more general
368 problem: we can't guarantee to produce BEGIN blocks or "use"
369 declarations in exactly the right place. So if you use a module
370 which affects compilation (such as by over-riding keywords,
371 overloading constants or whatever) then the output code might not
372 work as intended.
373 This is the most serious outstanding problem, and will require some
375 help from the Perl core to fix.
376 · If a keyword is over-ridden, and your program explicitly calls the
378 built-in version by using CORE::keyword, the output of B::Deparse
379 will not reflect this. If you run the resulting code, it will call
380 the over-ridden version rather than the built-in one. (Maybe there
381 should be an option to always print keyword calls as "CORE::name".)
382 · Some constants don't print correctly either with or without -d.
384 For instance, neither B::Deparse nor Data::Dumper know how to print
385 dual-valued scalars correctly, as in:
386 use constant E2BIG => ($!=7); $y = E2BIG; print $y, 0+$y;
388 use constant H => { "#" => 1 }; H->{"#"};
390 · An input file that uses source filtering probably won't be deparsed
392 into runnable code, because it will still include the use
393 declaration for the source filtering module, even though the code
394 that is produced is already ordinary Perl which shouldn't be
395 filtered again.
396 · Optimised away statements are rendered as '???'. This includes
398 statements that have a compile-time side-effect, such as the
399 obscure
400 my $x if 0;
402 which is not, consequently, deparsed correctly.
404 foreach my $i (@_) { 0 }
406 =>
407 foreach my $i (@_) { '???' }
408 · Lexical (my) variables declared in scopes external to a subroutine
410 appear in code2ref output text as package variables. This is a
411 tricky problem, as perl has no native facility for refering to a
412 lexical variable defined within a different scope, although
413 PadWalker is a good start.
414 · There are probably many more bugs on non-ASCII platforms (EBCDIC).
416
418 Stephen McCamant <smcc@CSUA.Berkeley.EDU>, based on an earlier version
419 by Malcolm Beattie <mbeattie@sable.ox.ac.uk>, with contributions from
420 Gisle Aas, James Duncan, Albert Dvornik, Robin Houston, Dave Mitchell,
421 Hugo van der Sanden, Gurusamy Sarathy, Nick Ing-Simmons, and Rafael
422 Garcia-Suarez.
423perl v5.12.4 2011-06-07 B::Deparse(3pm)