5.16.1 > attributes
5.16.1
Other versions:
5.14.2
attributes-0.09

名前

attributes - get/set subroutine or variable attributes

attributes - 変数若しくは関数の属性を取得/設定

概要

  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;

説明

Subroutine declarations and definitions may optionally have attribute lists associated with them. (Variable 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:

関数の宣言と定義ではそれに関連した属性のリストを任意で持つことが できます. (変数の my 宣言もできますが, 後述の警告も参照して ください.) Perl はこれらの宣言を, 呼び出す場所と属性リストと ともに宣言されようとしているものの情報をこのモジュールに渡すことで これらの宣言を処理します. 特に, 上の最初の例は次のものと等価です:

    use attributes __PACKAGE__, \&foo, 'method';

The second example in the synopsis does something equivalent to this:

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;

Yes, that's a lot of expansion.

ここでは多くの展開がなされます.

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.

警告: 変数に対する属性の宣言はまだ進歩の途上にあります. これらの宣言の意味とインターフェースは今後のバージョンで 変更される可能性があります. これらは今後くる意味を体験する のを目的として提供されています. この機能の現在の実装には 頼らないでください.

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 "Package-specific Attribute Handling" below.)

現在 Perl 自身(若しくは見方によってはこのモジュールが直接)で 処理される属性はわずかです. しかし, あるパッケージ用の属性という ものが拡張メカニズムとして使うことができます. (後述の "Package-specific Attribute Handling"を参照してください.)

The setting of subroutine attributes happens at compile time. Variable attributes in our declarations are also applied at compile time. However, my variables get their attributes applied at run-time. This means that you have to reach the run-time component of the my before those attributes will get applied. For example:

関数の属性の設定はコンパイル時に起きます. our 宣言での変数属性も コンパイル時に適用されます. しかし, my 変数は実行時に属性の 適用が行われます. これは属性が適用される前に my の実行時構成に 到達しなければならないことを意味します. 例えば:

    my $x : Bent = 42 if 0;

will neither assign 42 to $x nor will it apply the Bent attribute to the variable.

は $x に 42 を代入すること変数に Bent 属性が適用される こともありません.

An attempt to set an unrecognized attribute is a fatal error. (The error is trappable, but it still stops the compilation within that 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 -w or use warnings 'reserved'.

知らない属性の設定は致命的なエラーとなります. (このエラーは トラップできますが, その eval の中でコンパイルは停止します.) 全てが小文字からなるけれど組み込みの属性ではない名前(例えば”foo") を設定すると -w 若しくは use warnings 'reserved' では 警告を発生します.

What import does

import が行うこと

In the description it is mentioned that

詳しく言うと, 次の宣言が行っていることは

  sub foo : method;

is equivalent to

次と等価です.

  use attributes __PACKAGE__, \&foo, 'method';

As you might know this calls the import function of attributes at compile time with these parameters: 'attributes', the caller's package name, the reference to the code and 'method'.

恐らくは知っているように, これはattributesimport 関数を コンパイル時に以下のパラメータで呼び出します: 'attributes', 呼び出し元のパッケージ名, コードへのリファレンス及び 'method'.

  attributes->import( __PACKAGE__, \&foo, 'method' );

So you want to know what import actually does?

そして import が実際に何がやっているかが知りたいんだっけ?

First of all import gets the type of the third parameter ('CODE' in this case). attributes.pm checks if there is a subroutine called MODIFY_<reftype>_ATTRIBUTES in the caller's namespace (here: 'main'). In this case a subroutine 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

まず最初に import は3番目のパラメータの型を取得します(このケースであれば 'CODE'). attribute.pmMODIFY_<reftype>_ATTRIBUTES という関数が呼び出し元 (ここでは 'main')にあるかを調べます. 今回は MODIFY_CODE_ATTRIBUTES を確認します.そしてこの メソッドは"間違った属性"を使っていないかを調べるために呼び出します. この関数呼び出しは次のようになります:

  MODIFY_CODE_ATTRIBUTES( 'main', \&foo, 'method' );

MODIFY_<reftype>_ATTRIBUTES has to return a list of all "bad attributes". If there are any bad attributes import croaks.

(See "Package-specific Attribute Handling" below.)

MODIFY_<reftype>_ATTRIBUTES は"間違った属性"のリストを返さなければなりません. もしなんらかの間違った属性があれば import は croak します.

(後述の "Package-specific Attribute Handling" を参照.)

Built-in Attributes

組み込みの属性

The following are the built-in attributes for subroutines:

以下のものは関数用の組み込み属性です

lvalue

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 perlsub.

参照された関数は左辺値(lvalue)として有効であり代入可能である ことを示します. 関数は perlsub で説明されているように 変更することのできる値, 例えばスカラー変数等を返さなければ なりません.

This module allows one to set this attribute on a subroutine that is already defined. For Perl subroutines (XSUBs are fine), it may or may not do what you want, depending on the code inside the subroutine, with details subject to change in future Perl versions. You may run into problems with lvalue context not being propagated properly into the subroutine, or maybe even assertion failures. For this reason, a warning is emitted if warnings are enabled. In other words, you should only do this if you really know what you are doing. You have been warned.

このモジュールは定義済みの関数に,この属性を設定することを許します. Perlの関数(XSUBsは大丈夫)にとって,それは,関数内のコードに依存して, あなたの望むことをするかもしれないし,しないかもしれません. 詳細は将来のPerlのバージョンで変更される可能性があります. 関数に対して,適切でない lvalue コンテキストを使うと,問題か,多分,失敗のアサートに ぶちあたるでしょう.そういうわけで,warningsを有効にしていると,警告が発生します(訳注 おそらく5.16.0以降). 言い換えれば,自分が何をしているか本当にわかっている場合のみに, それをすべきです.警告しましたからね.

method

Indicates that the referenced subroutine is a method. A subroutine so marked will not trigger the "Ambiguous call resolved as CORE::%s" warning.

参照された関数はメソッドであると 提示します. これでマークされた関数は "Ambiguous call resolved as CORE::%s" (CORE::%sとして処理される曖昧な呼び出し)警告は発生させません.

locked

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".

"locked"属性は 5.10.0以降で何も起きません.これは,今は削除された"Perl 5.005 threads" の一部として使われていました.

Available Subroutines

提供されている関数

The following subroutines are available for general use once this module has been loaded:

以下の関数は一般的な使用のためにこのモジュールをロード したときに提供されます.

get

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 Carp::croak) 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 FETCH_type_ATTRIBUTES call in its return list, as described in "Package-specific Attribute Handling" below. Otherwise, only built-in attributes will be returned.

このルーチンは1つのパラメータ -- 関数若しくは変数へのリファレンスを 受け取ります. そして属性の一覧を返します, これは空かもしれません. 正しくない引数を渡した場合は, 致命的な例外を投げるために (Carp::croak を通して) die() を呼び出します. もしメソッド探索に適切なパッケージ名を見つけることが出来たのなら, 後述の "Package-specific Attribute Handling" にあるように その返されるリストに FETCH_type_ATTRIBUTES からの 結果も含めます. そうでなければ 組み込みの属性のみが返されます.

reftype

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 type value which forms part of the method names described in "Package-specific Attribute Handling" below.

この関数は1つのパラメータ -- 関数若しくは変数へのリファレンスを 受け取ります. これは bless されていたとしてもパッケージ名を 無視して, 参照されている変数の組み込み型を返します. これは後述の "Package-specific Attribute Handling" で 説明されているメソッド名の一部を構成する type 値を決定するのに 便利です.

Note that these routines are not exported by default.

これらの関数はデフォルトではエクスポートされません.

Package-specific Attribute Handling

パッケージ別の属性処理

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 "Making References" in perlref for information on closures.) Package-specific attribute handling may change incompatibly in a future release.

