Commit | Line | Data |
---|---|---|
920dae64 AT |
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 |