=encoding utf8

=head1 NAME

=begin original

perlclass - Perl class syntax reference

=end original

perlclass - Perl クラス構文リファレンス

=head1 SYNOPSIS

    use v5.38;
    use feature 'class';

    class My::Example 1.234 {
        field $x;

        ADJUST {
            $x = "Hello, world";
        }

        method print_message {
            say $x;
        }
    }

    My::Example->new->print_message;

=head1 DESCRIPTION

=begin original

This document describes the syntax of Perl's C<class> feature, which provides
native keywords for object-oriented programming.

=end original

この文書では、オブジェクト指向プログラミングをサポートする
ネイティブなキーワードを提供する Perl の C<class> 機能の構文について
説明します。

=head2 History

(歴史)

=begin original

Since Perl 5, support for objects revolved around the concept of I<blessing>
references with a package name (see L<perlfunc/"bless REF,CLASSNAME">). Such a
reference could then be used to call subroutines from the package it was
blessed with (or any of its parents). This system, while bare-bones, was
flexible enough to allow creation of multiple more advanced, community-driven
systems for object orientation. For more information, see L<perlmod> and
L<perlobj>.

=end original

Perl 5 以降、オブジェクトのサポートは、パッケージ名によって
I<bless された> リファレンスの概念に基づいて拡張されました
(L<perlfunc/"bless REF,CLASSNAME"> 参照)。
このようなリファレンスは、bless されたパッケージ(またはその親のいずれか)から
サブルーチンを呼び出すために使えます。
このシステムは、必要最小限のものではありますが、オブジェクト指向のための
複数のより高度な、コミュニティ駆動システムの作成を可能にするのに
十分な柔軟性を備えていました。
さらなる情報については、L<perlmod> と L<perlobj> を参照してください。

=begin original

The C<class> feature is a core implementation of a class syntax that is similar
to what one would find in other programming languages. It is not a wrapper
around C<bless>, but a completely new system built right into the perl
interpreter.

=end original

C<class> 機能は、他のプログラミング言語で見られるものに似ている、
クラス構文のコア実装です。
これは C<bless> へのラッパーではなく、perl インタプリタに直接組み込まれた
全く新しいシステムです。

=head1 KEYWORDS

(キーワード)

=begin original

Enabling the C<class> feature allows the usage of the following new keywords in
the current lexical scope:

=end original

C<class> 機能を有効にすると、現在のレキシカルスコープ内で次の新しい
キーワードを使えます。

=head2 class

    class NAME BLOCK

    class NAME VERSION BLOCK

    class NAME VERSION : ATTRIBUTES... BLOCK

    class NAME;

    class NAME VERSION;

    class NAME VERSION : ATTRIBUTES...;

=begin original

The C<class> keyword declares a new package (see L<perlmod/Packages>) that is
intended to be a class. All other keywords from the C<class> feature should be
used within the scope of this declaration.

=end original

C<class>  キーワードは、クラスとして意図された新しいパッケージを宣言します
(L<perlmod/Packages> 参照)。
C<class>機能からの他のすべてのキーワードは、この宣言のスコープ内で
使われる必要があります。

    class WithVersion 1.000 {
        # class definition goes here
    }

=begin original

Classes can be declared in either block or statement syntax. If a block is
used, the body of the block contains the implementation of the class. If the
statement form is used, the remainder of the file is used up until the next
C<class> or C<package> statement.

=end original

クラスは、ブロック構文または文構文のいずれかで宣言できます。
ブロックを使う場合、ブロックの本体にはクラスの実装が含まれます。
文形式を使用する場合、ファイルの残りの部分は、次の
C<class> または C<package> ステートメントまで使い切られます。

=begin original

A C<class> declaration can optionally have a version number, similar to the
C<package> keyword. It can also optionally have attributes. If both are
specified, the version number must come first, before the attributes.

=end original

