1Object::Pad(3) User Contributed Perl Documentation Object::Pad(3)
2
6 "Object::Pad" - a simple syntax for lexical slot-based objects
7
9 use Object::Pad;
10 class Point {
12 has $x = 0;
13 has $y = 0;
14 BUILD {
16 ($x, $y) = @_;
17 }
18 method move ($dX, $dY) {
20 $x += $dX;
21 $y += $dY;
22 }
23 method describe {
25 print "A point at ($x, $y)\n";
26 }
27 }
28 Point->new(5,10)->describe;
30
32 This module provides a simple syntax for creating object classes, which
33 uses private variables that look like lexicals as object member fields.
34 WARNING This module is still very experimental. The parts that
36 currently exist do seem to work reliably but much of the design is
37 still evolving, and many features and have yet to be implemented. I
38 don't yet guarantee I won't have to change existing details in order to
39 continue its development. Feel free to try it out in experimental or
40 newly-developed code, but don't complain if a later version is
41 incompatible with your current code and you'll have to change it.
42 That all said, please do get in contact if you find the module overall
44 useful. The more feedback you provide in terms of what features you
45 are using, what you find works, and what doesn't, will help the ongoing
46 development and hopefully eventual stability of the design. See the
47 "FEEDBACK" section.
48 Automatic Construction
50 Classes are automatically provided with a constructor method, called
51 "new", which helps create the object instances.
52 As part of the construction process, the "BUILD" block of every
54 component class will be invoked, passing in the list of arguments the
55 constructor was invoked with. Each class should perform its required
56 setup behaviour, but does not need to chain to the "SUPER" class first;
57 this is handled automatically.
58 If the class provides a "BUILDARGS" class method, that is used to
60 mangle the list of arguments before the "BUILD" blocks are called. Note
61 this must be a class method not an instance method (and so implemented
62 using "sub"). It should perform any "SUPER" chaining as may be
63 required.
64 @args = $class->BUILDARGS( @_ )
66
68 class
69 class Name :ATTRS... {
70 ...
71 }
72 class Name :ATTRS...;
74 Behaves similarly to the "package" keyword, but provides a package that
76 defines a new class. Such a class provides an automatic constructor
77 method called "new".
78 As with "package", an optional block may be provided. If so, the
80 contents of that block define the new class and the preceding package
81 continues afterwards. If not, it sets the class as the package context
82 of following keywords and definitions.
83 As with "package", an optional version declaration may be given. If so,
85 this sets the value of the package's $VERSION variable.
86 class Name VERSION { ... }
88 class Name VERSION;
90 A single superclass is supported by the keyword "extends"
92 class Name extends BASECLASS {
94 ...
95 }
96 class Name extends BASECLASS BASEVER {
98 ...
99 }
100 If a package providing the superclass does not exist, an attempt is
102 made to load it by code equivalent to
103 require Animal ();
105 and thus it must either already exist, or be locatable via the usual
107 @INC mechanisms.
108 The superclass may or may not itself be implemented by "Object::Pad",
110 but if it is not then see "SUBCLASSING CLASSIC PERL CLASSES" for
111 further detail on the semantics of how this operates.
112 An optional version check can also be supplied; it performs the
114 equivalent of
115 BaseClass->VERSION( $ver )
117 One or more roles can be composed into the class by the keyword
119 "implements"
120 class Name implements ROLE, ROLE,... {
122 ...
123 }
124 An optional list of attributes may be supplied in similar syntax as for
126 subs or lexical variables. (These are annotations about the class
127 itself; the concept should not be confused with per-object-instance
128 data, which here is called "slots"). The following class attributes are
129 supported:
130 :repr(TYPE)
132 Sets the representation type for instances of this class. Must be one
134 of the following values:
135 :repr(native)
137 The native representation. This is an opaque representation type whose
139 contents are not specified. It only works for classes whose entire
140 inheritence hierarchy is built only from classes based on
141 "Object::Pad".
142 :repr(HASH)
144 The representation will be a blessed hash reference. The instance data
146 will be stored in an array referenced by a key called
147 "Object::Pad/slots", which is fairly unlikely to clash with existing
148 storage on the instance. No other keys will be used; they are available
149 for implementions and subclasses to use. The exact format of the value
150 stored here is not specified and may change between module versions,
151 though it can be relied on to be well-behaved as some kind of perl data
152 structure for purposes of modules like Data::Dumper or serialisation
153 into things like "YAML" or "JSON".
154 This representation type may be useful when converting existing classes
156 into using "Object::Pad" where there may be existing subclasses of it
157 that presume a blessed hash for their own use.
158 :repr(magic)
160 The representation will use MAGIC to apply the instance data in a way
162 that is invisible at the Perl level, and shouldn't get in the way of
163 other things the instance is doing even in XS modules.
164 This representation type is the only one that will work for subclassing
166 existing classes that do not use blessed hashes.
167 :repr(autoselect), :repr(default)
169 Since version 0.23.
171 This representation will select one of the representations above
173 depending on what is best for the situation. Classes not derived from a
174 non-"Object::Pad" base class will pick "native", and classes derived
175 from non-"Object::Pad" bases will pick either the "HASH" or "magic"
176 forms depending on whether the instance is a blessed hash reference or
177 some other kind.
178 This achieves the best combination of DWIM while still allowing the
180 common forms of hash reference to be inspected by "Data::Dumper", etc.
181 This is the default representation type, and does not have to be
182 specifically requested.
183 role
185 role Name :ATTRS... {
186 ...
187 }
188 role Name :ATTRS...;
190 Since version 0.32.
192 Similar to "class", but provides a package that defines a new role. A
194 role acts simliar to a class in some respects, and differently in
195 others.
196 Like a class, a role can have a version, and named methods.
198 role Name VERSION {
200 method a { ... }
201 method b { ... }
202 }
203 A role does not provide a constructor, and instances cannot directly be
205 constructed. A role cannot extend a class.
206 A role can declare that it requires methods of given names from any
208 class that implements the role.
209 role Name {
211 requires METHOD;
212 }
213 A role can provide instance slots. These are visible to any "BUILD"
215 blocks or methods provided by that role.
216 Since version 0.33.
218 role Name {
220 has $slot;
221 BUILD { $slot = "a value" }
223 method slot { return $slot }
225 }
226 The following role attributes are supported:
228 :compat(invokable)
230 Since version 0.35.
232 Enables a form of backward-compatibility behaviour useful for gradually
234 upgrading existing code from classical Perl inheritance or mixins into
235 using roles.
236 Normally, methods of a role cannot be directly invoked and the role
238 must be applied to an Object::Pad-based class in order to be used. This
239 however presents a problem when gradually upgrading existing code that
240 already uses techniques like roles, multiple inheritance or mixins when
241 that code may be split across multiple distributions, or for some other
242 reason cannot be upgraded all at once. Methods within a role that has
243 the ":compat(invokable)" attribute applied to it may be directly
244 invoked on any object instance. This allows the creation of a role that
245 can still provide code for existing classes written in classical Perl
246 that has not yet been rewritten to use "Object::Pad".
247 The tradeoff is that a ":compat(invokable)" role may not create slot
249 data using the "has" keyword. Whatever behaviours the role wishes to
250 perform must be provided only by calling other methods on $self, or
251 perhaps by making assumptions about the representation type of
252 instances.
253 It should be stressed again: This option is only intended for gradual
255 upgrade of existing classical Perl code into using "Object::Pad". When
256 all existing code is using "Object::Pad" then this attribute can be
257 removed from the role.
258 has
260 has $var;
261 has $var = EXPR;
262 has @var;
263 has %var;
264 has $var :ATTR ATTR...;
266 Declares that the instances of the class or role have a member field of
268 the given name. This member field (called a "slot") will be accessible
269 as a lexical variable within any "method" declarations in the class.
270 Array and hash members are permitted and behave as expected; you do not
272 need to store references to anonymous arrays or hashes.
273 Member fields are private to a class or role. They are not visible to
275 users of the class, nor to subclasses, nor to any class that a role is
276 applied to. In order to provide access to them a class may wish to use
277 "method" to create an accessor, or use the attributes such as ":reader"
278 to get one generated.
279 A scalar slot may provide a expression that gives an initialisation
281 value, which will be assigned into the slot of every instance during
282 the constructor before the "BUILD" blocks are invoked. Since version
283 0.29 this expression does not have to be a compiletime constant, though
284 it is evaluated exactly once, at runtime, after the class definition
285 has been parsed. It is not evaluated individually for every object
286 instance of that class.
287 The following slot attributes are supported:
289 :reader, :reader(NAME)
291 Since version 0.27.
293 Generates a reader method to return the current value of the slot.
295 Currently these are only permitted for scalar slots. If no name is
296 given, the name of the slot is used. A single prefix character "_" will
297 be removed if present.
298 has $slot :reader;
300 # equivalent to
302 has $slot; method slot { return $slot }
303 :writer, :writer(NAME)
305 Since version 0.27.
307 Generates a writer method to set a new value of the slot from its first
309 argument. Currently these are only permitted for scalar slots. If no
310 name is given, the name of the slot is used prefixed by "set_". A
311 single prefix character "_" will be removed if present.
312 has $slot :writer;
314 # equivalent to
316 has $slot; method set_slot { $slot = shift; return $self }
317 Since version 0.28 a generated writer method will return the object
319 invocant itself, allowing a chaining style.
320 $obj->set_x("x")
322 ->set_y("y")
323 ->set_z("z");
324 :mutator, :mutator(NAME)
326 Since version 0.27.
328 Generates an lvalue mutator method to return or set the value of the
330 slot. These are only permitted for scalar slots. If no name is given,
331 the name of the slot is used. A single prefix character "_" will be
332 removed if present.
333 has $slot :mutator;
335 # equivalent to
337 has $slot; method slot :lvalue { $slot }
338 Since version 0.28 all of these generated accessor methods will include
340 argument checking similar to that used by subroutine signatures, to
341 ensure the correct number of arguments are passed - usually zero, but
342 exactly one in the case of a ":writer" method.
343 method
345 method NAME {
346 ...
347 }
348 method NAME (SIGNATURE) {
350 ...
351 }
352 method NAME :ATTRS... {
354 ...
355 }
356 Declares a new named method. This behaves similarly to the "sub"
358 keyword, except that within the body of the method all of the member
359 fields ("slots") are also accessible. In addition, the method body will
360 have a lexical called $self which contains the invocant object
361 directly; it will already have been shifted from the @_ array.
362 The "signatures" feature is automatically enabled for method
364 declarations. In this case the signature does not have to account for
365 the invocant instance; that is handled directly.
366 method m ($one, $two) {
368 say "$self invokes method on one=$one two=$two";
369 }
370 ...
372 $obj->m(1, 2);
373 A list of attributes may be supplied as for "sub". The most useful of
375 these is ":lvalue", allowing easy creation of read-write accessors for
376 slots (but see also the ":reader", ":writer" and ":mutator" slot
377 attributes).
378 class Counter {
380 has $count;
381 method count :lvalue { $count }
383 }
384 my $c = Counter->new;
386 $c->count++;
387 Every method automatically gets the ":method" attribute applied, which
389 suppresses warnings about ambiguous calls resolved to core functions if
390 the name of a method matches a core function.
391 The following additional attributes are recognised by "Object::Pad"
393 directly:
394 :override
396 Since version 0.29.
398 Marks that this method expects to override another of the same name
400 from a superclass. It is an error at compiletime if the superclass does
401 not provide such a method.
402 BUILD
404 BUILD {
405 ...
406 }
407 BUILD (SIGNATURE) {
409 ...
410 }
411 Since version 0.27.
413 Declares the builder block for this component class. A builder block
415 may use subroutine signature syntax, as for methods, to assist in
416 unpacking its arguments. A build block is not a subroutine and thus is
417 not permitted to use subroutine attributes (for example ":lvalue").
418 Currently attempts to create a method named "BUILD" (i.e. with syntax
420 "method BUILD {...}") will create a builder block instead. As of
421 version 0.31 such attempts will print a warning at compiletime, and a
422 later version may remove this altogether.
423 requires
425 requires NAME;
426 Declares that this role requires a method of the given name from any
428 class that implements it. It is an error at compiletime if the
429 implementing class does not provide such a method.
430
432 In order to encourage users to write clean, modern code, the body of
433 the "class" block acts as if the following pragmata are in effect:
434 use strict;
436 use warnings;
437 no indirect ':fatal'; # or no feature 'indirect' on perl 5.32 onwards
438 use feature 'signatures';
439 This list may be extended in subsequent versions to add further
441 restrictions and should not be considered exhaustive.
442 Further additions will only be ones that remove "discouraged" or
444 deprecated language features with the overall goal of enforcing a more
445 clean modern style within the body. As long as you write code that is
446 in a clean, modern style (and I fully accept that this wording is vague
447 and subjective) you should not find any new restrictions to be majorly
448 problematic. Either the code will continue to run unaffected, or you
449 may have to make some small alterations to bring it into a conforming
450 style.
451
453 There are a number of details specific to the case of deriving an
454 "Object::Pad" class from an existing classic Perl class that is not
455 implemented using "Object::Pad".
456 Storage of Instance Data
458 Instances will pick either the ":repr(HASH)" or ":repr(magic)" storage
459 type.
460 Object State During Methods Invoked By Superclass Constructor
462 It is common in classic Perl OO style to invoke methods on $self during
463 the constructor. This is supported here since "Object::Pad" version
464 0.19. Note however that any methods invoked by the superclass
465 constructor may not see the object in a fully consistent state. (This
466 fact is not specific to using "Object::Pad" and would happen in classic
467 Perl OO as well). The slot initialisers will have been invoked but the
468 "BUILD" blocks will not.
469 For example; in the following
471 package ClassicPerlBaseClass {
473 sub new {
474 my $self = bless {}, shift;
475 say "Value seen by superconstructor is ", $self->get_value;
476 return $self;
477 }
478 sub get_value { return "A" }
479 }
480 class DerivedClass extends ClassicPerlBaseClass {
482 has $_value = "B";
483 BUILD {
484 $_value = "C";
485 }
486 method get_value { return $_value }
487 }
488 my $obj = DerivedClass->new;
490 say "Value seen by user is ", $obj->get_value;
491 Until the "ClassicPerlBaseClass::new" superconstructor has returned the
493 "BUILD" block will not have been invoked. The $_value slot will still
494 exist, but its value will be "B" during the superconstructor. After the
495 superconstructor, the "BUILD" blocks are invoked before the completed
496 object is returned to the user. The result will therefore be:
497 Value seen by superconstructor is B
499 Value seen by user is C
500
502 While in no way required, the following suggestions of code style
503 should be noted in order to establish a set of best practices, and
504 encourage consistency of code which uses this module.
505 $VERSION declaration
507 While it would be nice for CPAN and other toolchain modules to parse
508 the embedded version declarations in "class" statements, the current
509 state at time of writing (June 2020) is that none of them actually do.
510 As such, it will still be necessary to make a once-per-file $VERSION
511 declaration in syntax those modules can parse.
512 Further note that these modules will also not parse the "class"
514 declaration, so you will have to duplicate this with a "package"
515 declaration as well as a "class" keyword. This does involve repeating
516 the package name, so is slightly undesirable.
517 It is hoped that eventually upstream toolchain modules will be adapted
519 to accept the "class" syntax as being sufficient to declare a package
520 and set its version.
521 See also
523 • <https://github.com/Perl-Toolchain-Gang/Module-Metadata/issues/33>
525 File Layout
527 Begin the file with a "use Object::Pad" line; ideally including a
528 minimum-required version. This should be followed by the toplevel
529 "package" and "class" declarations for the file. As it is at toplevel
530 there is no need to use the block notation; it can be a unit class.
531 There is no need to "use strict" or apply other usual pragmata; these
533 will be implied by the "class" keyword.
534 use Object::Pad 0.16;
536 package My::Classname 1.23;
538 class My::Classname;
539 # other use statements
541 # has, methods, etc.. can go here
543 Slot Names
545 Slot names should follow similar rules to regular lexical variables in
546 code - lowercase, name components separated by underscores. For tiny
547 examples such as "dumb record" structures this may be sufficient.
548 class Tag {
550 has $name :mutator;
551 has $value :mutator;
552 }
553 In larger examples with lots of non-trivial method bodies, it can get
555 confusing to remember where the slot variables come from (because we no
556 longer have the "$self->{ ... }" visual clue). In these cases it is
557 suggested to prefix the slot names with a leading underscore, to make
558 them more visually distinct.
559 class Spudger {
561 has $_grapefruit;
562 ...
564 method mangle {
566 $_grapefruit->peel; # The leading underscore reminds us this is a slot
567 }
568 }
569
571 Syntax::Keyword::Dynamically
572 A cross-module integration test asserts that "dynamically" works
573 correctly on object instance slots:
574 use Object::Pad;
576 use Syntax::Keyword::Dynamically;
577 class Container {
579 has $value = 1;
580 method example {
582 dynamically $value = 2;
583 ,..
584 # value is restored to 1 on return from this method
585 }
586 }
587 Future::AsyncAwait
589 As of Future::AsyncAwait version 0.38 and Object::Pad version 0.15,
590 both modules now use XS::Parse::Sublike to parse blocks of code.
591 Because of this the two modules can operate together and allow class
592 methods to be written as async subs which await expressions:
593 use Future::AsyncAwait;
595 use Object::Pad;
596 class Example
598 {
599 async method perform ($block)
600 {
601 say "$self is performing code";
602 await $block->();
603 say "code finished";
604 }
605 }
606 These three modules combine; there is additionally a cross-module test
608 to ensure that object instance slots can be "dynamically" set during a
609 suspended "async method".
610
612 The following points are details about the design of pad slot-based
613 object systems in general:
614 • Is multiple inheritence actually required, if role composition is
616 implemented including giving roles the ability to use private
617 slots?
618 • Consider the visibility of superclass slots to subclasses. Do
620 subclasses even need to be able to see their superclass's slots, or
621 are accessor methods always appropriate?
622 Concrete example: The "$self->{split_at}" access that
624 Tickit::Widget::HSplit makes of its parent class
625 Tickit::Widget::LinearSplit.
626
628 These points are more about this particular module's implementation:
629 • Consider multiple inheritence of subclassing, if that is still
631 considered useful after adding roles.
632 • Work out why "no indirect" doesn't appear to work properly before
634 perl 5.20.
635 • Work out why we don't get a "Subroutine new redefined at ..."
637 warning if we
638 sub new { ... }
640 • The "local" modifier does not work on slot variables, because they
642 appear to be regular lexicals to the parser at that point. A
643 workaround is to use Syntax::Keyword::Dynamically instead:
644 use Syntax::Keyword::Dynamically;
646 has $loglevel;
648 method quietly {
650 dynamically $loglevel = LOG_ERROR;
651 ...
652 }
653
655 The following resources are useful forms of providing feedback,
656 especially in the form of reports of what you find good or bad about
657 the module, requests for new features, questions on best practice,
658 etc...
659 • The RT queue at
661 <https://rt.cpan.org/Dist/Display.html?Name=Object-Pad>.
662 • The "#cor" IRC channel on "irc.perl.org".
664
666 Paul Evans <leonerd@leonerd.org.uk>
667perl v5.32.1 2021-05-14 Object::Pad(3)