=head1 NAME

O - Generic interface to Perl Compiler backends
J<< ja; O - Perl コンパイラバックエンドへの汎用インターフェース >>

=head1 SYNOPSIS

	perl -MO=[-q,]Backend[,OPTIONS] foo.pl

=head1 DESCRIPTION

J<< ja;
これは Perl コンパイラへのフロントエンドとして使われる
モジュールです. 
>>
J<< en;
This is the module that is used as a frontend to the Perl Compiler.
>>

J<< ja;
モジュールに対して C<-q> オプションを渡すと, コンパイル中 STDOUT 
ファイルハンドルが C<$O::BEGIN_output> に対してリダイレクトされます. 
これによって BEGIN ブロックや use されたモジュールから STDOUT への出力が, 
出力される代わりにこの変数に格納されます. これは結果を出力するバックエンド
(C<Deparse>, C<Concise> 等)を使う際に便利です. そしてその出力はコンパイル
されているコードから生成される出力と混同しません. 
>>
J<< en;
If you pass the C<-q> option to the module, then the STDOUT
filehandle will be redirected into the variable C<$O::BEGIN_output>
during compilation.  This has the effect that any output printed
to STDOUT by BEGIN blocks or use'd modules will be stored in this
variable rather than printed. It's useful with those backends which
produce output themselves (C<Deparse>, C<Concise> etc), so that
their output is not confused with that generated by the code
being compiled.
>>

J<< ja;
C<-qq> オプションは C<-q> と同じように振る舞います. 違いは deparse 
終了時に STDERR を閉じることです. これは通常 perl が通常生成する 
"Syntax OK" メッセージを抑制します. 
>>
The C<-qq> option behaves like C<-q>, except that it also closes
STDERR after deparsing has finished. This suppresses the "Syntax OK"
message normally produced by perl.

=head1 CONVENTIONS
J<< ja; 慣例 >>

J<< ja;
多くのコンパイラバックエンドは次のような慣例を持っています: 
OPTIONS はコンマで区切られた(空白を持たない)単語のリストから成る.
C<-v> オプションは大抵バックエンドを verbose モードにする. 
C<-ofile> オプションは出力を標準出力ではなく B<file> に生成する. 
様々な文字が続く C<-D> オプションは内部でバッグフラグを有効にする. 
欲しているバックエンドに関するドキュメントも読んでください.
(以下ではC<B::Backend>とします.)
>>
J<< en;
Most compiler backends use the following conventions: OPTIONS
consists of a comma-separated list of words (no white-space).
The C<-v> option usually puts the backend into verbose mode.
The C<-ofile> option generates output to B<file> instead of
stdout. The C<-D> option followed by various letters turns on
various internal debugging flags. See the documentation for the
desired backend (named C<B::Backend> for the example above) to
find out about that backend.
>>

=head1 IMPLEMENTATION
J<< ja; 実装 >>

J<< ja;
このセクションではこのモジュールを通して使うことができる
コンパイラバックエンドモジュールを書こうとしている人にのみ
必要となります. 
>>
J<< en;
This section is only necessary for those who want to write a
compiler backend module that can be used via this module.
>>

J<< ja;
SYNOPSIS(概要)セクションにかかれているコマンドラインは以下のような Perl
コードに対応します. 
>>
J<< en;
The command-line mentioned in the SYNOPSIS section corresponds to
the Perl code
>>

    use O ("Backend", OPTIONS);

J<< ja;
C<import>と呼ばれる関数で適切なC<B::Backend>モジュールをロードし, 
そのパッケージのC<compile>関数を OPTIONS を渡して呼び出します.
この関数は CALLBACK と呼ばれる関数リファレンスを返す必要があります. 
次に, "コンパイルのみ" フラグ(コマンドラインオプション C<-c> と
等価です)が設定され, CALLBACK を呼び出すCHECKブロックが登録されます.
そしてコマンドラインで指定されているメインPerlプログラムが読み込まれ, 
parse, そして内部構文木形式へとコンパイルされます. C<-c>フラグが
設定されているときは, プログラムは実行を開始されません(もちろん
BEGINブロックは除いて)が, コンパイラバックエンドによって登録された
CALLBACK 関数は呼び出されます. 
>>
J<< en;
The C<import> function which that calls loads in the appropriate
C<B::Backend> module and calls the C<compile> function in that
package, passing it OPTIONS. That function is expected to return
a sub reference which we'll call CALLBACK. Next, the "compile-only"
flag is switched on (equivalent to the command-line option C<-c>)
and a CHECK block is registered which calls CALLBACK. Thus the main
Perl program mentioned on the command-line is read in, parsed and
compiled into internal syntax tree form. Since the C<-c> flag is
set, the program does not start running (excepting BEGIN blocks of
course) but the CALLBACK function registered by the compiler
backend is called.
>>

J<< ja;
要約すると, コンパイラバックエンドモジュールは "B::Foo" として
呼ばれるべきで, その名前に対応するディレクトリに配置します. 
そして C<compile> という関数を定義しなければ成りません. 
ユーザが次のように入力すると, 
>>
J<< en;
In summary, a compiler backend module should be called "B::Foo"
for some foo and live in the appropriate directory for that name.
It should define a function called C<compile>. When the user types
>>

    perl -MO=Foo,OPTIONS foo.pl

J<< ja;
その関数が呼び出され, OPTIONS (をコンマで切り分けた物)が引数として
渡されます. この関数はメインコンパイル関数となる関数リファレンスを
返さなければなりません. ユーザのプログラムがロード, そしてparseされ
ると, 関数が返した関数リファレンスが呼び出され, コンパイルを実行します. 
コンパイルは大抵 C<B> モジュールの機能を使って行われるでしょう. 
>>
J<< en;
that function is called and is passed those OPTIONS (split on
commas). It should return a sub ref to the main compilation function.
After the user's program is loaded and parsed, that returned sub ref
is invoked which can then go ahead and do the compilation, usually by
making use of the C<B> module's functionality.
>>

=head1 BUGS

J<< ja;
perl が PerlIO のサポート付きでコンパイルされていないと
C<-q> 及び C<-qq> オプションは正しく動作しません : C<$O::BEGIN_output> 
にリダイレクトされる代わりに STDOUT が閉じられるでしょう.
>>
J<< en;
The C<-q> and C<-qq> options don't work correctly if perl isn't
compiled with PerlIO support : STDOUT will be closed instead of being
redirected to C<$O::BEGIN_output>.
>>

=head1 AUTHOR

Malcolm Beattie, C<mbeattie@sable.ox.ac.uk>