=encoding utf8

=head1 NAME

=begin original

C<Feature::Compat::Class> - make C<class> syntax available

=end original

C<Feature::Compat::Class> - C<class> シンタックスを使えるようにします

=head1 SYNOPSIS

   use Feature::Compat::Class;

   class Point {
      field $x :param = 0;
      field $y :param = 0;

      method move_to ($new_x, $new_y) {
         $x = $new_x;
         $y = $new_y;
      }

      method describe {
         say "A point at ($x, $y)";
      }
   }

   Point->new(x => 5, y => 10)->describe;

=head1 DESCRIPTION

=begin original

This module provides the new C<class> keyword and related others (C<method>,
C<field> and C<ADJUST>) in a forward-compatible way.

There is a branch of Perl development source code which provides this syntax,
under the C<class> named feature. If all goes well, this will become available
in a stable release in due course. On such perls that contain the feature,
this module simple enables it.

On older versions of perl before such syntax is availble in core, it is
currently provided instead using the L<Object::Pad> module, imported with a
special set of options to configure it to only recognise the same syntax as
the core perl feature, thus ensuring any code using it will still continue to
function on that newer perl.

=end original

このモジュールは、新しい C<class> キーワードと、それに関連する C<method>,
C<field> and C<ADJUST> を前方互換として提供します。

このモジュールが提供する文法は、Perlの開発版ソースコードのブランチに C<class> という
名前の機能としてあります。全てうまくいけば、この機能は安定板に入るでしょう。
そのような perl が持つ機能をこのモジュールは有効にします。

L<Object::Pad>が、コアのperlのclassの文法と同等となるオプションを用いてインポートされ、
代わりに提供されます。つまり、これを利用しているコードは、新しいperlの機能が引き続き
機能することを保証します。

=head2 Perl Branch with C<feature 'class'>

(C<feature 'class'> をもった Perlブランチ)

=begin original

At time of writing, the C<use feature 'class'> syntax is not part of mainline
perl source but is available in a branch. That branch currently resides at
L<https://github.com/leonerd/perl5/tree/feature-class/>. It is intended this
will be migrated to the main C<perl> repository ahead of actually being merged
once development has progressed further.

This module is a work-in-progress, because the underlying C<feature-class>
branch is too. Many of the limitations and inabilities listed below are a
result of the early-access nature of this branch, and are expected to be
lifted as work progresses towards a more featureful and complete
implementation.

=end original

これを書いている時点では、C<use feature 'class'> シンタックスは perl のメインブランチには
入っていませんが、ブランチでは有効です。有効なブランチは現在
L<https://github.com/leonerd/perl5/tree/feature-class/> にあります。いまより開発が
進んだ時に C<perl> 本体にマージされることが計画されます。

このモジュールは開発中 WIP です。C<feature-class> ブランチのもとに同じだからです。
以下に列挙されるたくさんの制約やできないことは、そのブランチを早くさわれるようにした
結果です。そして、もっと機能が進歩することと実装が完了することが期待されます。


=head1 KEYWORDS

=begin original

The keywords provided by this module offer a subset of the abilities of those
provided by C<Object::Pad>, restricted to specifically only what is commonly
supported by the core syntax as well. In general, the reader should first
consult the documentation for the corresponding C<Object::Pad> keyword, but
the following notes may be of interest:

=end original

このモジュールで提供されるキーワードは C<Object::Pad> が提供するものと同じことができる
サブセットになります。コアのシンタックスでサポートされるものだけに限られます。
読者はまずは C<Object::Pad> のキーワードのドキュメントを参照すべきですが、
以下の注意事項が参考になるかもしれません。

=head2 class

   class NAME { ... }
   class NAME VERSION { ... }

   class NAME; ...
   class NAME VERSION; ...

See also L<Object::Pad/class>.

=begin original

There is no ability to declare any roles with C<:does>. The legacy subkeywords
for these are equally not supported.

The C<:repr> attribute is also not supported; the default representation type
will always be selected.

