1B::Deparse(3pm)        Perl Programmers Reference Guide        B::Deparse(3pm)
2
3
4

NAME

6       B::Deparse - Perl compiler backend to produce perl code
7

SYNOPSIS

9       perl -MO=Deparse[,-d][,-fFILE][,-p][,-q][,-l]
10               [,-sLETTERS][,-xLEVEL] prog.pl
11

DESCRIPTION

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
24       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

OPTIONS

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
35       -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
42       -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
51       -l  Add '#line' declarations to the output based on the line and file
52           locations of the original code.
53
54       -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
61               if ($var & 0x7f == 65) {print "Gimme an A!"}
62               print ($which ? $a : $b), "\n";
63               $name = $ENV{USER} or "Bob";
64
65           "B::Deparse,-p" will print
66
67               if (($var & 0)) {
68                   print('Gimme an A!')
69               };
70               (print(($which ? $a : $b)), '???');
71               (($name = $ENV{'USER'}) or '???')
72
73           which probably isn't what you intended (the '???' is a sign that
74           perl optimized away a constant value).
75
76       -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
80               perl -MO=Deparse,-P -e 'sub foo (\@) { 1 } foo @x'
81
82           will print
83
84               sub foo (\@) {
85                   1;
86               }
87               &foo(\@x);
88
89           making clear how the parameters are actually passed to "foo".
90
91       -q  Expand double-quoted strings into the corresponding combinations of
92           concatenation, uc, ucfirst, lc, lcfirst, quotemeta, and join.  For
93           instance, print
94
95               print "Hello, $world, @ladies, \u$gentlemen\E, \u\L$me!";
96
97           as
98
99               print 'Hello, ' . $world . ', ' . join($", @ladies) . ', '
100                     . ucfirst($gentlemen) . ', ' . ucfirst(lc $me . '!');
101
102           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
109       -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
114           C   Cuddle "elsif", "else", and "continue" blocks.  For example,
115               print
116
117                   if (...) {
118                        ...
119                   } else {
120                        ...
121                   }
122
123               instead of
124
125                   if (...) {
126                        ...
127                   }
128                   else {
129                        ...
130                   }
131
132               The default is not to cuddle.
133
134           iNUMBER
135               Indent lines by multiples of NUMBER columns.  The default is 4
136               columns.
137
138           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
144           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
161       -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
168           If LEVEL is at least 3, "for" loops will be translated into
169           equivalent while loops with continue blocks; for instance
170
171               for ($i = 0; $i < 10; ++$i) {
172                   print $i;
173               }
174
175           turns into
176
177               $i = 0;
178               while ($i < 10) {
179                   print $i;
180               } continue {
181                   ++$i
182               }
183
184           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
189           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
193               use strict 'refs';
194
195           turns into
196
197               sub BEGIN {
198                   require strict;
199                   do {
200                       'strict'->import('refs')
201                   };
202               }
203
204           If LEVEL is at least 7, "if" statements will be translated into
205           equivalent expressions using "&&", "?:" and "do {}"; for instance
206
207               print 'hi' if $nice;
208               if ($nice) {
209                   print 'hi';
210               }
211               if ($nice) {
212                   print 'hi';
213               } else {
214                   print 'bye';
215               }
216
217           turns into
218
219               $nice and print 'hi';
220               $nice and do { print 'hi' };
221               $nice ? do { print 'hi' } : do { print 'bye' };
222
223           Long sequences of elsifs will turn into nested ternary operators,
224           which B::Deparse doesn't know how to indent nicely.
225

USING B::Deparse AS A MODULE

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
233   Description
234       B::Deparse can also be used on a sub-by-sub basis from other perl
235       programs.
236
237   new
238           $deparse = B::Deparse->new(OPTIONS)
239
240       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
245   ambient_pragmas
246           $deparse->ambient_pragmas(strict => 'all', '$[' => $[);
247
248       The compilation of a subroutine can be affected by a few compiler
249       directives, pragmas.  These are:
250
251       ·   use strict;
252
253       ·   use warnings;
254
255       ·   Assigning to the special variable $[
256
257       ·   use integer;
258
259       ·   use bytes;
260
261       ·   use utf8;
262
263       ·   use re;
264
265       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
271       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
276       Not all of the options currently have any useful effect.  See "BUGS"
277       for more details.
278
279       The parameters it accepts are:
280
281       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
286               $deparse->ambient_pragmas(strict => 'subs refs');
287
288       $[  Takes a number, the value of the array base $[.  Obsolete: cannot
289           be non-zero.
290
291       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
297       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
301               $deparser->ambient_pragmas(re => 'eval');
302
303       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
308               $deparser->ambient_pragmas(warnings => [qw[void io]]);
309
310           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
316               $deparser->ambient_pragmas(
317                   warnings => 'all',
318                   warnings => [FATAL => qw/void io/],
319               );
320
321           See warnings for more information about lexical warnings.
322
323       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
328           They exist principally so that you can write code like:
329
330               { 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
338           which specifies that the ambient pragmas are exactly those which
339           are in scope at the point of calling.
340
341       %^H This parameter is used to specify the ambient pragmas which are
342           stored in the special hash %^H.
343
344   coderef2text
345           $body = $deparse->coderef2text(\&func)
346           $body = $deparse->coderef2text(sub ($$) { ... })
347
348       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

BUGS

357       ·   The only pragmas to be completely supported are: "use warnings",
358           "use strict", "use bytes", "use integer" and "use feature".
359
360           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
368       ·   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
375       ·   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
379               use constant E2BIG => ($!=7); $y = E2BIG; print $y, 0+$y;
380
381               use constant H => { "#" => 1 }; H->{"#"};
382
383       ·   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
389       ·   Optimized-away statements are rendered as '???'.  This includes
390           statements that have a compile-time side-effect, such as the
391           obscure
392
393               my $x if 0;
394
395           which is not, consequently, deparsed correctly.
396
397               foreach my $i (@_) { 0 }
398             =>
399               foreach my $i (@_) { '???' }
400
401       ·   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
407           See also Data::Dump::Streamer, which combines B::Deparse and
408           PadWalker to serialize closures properly.
409
410       ·   There are probably many more bugs on non-ASCII platforms (EBCDIC).
411

AUTHOR

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.
418
419
420
421perl v5.30.2                      2020-03-27                   B::Deparse(3pm)
Impressum