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