The C<:strict(params)> attribute is not available, but all constructed classes
will behave as if the attribute had been declared. Every generated constructor
will check its parameters for key names left unhandled by C<ADJUST> blocks,
and throw an exception if any remain.

The following class attributes are supported:

=end original

C<:does> を伴うロールを宣言することはできません。そのための古いサブキーワードは同じく
サポートされません。

C<:repr> 属性もサポートされません。デフォルトの representation type は
常に選択されます。

C<:strict(params)> 属性はありません。しかし、全てのコンストラクトされたクラスは
この属性が宣言されているとして振る舞います。生成される毎のコンストラクタが、キーネームが
C<ADJUST> ブロックによって unhandled になったものを残していないか、チェックします。そして、
もし残されていたら例外を投げます。

以下の属性はサポートされます。

=head3 :isa

   :isa(CLASS)

   :isa(CLASS CLASSVER)

=begin original

I<Since version 0.02.>

Declares a superclass that this class extends. At most one superclass is
supported.

If the package providing the superclass does not exist, an attempt is made to
load it by code equivalent to

=end original

I<Since version 0.02.>

スーパークラスの宣言はクラスを継承します。ほとんどのスーパークラスはサポートされます。

スーパークラスを提供するパッケージは存在しません。以下のコードが同じことをしています。

   require CLASS ();

=begin original

and thus it must either already exist, or be locatable via the usual C<@INC>
mechanisms.

An optional version check can also be supplied; it performs the equivalent of

=end original

というわけで、いずれもすでに存在していなけばなりません。もしくは、いわゆる C<@INC> の
仕組みに入っていないといけません。

バージョンを確認するオプションも提供されます。以下と同じように動きます。

   BaseClass->VERSION( $ver )

=begin original

Note that C<class> blocks B<do not> implicitly enable the C<strict> and
C<warnings> pragmata; either when using the core feature or C<Object::Pad>.
This is to avoid surprises when eventually switching to purely using the core
perl feature, which will not do that. Remember however that a C<use VERSION>
of a version C<v5.36> or above will enable both these pragmata anyway, so that
will be sufficient.

=end original

C<class> ブロックは C<strict> と C<warnings> プラグマを暗黙的に有効にしません。
いずれもコアの機能を使うか、C<Object::Pad> を使うときは有効です。これは最終的にコアの機能に
切り替えるときの驚きを避けるためです。C<v5.36> 以降の C<use VERSION> をすると、
両方の C<strict> と C<warnings> プラグマが有効になります。なので充分でしょう。

(翻訳注：C<strict> と C<warnings> プラグマの状態は以下のようです。
* perlコア(素のperl): 明示的にuseしないと無効
* C<class feature>: 明示的にuseしないと無効
* C<Object::Pad>: 暗黙的に有効
* C<use VERSION>: C<v5.36>以降を書くと暗黙的に有効)

=head2 method

   method NAME { ... }
   method NAME;

=begin original

See also L<Object::Pad/method>.

Attributes are not supported, other than the usual ones provided by perl
itself. Of these, only C<:lvalue> is particularly useful.

Lexical methods are not supported.

=end original

L<Object::Pad/method> も参照してください。

perl そのものによって提供された通例の属性はサポートされません。
C<:lvalue> だけは明らかに便利です。

レキシカルメソッドはサポートされません。

=head2 field

   field $NAME;
   field @NAME;
   field %NAME;

   field $NAME = EXPR;

   field $NAME :ATTRS... = EXPR;

=begin original

See also L<Object::Pad/field>.

Most field attributes are not supported. In particular, rather than using the
accessor-generator attributes you will have to create accessor methods
yourself; such as

=end original


L<Object::Pad/field> も参照してください。

ほとんどのフィールド属性もサポートされません。特に、以下のようにアクセサを自力で
作成するのに使うアクセサジェネレータ属性ではないもの

   field $var;
   method var { return $var; }
   method set_var ($new_var) { $var = $new_var; }