C<package> キーワードと同様に、C<class> 宣言にはオプションでバージョン番号を
持ちます。
また、オプションの属性も持ちます。
両方が指定された場合、バージョン番号は属性の前、先頭でなければなりません。

=begin original

C<class> and C<package> declarations are similar, but classes automatically get
a constructor named C<new> - you don't have to (and should not) write one.
Additionally, in the class BLOCK you are allowed to declare fields and methods.

=end original

C<class> と C<package> の宣言は似ていますが、クラスは自動的に C<new> という
名前のコンストラクタを取得します - 
あなたはこれを書く必要はありません(書くべきではありません)。
さらに、class の BLOCK の中では、フィールドとメソッドを宣言できます。

=head2 field

    field VARIABLE_NAME;

    field VARIABLE_NAME = EXPR;

    field VARIABLE_NAME : ATTRIBUTES;

    field VARIABLE_NAME : ATTRIBUTES = EXPR;

=begin original

Fields are variables that are visible in the scope of the class - more
specifically within L</method> and L<ADJUST|/Adjustment> blocks. Each class
instance gets its own storage of fields, independent of other instances.

=end original

フィールドは、クラスのスコープ内(より具体的には
L</method> および L<ADJUST|/Adjustment> ブロック内)で見える変数です。
各クラス実体は、フィールドのための他の実態と独立した独自の保管場所を
取得します。

=begin original

A field behaves like a normal lexically scoped variable. It has a sigil and is
private to the class (though creation of an accessor method will make it
accessible from the outside). The main difference is that different instances
access different values in the same scope.

=end original

フィールドは、通常のレキシカルスコープの変数のように振る舞います。
それには印(sigil)があり、クラスに対してプライベートです(ただし、
アクセサメソッドを作成すると、外部からアクセスできるようになります)。
主な違いは、異なる実体は同じスコープ内の異なる値にアクセスすることです。

    class WithFields {
        field $scalar = 42;
        field @array  = qw(this is just an array);
        field %hash   = (species => 'Martian', planet => 'Mars');
    }

=begin original

Fields may optionally have initializing expressions. If present, the expression
will be evaluated within the constructor of each object instance. During each
evaluation, the expression can use the value of any previously-set field, as
well as any other variables in scope.

=end original

フィールドは、オプションで初期化式を持つことができます。
存在する場合、式は各オブジェクト実体のコンストラクタ内で評価されます。
それぞれの評価中に、式はスコープ内の他の変数と同様、
それまでに設定されたフィールドの値を使用できます。

    class WithACounter {
        my $next_count = 1;
        field $count = $next_count++;
    }

=begin original

When combined with the C<:param> field attribute, the defaulting expression can
use any of the C<=>, C<//=> or C<||=> operators. Expressions using C<=> will
apply whenever the caller did not pass the corresponding parameter to the
constructor at all. Expressions using C<//=> will also apply if the caller did
pass the parameter but the value was undefined, and expressions using C<||=>
will apply if the value was false.

=end original

C<:param> フィールド属性と組み合わせた場合、デフォルト式では、
C<=>, C<//=>, C<||$=> 演算子のいずれかを使えます。
C<=> を使った式は、呼び出し側がコンストラクタに対応する引数を
まったく渡さなかった場合に適用されます。
C<//=> を使った式は、呼び出し側が引数を渡したが値が
未定義であった場合にも適用され、
C<||=> を使った式は、値が偽であった場合に適用されます。

=begin original

During a field initializing expression, the instance is not yet constructed
and so the C<$self> lexical is not available.  However, the special
C<__CLASS__> token may be used to obtain the name of the class being
constructed, for example in order to invoke class methods on it to help in
constructing values for fields.

=end original

フィールド初期化式の間、実体はまだ構築されていないので、
C<$self> レキシカル変数は利用できません。
しかし、例えばフィールドのための値の構築を助けるための
クラスメソッドを呼び出すために、
構築中のクラスの名前を得るために C<__CLASS__> トークンが使えます。

    class WithCustomField {
        use constant DEFAULT_X => 10;
        field $x = __CLASS__->DEFAULT_X;
    }

