| 1 | package O; |
| 2 | |
| 3 | our $VERSION = '1.00'; |
| 4 | |
| 5 | use B qw(minus_c save_BEGINs); |
| 6 | use Carp; |
| 7 | |
| 8 | sub import { |
| 9 | my ($class, @options) = @_; |
| 10 | my ($quiet, $veryquiet) = (0, 0); |
| 11 | if ($options[0] eq '-q' || $options[0] eq '-qq') { |
| 12 | $quiet = 1; |
| 13 | open (SAVEOUT, ">&STDOUT"); |
| 14 | close STDOUT; |
| 15 | open (STDOUT, ">", \$O::BEGIN_output); |
| 16 | if ($options[0] eq '-qq') { |
| 17 | $veryquiet = 1; |
| 18 | } |
| 19 | shift @options; |
| 20 | } |
| 21 | my $backend = shift (@options); |
| 22 | eval q[ |
| 23 | BEGIN { |
| 24 | minus_c; |
| 25 | save_BEGINs; |
| 26 | } |
| 27 | |
| 28 | CHECK { |
| 29 | if ($quiet) { |
| 30 | close STDOUT; |
| 31 | open (STDOUT, ">&SAVEOUT"); |
| 32 | close SAVEOUT; |
| 33 | } |
| 34 | |
| 35 | # Note: if you change the code after this 'use', please |
| 36 | # change the fudge factors in B::Concise (grep for |
| 37 | # "fragile kludge") so that its output still looks |
| 38 | # nice. Thanks. --smcc |
| 39 | use B::].$backend.q[ (); |
| 40 | if ($@) { |
| 41 | croak "use of backend $backend failed: $@"; |
| 42 | } |
| 43 | |
| 44 | |
| 45 | my $compilesub = &{"B::${backend}::compile"}(@options); |
| 46 | if (ref($compilesub) ne "CODE") { |
| 47 | die $compilesub; |
| 48 | } |
| 49 | |
| 50 | local $savebackslash = $\; |
| 51 | local ($\,$",$,) = (undef,' ',''); |
| 52 | &$compilesub(); |
| 53 | |
| 54 | close STDERR if $veryquiet; |
| 55 | } |
| 56 | ]; |
| 57 | die $@ if $@; |
| 58 | } |
| 59 | |
| 60 | 1; |
| 61 | |
| 62 | __END__ |
| 63 | |
| 64 | =head1 NAME |
| 65 | |
| 66 | O - Generic interface to Perl Compiler backends |
| 67 | |
| 68 | =head1 SYNOPSIS |
| 69 | |
| 70 | perl -MO=[-q,]Backend[,OPTIONS] foo.pl |
| 71 | |
| 72 | =head1 DESCRIPTION |
| 73 | |
| 74 | This is the module that is used as a frontend to the Perl Compiler. |
| 75 | |
| 76 | If you pass the C<-q> option to the module, then the STDOUT |
| 77 | filehandle will be redirected into the variable C<$O::BEGIN_output> |
| 78 | during compilation. This has the effect that any output printed |
| 79 | to STDOUT by BEGIN blocks or use'd modules will be stored in this |
| 80 | variable rather than printed. It's useful with those backends which |
| 81 | produce output themselves (C<Deparse>, C<Concise> etc), so that |
| 82 | their output is not confused with that generated by the code |
| 83 | being compiled. |
| 84 | |
| 85 | The C<-qq> option behaves like C<-q>, except that it also closes |
| 86 | STDERR after deparsing has finished. This suppresses the "Syntax OK" |
| 87 | message normally produced by perl. |
| 88 | |
| 89 | =head1 CONVENTIONS |
| 90 | |
| 91 | Most compiler backends use the following conventions: OPTIONS |
| 92 | consists of a comma-separated list of words (no white-space). |
| 93 | The C<-v> option usually puts the backend into verbose mode. |
| 94 | The C<-ofile> option generates output to B<file> instead of |
| 95 | stdout. The C<-D> option followed by various letters turns on |
| 96 | various internal debugging flags. See the documentation for the |
| 97 | desired backend (named C<B::Backend> for the example above) to |
| 98 | find out about that backend. |
| 99 | |
| 100 | =head1 IMPLEMENTATION |
| 101 | |
| 102 | This section is only necessary for those who want to write a |
| 103 | compiler backend module that can be used via this module. |
| 104 | |
| 105 | The command-line mentioned in the SYNOPSIS section corresponds to |
| 106 | the Perl code |
| 107 | |
| 108 | use O ("Backend", OPTIONS); |
| 109 | |
| 110 | The C<import> function which that calls loads in the appropriate |
| 111 | C<B::Backend> module and calls the C<compile> function in that |
| 112 | package, passing it OPTIONS. That function is expected to return |
| 113 | a sub reference which we'll call CALLBACK. Next, the "compile-only" |
| 114 | flag is switched on (equivalent to the command-line option C<-c>) |
| 115 | and a CHECK block is registered which calls CALLBACK. Thus the main |
| 116 | Perl program mentioned on the command-line is read in, parsed and |
| 117 | compiled into internal syntax tree form. Since the C<-c> flag is |
| 118 | set, the program does not start running (excepting BEGIN blocks of |
| 119 | course) but the CALLBACK function registered by the compiler |
| 120 | backend is called. |
| 121 | |
| 122 | In summary, a compiler backend module should be called "B::Foo" |
| 123 | for some foo and live in the appropriate directory for that name. |
| 124 | It should define a function called C<compile>. When the user types |
| 125 | |
| 126 | perl -MO=Foo,OPTIONS foo.pl |
| 127 | |
| 128 | that function is called and is passed those OPTIONS (split on |
| 129 | commas). It should return a sub ref to the main compilation function. |
| 130 | After the user's program is loaded and parsed, that returned sub ref |
| 131 | is invoked which can then go ahead and do the compilation, usually by |
| 132 | making use of the C<B> module's functionality. |
| 133 | |
| 134 | =head1 BUGS |
| 135 | |
| 136 | The C<-q> and C<-qq> options don't work correctly if perl isn't |
| 137 | compiled with PerlIO support : STDOUT will be closed instead of being |
| 138 | redirected to C<$O::BEGIN_output>. |
| 139 | |
| 140 | =head1 AUTHOR |
| 141 | |
| 142 | Malcolm Beattie, C<mbeattie@sable.ox.ac.uk> |
| 143 | |
| 144 | =cut |