argra****@users*****
argra****@users*****
2009年 1月 3日 (土) 03:53:34 JST
Index: docs/perl/5.8.8/perlxs.pod diff -u docs/perl/5.8.8/perlxs.pod:1.7 docs/perl/5.8.8/perlxs.pod:1.8 --- docs/perl/5.8.8/perlxs.pod:1.7 Thu Jan 1 04:45:25 2009 +++ docs/perl/5.8.8/perlxs.pod Sat Jan 3 03:53:34 2009 @@ -48,10 +48,8 @@ B<XSUB> は XS インターフェースの基本単位を形成します。 B<xsubpp> コンパイラによるコンパイル後、 -each XSUB amounts to a C function definition -which will provide the glue between Perl calling conventions and C -calling conventions. -(TBT) +それぞれの XSUB は Perl 呼び出し規則と C 呼び出し規則の間の糊を提供する +C 関数定義となります。 =begin original @@ -65,14 +63,13 @@ =end original -The glue code pulls the arguments from the Perl stack, converts these -Perl values to the formats expected by a C function, call this C function, -transfers the return values of the C function back to Perl. -Return values here may be a conventional C return value or any C -function arguments that may serve as output parameters. These return -values may be passed back to Perl either by putting them on the -Perl stack, or by modifying the arguments supplied from the Perl side. -(TBT) +糊のコードは Perl スタックから引数を取り出し、Perl の値を C 関数が +想定している形式に変換し、C 関数を酔いだし、C 関数の返り値を Perl に +返します。 +ここでの返り値は、伝統的な C の返り値か、出力パラメータの役目をする +C 関数引数です。 +これらの返り値は、Perl スタックに置かれるか、Perl 側から供給された +引数を変更することによって Perl に返されます。 =begin original @@ -86,14 +83,12 @@ =end original -The above is a somewhat simplified view of what really happens. Since -Perl allows more flexible calling conventions than C, XSUBs may do much -more in practice, such as checking input parameters for validity, -throwing exceptions (or returning undef/empty list) if the return value -from the C function indicates failure, calling different C functions -based on numbers and types of the arguments, providing an object-oriented -interface, etc. -(TBT) +上記は実際に起きることをいくらか単純化したものです。 +Perl は C よりもより柔軟な呼び出し規則を認めているので、 +実際には XSUB は、検証のために入力をチェックする、もし C 関数からの +返り値が失敗を示していたら例外を投げる(あるいは undef/空リストを返す)、 +引数の数と型によって異なった C 関数を呼び出す、オブジェクト指向 +インターフェースを提供する、といった、遥かに多くのことができます。 =begin original @@ -107,14 +102,13 @@ =end original -もちろん、このような糊コードを直接 C で書くこともできます。 +もちろん、このような糊のコードを直接 C で書くこともできます。 しかし、これはつまらない仕事です; 特に複数の C 関数に対する糊を書く 必要があったり、Perl スタックの分野やその奥義に親しくない場合はそうです。 XS はこれを助けます: -instead of writing this glue C code in long-hand, one can write -a more concise short-hand I<description> of what should be done by -the glue, and let the XS compiler B<xsubpp> handle the rest. -(TBT) +糊の C コードを長々と書く代わりに、糊にしてほしいことに関する、 +もっと簡潔で短い I<記述> を書いて、XS コンパイラ B<xsubpp> に +残りを扱わせることができます。 =begin original @@ -133,16 +127,13 @@ XS 言語は、どのように C ルーチンが使うのかと、どのように対応する Perl ルーチンが使うのかとのマッピングを記述できます。 -It -also allows creation of Perl routines which are directly translated to -C code and which are not related to a pre-existing C function. In cases -when the C interface coincides with the Perl interface, the XSUB -declaration is almost identical to a declaration of a C function (in K&R -style). In such circumstances, there is another tool called C<h2xs> -that is able to translate an entire C header file into a corresponding -XS file that will provide glue to the functions/macros described in -the header file. -(TBT) +これはまた、直接 C コードに変換され、既に存在する C 関数と関係ない +Perl ルーチンの作成も可能にします。 +C インターフェースが Perl インターフェースと同期している場合、 +XSUB 宣言はほとんど (K&R 形式の) C 関数の宣言と同じです。 +このような事情から、C ヘッダ全体から、ヘッダファイルに記述されている +関数/マクロへの糊を提供する XS ファイルへ変換する、C<h2xs> と呼ばれる +もう一つのツールがあります。 =begin original @@ -181,11 +172,10 @@ XS 形式のファイルは、最初の C<MODULE =Z<>> 指示子が現れるまで C 言語 セクションから開始します。 その他の XS 指示子と XSUB 定義はこの行に続きます。 -The "language" used in this part of the file -is usually referred to as the XS language. B<xsubpp> recognizes and -skips POD (see L<perlpod>) in both the C and XS language sections, which -allows the XS file to contain embedded documentation. -(TBT) +ファイルのこの部分で使われる「言語」は普通 XS 言語として参照されます。 +B<xsubpp> は C と XS の言語セクションで POD (L<perlpod> を +参照してください)を認識して呼び飛ばすので、XS ファイルに組み込み +ドキュメントを含めることができます。 =begin original @@ -363,10 +353,8 @@ =end original -The simplest XSUBs consist of 3 parts: a description of the return -value, the name of the XSUB routine and the names of its arguments, -and a description of types or formats of the arguments. -(TBT) +もっとも単純な XSUB は 3 つの部分からなります: 返り値の記述、XSUB +ルーチンの名前とその引数の名前、引数の型や形式の記述です。 =begin original Index: docs/perl/5.8.8/perlxstut.pod diff -u docs/perl/5.8.8/perlxstut.pod:1.7 docs/perl/5.8.8/perlxstut.pod:1.8 --- docs/perl/5.8.8/perlxstut.pod:1.7 Thu Jan 1 04:45:25 2009 +++ docs/perl/5.8.8/perlxstut.pod Sat Jan 3 03:53:34 2009 @@ -88,12 +88,12 @@ =end original -When writing a Perl extension for general consumption, one should expect that -the extension will be used with versions of Perl different from the -version available on your machine. Since you are reading this document, -the version of Perl on your machine is probably 5.005 or later, but the users -of your extension may have more ancient versions. -(TBT) +一般向けに Perl エクステンションを書くとき、あなたのマシンで +利用可能なバージョンと異なるバージョンの Perl でエクステンションが +使われることを想定するべきです。 +この文書を読んでいるということは、あなたのマシンの Perl のバージョンは +おそらく 5.005 以降でしょうが、エクステンションのユーザーはもっと古い +バージョンかもしれません。 =begin original @@ -103,7 +103,7 @@ =end original -どのような非互換性が想定されるかを理解するために、、また珍しい場合として +どのような非互換性が想定されるかを理解するために、また珍しい場合として、 マシンに入っている Perl のバージョンがこのドキュメントより古い場合、 さらなる情報は "Troubleshooting these Examples" の章を参照してください。 @@ -117,12 +117,11 @@ =end original -If your extension uses some features of Perl which are not available on older -releases of Perl, your users would appreciate an early meaningful warning. -You would probably put this information into the F<README> file, but nowadays -installation of extensions may be performed automatically, guided by F<CPAN.pm> -module or other tools. -(TBT) +もしエクステンションが、Perl の古いリリースでは利用できないような Perl の +機能を使っているなら、ユーザーは早期の意味のある警告で理解します。 +おそらくこの情報を F<README> ファイルに追加するべきでしょうが、最近の +エクステンションのインストールは、F<CPAN.pm> モジュールやその他の +ツールによって自動的に行われるかもしれません。 =begin original @@ -1519,6 +1518,8 @@ =head2 Anatomy of .xs file +(.xs ファイルの解剖) + =begin original The .xs file of L<"EXAMPLE 4"> contained some new elements. To understand @@ -1540,11 +1541,11 @@ =end original -Anything before this line is plain C code which describes which headers -to include, and defines some convenience functions. No translations are -performed on this part, apart from having embedded POD documentation -skipped over (see L<perlpod>) it goes into the generated output C file as is. -(TBT) +この行以前の全てはインクルードするヘッダおよび便利な関数を定義した +プレーンな C コードです。 +この部分では、組み込みの POD 文書が読み飛ばされる(L<perlpod> を +参照してください)ことを除いては何の変換は行われず、そのまま出力 C ファイルが +出力されます。 =begin original @@ -1555,11 +1556,9 @@ =end original -Anything after this line is the description of XSUB functions. -These descriptions are translated by B<xsubpp> into C code which -implements these functions using Perl calling conventions, and which -makes these functions visible from Perl interpreter. -(TBT) +この行以降の全ては XSUB 関数の記述です。 +これらの記述は、関数を Perl 呼び出し規則を使って実装し、関数が Perl +インタプリタから見えるように、B<xsubpp> が C コードに変換します。 =begin original @@ -1570,11 +1569,10 @@ =end original -Pay a special attention to the function C<constant>. This name appears -twice in the generated .xs file: once in the first part, as a static C -function, then another time in the second part, when an XSUB interface to -this static C function is defined. -(TBT) +C<constant> 関数には特別な注意を払ってください。 +この名前は生成された .xs ファイルに 2 回現れます: +1 回目は最初の部分に static C 関数として、2 回目は 2 番目の部分に、 +この static C 関数への XSUB インターフェースが定義されたときです。 =begin original @@ -1588,17 +1586,19 @@ =end original -This is quite typical for .xs files: usually the .xs file provides -an interface to an existing C function. Then this C function is defined -somewhere (either in an external library, or in the first part of .xs file), -and a Perl interface to this function (i.e. "Perl glue") is described in the -second part of .xs file. The situation in L<"EXAMPLE 1">, L<"EXAMPLE 2">, -and L<"EXAMPLE 3">, when all the work is done inside the "Perl glue", is -somewhat of an exception rather than the rule. -(TBT) +これは .xs ファイルではかなり典型的です: 普通 .xs ファイルは既にある +C 関数へのインターフェースを提供します。 +それからこの C 関数はどこか(外部ライブラリか、.xs ファイルの最初の部分)で +定義され、この関数への Perl インターフェース(つまり「Perl の糊」)が +.xs ファイルの 2 番目の部分に記述されます。 +L<"EXAMPLE 1">, L<"EXAMPLE 2">, L<"EXAMPLE 3"> の状況、 +つまり全ての動作が「Perl の糊」の内側で行われるときは、 +規則ではなく何らかの例外があります。 =head2 Getting the fat out of XSUBs +(太った部分を XSUB の外に出す) + =begin original In L<"EXAMPLE 4"> the second part of .xs file contained the following @@ -1626,12 +1626,11 @@ =end original -Note that in contrast with L<"EXAMPLE 1">, L<"EXAMPLE 2"> and L<"EXAMPLE 3">, -this description does not contain the actual I<code> for what is done -is done during a call to Perl function foo(). +L<"EXAMPLE 1">, L<"EXAMPLE 2">, L<"EXAMPLE 3"> と比較して、この記述は +Perl 関数 foo() の呼び出しに何が起きているのかの実際の I<コード> は +含んでいません。 ここで何が起きているのかを理解するために、この XSUB に CODE セクションを 追加できます: -(TBT) double foo(a,b,c) @@ -1656,15 +1655,15 @@ =end original -However, these two XSUBs provide almost identical generated C code: B<xsubpp> -compiler is smart enough to figure out the C<CODE:> section from the first -two lines of the description of XSUB. What about C<OUTPUT:> section? In -fact, that is absolutely the same! The C<OUTPUT:> section can be removed -as well, I<as far as C<CODE:> section or C<PPCODE:> section> is not -specified: B<xsubpp> can see that it needs to generate a function call -section, and will autogenerate the OUTPUT section too. Thus one can -shortcut the XSUB to become: -(TBT) +しかし、これら 2 つの XSUB はほとんど同じ C コードを生成します: +B<xsubpp> コンパイラは、XSUB の記述の最初の 2 行から +C<CODE:> セクションを見つけ出すことができるぐらい賢いです。 +C<OUTPUT:> セクションについてはどうでしょう? +実際、これは全く同じです! +I<C<CODE:> セクションや C<PPCODE:> セクションが指定されない限り>、 +C<OUTPUT:> セクションも同様に削除でき、同様に OUTPUT セクションを +自動生成します。 +従って、XSUB を以下のように省略できます: double foo(a,b,c) @@ -1697,8 +1696,8 @@ =end original で出来るでしょうか? -これをするためには、C 関数 C<int is_even(int input)> を定義する必要が -あります。 +これをするためには、C 関数 C<int is_even(int input)> を定義する +必要があります。 L<Anatomy of .xs file> で見たように、この定義に適切な場所は .xs ファイルの 最初の部分です。 実際、C 関数 @@ -1747,14 +1746,13 @@ =end original -This technique of separation of the glue part from the workhorse part has -obvious tradeoffs: if you want to change a Perl interface, you need to -change two places in your code. However, it removes a lot of clutter, -and makes the workhorse part independent from idiosyncrasies of Perl calling -convention. (In fact, there is nothing Perl-specific in the above description, -a different version of B<xsubpp> might have translated this to TCL glue or -Python glue as well.) -(TBT) +実際の動作の部分から糊の部分を分離する技術は明らかなトレードオフです: +もし Perl インターフェースをしようとすると、コードの 2 箇所を変更する +必要があります。 +しかし、これは多くの乱雑なものを取り除き、実際の動作の部分を Perl 呼び出し +規則の特異性から独立させます。 +(実際のところ、上述の記述には Perl 固有のものはなく、異なるバージョンの +B<xsubpp> はこれを TCL の糊や Python の糊にも変換できるかもしれません。) =head2 More about XSUB arguments @@ -2172,13 +2170,14 @@ =end original -This extension is very Unix-oriented (struct statfs and the statfs system -call). If you are not running on a Unix system, you can substitute for -statfs any other function that returns multiple values, you can hard-code -values to be returned to the caller (although this will be a bit harder -to test the error case), or you can simply not do this example. If you -change the XSUB, be sure to fix the test cases to match the changes. -(TBT) +このエクステンションはとても Unix 指向です(struct statfs と +statfs システムコール)。 +もし Unix システム以外で実行するなら、statfs を複数の値を返す別の関数に +置き換えるか、呼び出し元に返す値をハードコーディングする(しかしこれは +エラーの場合をテストするのが少し難しくなります)か、あるいは単に +この例を実行しないということもできます。 +もし XSUB を変更したなら、テストケースも変更にあわせて確実に +修正してください。 =begin original
