1Class::Std(3) User Contributed Perl Documentation Class::Std(3)
2
6 Class::Std - Support for creating standard "inside-out" classes
7
9 This document describes Class::Std version 0.013
10
12 package MyClass;
13 use Class::Std;
14 # Create storage for object attributes...
16 my %name : ATTR;
17 my %rank : ATTR;
18 my %snum : ATTR;
19 my %public_data : ATTR;
21 # Handle initialization of objects of this class...
23 sub BUILD {
24 my ($self, $obj_ID, $arg_ref) = @_;
25 $name{$obj_ID} = check_name( $arg_ref->{name} );
27 $rank{$obj_ID} = check_rank( $arg_ref->{rank} );
28 $snum{$obj_ID} = _gen_uniq_serial_num();
29 }
30 # Handle cleanup of objects of this class...
32 sub DEMOLISH {
33 my ($self, $obj_ID) = @_;
34 _recycle_serial_num( $snum{$obj_ID} );
36 }
37 # Handle unknown method calls...
39 sub AUTOMETHOD {
40 my ($self, $obj_ID, @other_args) = @_;
41 # Return any public data...
43 if ( m/\A get_(.*)/ ) { # Method name passed in $_
44 my $get_what = $1;
45 return sub {
46 return $public_data{$obj_ID}{$get_what};
47 }
48 }
49 warn "Can't call $method_name on ", ref $self, " object";
51 return; # The call is declined by not returning a sub ref
53 }
54
56 This module provides tools that help to implement the "inside out
57 object" class structure in a convenient and standard way.
58 Portions of the following code and documentation from "Perl Best
60 Practices" copyright (c) 2005 by O'Reilly Media, Inc. and reprinted
61 with permission.
62 Introduction
64 Most programmers who use Perl's object-oriented features construct
65 their objects by blessing a hash. But, in doing so, they undermine the
66 robustness of the OO approach. Hash-based objects are unencapsulated:
67 their entries are open for the world to access and modify.
68 Objects without effective encapsulation are vulnerable. Instead of
70 politely respecting their public interface, some clever client coder
71 inevitably will realize that it's marginally faster to interact
72 directly with the underlying implementation, pulling out attribute
73 values directly from the hash of an object:
74 for my $file ( get_file_objs() ) {
76 print $file->{name}, "\n";
77 }
78 instead of using the official interface:
80 for my $file ( get_file_objs() ) {
82 print $file->get_name(), "\n";
83 }
84 From the moment someone does that, your class is no longer cleanly
86 decoupled from the code that uses it. You can't be sure that any bugs
87 in your class are actually caused by the internals of your class, and
88 not the result of some kind of monkeying by the client code. And to
89 make matters worse, now you can't ever change those internals without
90 the risk of breaking some other part of the system.
91 There is a simple, convenient, and utterly secure way to prevent client
93 code from accessing the internals of the objects you provide. Happily,
94 that approach also guards against misspelling attribute names (a common
95 error in hash-based classes), as well as being just as fast as--and
96 often more memory-efficient than--ordinary hash-based objects.
97 That approach is referred to by various names--flyweight scalars,
99 warehoused attributes, inverted indices--but most commonly it's known
100 as: inside-out objects. Consider the following class definitions:
101 package File::Hierarchy;
103 {
104 # Objects of this class have the following attributes...
105 my %root_of; # The root directory of the file hierarchy
106 my %files_of; # Array storing object for each file in root directory
107 # Constructor takes path of file system root directory...
109 sub new {
110 my ($class, $root) = @_;
111 # Bless a scalar to instantiate the new object...
113 my $new_object = bless \do{my $anon_scalar}, $class;
114 # Initialize the object's "root" attribute...
116 $root_of{ident $new_object} = $root;
117 return $new_object;
119 }
120 # Retrieve files from root directory...
122 sub get_files {
123 my ($self) = @_;
124 # Load up the "files" attribute, if necessary...
126 if (!exists $files_of{ident $self}) {
127 $files_of{ident $self}
128 = File::System->list_files($root_of{ident $self});
129 }
130 # Flatten the "files" attribute's array to produce a file list...
132 return @{ $files_of{ident $self} };
133 }
134 }
135 package File::Hierarchy::File;
137 {
138 # Objects of this class have the following attributes...
139 my %name_of; # the name of the file
140 # Constructor takes name of file...
142 sub new {
143 my ($class, $filename) = @_;
144 # Bless a scalar to instantiate the new object...
146 my $new_object = bless \do{my $anon_scalar}, $class;
147 # Initialize the object's "name" attribute...
149 $name_of{ident $new_object} = $filename;
150 return $new_object;
152 }
153 # Retrieve name of file...
155 sub get_name {
156 my ($self) = @_;
157 return $name_of{ident $self};
159 }
160 }
161 Unlike a hash-based class, each of these inside-out class is specified
163 inside a surrounding code block:
164 package File::Hierarchy;
166 {
167 # [Class specification here]
168 }
169 package File::Hierarchy::File;
171 {
172 # [Class specification here]
173 }
174 That block is vital, because it creates a limited scope, to which any
176 lexical variables that are declared as part of the class will
177 automatically be restricted.
178 The next difference between the two versions of the classes is that
180 each attribute of all the objects in the class is now stored in a
181 separate single hash:
182 # Objects of this class have the following attributes...
184 my %root_of; # The root directory of the file hierarchy
186 my %files_of; # Array storing object for each file in root directory
187 This is 90 degrees to the usual hash-based approach. In hash-based
189 classes, all the attributes of one object are stored in a single hash;
190 in inside-out classes, one attribute from all objects is stored in a
191 single hash. Diagrammatically:
192 Hash-based:
194 Attribute 1 Attribute 2
195 Object A { attr1 => $valA1, attr2 => $val2 }
197 Object B { attr1 => $valB1, attr2 => $val2 }
199 Object C { attr1 => $valB1, attr2 => $val2 }
201 Inside-out:
205 Object A Object B Object C
206 Attribute 1 { 19817 => $valA1, 172616 => $valB1, 67142 => $valC1 }
208 Attribute 2 { 19817 => $valA2, 172616 => $valB2, 67142 => $valC3 }
210 Attribute 3 { 19817 => $valA3, 172616 => $valB3, 67142 => $valC3 }
212 So the attributes belonging to each object are distributed across a set
214 of predeclared hashes, rather than being squashed together into one
215 anonymous hash.
216 This is a significant improvement. By telling Perl what attributes you
218 expect to use, you enable the compiler to check--via use strict--that
219 you do indeed use only those attributes.
220 That's because of the third difference in the two approaches. Each
222 attribute of a hash-based object is stored in an entry in the object's
223 hash: "$self->{name}". In other words, the name of a hash-based
224 attribute is symbolic: specified by the string value of a hash key. In
225 contrast, each attribute of an inside-out object is stored in an entry
226 of the attribute's hash: $name_of{ident $self}. So the name of an
227 inside-out attribute isn't symbolic; it's a hard-coded variable name.
228 With hash-based objects, if an attribute name is accidentally
230 misspelled in some method:
231 sub set_name {
233 my ($self, $new_name) = @_;
234 $self->{naem} = $new_name; # Oops!
236 return;
238 }
239 then the $self hash will obligingly--and silently!--create a new entry
241 in the hash, with the key 'naem', then assign the new name to it. But
242 since every other method in the class correctly refers to the attribute
243 as "$self-"{name}>, assigning the new value to "$self-"{naem}>
244 effectively makes that assigned value "vanish".
245 With inside-out objects, however, an object's "name" attribute is
247 stored as an entry in the class's lexical %name_of hash. If the
248 attribute name is misspelled then you're attempting to refer to an
249 entirely different hash: %naem_of. Like so:
250 sub set_name {
252 my ($self, $new_name) = @_;
253 $naem_of{ident $self} = $new_name; # Kaboom!
255 return;
257 }
258 But, since there's no such hash declared in the scope, use strict will
260 complain (with extreme prejudice):
261 Global symbol "%naem_of" requires explicit package name at Hierarchy.pm line 86
263 Not only is that consistency check now automatic, it's also performed
265 at compile time.
266 The next difference is even more important and beneficial. Instead of
268 blessing an empty anonymous hash as the new object:
269 my $new_object = bless {}, $class;
271 the inside-out constructor blesses an empty anonymous scalar:
273 my $new_object = bless \do{my $anon_scalar}, $class;
275 That odd-looking "\do{my $anon_scalar}" construct is needed because
277 there's no built-in syntax in Perl for creating a reference to an
278 anonymous scalar; you have to roll-your-own.
279 The anonymous scalar is immediately passed to bless, which anoints it
281 as an object of the appropriate class. The resulting object reference
282 is then stored in $new_object.
283 Once the object exists, it's used to create a unique key ("ident
285 $new_object") under which each attribute that belongs to the object
286 will be stored (e.g. $root_of{ident $new_object} or $name_of{ident
287 $self}). The "ident()" utility that produces this unique key is
288 provided by the Class::Std module and is identical in effect to the
289 "refaddr()" function in the standard Scalar::Util module.
290 To recap: every inside-out object is a blessed scalar, and
292 has--intrinsic to it--a unique identifying integer. That integer can be
293 obtained from the object reference itself, and then used to access a
294 unique entry for the object in each of the class's attribute hashes.
295 This means that every inside-out object is nothing more than an
297 unintialized scalar. When your constructor passes a new inside-out
298 object back to the client code, all that comes back is an empty scalar,
299 which makes it impossible for that client code to gain direct access to
300 the object's internal state.
301 Of the several popular methods of reliably enforcing encapsulation in
303 Perl, inside-out objects are also by far the cheapest. The run-time
304 performance of inside-out classes is effectively identical to that of
305 regular hash-based classes. In particular, in both schemes, every
306 attribute access requires only a single hash look-up. The only
307 appreciable difference in speed occurs when an inside-out object is
308 destroyed.
309 Hash-based classes usually don't even have destructors. When the
311 object's reference count decrements to zero, the hash is automatically
312 reclaimed, and any data structures stored inside the hash are likewise
313 cleaned up. This works so well that many OO Perl programmers find they
314 never need to write a "DESTROY()" method; Perl's built-in garbage
315 collection handles everything just fine. In fact, the only time a
316 destructor is needed is when objects have to manage resources outside
317 that are not actually located inside the object, resources that need to
318 be separately deallocated.
319 But the whole point of an inside-out object is that its attributes are
321 stored in allocated hashes that are not actually located inside the
322 object. That's precisely how it achieves secure encapsulation: by not
323 sending the attributes out into the client code.
324 Unfortunately, that means when an inside-out object is eventually
326 garbage collected, the only storage that is reclaimed is the single
327 blessed scalar implementing the object. The object's attributes are
328 entirely unaffected by the object's deallocation, because the
329 attributes are not inside the object, nor are they referred to by it in
330 any way.
331 Instead, the attributes are referred to by the various attribute hashes
333 in which they're stored. And since those hashes will continue to exist
334 until the end of the program, the defunct object's orphaned attributes
335 will likewise continue to exist, safely nestled inside their respective
336 hashes, but now untended by any object. In other words, when an inside-
337 out object dies, its associated attribute hashes leak memory.
338 The solution is simple. Every inside-out class has to provide a
340 destructor that "manually" cleans up the attributes of the object being
341 destructed:
342 package File::Hierarchy;
344 {
345 # Objects of this class have the following attributes...
346 my %root_of; # The root directory of the file hierarchy
347 my %files_of; # Array storing object for each file in root directory
348 # Constructor takes path of file system root directory...
350 sub new {
351 # As before
352 }
353 # Retrieve files from root directory...
355 sub get_files {
356 # As before
357 }
358 # Clean up attributes when object is destroyed...
360 sub DESTROY {
361 my ($self) = @_;
362 delete $root_of{ident $self};
364 delete $files_of{ident $self};
365 }
366 }
367 The obligation to provide a destructor like this in every inside-out
369 class can be mildly irritating, but it is still a very small price to
370 pay for the considerable benefits that the inside-out approach
371 otherwise provides for free. And the irritation can easily be
372 eliminated by using the appropriate class construction tools. See
373 below.
374 Automating Inside-Out Classes
376 Perhaps the most annoying part about building classes in Perl (no
377 matter how the objects are implemented) is that the basic structure of
378 every class is more or less identical. For example, the implementation
379 of the "File::Hierarchy::File" class used in "File::Hierarchy" looks
380 like this:
381 package File::Hierarchy::File;
383 {
384 # Objects of this class have the following attributes...
385 my %name_of; # the name of the file
386 # Constructor takes name of file...
388 sub new {
389 my ($class, $filename) = @_;
390 # Bless a scalar to instantiate the new object...
392 my $new_object = bless \do{my $anon_scalar}, $class;
393 # Initialize the object's "name" attribute...
395 $name_of{ident $new_object} = $filename;
396 return $new_object;
398 }
399 # Retrieve name of file...
401 sub get_name {
402 my ($self) = @_;
403 return $name_of{ident $self};
405 }
406 # Clean up attributes when object is destroyed...
408 sub DESTROY {
409 my ($self) = @_;
410 delete $name_of{ident $self};
412 }
413 }
414 Apart from the actual names of the attributes, and their accessor
416 methods, that's exactly the same structure, and even the same code, as
417 in the "File::Hierarchy" class.
418 Indeed, the standard infrastructure of every inside-out class looks
420 exactly the same. So it makes sense not to have to rewrite that
421 standard infrastructure code in every separate class.
422 That's precisely what this module does: it implements the necessary
424 infrastructure for inside-out objects. See below.
425
427 Exported subroutines
428 "ident()"
429 Class::Std always exports a subroutine called "ident()". This
430 subroutine returns a unique integer ID for any object passed to it.
431 Non-exported subroutines
433 "Class::Std::initialize()"
434 This subroutine sets up all the infrastructure to support your
435 Class::Std- based class. It is usually called automatically in a
436 "CHECK" block, or (if the "CHECK" block fails to run -- under
437 "mod_perl" or "require Class::Std" or "eval "..."") during the
438 first constructor call made to a Class::Std-based object.
439 In rare circumstances, you may need to call this subroutine
441 directly yourself. Specifically, if you set up cumulative,
442 restricted, private, or automethodical class methods (see below),
443 and call any of them before you create any objects, then you need
444 to call "Class::Std::initialize()" first.
445 Methods created automatically
447 The following subroutines are installed in any class that uses the
448 Class::Std module.
449 "new()"
451 Every class that loads the Class::Std module automatically has a
452 "new()" constructor, which returns an inside-out object (i.e. a
453 blessed scalar).
454 $obj = MyClass->new();
456 The constructor can be passed a single argument to initialize the
458 object. This argument must be a hash reference.
459 $obj = MyClass->new({ name=>'Foo', location=>'bar' });
461 See the subsequent descriptions of the "BUILD()" and "START()"
463 methods and ":ATTR()" trait, for an explanation of how the contents
464 of this optional hash can be used to initialize the object.
465 It is almost always an error to implement your own "new()" in any
467 class that uses Class::Std. You almost certainly want to write a
468 "BUILD()" or "START()" method instead. See below.
469 "DESTROY()"
471 Every class that loads the Class::Std module automatically has a
472 "DESTROY()" destructor, which automatically cleans up any
473 attributes declared with the ":ATTR()" trait (see below).
474 It is almost always an error to write your own "DESTROY()" in any
476 class that uses Class::Std. You almost certainly want to write your
477 own "DEMOLISH()" instead. See below.
478 "AUTOLOAD()"
480 Every class that loads the Class::Std module automatically has an
481 "AUTOLOAD()" method, which implements the "AUTOMETHOD()" mechanism
482 described below.
483 It is almost always an error to write your own "AUTOLOAD()" in any
485 class that uses Class::Std. You almost certainly want to write your
486 own "AUTOMETHOD()" instead.
487 "_DUMP()"
489 This method returns a string that represents the internal state
490 (i.e. the attribute values) of the object on which it's called.
491 Only those attributes which are marked with an ":ATTR" (see below)
492 are reported. Attribute names are reported only if they can be
493 ascertained from an ":init_arg", ":get", or ":set" option within
494 the ":ATTR()".
495 Note that "_DUMP()" is not designed to support full
497 serialization/deserialization of objects. See the separate
498 Class::Std::Storable module (on CPAN) for that.
499 Methods that can be supplied by the developer
501 The following subroutines can be specified as standard methods of a
502 Class::Std class.
503 "BUILD()"
505 When the "new()" constructor of a Class::Std class is called, it
506 automatically calls every method named "BUILD()" in all the classes
507 in the new object's hierarchy. That is, when the constructor is
508 called, it walks the class's inheritance tree (from base classes
509 downwards) and calls every "BUILD()" method it finds along the way.
510 This means that, to initialize any class, you merely need to
512 provide a "BUILD()" method for that class. You don't have to worry
513 about ensuring that any ancestral "BUILD()" methods also get
514 called; the constructor will take care of that.
515 Each "BUILD()" method is called with three arguments: the invocant
517 object, the identifier number of that object, and a reference to (a
518 customized version of) the hash of arguments that was originally
519 passed to the constructor:
520 sub BUILD {
522 my ($self, $ident, $args_ref) = @_;
523 ...
524 }
525 The argument hash is a "customized version" because the module
527 automatically does some fancy footwork to ensure that the arguments
528 are the ones appropriate to the class itself. That's because
529 there's a potential for collisions when Class::Std classes are used
530 in a hierarchy.
531 One of the great advantages of using inside-out classes instead of
533 hash-based classes is that an inside-out base class and an inside-
534 out derived class can then each have an attribute of exactly the
535 same name, which are stored in separate lexical hashes in separate
536 scopes. In a hash-based object that's impossible, because the
537 single hash can't have two attributes with the same key.
538 But that very advantage also presents something of a problem when
540 constructor arguments are themselves passed by hash. If two or more
541 classes in the name hierarchy do happen to have attributes of the
542 same name, the constructor will need two or more initializers with
543 the name key. Which a single hash can't provide.
544 The solution is to allow initializer values to be partitioned into
546 distinct sets, each uniquely named, and which are then passed to
547 the appropriate base class. The easiest way to accomplish that is
548 to pass in a hash of hashes, where each top level key is the name
549 of one of the base classes, and the corresponding value is a hash
550 of initializers specifically for that base class.
551 For example:
553 package Client;
555 use Class::Std::Utils;
556 {
557 my %client_num_of :ATTR; # Every client has a basic ID number
558 my %name_of :ATTR;
559 sub BUILD {
561 my ($self, $ident, $arg_ref) = @_;
562 $client_num_of{$ident} = $arg_ref->{'Client'}{client_num};
564 $name_of{$ident} = $arg_ref->{'Client'}{client_name};
565 }
566 }
567 package Client::Corporate;
569 use base qw( Client );
570 use Class::Std::Utils;
571 {
572 my %client_num_of; # Corporate clients have an additional ID number
573 my %corporation_of;
574 my %position_of;
575 sub BUILD {
577 my ($self, $ident, $arg_ref) = @_;
578 $client_num_of{$ident}
580 = $arg_ref->{'Client::Corporate'}{client_num};
581 $corporation_of{$ident}
582 = $arg_ref->{'Client::Corporate'}{corp_name};
583 $position_of{$ident}
584 = $arg_ref->{'Client::Corporate'}{position};
585 }
586 }
587 # and later...
589 my $new_client
591 = Client::Corporate->new( {
592 'Client' => {
593 client_num => '124C1',
594 client_name => 'Humperdinck',
595 },
596 'Client::Corporate' => {
597 client_num => 'F_1692',
598 corp_name => 'Florin',
599 position => 'CEO',
600 },
601 });
602 Now each class's "BUILD()" method picks out only the initializer
604 sub-hash whose key is that class's own name. Since every class name
605 is different, the top-level keys of this multi-level initializer
606 hash are guaranteed to be unique. And since no single class can
607 have two identically named attributes, the keys of each second-
608 level hash will be unique as well. If two classes in the hierarchy
609 both need an initializer of the same name (e.g. 'client_num'),
610 those two hash entries will now be in separate sub-hashes, so they
611 will never clash.
612 Class::Std provides an even more sophisticated variation on this
614 functionality, which is generally much more convenient for the
615 users of classes. Classes that use Class::Std infrastructure allow
616 both general and class-specific initializers in the initialization
617 hash. Clients only need to specify classes for those initializers
618 whose names actually are ambiguous. Any other arguments can just be
619 passed directly in the top-level hash:
620 my $new_client
622 = Client::Corporate->new( {
623 client_name => 'Humperdinck',
624 corp_name => 'Florin',
625 position => 'CEO',
626 'Client' => { client_num => '124C1' },
628 'Client::Corporate' => { client_num => 'F_1692' },
629 });
630 Class::Std also makes it easy for each class's "BUILD()" to access
632 these class-specific initializer values. Before each "BUILD()" is
633 invoked, the nested hash whose key is the same as the class name is
634 flattened back into the initializer hash itself. That is,
635 "Client::BUILD()" is passed the hash:
636 {
638 client_name => 'Humperdinck',
639 corp_name => 'Florin',
640 position => 'CEO',
641 client_num => '124C1', # Flattened from 'Client' nested subhash
642 'Client' => { client_num => '124C1' },
644 'Client::Corporate' => { client_num => 'F_1692' },
645 }
646 whereas "Client::Corporate::BUILD()" is passed the hash:
648 {
650 client_name => 'Humperdinck',
651 corp_name => 'Florin',
652 position => 'CEO',
653 client_num => 'F_1692', # Flattened from 'Client::Corporate' subhash
654 'Client' => { client_num => '124C1' },
656 'Client::Corporate' => { client_num => 'F_1692' },
657 }
658 This means that the "BUILD()" method for each class can just assume
660 that the correct class-specific initializer values will available
661 at the top level of the hash. For example:
662 sub Client::BUILD {
664 my ($self, $ident, $arg_ref) = @_;
665 $client_num_of{$ident} = $arg_ref->{client_num}; # '124C1'
667 $name_of{$ident} = $arg_ref->{client_name};
668 }
669 sub Client::Corporate::BUILD {
671 my ($self, $ident, $arg_ref) = @_;
672 $client_num_of{$ident} = $arg_ref->{client_num}; # 'F_1692'
674 $corporation_of{$ident} = $arg_ref->{corp_name};
675 $position_of{$ident} = $arg_ref->{position};
676 }
677 Both classes use the "$arg_ref->{client_num}" initializer value,
679 but Class::Std automatically arranges for that value to be the
680 right one for each class.
681 Also see the ":ATTR()" marker (described below) for a simpler way
683 of initializing attributes.
684 "START()"
686 Once all the "BUILD()" methods of a class have been called and any
687 initialization values or defaults have been subsequently applied to
688 uninitialized attributes, Class::Std arranges for any "START()"
689 methods in the class's hierarchy to be called befre the constructor
690 finishes. That is, after the build and default initialization
691 processes are complete, the constructor walks down the class's
692 inheritance tree a second time and calls every "START()" method it
693 finds along the way.
694 As with "BUILD()", each "START()" method is called with three
696 arguments: the invocant object, the identifier number of that
697 object, and a reference to (a customized version of) the hash of
698 arguments that was originally passed to the constructor.
699 The main difference between a "BUILD()" method and a "START()"
701 method is that a "BUILD()" method runs before any attribute of the
702 class is auto-initialized or default-initialized, whereas a
703 "START()" method runs after all the attributes of the class
704 (including attributes in derived classes) have been initialized in
705 some way. So if you want to pre-empt the initialization process,
706 write a "BUILD()". But if you want to do something with the newly
707 created and fully initialized object, write a "START()" instead. Of
708 course, any class can define both a "BUILD()" and a "START()"
709 method, if that happens to be appropriate.
710 "DEMOLISH()"
712 The "DESTROY()" method that is automatically provided by Class::Std
713 ensures that all the marked attributes (see the ":ATTR()" marker
714 below) of an object, from all the classes in its inheritance
715 hierarchy, are automatically cleaned up.
716 But, if a class requires other destructor behaviours (e.g. closing
718 filehandles, decrementing allocation counts, etc.) then you may
719 need to specify those explicitly.
720 Whenever an object of a Class::Std class is destroyed, the
722 "DESTROY()" method supplied by Class::Std automatically calls every
723 method named "DEMOLISH()" in all the classes in the new object's
724 hierarchy. That is, when the destructor is called, it walks the
725 class's inheritance tree (from derived classes upwards) and calls
726 every "DEMOLISH()" method it finds along the way.
727 This means that, to clean up any class, you merely need to provide
729 a "DEMOLISH()" method for that class. You don't have to worry about
730 ensuring that any ancestral "DEMOLISH()" methods also get called;
731 the destructor will take care of that.
732 Each "DEMOLISH()" method is called with two arguments: the invocant
734 object, and the identifier number of that object. For example:
735 sub DEMOLISH {
737 my ($self, $ident) = @_;
738 $filehandle_of{$ident}->flush();
740 $filehandle_of{$ident}->close();
741 }
742 Note that the attributes of the object are cleaned up after the
744 "DEMOLISH()" method is complete, so they may still be used within
745 that method.
746 "AUTOMETHOD()"
748 There is a significant problem with Perl's built-in "AUTOLOAD"
749 mechanism: there's no way for a particular "AUTOLOAD()" to say
750 "no".
751 If two or more classes in a class hierarchy have separate
753 "AUTOLOAD()" methods, then the one belonging to the left-most-
754 depth-first class in the inheritance tree will always be invoked in
755 preference to any others. If it can't handle a particular call,
756 the call will probably fail catastrophically. This means that
757 derived classes can't always be used in place of base classes (a
758 feature known as "Liskov substitutability") because their inherited
759 autoloading behaviour may be pre-empted by some other unrelated
760 base class on their left in the hierarchy.
761 Class::Std provides a mechanism that solves this problem: the
763 "AUTOMETHOD" method. An AUTOMETHOD() is expected to return either a
764 handler subroutine that implements the requested method
765 functionality, or else an "undef" to indicate that it doesn't know
766 how to handle the request. Class::Std then coordinates every
767 "AUTOMETHOD()" in an object's hierarchy, trying each one in turn
768 until one of them produces a suitable handler.
769 The advantage of this approach is that the first "AUTOMETHOD()"
771 that's invoked doesn't have to disenfranchise every other
772 "AUTOMETHOD()" in the hierarchy. If the first one can't handle a
773 particular method call, it simply declines it and Class::Std tries
774 the next candidate instead.
775 Using "AUTOMETHOD()" instead of "AUTOLOAD()" makes a class cleaner,
777 more robust, and less disruptive in class hierarchies. For
778 example:
779 package Phonebook;
781 use Class::Std;
782 {
783 my %entries_of : ATTR;
784 # Any method call is someone's name:
786 # so store their phone number or get it...
787 sub AUTOMETHOD {
788 my ($self, $ident, $number) = @_;
789 my $subname = $_; # Requested subroutine name is passed via $_
791 # Return failure if not a get_<name> or set_<name>
793 # (Next AUTOMETHOD() in hierarchy will then be tried instead)...
794 my ($mode, $name) = $subname =~ m/\A ([gs]et)_(.*) \z/xms
795 or return;
796 # If get_<name>, return a handler that just returns the old number...
798 return sub { return $entries_of{$ident}->{$name}; }
799 if $mode eq 'get';
800 # Otherwise, set_<name>, so return a handler that
802 # updates the entry and then returns the old number...
803 return sub {
804 $entries_of{$ident}->{$name} = $number;
805 return;
806 };
807 }
808 }
809 # and later...
811 my $lbb = Phonebook->new();
813 $lbb->set_Jenny(867_5309);
815 $lbb->set_Glenn(736_5000);
816 print $lbb->get_Jenny(), "\n";
818 print $lbb->get_Glenn(), "\n";
819 Note that, unlike "AUTOLOAD()", an "AUTOMETHOD()" is called with
821 both the invocant and the invocant's unique "ident" number,
822 followed by the actual arguments that were passed to the method.
823 Note too that the name of the method being called is passed as $_
825 instead of $AUTOLOAD, and does not have the class name prepended to
826 it, so you don't have to strip that name off the front like almost
827 everyone almost always does in their "AUTOLOAD()". If your
828 "AUTOMETHOD()" also needs to access the $_ from the caller's scope,
829 that's still available as $CALLER::_.
830 Variable traits that can be ascribed
832 The following markers can be added to the definition of any hash used
833 as an attribute storage within a Class::Std class
834 ":ATTR()"
836 This marker can be used to indicate that a lexical hash is being
837 used to store one particular attribute of all the objects of the
838 class. That is:
839 package File::Hierarchy;
841 {
842 my %root_of :ATTR;
843 my %files_of :ATTR;
844 # etc.
846 }
847 package File::Hierarchy::File;
849 {
850 my %name_of; :ATTR;
851 # etc.
853 }
854 Adding the ":ATTR" marker to an attribute hash ensures that the
856 corresponding attribute belonging to each object of the class is
857 automatically cleaned up when the object is destroyed.
858 The ":ATTR" marker can also be given a number of options which
860 automate other attribute-related behaviours. Each of these options
861 consists of a key/value pair, which may be specified in either Perl
862 5 "fat comma" syntax ( "key => 'value'" ) or in one of the Perl 6
863 option syntaxes ( ":key<value>" or ":key('value')" or
864 ":keyXvalueX").
865 Note that, due to a limitation in Perl itself, the complete ":ATTR"
867 marker, including its options must appear on a single line.
868 interpolate variables into the option values
869 ":ATTR( :init_arg<initializer_key> )"
871 This option tells Class::Std which key in the constructor's
872 initializer hash holds the value with which the marked
873 attribute should be initialized. That is, instead of writing:
874 my %rank_of :ATTR;
876 sub BUILD {
878 my ($self, $ident, $arg_ref) = @_;
879 $rank_of{$ident} = $arg_ref->{rank};
881 }
882 you can achieve the same initialization, by having Class::Std
884 automatically pull that entry out of the hash and store it in
885 the right attribute:
886 my %rank_of :ATTR( :init_arg<rank> );
888 # No BUILD() method required
890 ":ATTR( :default<compile_time_default_value> )"
892 If a marked attribute is not initialized (either directly
893 within a "BUILD()", or automatically via an ":init_arg"
894 option), the constructor supplied by Class::Std checks to see
895 if a default value was specified for that attribute. If so,
896 that value is assigned to the attribute.
897 So you could replace:
899 my %seen_of :ATTR;
901 sub BUILD {
903 my ($self, $ident, $arg_ref) = @_;
904 $seen_of{$ident} = 0; # Not seen yet
906 }
907 with:
909 my %seen_of :ATTR( :default(0) );
911 # No BUILD() required
913 Note that only literal strings and numbers can be used as
915 default values. A common mistake is to write:
916 my %seen_of :ATTR( :default($some_variable) );
918 But variables like this aren't interpolated into ":ATTR"
920 markers (this is a limitation of Perl, not Class::Std).
921 If your attribute needs something more complex, you will have
923 to default initialize it in a "START()" method:
924 my %seen_of :ATTR;
926 sub START {
928 my ($self, $id, $args_ref) = @_;
929 if (!defined $seen_of{$id}) {
931 $seen_of{$id} = $some_variable;
932 }
933 }
934 ":ATTR( :get<name> )"
936 If the ":get" option is specified, a read accessor is created
937 for the corresponding attribute. The name of the accessor is
938 "get_" followed by whatever name is specified as the value of
939 the ":get" option. For example, instead of:
940 my %current_count_of :ATTR;
942 sub get_count {
944 my ($self) = @_;
945 return $current_count_of{ident($self)};
947 }
948 you can just write:
950 my %count_of :ATTR( :get<count> );
952 Note that there is no way to prevent Class::Std adding the
954 initial "get_" to each accessor name it creates. That's what
955 "standard" means. See Chapter 15 of Perl Best Practices
956 (O'Reilly, 2005) for a full discussion on why accessors should
957 be named this way.
958 ":ATTR( :set<name> )"
960 If the ":set" option is specified, a write accessor is created
961 for the corresponding attribute. The name of the accessor is
962 "set_" followed by whatever name is specified as the value of
963 the ":set" option. For example, instead of:
964 my %current_count_of :ATTR;
966 sub set_count {
968 my ($self, $new_value) = @_;
969 croak "Missing new value in call to 'set_count' method"
971 unless @_ == 2;
972 $current_count_of{ident($self)} = $new_value;
974 }
975 you can just write:
977 my %count_of :ATTR( :set<count> );
979 Note that there is no way to prevent Class::Std adding the
981 initial "set_" to each accessor name it creates. Nor is there
982 any way to create a combined "getter/setter" accessor. See
983 Chapter 15 of Perl Best Practices (O'Reilly, 2005) for a full
984 discussion on why accessors should be named and implemented
985 this way.
986 ":ATTR( :name<name> )"
988 Specifying the ":name" option is merely a convenient shorthand
989 for specifying all three of ":get", ":set", and ":init_arg".
990 You can, of course, specify two or more arguments in a single
992 ":ATTR()" specification:
993 my %rank_of : ATTR( :init_arg<starting_rank> :get<rank> :set<rank> );
995 ":ATTRS()"
997 This is just another name for the ":ATTR" marker (see above). The
998 plural form is convenient when you want to specify a series of
999 attribute hashes in the same statement:
1000 my (
1002 %name_of,
1003 %rank_of,
1004 %snum_of,
1005 %age_of,
1006 %unit_of,
1007 %assignment_of,
1008 %medals_of,
1009 ) : ATTRS;
1010 Method traits that can be ascribed
1012 The following markers can be added to the definition of any subroutine
1013 used as a method within a Class::Std class
1014 ":RESTRICTED()"
1016 ":PRIVATE()"
1017 Occasionally, it is useful to be able to create subroutines that
1018 can only be accessed within a class's own hierarchy (that is, by
1019 derived classes). And sometimes it's even more useful to be able to
1020 create methods that can only be called within a class itself.
1021 Typically these types of methods are utility methods: subroutines
1023 that provide some internal service for a class, or a class
1024 hierarchy. Class::Std supports the creation of these kinds of
1025 methods by providing two special markers: ":RESTRICTED()" and
1026 ":PRIVATE()".
1027 Methods marked ":RESTRICTED()" are modified at the end of the
1029 compilation phase so that they throw an exception when called from
1030 outside a class's hierarchy. Methods marked ":PRIVATE()" are
1031 modified so that they throw an exception when called from outside
1032 the class in which they're declared.
1033 For example:
1035 package DogTag;
1037 use Class::Std;
1038 {
1039 my %ID_of : ATTR;
1040 my %rank_of : ATTR;
1041 my $ID_num = 0;
1043 sub _allocate_next_ID : RESTRICTED {
1045 my ($self) = @_;
1046 $ID_of{ident $self} = $ID_num++;
1047 return;
1048 }
1049 sub _check_rank : PRIVATE {
1051 my ($rank) = @_;
1052 return $rank if $VALID_RANK{$rank};
1053 croak "Unknown rank ($rank) specified";
1054 }
1055 sub BUILD {
1057 my ($self, $ident, $arg_ref) = @_;
1058 $self->_allocate_next_ID();
1060 $rank_of{$ident} = _check_rank($arg_ref->{rank});
1061 }
1062 }
1063 Of course, this code would run exactly the same without the
1065 ":RESTRICTED()" and ":PRIVATE()" markers, but they ensure that any
1066 attempt to call the two subroutines inappropriately:
1067 package main;
1069 my $dogtag = DogTag->new({ rank => 'PFC' });
1071 $dogtag->_allocate_next_ID();
1073 is suitably punished:
1075 Can't call restricted method DogTag::_allocate_next_ID() from class main
1077 ":CUMULATIVE()"
1079 One of the most important advantages of using the "BUILD()" and
1080 "DEMOLISH()" mechanisms supplied by Class::Std is that those
1081 methods don't require nested calls to their ancestral methods, via
1082 the "SUPER" pseudo-class. The constructor and destructor provided
1083 by Class::Std take care of the necessary redispatching
1084 automatically. Each "BUILD()" method can focus solely on its own
1085 responsibilities; it doesn't have to also help orchestrate the
1086 cumulative constructor effects across the class hierarchy by
1087 remembering to call "$self->SUPER::BUILD()".
1088 Moreover, calls via "SUPER" can only ever call the method of
1090 exactly one ancestral class, which is not sufficient under multiple
1091 inheritance.
1092 Class::Std provides a different way of creating methods whose
1094 effects accumulate through a class hierarchy, in the same way as
1095 those of "BUILD()" and "DEMOLISH()" do. Specifically, the module
1096 allows you to define your own "cumulative methods".
1097 An ordinary non-cumulative method hides any method of the same name
1099 inherited from any base class, so when a non-cumulative method is
1100 called, only the most-derived version of it is ever invoked. In
1101 contrast, a cumulative method doesn't hide ancestral methods of the
1102 same name; it assimilates them. When a cumulative method is called,
1103 the most-derived version of it is invoked, then any parental
1104 versions, then any grandparental versions, etc. etc, until every
1105 cumulative method of the same name throughout the entire hierarchy
1106 has been called.
1107 For example, you could define a cumulative "describe()" method to
1109 the various classes in a simple class hierarchy like so:
1110 package Wax::Floor;
1112 use Class::Std;
1113 {
1114 my %name_of :ATTR( init_arg => 'name' );
1115 my %patent_of :ATTR( init_arg => 'patent' );
1116 sub describe :CUMULATIVE {
1118 my ($self) = @_;
1119 print "The floor wax $name_of{ident $self} ",
1121 "(patent: $patent_of{ident $self})\n";
1122 return;
1124 }
1125 }
1126 package Topping::Dessert;
1128 use Class::Std;
1129 {
1130 my %name_of :ATTR( init_arg => 'name' );
1131 my %flavour_of :ATTR( init_arg => 'flavour' );
1132 sub describe :CUMULATIVE {
1134 my ($self) = @_;
1135 print "The dessert topping $name_of{ident $self} ",
1137 "with that great $flavour_of{ident $self} taste!\n";
1138 return;
1140 }
1141 }
1142 package Shimmer;
1144 use base qw( Wax::Floor Topping::Dessert );
1145 use Class::Std;
1146 {
1147 my %name_of :ATTR( init_arg => 'name' );
1148 my %patent_of :ATTR( init_arg => 'patent' );
1149 sub describe :CUMULATIVE {
1151 my ($self) = @_;
1152 print "New $name_of{ident $self} ",
1154 "(patent: $patent_of{ident $self})\n",
1155 "Combining...\n";
1156 return;
1158 }
1159 }
1160 Because the various "describe()" methods are marked as being
1162 cumulative, a subsequent call to:
1163 my $product
1165 = Shimmer->new({
1166 name => 'Shimmer',
1167 patent => 1562516251,
1168 flavour => 'Vanilla',
1169 });
1170 $product->describe();
1172 will work its way up through the classes of Shimmer's inheritance
1174 tree (in the same order as a destructor call would), calling each
1175 "describe()" method it finds along the way. So the single call to
1176 "describe()" would invoke the corresponding method in each class,
1177 producing:
1178 New Shimmer (patent: 1562516251)
1180 Combining...
1181 The floor wax Shimmer (patent: 1562516251)
1182 The dessert topping Shimmer with that great Vanilla taste!
1183 Note that the accumulation of "describe()" methods is hierarchical,
1185 and dynamic in nature. That is, each class only sees those
1186 cumulative methods that are defined in its own package or in one of
1187 its ancestors. So calling the same "describe()" on a base class
1188 object:
1189 my $wax
1191 = Wax::Floor->new({ name=>'Shimmer ', patent=>1562516251 });
1192 $wax->describe();
1194 only invokes the corresponding cumulative methods from that point
1196 on up the hierarchy, and hence only prints:
1197 The floor wax Shimmer (patent: 1562516251)
1199 Cumulative methods also accumulate their return values. In a list
1201 context, they return a (flattened) list that accumulates the lists
1202 returned by each individual method invoked.
1203 In a scalar context, a set of cumulative methods returns an object
1205 that, in a string context, concatenates individual scalar returns
1206 to produce a single string. When used as an array reference that
1207 same scalar-context-return object acts like an array of the list
1208 context values. When used as a hash reference, the object acts like
1209 a hash whose keys are the classnames from the object's hierarchy,
1210 and whose corresponding values are the return values of the
1211 cumulative method from that class.
1212 For example, if the classes each have a cumulative method that
1214 returns their list of sales features:
1215 package Wax::Floor;
1217 use Class::Std;
1218 {
1219 sub feature_list :CUMULATIVE {
1220 return ('Long-lasting', 'Non-toxic', 'Polymer-based');
1221 }
1222 }
1223 package Topping::Dessert;
1225 use Class::Std;
1226 {
1227 sub feature_list :CUMULATIVE {
1228 return ('Low-carb', 'Non-dairy', 'Sugar-free');
1229 }
1230 }
1231 package Shimmer;
1233 use Class::Std;
1234 use base qw( Wax::Floor Topping::Dessert );
1235 {
1236 sub feature_list :CUMULATIVE {
1237 return ('Multi-purpose', 'Time-saving', 'Easy-to-use');
1238 }
1239 }
1240 then calling feature_list() in a list context:
1242 my @features = Shimmer->feature_list();
1244 print "Shimmer is the @features alternative!\n";
1245 would produce a concatenated list of features, which could then be
1247 interpolated into a suitable sales-pitch:
1248 Shimmer is the Multi-purpose Time-saving Easy-to-use
1250 Long-lasting Non-toxic Polymer-based Low-carb Non-dairy
1251 Sugar-free alternative!
1252 It's also possible to specify a set of cumulative methods that
1254 start at the base class(es) of the hierarchy and work downwards,
1255 the way BUILD() does. To get that effect, you simply mark each
1256 method with :CUMULATIVE(BASE FIRST), instead of just :CUMULATIVE.
1257 For example:
1258 package Wax::Floor;
1260 use Class::Std;
1261 {
1262 sub active_ingredients :CUMULATIVE(BASE FIRST) {
1263 return "\tparadichlorobenzene, cyanoacrylate, peanuts\n";
1264 }
1265 }
1266 package Topping::Dessert;
1268 use Class::Std;
1269 {
1270 sub active_ingredients :CUMULATIVE(BASE FIRST) {
1271 return "\tsodium hypochlorite, isobutyl ketone, ethylene glycol\n";
1272 }
1273 }
1274 package Shimmer;
1276 use Class::Std;
1277 use base qw( Wax::Floor Topping::Dessert );
1278 {
1280 sub active_ingredients :CUMULATIVE(BASE FIRST) {
1281 return "\taromatic hydrocarbons, xylene, methyl mercaptan\n";
1282 }
1283 }
1284 So a scalar-context call to active_ingredients():
1286 my $ingredients = Shimmer->active_ingredients();
1288 print "May contain trace amounts of:\n$ingredients";
1289 would start in the base classes and work downwards, concatenating
1291 base- class ingredients before those of the derived class, to
1292 produce:
1293 May contain trace amounts of:
1295 paradichlorobenzene, cyanoacrylate, peanuts
1296 sodium hypochlorite, isobutyl ketone, ethylene glycol
1297 aromatic hydrocarbons, xylene, methyl mercaptan
1298 Or, you could treat the return value as a hash:
1300 print Data::Dumper::Dumper \%{$ingredients};
1302 and see which ingredients came from where:
1304 $VAR1 = {
1306 'Shimmer'
1307 => 'aromatic hydrocarbons, xylene, methyl mercaptan',
1308 'Topping::Dessert'
1310 => 'sodium hypochlorite, isobutyl ketone, ethylene glycol',
1311 'Wax::Floor'
1313 => 'Wax: paradichlorobenzene, hydrogen peroxide, cyanoacrylate',
1314 };
1315 Note that you can't specify both ":CUMULATIVE" and
1317 ":CUMULATIVE(BASE FIRST)" on methods of the same name in the same
1318 hierarchy. The resulting set of methods would have no well-defined
1319 invocation order, so Class::Std throws a compile-time exception
1320 instead.
1321 ":STRINGIFY"
1323 If you define a method and add the ":STRINGIFY" marker then that
1324 method is used whenever an object of the corresponding class needs
1325 to be coerced to a string. In other words, instead of:
1326 # Convert object to a string...
1328 sub as_str {
1329 ...
1330 }
1331 # Convert object to a string automatically in string contexts...
1333 use overload (
1334 q{""} => 'as_str',
1335 fallback => 1,
1336 );
1337 you can just write:
1339 # Convert object to a string (automatically in string contexts)...
1341 sub as_str : STRINGIFY {
1342 ...
1343 }
1344 ":NUMERIFY"
1346 If you define a method and add the ":NUMERIFY" marker then that
1347 method is used whenever an object of the corresponding class needs
1348 to be coerced to a number. In other words, instead of:
1349 # Convert object to a number...
1351 sub as_num {
1352 ...
1353 }
1354 # Convert object to a string automatically in string contexts...
1356 use overload (
1357 q{0+} => 'as_num',
1358 fallback => 1,
1359 );
1360 you can just write:
1362 # Convert object to a number (automatically in numeric contexts)...
1364 sub as_num : NUMERIFY {
1365 ...
1366 }
1367 ":BOOLIFY"
1369 If you define a method and add the ":BOOLIFY" marker then that
1370 method is used whenever an object of the corresponding class needs
1371 to be coerced to a boolean value. In other words, instead of:
1372 # Convert object to a boolean...
1374 sub as_bool {
1375 ...
1376 }
1377 # Convert object to a boolean automatically in boolean contexts...
1379 use overload (
1380 q{bool} => 'as_bool',
1381 fallback => 1,
1382 );
1383 you can just write:
1385 # Convert object to a boolean (automatically in boolean contexts)...
1387 sub as_bool : BOOLIFY {
1388 ...
1389 }
1390 ":SCALARIFY"
1392 ":ARRAYIFY"
1393 ":HASHIFY"
1394 ":GLOBIFY"
1395 ":CODIFY"
1396 If a method is defined with one of these markers, then it is
1397 automatically called whenever an object of that class is treated as
1398 a reference of the corresponding type.
1399 For example, instead of:
1401 sub as_hash {
1403 my ($self) = @_;
1404 return {
1406 age => $age_of{ident $self},
1407 shoesize => $shoe_of{ident $self},
1408 };
1409 }
1410 use overload (
1412 '%{}' => 'as_hash',
1413 fallback => 1,
1414 );
1415 you can just write:
1417 sub as_hash : HASHIFY {
1419 my ($self) = @_;
1420 return {
1422 age => $age_of{ident $self},
1423 shoesize => $shoe_of{ident $self},
1424 };
1425 }
1426 Likewise for methods that allow an object to be treated as a scalar
1428 reference (":SCALARIFY"), a array reference (":ARRAYIFY"), a
1429 subroutine reference (":CODIFY"), or a typeglob reference
1430 (":GLOBIFY").
1431
1433 Can't find class %s
1434 You tried to call the Class::Std::new() constructor on a class that
1435 isn't built using Class::Std. Did you forget to write "use
1436 Class::Std" after the package declaration?
1437 Argument to %s->new() must be hash reference
1439 The constructors created by Class::Std require all initializer
1440 values to be passed in a hash, but you passed something that wasn't
1441 a hash. Put your constructor arguments in a hash.
1442 Missing initializer label for %s: %s
1444 You specified that one or more attributes had initializer values
1445 (using the "init" argument inside the attribute's "ATTR" marker),
1446 but then failed to pass in the corresponding initialization value.
1447 Often this happens because the initialization value was passed, but
1448 the key specifying the attribute name was misspelled.
1449 Can't make anonymous subroutine cumulative
1451 You attempted to use the ":CUMULATIVE" marker on an anonymous
1452 subroutine. But that marker can only be applied to the named
1453 methods of a class. Convert the anonymous subroutine to a named
1454 subroutine, or find some other way to make it interoperate with
1455 other methods.
1456 Conflicting definitions for cumulative method: %s
1458 You defined a ":CUMULATIVE" and a ":CUMULATIVE(BASE FIRST)" method
1459 of the same name in two classes within the same hierarchy. Since
1460 methods can only be called going strictly up through the hierarchy
1461 or going strictly down through the hierarchy, specifying both
1462 directions is obviously a mistake. Either rename one of the
1463 methods, or decide whether they should accumulate upwards or
1464 downwards.
1465 Missing new value in call to 'set_%s' method
1467 You called an attribute setter method without providing a new value
1468 for the attribute. Often this happens because you passed an array
1469 that happened to be empty. Make sure you pass an actual value.
1470 Can't locate %s method "%s" via package %s
1472 You attempted to call a method on an object but no such method is
1473 defined anywhere in the object's class hierarchy. Did you misspell
1474 the method name, or perhaps misunderstand which class the object
1475 belongs to?
1476 %s method %s declared but not defined
1478 A method was declared with a ":RESTRICTED" or ":PRIVATE", like so:
1479 sub foo :RESTRICTED;
1481 sub bar :PRIVATE;
1482 But the actual subroutine was not defined by the end of the
1484 compilation phase, when the module needed it so it could be
1485 rewritten to restrict or privatize it.
1486 Can't call restricted method %s from class %s
1488 The specified method was declared with a ":RESTRICTED" marker but
1489 subsequently called from outside its class hierarchy. Did you call
1490 the wrong method, or the right method from the wrong place?
1491 Can't call private method %s from class %s
1493 The specified method was declared with a ":PRIVATE" marker but
1494 subsequently called from outside its own class. Did you call the
1495 wrong method, or the right method from the wrong place?
1496 Internal error: %s
1498 Your code is okay, but it uncovered a bug in the Class::Std module.
1499 "BUGS AND LIMITATIONS" explains how to report the problem.
1500
1502 Class::Std requires no configuration files or environment variables.
1503
1505 Class::Std depends on the following modules:
1506 • version
1508 • Scalar::Util
1510 • Data::Dumper
1512
1514 Incompatible with the Attribute::Handlers module, since both define
1515 meta-attributes named :ATTR.
1516
1518 • Does not handle threading (including "fork()" under Windows).
1519 • ":ATTR" declarations must all be on the same line (due to a
1521 limitation in Perl itself).
1522 • ":ATTR" declarations cannot include variables, since these are not
1524 interpolated into the declaration (a limitation in Perl itself).
1525 Please report any bugs or feature requests to
1527 "bug-class-std@rt.cpan.org", or through the web interface at
1528 <http://rt.cpan.org>.
1529
1531 Inside-out objects are gaining in popularity and there are now many
1532 other modules that implement frameworks for building inside-out
1533 classes. These include:
1534 Object::InsideOut
1536 Array-based objects, with support for threading. Many excellent
1537 features (especially thread-safety), but slightly less secure than
1538 Class::Std, due to non-encapsulation of attribute data addressing.
1539 Class::InsideOut
1541 A minimalist approach to building inside-out classes.
1542 Lexical::Attributes
1544 Uses source filters to provide a near-Perl 6 approach to declaring
1545 inside-out classes.
1546 Class::Std::Storable
1548 Adds serialization/deserialization to Class::Std.
1549
1551 Damian Conway "<DCONWAY@cpan.org>"
1552
1554 Copyright (c) 2005, Damian Conway "<DCONWAY@cpan.org>". All rights
1555 reserved.
1556 Portions of the documentation from "Perl Best Practices" copyright (c)
1558 2005 by O'Reilly Media, Inc. and reprinted with permission.
1559 This module is free software; you can redistribute it and/or modify it
1561 under the same terms as Perl itself.
1562
1564 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
1565 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
1566 WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
1567 PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
1568 EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
1569 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
1570 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
1571 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
1572 NECESSARY SERVICING, REPAIR, OR CORRECTION.
1573 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
1575 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
1576 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
1577 TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
1578 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
1579 SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
1580 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
1581 FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
1582 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
1583 DAMAGES.
1584perl v5.34.0 2022-01-21 Class::Std(3)