1Feature::Compat::Class(U3spemr)Contributed Perl DocumentFaetaitounre::Compat::Class(3pm)
2
3
4
6 "Feature::Compat::Class" - make "class" syntax available
7
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
28 This module provides the new "class" keyword and related others
29 ("method", "field" and "ADJUST") in a forward-compatible way.
30
31 Perl added such syntax at version 5.38.0, which is enabled by
32
33 use feature 'class';
34
35 On that version of perl or later, this module simply enables the core
36 feature equivalent of using it directly. On such perls, this module
37 will install with no non-core dependencies, and requires no C compiler.
38
39 On older versions of perl before such syntax is availble in core, it is
40 currently provided instead using the Object::Pad module, imported with
41 a special set of options to configure it to only recognise the same
42 syntax as the core perl feature, thus ensuring any code using it will
43 still continue to function on that newer perl.
44
45 This module is a work-in-progress, because the underlying "feature
46 'class'" is too. Many of the limitations and inabilities listed below
47 are a result of the early-access nature of this branch, and are
48 expected to be lifted as work progresses towards a more featureful and
49 complete implementation.
50
52 The keywords provided by this module offer a subset of the abilities of
53 those provided by "Object::Pad", restricted to specifically only what
54 is commonly supported by the core syntax as well. In general, the
55 reader should first consult the documentation for the corresponding
56 "Object::Pad" keyword, but the following notes may be of interest:
57
58 class
59 class NAME { ... }
60 class NAME VERSION { ... }
61
62 class NAME; ...
63 class NAME VERSION; ...
64
65 See also "class" in Object::Pad.
66
67 There is no ability to declare any roles with ":does". The legacy
68 subkeywords for these are equally not supported.
69
70 The ":repr" attribute is also not supported; the default representation
71 type will always be selected.
72
73 The :strict(params) attribute is not available, but all constructed
74 classes will behave as if the attribute had been declared. Every
75 generated constructor will check its parameters for key names left
76 unhandled by "ADJUST" blocks, and throw an exception if any remain.
77
78 The following class attributes are supported:
79
80 :isa
81
82 :isa(CLASS)
83
84 :isa(CLASS CLASSVER)
85
86 Since version 0.02.
87
88 Declares a superclass that this class extends. At most one superclass
89 is supported.
90
91 If the package providing the superclass does not exist, an attempt is
92 made to load it by code equivalent to
93
94 require CLASS ();
95
96 and thus it must either already exist, or be locatable via the usual
97 @INC mechanisms.
98
99 An optional version check can also be supplied; it performs the
100 equivalent of
101
102 BaseClass->VERSION( $ver )
103
104 Note that "class" blocks do not implicitly enable the "strict" and
105 "warnings" pragmata; either when using the core feature or
106 "Object::Pad". This is to avoid surprises when eventually switching to
107 purely using the core perl feature, which will not do that. Remember
108 however that a "use VERSION" of a version "v5.36" or above will enable
109 both these pragmata anyway, so that will be sufficient.
110
111 method
112 method NAME { ... }
113 method NAME;
114
115 See also "method" in Object::Pad.
116
117 Attributes are not supported, other than the usual ones provided by
118 perl itself. Of these, only ":lvalue" is particularly useful.
119
120 Lexical methods are not supported.
121
122 field
123 field $NAME;
124 field @NAME;
125 field %NAME;
126
127 field $NAME = EXPR;
128
129 field $NAME :ATTRS... = EXPR;
130
131 See also "field" in Object::Pad.
132
133 Most field attributes are not supported. In particular, rather than
134 using the accessor-generator attributes you will have to create
135 accessor methods yourself; such as
136
137 field $var;
138 method var { return $var; }
139 method set_var ($new_var) { $var = $new_var; }
140
141 Since version 0.04 fields of any type may take initialising
142 expressions. Initialiser blocks are not supported.
143
144 field $five = 5;
145
146 The following field attributes are supported:
147
148 :param
149
150 field $var :param;
151
152 field $var :param(name)
153
154 Since version 0.04.
155
156 Declares that the constructor will take a named parameter to set the
157 value for this field in a new instance.
158
159 field $var :param = EXPR;
160
161 Without a defaulting expression, the parameter is mandatory. When
162 combined with a defaulting expression, the parameter is optional and
163 the default will only apply if the named parameter was not passed to
164 the constructor.
165
166 field $var :param //= EXPR;
167 field $var :param ||= EXPR;
168
169 With both the ":param" attribute and a defaulting expression, the
170 operator can also be written as "//=" or "||=". In this case, the
171 defaulting expression will be used even if the caller passed an
172 undefined value (for "//=") or a false value (for "||="). This
173 simplifies many situations where "undef" would not be a valid value for
174 a field parameter.
175
176 class C {
177 field $timeout :param //= 20;
178 }
179
180 C->new( timeout => $args{timeout} );
181 # default applies if %args has no 'timeout' key, or if its value is undef
182
183 ADJUST
184 ADJUST { ... }
185
186 See also "ADJUST" in Object::Pad.
187
188 Attributes are not supported; in particular the ":params" attribute of
189 "Object::Pad" v0.70.
190
191 Other Keywords
192 The following other keywords provided by "Object::Pad" are not
193 supported here at all:
194
195 role
196
197 BUILD, ADJUSTPARAMS
198
199 has
200
201 requires
202
204 This module may use either Object::Pad or the perl core "class" feature
205 to implement its syntax. While the two behave very similarly and both
206 conform to the description given above, the following differences
207 should be noted.
208
209 Fields in later field expressions
210 The core perl "class" feature makes every field variable visible to
211 the initialising expression of later fields. For example,
212
213 field $one = 1;
214 field $two = $one + 1;
215
216 This is not currently supported by "Object::Pad". As a result, it
217 is possible to write code that works fine with the core perl
218 feature but older perls cannot support by using "Object::Pad".
219
221 Paul Evans <leonerd@leonerd.org.uk>
222
223
224
225perl v5.38.0 2023-07-20 Feature::Compat::Class(3pm)