警告: ここで説明されているメカニズムは未だ実験段階です. 現在の実装を当てにしないでください. 特に, クロージャとして 使われている関数の 'cloneされた' 複製に対する パッケージ属性の適用に関しては何も大作はありません. (クロージャに関する詳細は "Making References" in perlref を参照.) パッケージ別の属性処理は今度のリリースで互換性なしに変更される可能性があります.

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 attributes::get is called on a valid reference, a check is made for an appropriate attribute 'fetch' handler. See "EXAMPLES" to see how the "appropriate package" determination works.

宣言に属性リストが指定されていると, 適切なパッケージ(若しくはその @ISA 継承ツリー)の中で 属性'変更(modify)'ハンドラが見つかるかどうか確認します. 同じように, 有効なリファレンスに対して attributes::get を 呼び出すと, 適切な'取得(fetch)'ハンドラを確認します. "適切なパッケージ"がどのように決定されるかは "EXAMPLES" を 参照してください.

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 type, and even a blessed hash reference uses "HASH" as its type.

ハンドラ名は宣言されようとしてる変数若しくは渡されたリファレンスの 型を元にしています. これらの属性は関数若しくは変数の宣言に 関連づけられているため, これはどこかのパッケージに bless されようとしてる 可能性を故意に無視しています. 従って関数宣言はその type に "CODE" を使い, ブレスされたハッシュリファレンスであってもその type に "HASH" を使います.

The class methods invoked for modifying and fetching are these:

変更若しくは取得に呼び出されるクラスメソッドには以下の物があります:

FETCH_type_ATTRIBUTES

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.

このメソッドは2つの引数で呼び出されます: 関連するパッケージ名 及びパッケージが定義する属性を要望する変数若しくは関数へのリファレンス. 予期される戻り値は関連づけられた属性のリストです. リストは空になることもあります.

MODIFY_type_ATTRIBUTES

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.

このメソッドは2つの固定の引数と, 関連する宣言からの属性のリストを伴って 呼び出されます. 2つの固定引数は関連するパッケージ名と宣言された 関数若しくは変数です. 予期される戻り値はこのハンドラで認識されなかった 属性のリストです. これは派生クラスが基底クラスへの呼び出しを代理 することができ, その後でのみ基底クラスが既に処理を行わなかった 属性を検査できます.

The call to this method is currently made 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.

