1Feature::Compat::Class(U3s)er Contributed Perl DocumentatFieoanture::Compat::Class(3)
2
3
4

NAME

6       "Feature::Compat::Class" - make "class" syntax available
7

SYNOPSIS

9          use Feature::Compat::Class;
10
11          class Point {
12             field $x :param = 0;
13             field $y :param = 0;
14
15             method move_to ($new_x, $new_y) {
16                $x = $new_x;
17                $y = $new_y;
18             }
19
20             method describe {
21                say "A point at ($x, $y)";
22             }
23          }
24
25          Point->new(x => 5, y => 10)->describe;
26

DESCRIPTION

28       This module provides the new "class" keyword and related others
29       ("method", "field" and "ADJUST") in a forward-compatible way.
30
31       There is a branch of Perl development source code which provides this
32       syntax, under the "class" named feature. If all goes well, this will
33       become available in a stable release in due course. On such perls that
34       contain the feature, this module simple enables it.
35
36       On older versions of perl before such syntax is availble in core, it is
37       currently provided instead using the Object::Pad module, imported with
38       a special set of options to configure it to only recognise the same
39       syntax as the core perl feature, thus ensuring any code using it will
40       still continue to function on that newer perl.
41
42   Perl Branch with "feature 'class'"
43       At time of writing, the "use feature 'class'" syntax is not part of
44       mainline perl source but is available in a branch. That branch
45       currently resides at
46       <https://github.com/leonerd/perl5/tree/feature-class/>. It is intended
47       this will be migrated to the main "perl" repository ahead of actually
48       being merged once development has progressed further.
49
50       This module is a work-in-progress, because the underlying
51       "feature-class" branch is too. Many of the limitations and inabilities
52       listed below are a result of the early-access nature of this branch,
53       and are expected to be lifted as work progresses towards a more
54       featureful and complete implementation.
55

KEYWORDS

57       The keywords provided by this module offer a subset of the abilities of
58       those provided by "Object::Pad", restricted to specifically only what
59       is commonly supported by the core syntax as well. In general, the
60       reader should first consult the documentation for the corresponding
61       "Object::Pad" keyword, but the following notes may be of interest:
62
63   class
64          class NAME { ... }
65          class NAME VERSION { ... }
66
67          class NAME; ...
68          class NAME VERSION; ...
69
70       See also "class" in Object::Pad.
71
72       There is no ability to declare any roles with ":does". The legacy
73       subkeywords for these are equally not supported.
74
75       The ":repr" attribute is also not supported; the default representation
76       type will always be selected.
77
78       The :strict(params) attribute is not available, but all constructed
79       classes will behave as if the attribute had been declared. Every
80       generated constructor will check its parameters for key names left
81       unhandled by "ADJUST" blocks, and throw an exception if any remain.
82
83       The following class attributes are supported:
84
85       :isa
86
87          :isa(CLASS)
88
89          :isa(CLASS CLASSVER)
90
91       Since version 0.02.
92
93       Declares a superclass that this class extends. At most one superclass
94       is supported.
95
96       If the package providing the superclass does not exist, an attempt is
97       made to load it by code equivalent to
98
99          require CLASS ();
100
101       and thus it must either already exist, or be locatable via the usual
102       @INC mechanisms.
103
104       An optional version check can also be supplied; it performs the
105       equivalent of
106
107          BaseClass->VERSION( $ver )
108
109       Note that "class" blocks do not implicitly enable the "strict" and
110       "warnings" pragmata; either when using the core feature or
111       "Object::Pad".  This is to avoid surprises when eventually switching to
112       purely using the core perl feature, which will not do that. Remember
113       however that a "use VERSION" of a version "v5.36" or above will enable
114       both these pragmata anyway, so that will be sufficient.
115
116   method
117          method NAME { ... }
118          method NAME;
119
120       See also "method" in Object::Pad.
121
122       Attributes are not supported, other than the usual ones provided by
123       perl itself. Of these, only ":lvalue" is particularly useful.
124
125       Lexical methods are not supported.
126
127   field
128          field $NAME;
129          field @NAME;
130          field %NAME;
131
132          field $NAME = EXPR;
133
134          field $NAME :ATTRS... = EXPR;
135
136       See also "field" in Object::Pad.
137
138       Most field attributes are not supported. In particular, rather than
139       using the accessor-generator attributes you will have to create
140       accessor methods yourself; such as
141
142          field $var;
143          method var { return $var; }
144          method set_var ($new_var) { $var = $new_var; }
145
146       Since version 0.04 fields of any type may take initialising
147       expressions.  Initialiser blocks are not supported.
148
149          field $five = 5;
150
151       The following field attributes are supported:
152
153       :param
154
155          field $var :param;
156
157          field $var :param(name)
158
159       Since version 0.04.
160
161       Declares that the constructor will take a named parameter to set the
162       value for this field in a new instance.
163
164          field $var :param = EXPR;
165
166       Without a defaulting expression, the parameter is mandatory. When
167       combined with a defaulting expression, the parameter is optional and
168       the default will only apply if the named parameter was not passed to
169       the constructor.
170
171          field $var :param //= EXPR;
172          field $var :param ||= EXPR;
173
174       With both the ":param" attribute and a defaulting expression, the
175       operator can also be written as "//=" or "||=". In this case, the
176       defaulting expression will be used even if the caller passed an
177       undefined value (for "//=") or a false value (for "||="). This
178       simplifies many situations where "undef" would not be a valid value for
179       a field parameter.
180
181          class C {
182             field $timeout :param //= 20;
183          }
184
185          C->new( timeout => $args{timeout} );
186          # default applies if %args has no 'timeout' key, or if its value is undef
187
188   ADJUST
189          ADJUST { ... }
190
191       See also "ADJUST" in Object::Pad.
192
193       Attributes are not supported; in particular the ":params" attribute of
194       "Object::Pad" v0.70.
195
196   Other Keywords
197       The following other keywords provided by "Object::Pad" are not
198       supported here at all:
199
200          role
201
202          BUILD, ADJUSTPARAMS
203
204          has
205
206          requires
207

COMPATIBILITY NOTES

209       This module may use either Object::Pad or the perl core "class" feature
210       to implement its syntax. While the two behave very similarly and both
211       conform to the description given above, the following differences
212       should be noted.
213
214       Fields in later field expressions
215           The core perl "class" feature makes every field variable visible to
216           the initialising expression of later fields. For example,
217
218              field $one = 1;
219              field $two = $one + 1;
220
221           This is not currently supported by "Object::Pad". As a result, it
222           is possible to write code that works fine with the core perl
223           feature but older perls cannot support by using "Object::Pad".
224

AUTHOR

226       Paul Evans <leonerd@leonerd.org.uk>
227
228
229
230perl v5.36.0                      2023-01-20         Feature::Compat::Class(3)