table of contents
other versions
- wheezy 5.14.2-21+deb7u3
- jessie 5.20.2-3+deb8u6
- testing 5.24.1-3
- unstable 5.24.1-3
- experimental 5.26.0-1
B::Deparse(3perl) | Perl Programmers Reference Guide | B::Deparse(3perl) |
NAME¶
B::Deparse - Perl compiler backend to produce perl codeSYNOPSIS¶
perl -MO=Deparse[,-d][,-fFILE][,-p][,-q][,-l][ ,-sLETTERS][,-xLEVEL] prog.pl
DESCRIPTION¶
B::Deparse is a backend module for the Perl compiler that generates perl source code, based on the internal compiled structure that perl itself creates after parsing a program. The output of B::Deparse won't be exactly the same as the original source, since perl doesn't keep track of comments or whitespace, and there isn't a one-to-one correspondence between perl's syntactical constructions and their compiled form, but it will often be close. When you use the -p option, the output also includes parentheses even when they are not required by precedence, which can make it easy to see if perl is parsing your expressions the way you intended. While B::Deparse goes to some lengths to try to figure out what your original program was doing, some parts of the language can still trip it up; it still fails even on some parts of Perl's own test suite. If you encounter a failure other than the most common ones described in the BUGS section below, you can help contribute to B::Deparse's ongoing development by submitting a bug report with a small example.OPTIONS¶
As with all compiler backend options, these must follow directly after the '-MO=Deparse', separated by a comma but not any white space.- -d
- Output data values (when they appear as constants) using Data::Dumper. Without this option, B::Deparse will use some simple routines of its own for the same purpose. Currently, Data::Dumper is better for some kinds of data (such as complex structures with sharing and self-reference) while the built-in routines are better for others (such as odd floating-point values).
- -fFILE
- Normally, B::Deparse deparses the main code of a program, and all the subs defined in the same file. To include subs defined in other files, pass the -f option with the filename. You can pass the -f option several times, to include more than one secondary file. (Most of the time you don't want to use it at all.) You can also use this option to include subs which are defined in the scope of a #line directive with two parameters.
- -l
- Add '#line' declarations to the output based on the line and file locations of the original code.
- -p
- Print extra parentheses. Without this option, B::Deparse
includes parentheses in its output only when they are needed, based on the
structure of your program. With -p, it uses parentheses (almost)
whenever they would be legal. This can be useful if you are used to LISP,
or if you want to see how perl parses your input. If you say
if ($var & 0x7f == 65) {print "Gimme an A!"} print ($which ? $a : $b), "\n"; $name = $ENV{USER} or "Bob";
if (($var & 0)) { print('Gimme an A!') }; (print(($which ? $a : $b)), '???'); (($name = $ENV{'USER'}) or '???')
- -P
- Disable prototype checking. With this option, all function
calls are deparsed as if no prototype was defined for them. In other
words,
perl -MO=Deparse,-P -e 'sub foo (\@) { 1 } foo @x'
sub foo (\@) { 1; } &foo(\@x);
- -q
- Expand double-quoted strings into the corresponding
combinations of concatenation, uc, ucfirst, lc, lcfirst, quotemeta, and
join. For instance, print
print "Hello, $world, @ladies, \u$gentlemen\E, \u\L$me!";
print 'Hello, ' . $world . ', ' . join($", @ladies) . ', ' . ucfirst($gentlemen) . ', ' . ucfirst(lc $me . '!');
- -sLETTERS
- Tweak the style of B::Deparse's output. The letters should follow directly after the 's', with no space or punctuation. The following options are available:
- C
- Cuddle "elsif", "else", and
"continue" blocks. For example, print
if (...) { ... } else { ... }
if (...) { ... } else { ... }
- iNUMBER
- Indent lines by multiples of NUMBER columns. The default is 4 columns.
- T
- Use tabs for each 8 columns of indent. The default is to use only spaces. For instance, if the style options are -si4T, a line that's indented 3 times will be preceded by one tab and four spaces; if the options were -si8T, the same line would be preceded by three tabs.
- vSTRING.
- Print STRING for the value of a constant that can't be determined because it was optimized away (mnemonic: this happens when a constant is used in void context). The end of the string is marked by a period. The string should be a valid perl expression, generally a constant. Note that unless it's a number, it probably needs to be quoted, and on a command line quotes need to be protected from the shell. Some conventional values include 0, 1, 42, '', 'foo', and 'Useless use of constant omitted' (which may need to be -sv"'Useless use of constant omitted'." or something similar depending on your shell). The default is '???'. If you're using B::Deparse on a module or other file that's require'd, you shouldn't use a value that evaluates to false, since the customary true constant at the end of a module will be in void context when the file is compiled as a main program.
- -xLEVEL
- Expand conventional syntax constructions into equivalent
ones that expose their internal operation. LEVEL should be a digit,
with higher values meaning more expansion. As with -q, this
actually involves turning off special cases in B::Deparse's normal
operations.
for ($i = 0; $i < 10; ++$i) { print $i; }
$i = 0; while ($i < 10) { print $i; } continue { ++$i }
use strict 'refs';
sub BEGIN { require strict; do { 'strict'->import('refs') }; }
print 'hi' if $nice; if ($nice) { print 'hi'; } if ($nice) { print 'hi'; } else { print 'bye'; }
$nice and print 'hi'; $nice and do { print 'hi' }; $nice ? do { print 'hi' } : do { print 'bye' };
USING B::Deparse AS A MODULE¶
Synopsis¶
use B::Deparse; $deparse = B::Deparse->new("-p", "-sC"); $body = $deparse->coderef2text(\&func); eval "sub func $body"; # the inverse operation
Description¶
B::Deparse can also be used on a sub-by-sub basis from other perl programs.new¶
$deparse = B::Deparse->new(OPTIONS)Create an object to store the state of a deparsing operation and any options. The options are the same as those that can be given on the command line (see "OPTIONS"); options that are separated by commas after -MO=Deparse should be given as separate strings.
ambient_pragmas¶
$deparse->ambient_pragmas(strict => 'all', '$[' => $[);The compilation of a subroutine can be affected by a few compiler directives, pragmas. These are:
- •
- use strict;
- •
- use warnings;
- •
- Assigning to the special variable $[
- •
- use integer;
- •
- use bytes;
- •
- use utf8;
- •
- use re;
- strict
- Takes a string, possibly containing several values
separated by whitespace. The special values "all" and
"none" mean what you'd expect.
$deparse->ambient_pragmas(strict => 'subs refs');
- $[
- Takes a number, the value of the array base $[.
- bytes
- utf8
- integer
- If the value is true, then the appropriate pragma is assumed to be in the ambient scope, otherwise not.
- re
- Takes a string, possibly containing a whitespace-separated
list of values. The values "all" and "none" are
special. It's also permissible to pass an array reference here.
$deparser->ambient_pragmas(re => 'eval');
- warnings
- Takes a string, possibly containing a whitespace-separated
list of values. The values "all" and "none" are
special, again. It's also permissible to pass an array reference here.
$deparser->ambient_pragmas(warnings => [qw[void io]]);
$deparser->ambient_pragmas( warnings => 'all', warnings => [FATAL => qw/void io/], );
- hint_bits
- warning_bits
- These two parameters are used to specify the ambient
pragmas in the format used by the special variables $^H and
${^WARNING_BITS}.
{ my ($hint_bits, $warning_bits); BEGIN {($hint_bits, $warning_bits) = ($^H, ${^WARNING_BITS})} $deparser->ambient_pragmas ( hint_bits => $hint_bits, warning_bits => $warning_bits, '$[' => 0 + $[ ); }
- %^H
- This parameter is used to specify the ambient pragmas which are stored in the special hash %^H.
coderef2text¶
$body = $deparse->coderef2text(\&func) $body = $deparse->coderef2text(sub ($$) { ... })Return source code for the body of a subroutine (a block, optionally preceded by a prototype in parens), given a reference to the sub. Because a subroutine can have no names, or more than one name, this method doesn't return a complete subroutine definition -- if you want to eval the result, you should prepend "sub subname ", or "sub " for an anonymous function constructor. Unless the sub was defined in the main:: package, the code will include a package declaration.
BUGS¶
- •
- The only pragmas to be completely supported are: "use
warnings", "use strict 'refs'", "use bytes", and
"use integer". ($[, which behaves like a pragma, is also
supported.)
- •
- In fact, the above is a specific instance of a more general
problem: we can't guarantee to produce BEGIN blocks or "use"
declarations in exactly the right place. So if you use a module which
affects compilation (such as by over-riding keywords, overloading
constants or whatever) then the output code might not work as intended.
- •
- If a keyword is over-ridden, and your program explicitly calls the built-in version by using CORE::keyword, the output of B::Deparse will not reflect this. If you run the resulting code, it will call the over-ridden version rather than the built-in one. (Maybe there should be an option to always print keyword calls as "CORE::name".)
- •
- Some constants don't print correctly either with or without
-d. For instance, neither B::Deparse nor Data::Dumper know how to
print dual-valued scalars correctly, as in:
use constant E2BIG => ($!=7); $y = E2BIG; print $y, 0+$y; use constant H => { "#" => 1 }; H->{"#"};
- •
- An input file that uses source filtering probably won't be deparsed into runnable code, because it will still include the use declaration for the source filtering module, even though the code that is produced is already ordinary Perl which shouldn't be filtered again.
- •
- Optimised away statements are rendered as '???'. This
includes statements that have a compile-time side-effect, such as the
obscure
my $x if 0;
foreach my $i (@_) { 0 } => foreach my $i (@_) { '???' }
- •
- Lexical (my) variables declared in scopes external to a subroutine appear in code2ref output text as package variables. This is a tricky problem, as perl has no native facility for referring to a lexical variable defined within a different scope, although PadWalker is a good start.
- •
- There are probably many more bugs on non-ASCII platforms (EBCDIC).
AUTHOR¶
Stephen McCamant <smcc@CSUA.Berkeley.EDU>, based on an earlier version by Malcolm Beattie <mbeattie@sable.ox.ac.uk>, with contributions from Gisle Aas, James Duncan, Albert Dvornik, Robin Houston, Dave Mitchell, Hugo van der Sanden, Gurusamy Sarathy, Nick Ing-Simmons, and Rafael Garcia-Suarez.2011-09-26 | perl v5.14.2 |