=begin original

This allows subclasses to override the method with different behaviour.

=end original

これにより、サブクラスが異なった振る舞いを持つメソッドを
オーバーライドできます。

    class DifferentCustomField :isa(WithCustomField) {
        sub DEFAULT_X { rand > 0.5 ? 20 : 30 }
    }

=begin original

When an instance of C<DifferentCustomField> is constructed, the C<__CLASS__>
expression in the base will yield the correct class name, and so invoke this
overridden method instead.

=end original

C<DifferentCustomField> の実体が構築されるとき、
基底クラスの C<__CLASS__> 式は正しいクラス名をもたらし、
オーバーライドされたメソッドを起動します。

=head2 method

    method METHOD_NAME SIGNATURE BLOCK

    method METHOD_NAME BLOCK

    method SIGNATURE BLOCK

    method BLOCK

=begin original

Methods are subroutines intended to be called in the context of class objects.

=end original

メソッドは、クラスオブジェクトのコンテキスト内で呼び出されることを目的とした
サブルーチンです。

=begin original

A variable named C<$self> populated with the current object instance will
automatically be created in the lexical scope of C<method>.

=end original

現在のオブジェクト実体が設定された C<$self> という名前の変数が、
C<method> のレキシカルスコープに自動的に作成されます。

=begin original

Methods always act as if C<use feature 'signatures'> is in effect, but C<$self>
will not appear in the arguments list as far as the signature is concerned.

=end original

メソッドは常に C<use feature 'signatures'> が有効であるかのように
動作しますが、C<$self> はシグニチャに関する限り引数リストには表示されません。

    class WithMethods {
        field $greetings;

        ADJUST {
            $greetings = "Hello";
        }

        method greet($name = "someone") {
            say "$greetings, $name";
        }
    }

=begin original

Just like regular subroutines, methods I<can> be anonymous:

=end original

通常のサブルーチンと同じように、メソッドは匿名にすることが I<できます>。

    class AnonMethodFactory {

        method get_anon_method {
            return method {
                return 'this is an anonymous method';
            };
        }
    }

=head1 ATTRIBUTES

(属性)

=begin original

Specific aspects of the keywords mentioned above are managed using
I<attributes>. Attributes all start with a colon, and one or more of them can
be appended after the item's name, separated by a space.

=end original

上述のキーワードの特定の様相は、I<属性> を使って管理されます。
属性はすべてコロンで始まり、一つまたは複数の属性をアイテム名の後に
スペースで区切って追加できます。

=head2 Class attributes

(クラス属性)

=head3 :isa

=begin original

Classes may inherit from B<one> superclass, by using the C<:isa> class
attribute.

=end original

クラスは、C<:isa> クラス属性を使用して、B<一つの> スーパークラスから
継承できます。

    class Example::Base { ... }

    class Example::Subclass :isa(Example::Base) { ... }

=begin original

Inherited methods are visible and may be invoked. Fields are always lexical
and therefore not visible by inheritance.

=end original

継承されたメソッドはアクセス可能で、呼び出すことができます。
フィールドは常にレキシカルであるため、継承によってアクセス可能にはなりません。

=begin original

The C<:isa> attribute may request a minimum version of the base class. As with
C<use MODULE VERSION>, if the actual version of the base class is too low,
compilation will fail.

=end original

C<:isa> 属性は、基本クラスの最小バージョンを要求する場合があります。
C<use MODULE VERSION> が使われている場合、基底クラスの実際のバージョンが
低すぎる場合、コンパイルは失敗します。

    class Example::Subclass :isa(Example::Base 2.345) { ... }

=begin original

The C<:isa> attribute will attempt to C<require> the named module if it is not
already loaded.

=end original

