


B::Deparse(3p)   Perl Programmers Reference Guide  B::Deparse(3p)


NAME
       B::Deparse - Perl compiler backend to produce perl code

SYNOPSIS
       perl -MO=Deparse[,-uPACKAGE][,-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 pro-
       gram. 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 cor-
       respondence 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.

       Please note that this module is mainly new and untested
       code and is still under development, so it may change in
       the future.

OPTIONS
       As with all compiler backend options, these must follow
       directly after the '-MO=Deparse', separated by a comma but
       not any white space.

       -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) when-
           ever 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";

           "B::Deparse,-p" will print

               if (($var & 0)) {
                   print('Gimme an A!')
               };
               (print(($which ? $a : $b)), '???');
               (($name = $ENV{'USER'}) or '???')

           which probably isn't what you intended (the "'???'" is



2001-05-24                 perl v5.6.1                          1





B::Deparse(3p)   Perl Programmers Reference Guide  B::Deparse(3p)


           a sign that perl optimized away a constant value).

       -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!";

           as

               print 'Hello, ' . $world . ', ' . join($", @ladies) . ', '
                     . ucfirst($gentlemen) . ', ' . ucfirst(lc $me . '!');

           Note that the expanded form represents the way perl
           handles such constructions internally -- this option
           actually turns off the reverse translation that
           B::Deparse usually does. On the other hand, note that
           "$x = "$y"" is not the same as "$x = $y": the former
           makes the value of $y into a string before doing the
           assignment.

       -uPACKAGE
           Normally, B::Deparse deparses the main code of a pro-
           gram, all the subs called by the main program (and all
           the subs called by them, recursively), and any other
           subs in the main:: package. To include subs in other
           packages that aren't called directly, such as
           AUTOLOAD, DESTROY, other subs called automatically by
           perl, and methods (which aren't resolved to subs until
           runtime), use the -u option. The argument to -u is the
           name of a package, and should follow directly after
           the 'u'. Multiple -u options may be given, separated
           by commas.  Note that unlike some other backends,
           B::Deparse doesn't (yet) try to guess automatically
           when -u is needed -- you must invoke it yourself.

       -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 {
                        ...
                   }

               instead of






2001-05-24                 perl v5.6.1                          2





B::Deparse(3p)   Perl Programmers Reference Guide  B::Deparse(3p)


                   if (...) {
                        ...
                   }
                   else {
                        ...
                   }

               The default is not to cuddle.

           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"'Use-
               less use of constant omitted'."  or something sim-
               ilar 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 equiva-
           lent 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.

           If LEVEL is at least 3, for loops will be translated
           into equivalent while loops with continue blocks; for
           instance






2001-05-24                 perl v5.6.1                          3





B::Deparse(3p)   Perl Programmers Reference Guide  B::Deparse(3p)


               for ($i = 0; $i < 10; ++$i) {
                   print $i;
               }

           turns into

               $i = 0;
               while ($i < 10) {
                   print $i;
               } continue {
                   ++$i
               }

           Note that in a few cases this translation can't be
           perfectly carried back into the source code -- if the
           loop's initializer declares a my variable, for
           instance, it won't have the correct scope outside of
           the loop.

           If LEVEL is at least 7, if statements will be trans-
           lated into equivalent expressions using "&&", "?:" and
           "do {}"; for instance

               print 'hi' if $nice;
               if ($nice) {
                   print 'hi';
               }
               if ($nice) {
                   print 'hi';
               } else {
                   print 'bye';
               }

           turns into

               $nice and print 'hi';
               $nice and do { print 'hi' };
               $nice ? do { print 'hi' } : do { print 'bye' };

           Long sequences of elsifs will turn into nested ternary
           operators, which B::Deparse doesn't know how to indent
           nicely.

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







2001-05-24                 perl v5.6.1                          4





B::Deparse(3p)   Perl Programmers Reference Guide  B::Deparse(3p)


       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 opera-
       tion and any options. The options are the same as those
       that can be given on the command line (see the OPTIONS
       entry elsewhere in this document); options that are sepa-
       rated by commas after -MO=Deparse should be given as sepa-
       rate strings. Some options, like -u, don't make sense for
       a single subroutine, so don't pass them.

       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
       See the 'to do' list at the beginning of the module file.

AUTHOR
       Stephen McCamant <smcc@CSUA.Berkeley.EDU>, based on an
       earlier version by Malcolm Beattie <mbeat-
       tie@sable.ox.ac.uk>, with contributions from Gisle Aas,
       James Duncan, Albert Dvornik, Hugo van der Sanden,
       Gurusamy Sarathy, and Nick Ing-Simmons.
















2001-05-24                 perl v5.6.1                          5


