| 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 |
|