C<:isa> 属性は、指定されたモジュールがまだロードされていない場合、
そのモジュールを C<require> しようとします。

=head2 Field attributes

(フィールド属性)

=head3 :param

=begin original

A scalar field with a C<:param> attribute will take its value from a named
parameter passed to the constructor. By default the parameter will have the
same name as the field (minus its leading C<$> sigil), but a different name
can be specified in the attribute.

=end original

C<:param> 属性を持つスカラーフィールドは、コンストラクタに渡された
名前付き引数から値を取得します。
デフォルトでは、引数はフィールドと同じ名前 (先頭の C<$> 印を除く) を
持ちますが、属性で別の名前を指定できます。

    field $x :param;
    field $y :param(the_y_value);

=begin original

If there is no defaulting expression, then the parameter is required by the
constructor; the caller must pass it or an exception is thrown. With a
defaulting expression this becomes optional.

=end original

デフォルトの式がない場合、コンストラクタには引数が必要です;
呼び出し元はパラメータを渡す必要があり、渡さない場合は例外が投げられます。
デフォルトの式を使用すると、これはオプションになります。

=head3 :reader

=begin original

A field with a C<:reader> attribute will generate a reader accessor method
automatically.  The generated method will have an empty (i.e. zero-argument)
signature, and its body will simply return the value of the field variable.

=end original

A field with a 
C<:reader> 属性を持つフィールドは、読み込みアクセサメソッドを
自動的に生成します。
生成されたメソッドは空の(つまり 0 引数の)シグネチャを持ち、
その本体は単にフィールド変数の値を返します。

    field $s :reader;

    # Equivalent to
    field $s;
    method s () { return $s; }

=begin original

By default the accessor method will have the same name as the field (minus the
leading sigil), but a different name can be specified in the attribute's value.

=end original

デフォルトでは、アクセサメソッドはフィールドと同じ名前(から戦闘の印を
引いたもの)ですが、属性の値で違う名前を指定できます。

    field $x :reader(get_x);

    # Generates a method
    method get_x () { return $x; }

=begin original

Reader methods can be applied to non-scalar fields. When invoked in list
context, they yield the contents of the field; in scalar context they yield
the count of elements, as if the field variable had been placed in scalar
context.

=end original

読み込みメソッドは非スカラフィールドに適用できます。
リストコンテキストで起動された場合、
これらはフィールドの内容を返します; スカラコンテキストでは、
フィールド変数がスカラコンテキストに置かれたかのように、
要素の数を返します。

    field @users :reader;
    ...

    scalar $instance->users;

=head2 Method attributes

(メソッド属性)

=begin original

None yet.

=end original

まだありません。

=head1 OBJECT LIFECYCLE

(オブジェクトのライフサイクル)

=head2 Construction

(構築)

=begin original

Each object begins its life with a constructor call. The constructor is always
named C<new> and is invoked like a method call on the class name:

=end original

各オブジェクトは、コンストラクタ呼び出しから始まります。
コンストラクタは常に C<new> という名前で、クラス名に対する
メソッド呼び出しのように呼び出されます。

    my $object = My::Class->new(%arguments);

=begin original

During object construction, class fields are looked up in the C<%arguments>
hash and populated where possible.

=end original

オブジェクト構築中に、クラスフィールドは C<%arguments> ハッシュ内を
検索され、可能な場所では値が伝搬されます。

=head2 Adjustment

(調整)

=begin original

Object adjustment is a way to run arbitrary user-defined code during object
construction. This is done by placing code in C<ADJUST> blocks. Every time an
object is constructed, its C<ADJUST> blocks are executed (in the order in which
they are declared).

=end original