=begin original

I<Since version 0.04> fields of any type may take initialising expressions.
Initialiser blocks are not supported.

=end original

I<version 0.04> から、フィールドはinitialising expressionsをとりますが、
initialiser ブロックはサポートされません。

   field $five = 5;

=begin original

The following field attributes are supported:

=end original

以下のフィールド属性はサポートされます。

=head3 :param

   field $var :param;

   field $var :param(name)

=begin original

I<Since version 0.04.>

Declares that the constructor will take a named parameter to set the value for
this field in a new instance.

=end original

I<version 0.04.> から、コンストラクタは名前付きパラメータをフィールドの値を設定するために
使えます。

   field $var :param = EXPR;

=begin original

Without a defaulting expression, the parameter is mandatory. When combined
with a defaulting expression, the parameter is optional and the default will
only apply if the named parameter was not passed to the constructor.

=end original

デフォルトの式がなければ、パラメータは必須です。デフォルトの式と組み合わさっていれば
パラメータはオプショナルです。そして、デフォルト値はnamed parameterがコンストラクタに
渡されなかった時だけ与えられます。

   field $var :param //= EXPR;
   field $var :param ||= EXPR;

=begin original

With both the C<:param> attribute and a defaulting expression, the operator
can also be written as C<//=> or C<||=>. In this case, the defaulting
expression will be used even if the caller passed an undefined value (for
C<//=>) or a false value (for C<||=>). This simplifies many situations where
C<undef> would not be a valid value for a field parameter.

=end original

C<:param> 属性とデフォルトの式の両方一緒なら、演算子は C<//=> と C<||=> の
どちらでも書くことができます。この場合、デフォルトの式は caller が未定義値( C<//=> )
か偽値 ( C<||=> ) を渡したとしても使われます。

   class C {
      field $timeout :param //= 20;
   }

   C->new( timeout => $args{timeout} );
   # もし %args が 'timeout' キーを持たないか、その値が undef の時にデフォルト値が適用されます。

=head2 ADJUST

   ADJUST { ... }

=begin original

See also L<Object::Pad/ADJUST>.

Attributes are not supported; in particular the C<:params> attribute of
C<Object::Pad> v0.70.

=end original

L<Object::Pad/ADJUST> も参照してください。

特に、C<Object::Pad> v0.70 の C<:params> 属性はサポートされません。

=head2 Other Keywords

=begin original

The following other keywords provided by C<Object::Pad> are not supported here
at all:

=end original

以下の C<Object::Pad> が提供するその他のキーワードはサポートされません。

   role

   BUILD, ADJUSTPARAMS

   has

   requires


=head1 COMPATIBILITY NOTES

=begin original

This module may use either L<Object::Pad> or the perl core C<class> feature to
implement its syntax. While the two behave very similarly and both conform to
the description given above, the following differences should be noted.

=end original

このモジュールは、シンタックスを実装するために、L<Object::Pad> か perl コアの
C<class> feature を使うでしょう。双方はとても似通った振る舞いをしますし、ともに
ここまでの説明に適合し、以下の違いについて記されるべきです。

=over 4

=item Fields in later field expressions

=begin original

The core perl C<class> feature makes every field variable visible to the
initialising expression of later fields. For example,

=end original

Perlコアの C<class> feature は、初期化式の中の後のフィールドのために
フィールド変数毎に見えるようにします。以下の例：

   field $one = 1;
   field $two = $one + 1;

=begin original

This is not currently supported by C<Object::Pad>. As a result, it is possible
to write code that works fine with the core perl feature but older perls
cannot support by using C<Object::Pad>.

=end original

これは C<Object::Pad> で今のところサポートされていません。結果として、perl コアでは
問題なく動くコードを書くことができますが、古い perl は　C<Object::Pad> でサポートすることは
できません。

=back

=head1 AUTHOR

Paul Evans <leonerd@leonerd.org.uk>


=cut