このメソッドの呼び出しは現在は宣言の処理の間に行われます. 特に, これはこの宣言が実際に定義の一部であったとしても 関数リファレンスは未定義の関数かもしれないことを意味します.

Calling attributes::get() from within the scope of a null package declaration 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.

null パッケージ宣言 package ; のスコープでブレスされていない変数への リファレンスを伴って attributes::get() 呼び出しを行った場合, これは'取得(fetch)'メソッド探索のための開始パッケージ名を提供 しません. 従って, この状態ではパッケージ定義の属性のためのメソッド呼び出しには なりません. 名前付きの関数はそれが所属する(若しくは最初に所属していた) シンボルテーブルエントリを知っているので, それに対応するパッケージを使います. 無名関数はそれがコンパイルされたパッケージ名を(そこが null パッケージ宣言内 だった場合を除けば)知っているので, そのパッケージ名を使います.

Syntax of Attribute Lists

属性リストの構文

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 q() operator. (See "Quote and Quote-like Operators" in perlop.) The parameter list is passed as it was found, however, and not as per q().

属性リストはスペース若しくはコロン(と省略可能なスペース)で区切られた 属性指定の並びです. それぞれの属性指定は単純な名前で, 省略可能な括弧で囲まれたパラメータリストが続きます. もしパラメータリストが提供されていれば, それは q() 演算子のルールで スキャンされます. ("Quote and Quote-like Operators" in perlop 参照.) パラメータリストは見つかったまま渡されますが, q() によりません.

Some examples of syntactically valid attribute lists:

構文的に正しい属性リストのいくつかの例:

    switch(10,foo(7,3))  :  expensive
    Ugly('\(") :Bad
    _5x5
    lvalue method

Some examples of syntactically invalid attribute lists (with annotation):

構文的に正しくない属性リストのいくつかの例(と説明):

    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

EXPORTS

Default exports

デフォルトのエクスポート

None.

なし.

Available exports

提供可能なエクスポート

The routines get and reftype are exportable.

get 及び reftype がエクスポート可能です.

Export tags defined

定義されているエクスポートタグ

The :ALL tag will get all of the above exports.

:ALL タグで前述のエクスポート関数全てを取り出します.

Here are some samples of syntactically valid declarations, with annotation as to how they resolve internally into 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.

構文的に正しい宣言のいくつかの例とそれらが perl によって どのように use attributes 呼び出しとなるかの説明. これらの例は"適切なパッケージ"がどうやってパッケージ定義属性のための メソッド探索の為に見つけ出されるかを見るのに主に役立ちます.

  1. Code:

    コード:

        package Canine;
        package Dog;
        my Canine $spot : Watchful ;

    Effect:

    効果:

        use attributes ();
        attributes::->import(Canine => \$spot, "Watchful");
  2. Code:

    コード:

        package Felis;
        my $cat : Nervous;

    Effect:

    効果:

        use attributes ();
        attributes::->import(Felis => \$cat, "Nervous");
  3. Code:

    コード:

        package X;
        sub foo : lvalue ;

    Effect:

    効果:

        use attributes X => \&foo, "lvalue";
  4. Code:

    コード:

        package X;
        sub Y::x : lvalue { 1 }

    Effect:

    効果:

        use attributes Y => \&Y::x, "lvalue";
  5. Code:

    コード:

        package X;
        sub foo { 1 }
    
        package Y;
        BEGIN { *bar = \&X::foo; }
    
        package Z;
        sub Y::bar : lvalue ;

    Effect:

    効果:

        use attributes X => \&X::foo, "lvalue";

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.

最後の例は純粋に完全性のためだけです. 自分のものでないパッケージの何らかの属性にちょっかいをだすべきではありません.

MORE EXAMPLES

もっと例

  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";
        }

    This example runs. At compile time MODIFY_CODE_ATTRIBUTES is called. In that subroutine, we check if any attribute is disallowed and we return a list of these "bad attributes".

    この例は動作します. コンパイル時に MODIFY_CODE_ATTRIBUTES が呼び出されます. この関数で何らかの属性が許可されていないかを調べて それら"間違った属性"のリストを返します.

    As we return an empty list, everything is fine.

    空のリストを返したのなら, 全部大丈夫です.

  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";
      }

    This example is aborted at compile time as we use the attribute "Test" which isn't allowed. MODIFY_CODE_ATTRIBUTES returns a list that contains a single element ('Test').

    この例は許可していない属性 "Test" を使っているために実行時にアボートします. MODIFY_CODE_ATTRIBUTES は1つの要素('Test')を含んだリストを返します.

SEE ALSO

"Private Variables via my()" in perlsub and "Subroutine Attributes" in perlsub for details on the basic declarations; "use" in perlfunc for details on the normal invocation mechanism.

基本的な宣言の詳細は "Private Variables via my()" in perlsub 及び "Subroutine Attributes" in perlsub 通常の呼び出し機構の詳細は "use" in perlfunc.

和訳

 山科 氷魚 (YAMASHINA Hio) <hio@hio.jp> (5.8.9)
 Kato Atsushi (5.14.2-)