オブジェクトの調整は、オブジェクト定義中に任意のユーザ定義コードを実行する
方法です。
これは、C<ADJUST> ブロックにあるコードによって行われます。
オブジェクトが構築されると毎回、その C<ADJUST> ブロックが
(宣言された順番に)実行されます。

    class WellAdjusted {
        field $x :param;
        ADJUST {
            say "Hello!";
        }
        ADJUST {
            say "x = $x";
        }
    }

    my $object = WellAdjusted->new(x => 42);
    # Output:
    #   Hello!
    #   x = 42

=begin original

C<ADJUST> blocks are syntactically similar to L<C<BEGIN> or C<INIT>
blocks|perlmod/BEGIN, UNITCHECK, CHECK, INIT and END>, which only run once.
However, C<ADJUST> blocks, like methods, have access to C<$self> (a lexical
variable holding the object being constructed) as well as all object fields
created up to that point.

=end original

C<ADJUST> ブロックは、一度だけ実行される L<C<BEGIN> や C<INIT>
ブロック|perlmod/BEGIN, UNITCHECK, CHECK, INIT and END> に似ています。
しかし、C<ADJUST> ブロックはメソッドと同様、この時点で作られている
全てのオブジェクトフィールドと同様、C<$self> (構築されたオブジェクトを
保持しているレキシカル変数) にアクセスできます。

=head2 Lifetime

(生存期間)

=begin original

After the construction phase, the object is ready to be used.

=end original

構築フェーズの後、オブジェクトは使用可能な状態になります。

=begin original

Using C<blessed> (C<Scalar::Util::blessed> or C<builtin::blessed>) on the
object will return the name of the class, while C<reftype>
(C<Scalar::Util::reftype> or C<builtin::reftype>) will return the string
C<'OBJECT'>.

=end original

オブジェクトに対して C<blessed> (C<Scalar::Util::blessed> または
C<builtin::blessed>) を使うと、クラスの名前が返されます;
一方、C<reftype>(C<Scalar::Util::reftype> または C<builtin::reftype>) を
使うと、文字列 C<'OBJECT'> が返されます。

=head2 Destruction

(破棄)

=begin original

An object is destroyed when the last reference to it goes away, just as with
other data structures in Perl.

=end original

Perl の他のデータ構造と同様に、オブジェクトも最後の参照がなくなると、
破棄されます。

=head1 TODO

=begin original

This feature is still experimental and very incomplete. The following list
gives an overview of features still to be added or changed:

=end original

この機能はまだ実験的であり、非常に不完全です。
次のリストは、追加または変更される機能の概要を示しています。

=over 4

=item * Roles

(ロール)

=begin original

Some syntax for declaring a role (likely a C<role> keyword), and for consuming
a role into a class (likely a C<:does()> attribute).

=end original

(C<role> キーワードのような) ロールを宣言するための構文と、
(C<:does()> 属性のような) ロールをクラスに取り込むための構文。

=item * Parameters to ADJUST blocks

(ADJUST ブロックへの引数)

=begin original

Some syntax for declaring that an C<ADJUST> block can consume named
parameters, which become part of the class constructor's API. This might be
inspired by a similar plan to add named arguments to subroutine signatures.

=end original

C<ADJUST> ブロックがクラスコンストラクタの API の一部となる
名前付き引数を消費できることを宣言するためのいくつかの構文。
これは、名前付き引数をサブルーチンシグネチャに追加する
同様の計画に触発された可能性があります。

    class X {
        ADJUST (:$alpha, :$beta = 123) {
           ...
        }
    }

    my $obj = X->new(alpha => 456);

=item * ADJUST blocks as true blocks

(真のブロックとしての ADJUST ブロック)

=begin original

Currently, every ADJUST block is wrapped in its own CV (subroutine) that gets
invoked with the full ENTERSUB overhead. It should be possible to use the same
mechanism that makes all field initializer expressions appear within the same
CV on ADJUST blocks as well, merging them all into a single CV per class. This
will make it faster to invoke if a class has more than one of them.

=end original

