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