Debian Codegraph @

README

raw
1 NAME
2
3 Feature::Compat::Class - make class syntax available
4
5 SYNOPSIS
6
7 use Feature::Compat::Class;
8
9 class Point {
10 field $x :param :reader :writer = 0;
11 field $y :param :reader :writer = 0;
12
13 method move_to ($new_x, $new_y) {
14 $x = $new_x;
15 $y = $new_y;
16 }
17
18 method describe {
19 say "A point at ($x, $y)";
20 }
21 }
22
23 Point->new(x => 5, y => 10)->describe;
24
25 DESCRIPTION
26
27 This module provides the new class keyword and related others (method,
28 field and ADJUST) in a forward-compatible way.
29
30 Perl added such syntax at version 5.38.0, which is enabled by
31
32 use feature 'class';
33
34 This syntax was further expanded in 5.40, adding the __CLASS__ keyword
35 and :reader attribute on fields, and again in 5.42 to add the :writer
36 attribute.
37
38 On that version of perl or later, this module simply enables the core
39 feature equivalent of using it directly. On such perls, this module
40 will install with no non-core dependencies, and requires no C compiler.
41
42 On older versions of perl before such syntax is availble in core, it is
43 currently provided instead using the Object::Pad module, imported with
44 a special set of options to configure it to only recognise the same
45 syntax as the core perl feature, thus ensuring any code using it will
46 still continue to function on that newer perl.
47
48 This module is a work-in-progress, because the underlying feature
49 'class' is too. Many of the limitations and inabilities listed below
50 are a result of the early-access nature of this branch, and are
51 expected to be lifted as work progresses towards a more featureful and
52 complete implementation.
53
54 KEYWORDS
55
56 The keywords provided by this module offer a subset of the abilities of
57 those provided by Object::Pad, restricted to specifically only what is
58 commonly supported by the core syntax as well. In general, the reader
59 should first consult the documentation for the corresponding
60 Object::Pad keyword, but the following notes may be of interest:
61
62 class
63
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 warnings
110 pragmata; either when using the core feature or Object::Pad. This is to
111 avoid surprises when eventually switching to purely using the core perl
112 feature, which will not do that. Remember however that a use VERSION of
113 a version v5.36 or above will enable both these pragmata anyway, so
114 that will be sufficient.
115
116 method
117
118 method NAME { ... }
119 method NAME;
120
121 See also "method" in Object::Pad.
122
123 Attributes are not supported, other than the usual ones provided by
124 perl itself. Of these, only :lvalue is particularly useful.
125
126 Lexical methods are not supported.
127
128 field
129
130 field $NAME;
131 field @NAME;
132 field %NAME;
133
134 field $NAME = EXPR;
135
136 field $NAME :ATTRS... = EXPR;
137
138 See also "field" in Object::Pad.
139
140 Most field attributes are not supported. In particular, rather than
141 using the accessor-generator attributes you will have to create
142 accessor methods yourself; such as
143
144 field $var;
145 method var { return $var; }
146 method set_var ($new_var) { $var = $new_var; }
147
148 Since version 0.04 fields of any type may take initialising
149 expressions. Initialiser blocks are not supported.
150
151 field $five = 5;
152
153 Since version 0.07 field initialiser expressions can see earlier fields
154 that have already been declared, and use their values:
155
156 field $fullname :param;
157 field $shortname :param = ( split m/ +/, $fullname )[0];
158
159 The following field attributes are supported:
160
161 :param
162
163 field $var :param;
164
165 field $var :param(name)
166
167 Since version 0.04.
168
169 Declares that the constructor will take a named parameter to set the
170 value for this field in a new instance.
171
172 field $var :param = EXPR;
173
174 Without a defaulting expression, the parameter is mandatory. When
175 combined with a defaulting expression, the parameter is optional and
176 the default will only apply if the named parameter was not passed to
177 the constructor.
178
179 field $var :param //= EXPR;
180 field $var :param ||= EXPR;
181
182 With both the :param attribute and a defaulting expression, the
183 operator can also be written as //= or ||=. In this case, the
184 defaulting expression will be used even if the caller passed an
185 undefined value (for //=) or a false value (for ||=). This simplifies
186 many situations where undef would not be a valid value for a field
187 parameter.
188
189 class C {
190 field $timeout :param //= 20;
191 }
192
193 C->new( timeout => $args{timeout} );
194 # default applies if %args has no 'timeout' key, or if its value is undef
195
196 :reader, :reader(NAME)
197
198 Since version 0.07.
199
200 Generates a reader method to return the current value of the field. If
201 no name is given, the name of the field is used. A single prefix
202 character _ will be removed if present.
203
204 field $x :reader;
205
206 # equivalent to
207 field $x; method x () { return $x }
208
209 These are permitted on an field type, not just scalars. The reader
210 method behaves identically to how a lexical variable would behave in
211 the same context; namely returning a list of values from an array or
212 key/value pairs from a hash when in list context, or the number of
213 items or keys when in scalar context.
214
215 field @items :reader;
216
217 foreach my $item ( $obj->items ) { ... } # iterates the list of items
218
219 my $count = $obj->items; # yields count of items
220
221 :writer, :writer(NAME)
222
223 Since version 0.08.
224
225 Generates a writer method to set a new value for the field. If no name
226 is given, the name of the field is used with a set_ prefix. If a name
227 is provided that will be used - you should remember to add a
228 distinguishing prefix if required to keep it distinct from the reader
229 method. A single prefix character _ will be removed if present.
230
231 field $x :writer;
232
233 # equivalent to
234 field $x; method set_x ($new_x) { $x = $new_x; return $self; }
235
236 When invoked, a :writer method will return the invocant object itself.
237 This is so that multiple fields can be modified in a convenient
238 chaining syntax; for example:
239
240 $obj->set_x( 10 )
241 ->set_y( 20 )
242 ->set_z( 30 );
243
244 ADJUST
245
246 ADJUST { ... }
247
248 See also "ADJUST" in Object::Pad.
249
250 Attributes are not supported; in particular the :params attribute of
251 Object::Pad v0.70.
252
253 __CLASS__
254
255 my $classname = __CLASS__;
256
257 Since version 0.07.
258
259 Only valid within the body (or signature) of a method, an ADJUST block,
260 or the initialising expression of a field. Yields the class name of the
261 instance that the method, block or expression is invoked on.
262
263 This is similar to the core perl __PACKAGE__ constant, except that it
264 cares about the dynamic class of the actual instance, not the static
265 class the code belongs to. When invoked by a subclass instance that
266 inherited code from its superclass it yields the name of the class of
267 the instance regardless of which class defined the code.
268
269 For example,
270
271 class BaseClass {
272 ADJUST { say "Constructing an instance of " . __CLASS__; }
273 }
274
275 class DerivedClass :isa(BaseClass) { }
276
277 my $obj = DerivedClass->new;
278
279 Will produce the following output
280
281 Constructing an instance of DerivedClass
282
283 This is particularly useful in field initialisers for invoking
284 (constant) methods on the invoking class to provide default values for
285 fields. This way a subclass could provide a different value.
286
287 class Timer {
288 use constant DEFAULT_DURATION => 60;
289 field $duration = __CLASS__->DEFAULT_DURATION;
290 }
291
292 class ThreeMinuteTimer :isa(Timer) {
293 use constant DEFAULT_DURATION => 3 * 60;
294 }
295
296 Other Keywords
297
298 The following other keywords provided by Object::Pad are not supported
299 here at all:
300
301 role
302
303 BUILD, ADJUSTPARAMS
304
305 has
306
307 requires
308
309 COMPATIBILITY NOTES
310
311 This module may use either Object::Pad or the perl core class feature
312 to implement its syntax. While the two behave very similarly and both
313 conform to the description given above, the following differences
314 should be noted.
315
316 No known issues at this time
317
318 AUTHOR
319
320 Paul Evans <[email protected]>
321