ktats****@users*****
ktats****@users*****
2013年 4月 24日 (水) 03:19:25 JST
Index: docs/perl/5.14.2/ext/attributes/attributes.pod diff -u /dev/null docs/perl/5.14.2/ext/attributes/attributes.pod:1.1 --- /dev/null Wed Apr 24 03:19:25 2013 +++ docs/perl/5.14.2/ext/attributes/attributes.pod Wed Apr 24 03:19:25 2013 @@ -0,0 +1,869 @@ +=encoding euc-jp + +=head1 NAME + +=begin original + +attributes - get/set subroutine or variable attributes + +=end original + +attributes - 変数若しくは関数の属性を取得/設定 + +=head1 SYNOPSIS + + sub foo : method ; + my ($x, ＠ y,%z) : Bent = 1; + my $s = sub : method { ... }; + + use attributes (); # optional, to get subroutine declarations + # 任意, 関数宣言用. + my @attrlist = attributes::get(\&foo); + + use attributes 'get'; # import the attributes::get subroutine + # attributes::get 関数のインポート. + my @attrlist = get \&foo; + +=head1 DESCRIPTION + +=begin original + +Subroutine declarations and definitions may optionally have attribute lists +associated with them. (Variable C<my> declarations also may, but see the +warning below.) Perl handles these declarations by passing some information +about the call site and the thing being declared along with the attribute +list to this module. In particular, the first example above is equivalent to +the following: + +=end original + +関数の宣言と定義ではそれに関連した属性のリストを任意で持つことが +できます. (変数の C<my> 宣言もできますが, 後述の警告も参照して +ください.) Perl はこれらの宣言を, 呼び出す場所と属性リストと +ともに宣言されようとしているものの情報をこのモジュールに渡すことで +これらの宣言を処理します. 特に, 上の最初の例は次のものと等価です: + + use attributes __PACKAGE__, \&foo, 'method'; + +=begin original + +The second example in the synopsis does something equivalent to this: + +=end original + +2番目の概要にある例は、次と等価です: + + use attributes (); + my ($x, ＠ y,%z); + attributes::->import(__PACKAGE__, \$x, 'Bent'); + attributes::->import(__PACKAGE__, \@y, 'Bent'); + attributes::->import(__PACKAGE__, \%z, 'Bent'); + ($x, ＠ y,%z) = 1; + +=begin original + +Yes, that's a lot of expansion. + +=end original + +ここでは多くの展開がなされます. + +=begin original + +B<WARNING>: attribute declarations for variables are still evolving. +The semantics and interfaces of such declarations could change in +future versions. They are present for purposes of experimentation +with what the semantics ought to be. Do not rely on the current +implementation of this feature. + +=end original + +B<警告>: 変数に対する属性の宣言はまだ進歩の途上にあります. +これらの宣言の意味とインターフェースは今後のバージョンで +変更される可能性があります. これらは今後くる意味を体験する +のを目的として提供されています. この機能の現在の実装には +頼らないでください. + +=begin original + +There are only a few attributes currently handled by Perl itself (or +directly by this module, depending on how you look at it.) However, +package-specific attributes are allowed by an extension mechanism. +(See L<"Package-specific Attribute Handling"> below.) + +=end original + +現在 Perl 自身(若しくは見方によってはこのモジュールが直接)で +処理される属性はわずかです. しかし, あるパッケージ用の属性という +ものが拡張メカニズムとして使うことができます. (後述の +L<"Package-specific Attribute Handling">を参照してください.) + +=begin original + +The setting of subroutine attributes happens at compile time. +Variable attributes in C<our> declarations are also applied at compile time. +However, C<my> variables get their attributes applied at run-time. +This means that you have to I<reach> the run-time component of the C<my> +before those attributes will get applied. For example: + +=end original + +関数の属性の設定はコンパイル時に起きます. C<our> 宣言での変数属性も +コンパイル時に適用されます. しかし, C<my> 変数は実行時に属性の +適用が行われます. これは属性が適用される前に C<my> の実行時構成に +I<到達>しなければならないことを意味します. 例えば: + + my $x : Bent = 42 if 0; + +=begin original + +will neither assign 42 to $x I<nor> will it apply the C<Bent> attribute +to the variable. + +=end original + +は $x に 42 を代入することI<も>変数に C<Bent> 属性が適用される +こともありません. + +=begin original + +An attempt to set an unrecognized attribute is a fatal error. (The +error is trappable, but it still stops the compilation within that +C<eval>.) Setting an attribute with a name that's all lowercase +letters that's not a built-in attribute (such as "foo") will result in +a warning with B<-w> or C<use warnings 'reserved'>. + +=end original + +知らない属性の設定は致命的なエラーとなります. (このエラーは +トラップできますが, その C<eval> の中でコンパイルは停止します.) +全てが小文字からなるけれど組み込みの属性ではない名前(例えば”foo") +を設定すると B<-w> 若しくは C<use warnings 'reserved'> では +警告を発生します. + +=begin original + +=head2 What C<import> does + +=end original + +=head2 C<import> が行うこと + +=begin original + +In the description it is mentioned that + +=end original + +詳しく言うと, 次の宣言が行っていることは + + sub foo : method; + +=begin original + +is equivalent to + +=end original + +次と等価です. + + use attributes __PACKAGE__, \&foo, 'method'; + +=begin original + +As you might know this calls the C<import> function of C<attributes> at compile +time with these parameters: 'attributes', the caller's package name, the reference +to the code and 'method'. + +=end original + +恐らくは知っているように, これはC<attributes> の C<import> 関数を +コンパイル時に以下のパラメータで呼び出します: 'attributes', +呼び出し元のパッケージ名, コードへのリファレンス及び 'method'. + + attributes->import( __PACKAGE__, \&foo, 'method' ); + +=begin original + +So you want to know what C<import> actually does? + +=end original + +そして C<import> が実際に何がやっているかが知りたいんだっけ? + +=begin original + +First of all C<import> gets the type of the third parameter ('CODE' in this case). +C<attributes.pm> checks if there is a subroutine called C<< MODIFY_<reftype>_ATTRIBUTES >> +in the caller's namespace (here: 'main'). In this case a subroutine C<MODIFY_CODE_ATTRIBUTES> is +required. Then this method is called to check if you have used a "bad attribute". +The subroutine call in this example would look like + +=end original + +まず最初に C<import> は３番目のパラメータの型を取得します(このケースであれば 'CODE'). +C<attribute.pm> は C<< MODIFY_<reftype>_ATTRIBUTES >> という関数が呼び出し元 +(ここでは 'main')にあるかを調べます. 今回は C<MODIFY_CODE_ATTRIBUTES> を確認します. +そしてこのメソッドは"間違った属性"を使っていないかを調べるために呼び出します. +この関数呼び出しは次のようになります: + + MODIFY_CODE_ATTRIBUTES( 'main', \&foo, 'method' ); + +=begin original + +C<< MODIFY_<reftype>_ATTRIBUTES >> has to return a list of all "bad attributes". +If there are any bad attributes C<import> croaks. + +(See L<"Package-specific Attribute Handling"> below.) + +=end original + +C<< MODIFY_<reftype>_ATTRIBUTES >> は"間違った属性"のリストを返さなければなりません. +もしなんらかの間違った属性があれば C<import> は croak します. + +(後述の L<"Package-specific Attribute Handling"> を参照.) + +=begin original + +=head2 Built-in Attributes + +=end original + +=head2 組み込みの属性 + +=begin original + +The following are the built-in attributes for subroutines: + +=end original + +以下のものは関数用の組み込み属性です + +=over 4 + +=item lvalue + +=begin original + +Indicates that the referenced subroutine is a valid lvalue and can +be assigned to. The subroutine must return a modifiable value such +as a scalar variable, as described in L<perlsub>. + +=end original + +参照された関数は左辺値(lvalue)として有効であり代入可能である +ことを示します. 関数は L<perlsub> で説明されているように +変更することのできる値, 例えばスカラー変数等を返さなければ +なりません. + +=item method + +=begin original + +Indicates that the referenced subroutine is a method. A subroutine so marked +will not trigger the "Ambiguous call resolved as CORE::%s" warning. + +=end original + +参照された関数はメソッドであると提示します. これでマークされた関数は +"Ambiguous call resolved as CORE::%s" (CORE::%sとして処理される曖昧な呼び出し）警告は発生させません. + +=item locked + +=begin original + +The "locked" attribute has no effect in 5.10.0 and later. It was used as part +of the now-removed "Perl 5.005 threads". + +=end original + +"locked"属性は 5.10.0以降で何も起きません.これは,今は削除された"Perl 5.005 threads" +の一部として使われていました. + +=back + +=begin original + +=head2 Available Subroutines + +=end original + +=head2 提供されている関数 + +=begin original + +The following subroutines are available for general use once this module +has been loaded: + +=end original + +以下の関数は一般的な使用のためにこのモジュールをロード +したときに提供されます. + +=over 4 + +=item get + +=begin original + +This routine expects a single parameter--a reference to a +subroutine or variable. It returns a list of attributes, which may be +empty. If passed invalid arguments, it uses die() (via L<Carp::croak|Carp>) +to raise a fatal exception. If it can find an appropriate package name +for a class method lookup, it will include the results from a +C<FETCH_I<type>_ATTRIBUTES> call in its return list, as described in +L<"Package-specific Attribute Handling"> below. +Otherwise, only L<built-in attributes|"Built-in Attributes"> will be returned. + +=end original + +このルーチンは１つのパラメータ -- 関数若しくは変数へのリファレンスを +受け取ります. そして属性の一覧を返します, これは空かもしれません. +正しくない引数を渡した場合は, 致命的な例外を投げるために +(L<Carp::croak|Carp> を通して) die() を呼び出します. +もしメソッド探索に適切なパッケージ名を見つけることが出来たのなら, +後述の L<"Package-specific Attribute Handling"> にあるように +その返されるリストに C<< FETCH_I<type>_ATTRIBUTES >> からの +結果も含めます. +そうでなければ L<組み込みの属性|"Built-in Attributes">のみが返されます. + +=item reftype + +=begin original + +This routine expects a single parameter--a reference to a subroutine or +variable. It returns the built-in type of the referenced variable, +ignoring any package into which it might have been blessed. +This can be useful for determining the I<type> value which forms part of +the method names described in L<"Package-specific Attribute Handling"> below. + +=end original + +この関数は１つのパラメータ -- 関数若しくは変数へのリファレンスを +受け取ります. これは bless されていたとしてもパッケージ名を +無視して, 参照されている変数の組み込み型を返します. +これは後述の L<"Package-specific Attribute Handling"> で +説明されているメソッド名の一部を構成する I<type> 値を決定するのに +便利です. + +=back + +=begin original + +=back + +Note that these routines are I<not> exported by default. + +=end original + +これらの関数はデフォルトではエクスポートされI<ません>. + +=begin original + +=head2 Package-specific Attribute Handling + +=end original + +=head2 パッケージ別の属性処理 + +=begin original + +B<WARNING>: the mechanisms described here are still experimental. Do not +rely on the current implementation. In particular, there is no provision +for applying package attributes to 'cloned' copies of subroutines used as +closures. (See L<perlref/"Making References"> for information on closures.) +Package-specific attribute handling may change incompatibly in a future +release. + +=end original + +B<警告>: ここで説明されているメカニズムは未だ実験段階です. +現在の実装を当てにしないでください. 特に, クロージャとして +使われている関数の 'cloneされた' 複製に対する +パッケージ属性の適用に関しては何も大作はありません. +(クロージャに関する詳細は L<perlref/"Making References"> を参照.) +パッケージ別の属性処理は今度のリリースで互換性なしに変更される可能性があります. + +=begin original + +When an attribute list is present in a declaration, a check is made to see +whether an attribute 'modify' handler is present in the appropriate package +(or its @ISA inheritance tree). Similarly, when C<attributes::get> is +called on a valid reference, a check is made for an appropriate attribute +'fetch' handler. See L<"EXAMPLES"> to see how the "appropriate package" +determination works. + +=end original + +宣言に属性リストが指定されていると, +適切なパッケージ(若しくはその @ISA 継承ツリー)の中で +属性'変更(modify)'ハンドラが見つかるかどうか確認します. +同じように, 有効なリファレンスに対して C<attributes::get> を +呼び出すと, 適切な'取得(fetch)'ハンドラを確認します. +"適切なパッケージ"がどのように決定されるかは L<"EXAMPLES"> を +参照してください. + +=begin original + +The handler names are based on the underlying type of the variable being +declared or of the reference passed. Because these attributes are +associated with subroutine or variable declarations, this deliberately +ignores any possibility of being blessed into some package. Thus, a +subroutine declaration uses "CODE" as its I<type>, and even a blessed +hash reference uses "HASH" as its I<type>. + +=end original + +ハンドラ名は宣言されようとしてる変数若しくは渡されたリファレンスの +型を元にしています. これらの属性は関数若しくは変数の宣言に +関連づけられているため, これはどこかのパッケージに bless されようとしてる +可能性を故意に無視しています. 従って関数宣言はその I<type> に +"CODE" を使い, ブレスされたハッシュリファレンスであってもその I<type> に +"HASH" を使います. + +=begin original + +The class methods invoked for modifying and fetching are these: + +=end original + +変更若しくは取得に呼び出されるクラスメソッドには以下の物があります: + +=over 4 + +=item FETCH_I<type>_ATTRIBUTES + +=begin original + +This method is called with two arguments: the relevant package name, +and a reference to a variable or subroutine for which package-defined +attributes are desired. The expected return value is a list of +associated attributes. This list may be empty. + +=end original + +このメソッドは２つの引数で呼び出されます: 関連するパッケージ名 +及びパッケージが定義する属性を要望する変数若しくは関数へのリファレンス. +予期される戻り値は関連づけられた属性のリストです. +リストは空になることもあります. + +=item MODIFY_I<type>_ATTRIBUTES + +=begin original + +This method is called with two fixed arguments, followed by the list of +attributes from the relevant declaration. The two fixed arguments are +the relevant package name and a reference to the declared subroutine or +variable. The expected return value is a list of attributes which were +not recognized by this handler. Note that this allows for a derived class +to delegate a call to its base class, and then only examine the attributes +which the base class didn't already handle for it. + +=end original + +このメソッドは２つの固定の引数と, 関連する宣言からの属性のリストを伴って +呼び出されます. ２つの固定引数は関連するパッケージ名と宣言された +関数若しくは変数です. 予期される戻り値はこのハンドラで認識されなかった +属性のリストです. これは派生クラスが基底クラスへの呼び出しを代理 +することができ, その後でのみ基底クラスが既に処理を行わなかった +属性を検査できます. + +=begin original + +The call to this method is currently made I<during> the processing of the +declaration. In particular, this means that a subroutine reference will +probably be for an undefined subroutine, even if this declaration is +actually part of the definition. + +=end original + +このメソッドの呼び出しは現在は宣言の処理のI<間に>行われます. +特に, これはこの宣言が実際に定義の一部であったとしても +関数リファレンスは未定義の関数かもしれないことを意味します. + +=back + +=begin original + +Calling C<attributes::get()> from within the scope of a null package +declaration C<package ;> for an unblessed variable reference will +not provide any starting package name for the 'fetch' method lookup. +Thus, this circumstance will not result in a method call for package-defined +attributes. A named subroutine knows to which symbol table entry it belongs +(or originally belonged), and it will use the corresponding package. +An anonymous subroutine knows the package name into which it was compiled +(unless it was also compiled with a null package declaration), and so it +will use that package name. + +=end original + +null パッケージ宣言 C<package ;> のスコープでブレスされていない変数への +リファレンスを伴って C<attributes::get()> 呼び出しを行った場合, +これは'取得(fetch)'メソッド探索のための開始パッケージ名を提供 +しません. +従って, この状態ではパッケージ定義の属性のためのメソッド呼び出しには +なりません. 名前付きの関数はそれが所属する(若しくは最初に所属していた) +シンボルテーブルエントリを知っているので, それに対応するパッケージを使います. +無名関数はそれがコンパイルされたパッケージ名を(そこが null パッケージ宣言内 +だった場合を除けば)知っているので, そのパッケージ名を使います. + +=begin original + +=head2 Syntax of Attribute Lists + +=end original + +=head2 属性リストの構文 + +=begin original + +An attribute list is a sequence of attribute specifications, separated by +whitespace or a colon (with optional whitespace). +Each attribute specification is a simple +name, optionally followed by a parenthesised parameter list. +If such a parameter list is present, it is scanned past as for the rules +for the C<q()> operator. (See L<perlop/"Quote and Quote-like Operators">.) +The parameter list is passed as it was found, however, and not as per C<q()>. + +=end original + +属性リストはスペース若しくはコロン(と省略可能なスペース)で区切られた +属性指定の並びです. それぞれの属性指定は単純な名前で, +省略可能な括弧で囲まれたパラメータリストが続きます. +もしパラメータリストが提供されていれば, それは C<q()> 演算子のルールで +スキャンされます. (L<perlop/"Quote and Quote-like Operators"> 参照.) +パラメータリストは見つかったまま渡されますが, C<q()> によりません. + +=begin original + +Some examples of syntactically valid attribute lists: + +=end original + +構文的に正しい属性リストのいくつかの例: + + switch(10,foo(7,3)) : expensive + Ugly('\(") :Bad + _5x5 + lvalue method + +=begin original + +Some examples of syntactically invalid attribute lists (with annotation): + +=end original + +構文的に正しくない属性リストのいくつかの例(と説明): + + switch(10,foo() # ()-string not balanced + Ugly('(') # ()-string not balanced + 5x5 # "5x5" not a valid identifier + Y2::north # "Y2::north" not a simple identifier + foo + bar # "+" neither a colon nor whitespace + +=head1 EXPORTS + + +=begin original + +=head2 Default exports + +=end original + +=head2 デフォルトのエクスポート + +=begin original + +None. + +=end original + +なし. + +=begin original + +=head2 Available exports + +=end original + +=head2 提供可能なエクスポート + +=begin original + +The routines C<get> and C<reftype> are exportable. + +=end original + +C<get> 及び C<reftype> がエクスポート可能です. + +=begin original + +=head2 Export tags defined + +=end original + +=head2 定義されているエクスポートタグ + +=begin original + +The C<:ALL> tag will get all of the above exports. + +=end original + +C<:ALL> タグで前述のエクスポート関数全てを取り出します. + +=head1 EXAMPLES + +=begin original + +Here are some samples of syntactically valid declarations, with annotation +as to how they resolve internally into C<use attributes> invocations by +perl. These examples are primarily useful to see how the "appropriate +package" is found for the possible method lookups for package-defined +attributes. + +=end original + +構文的に正しい宣言のいくつかの例とそれらが perl によって +どのように C<use attributes> 呼び出しとなるかの説明. +これらの例は"適切なパッケージ"がどうやってパッケージ定義属性のための +メソッド探索の為に見つけ出されるかを見るのに主に役立ちます. + +=over 4 + +=item 1. + +=begin original + +Code: + +=end original + +コード: + + package Canine; + package Dog; + my Canine $spot : Watchful ; + +=begin original + +Effect: + +=end original + +効果: + + use attributes (); + attributes::->import(Canine => \$spot, "Watchful"); + +=item 2. + +=begin original + +Code: + +=end original + +コード: + + package Felis; + my $cat : Nervous; + +=begin original + +Effect: + +=end original + +効果: + + use attributes (); + attributes::->import(Felis => \$cat, "Nervous"); + +=item 3. + +=begin original + +Code: + +=end original + +コード: + + package X; + sub foo : lvalue ; + +=begin original + +Effect: + +=end original + +効果: + + use attributes X => \&foo, "lvalue"; + +=item 4. + +=begin original + +Code: + +=end original + +コード: + + package X; + sub Y::x : lvalue { 1 } + +=begin original + +Effect: + +=end original + +効果: + + use attributes Y => \&Y::x, "lvalue"; + +=item 5. + +=begin original + +Code: + +=end original + +コード: + + package X; + sub foo { 1 } + + package Y; + BEGIN { *bar = \&X::foo; } + + package Z; + sub Y::bar : lvalue ; + +=begin original + +Effect: + +=end original + +効果: + + use attributes X => \&X::foo, "lvalue"; + +=back + +=begin original + +This last example is purely for purposes of completeness. You should not +be trying to mess with the attributes of something in a package that's +not your own. + +=end original + +最後の例は純粋に完全性のためだけです. +自分のものでないパッケージの何らかの属性にちょっかいをだすべきではありません. + +=begin original + +=head1 MORE EXAMPLES + +=end original + +=head1 もっと例 + +=over 4 + +=item 1. + + sub MODIFY_CODE_ATTRIBUTES { + my ($class,$code, ＠ attrs) = @_; + + my $allowed = 'MyAttribute'; + my @bad = grep { $_ ne $allowed } @attrs; + + return @bad; + } + + sub foo : MyAttribute { + print "foo\n"; + } + +=begin original + +This example runs. At compile time C<MODIFY_CODE_ATTRIBUTES> is called. In that +subroutine, we check if any attribute is disallowed and we return a list of +these "bad attributes". + +=end original + +この例は動作します. コンパイル時に C<MODIFY_CODE_ATTRIBUTES> が +呼び出されます. この関数で何らかの属性が許可されていないかを調べて +それら"間違った属性"のリストを返します. + +=begin original + +As we return an empty list, everything is fine. + +=end original + +空のリストを返したのなら, 全部大丈夫です. + +=item 2. + + sub MODIFY_CODE_ATTRIBUTES { + my ($class,$code, ＠ attrs) = @_; + + my $allowed = 'MyAttribute'; + my @bad = grep{ $_ ne $allowed }@attrs; + + return @bad; + } + + sub foo : MyAttribute Test { + print "foo\n"; + } + +=begin original + +This example is aborted at compile time as we use the attribute "Test" which +isn't allowed. C<MODIFY_CODE_ATTRIBUTES> returns a list that contains a single +element ('Test'). + +=end original + +この例は許可していない属性 "Test" を使っているために実行時にアボートします. +C<MODIFY_CODE_ATTRIBUTES> は１つの要素('Test')を含んだリストを返します. + +=back + +=head1 SEE ALSO + +=begin original + +L<perlsub/"Private Variables via my()"> and +L<perlsub/"Subroutine Attributes"> for details on the basic declarations; +L<perlfunc/use> for details on the normal invocation mechanism. + +=end original + +基本的な宣言の詳細は L<perlsub/"Private Variables via my()"> 及び +L<perlsub/"Subroutine Attributes"> +通常の呼び出し機構の詳細は L<perlfunc/use>. + +=head1 和訳 + + 山科 氷魚 (YAMASHINA Hio) <hio****@hio*****> (5.8.9) + Kato Atsushi (5.14.2-) + +=begin meta + +Translate: YAMASHINA Hio +Update: Kato Atsushi (5.14.2-) +Status: completed + +=end meta