現在、すべての ADJUST ブロックは、完全な ENTERSUB オーバーヘッドで
呼び出される独自の CV (サブルーチン)にラップされています。
すべてのフィールド初期化式を ADJUST ブロックの同じ CV 内に表示する
同じ機構を使って、クラスごとにすべてを
単一の CV にマージすることも可能です。
これにより、クラスに複数の CV がある場合の呼び出しが高速になります。

=item * More accessor generator attributes

(さらなるアクセサ生成属性)

=begin original

Attributes to request that other kinds of accessor methods be generated for
fields. Likely C<:writer>.

=end original

フィールドに対して他の種類のアクセサメソッドの生成を要求する属性。
C<:writer> が考えられます。

    class X {
        field $name :writer;
    }

=begin original

Equivalent to

=end original

次と同等です:

    class X {
        field $name;
        method set_name ($new) { $name = $new; return $self; }
    }

=item * Metaprogramming

(メタプログラミング)

=begin original

An extension of the metaprogramming API (currently proposed by
L<PPC0022|https://github.com/Perl/PPCs/pull/25>) which adds knowledge of
classes, methods, fields, ADJUST blocks, and other such class-related details.

=end original

(現在 L<PPC0022|https://github.com/Perl/PPCs/pull/25> によって
提案されている) メタプログラミング API の拡張で、クラス、メソッド、
フィールド、ADJUST ブロック、およびその他のクラス関連の
詳細に関する知識を追加します。

=item * Extension Customisation

(拡張のカスタマイズ)

=begin original

Ways in which out-of-core modules can interact with the class system,
including an ability for them to provide new class or field attributes.

=end original

コア外モジュールがクラスシステムと相互作用する方法;
これには、新しいクラスまたはフィールド属性を提供する機能が含まれます。

=back

=head1 KNOWN BUGS

=begin original

The following bugs have been found in the experimental C<class> feature:

=end original

実験的な C<class> 機能には、次のバグが発見されています:

=over 4

=item *

=begin original

Since Perl v5.38, inheriting from a parent class which is declared in the same
file and which hadn't already been sealed can cause a segmentation fault.
[L<GH #20890|https://github.com/Perl/perl5/issues/20890>]

=end original

Perl v5.38 から、同じファイルにあってすでに閉じていない親クラスから
継承すると、セグメンテーションフォルトを起こすことがあります。
[L<GH #20890|https://github.com/Perl/perl5/issues/20890>]

=item *

=begin original

Since Perl v5.38 and with the experimental C<refaliasing> feature, trying to
replace a field variable causes a segmentation fault.
[L<GH #20947|https://github.com/Perl/perl5/issues/20947>]

=end original

Perl v5.38 から、実験的な C<refaliasing> 機能が有効の場合、
フィールド変数を置き換えようとするとセグメンテーションフォルトを
引き起こします。
[L<GH #20947|https://github.com/Perl/perl5/issues/20947>]

=item *

=begin original

Since Perl v5.38, it's possible to craft a class with leaky encapsulation,
which can cause a segmentation fault.
[L<GH #20956|https://github.com/Perl/perl5/issues/20956>]

=end original

Perl v5.38 から、細工して、
セグメンテーションフォルトを引き起こすことがある、
リークのあるクラスを作ることができます。
[L<GH #20956|https://github.com/Perl/perl5/issues/20956>]

=item *

=begin original

In Perl v5.38, inheriting from a class would not always attempt to load the
parent class (fixed in Perl v5.40).
[L<GH #21332|https://github.com/Perl/perl5/issues/21332>]

=end original

Perl v5.38 で、クラスからの継承が、常に親クラスを
読み込もうとしませんでした(Perl 5.40 で修正されました)。
[L<GH #21332|https://github.com/Perl/perl5/issues/21332>]

=back

=head1 AUTHORS

Paul Evans

Bartosz Jarzyna

=begin meta

Translate: SHIRAKATA Kentaro <argrath@ub32.org>
Status: completed

=end meta

=cut