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.0.8
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 Prac‐
60 tices" copyright (c) 2005 by O'Reilly Media, Inc. and reprinted with
61 permission.
62 Introduction
64 Most programmers who use Perl's object-oriented features construct
66 their objects by blessing a hash. But, in doing so, they undermine the
67 robustness of the OO approach. Hash-based objects are unencapsulated:
68 their entries are open for the world to access and modify.
69 Objects without effective encapsulation are vulnerable. Instead of
71 politely respecting their public interface, some clever client coder
72 inevitably will realize that it's marginally faster to interact
73 directly with the underlying implementation, pulling out attribute val‐
74 ues directly from the hash of an object:
75 for my $file ( get_file_objs() ) {
77 print $file->{name}, "\n";
78 }
79 instead of using the official interface:
81 for my $file ( get_file_objs() ) {
83 print $file->get_name(), "\n";
84 }
85 From the moment someone does that, your class is no longer cleanly
87 decoupled from the code that uses it. You can't be sure that any bugs
88 in your class are actually caused by the internals of your class, and
89 not the result of some kind of monkeying by the client code. And to
90 make matters worse, now you can't ever change those internals without
91 the risk of breaking some other part of the system.
92 There is a simple, convenient, and utterly secure way to prevent client
94 code from accessing the internals of the objects you provide. Happily,
95 that approach also guards against misspelling attribute names (a common
96 error in hash-based classes), as well as being just as fast as--and
97 often more memory-efficient than--ordinary hash-based objects.
98 That approach is referred to by various names--flyweight scalars, ware‐
100 housed attributes, inverted indices--but most commonly it's known as:
101 inside-out objects. Consider the following class definitions:
102 package File::Hierarchy;
104 {
105 # Objects of this class have the following attributes...
106 my %root_of; # The root directory of the file hierarchy
107 my %files_of; # Array storing object for each file in root directory
108 # Constructor takes path of file system root directory...
110 sub new {
111 my ($class, $root) = @_;
112 # Bless a scalar to instantiate the new object...
114 my $new_object = bless \do{my $anon_scalar}, $class;
115 # Initialize the object's "root" attribute...
117 $root_of{ident $new_object} = $root;
118 return $new_object;
120 }
121 # Retrieve files from root directory...
123 sub get_files {
124 my ($self) = @_;
125 # Load up the "files" attribute, if necessary...
127 if (!exists $files_of{ident $self}) {
128 $files_of{ident $self}
129 = File::System->list_files($root_of{ident $self});
130 }
131 # Flatten the "files" attribute's array to produce a file list...
133 return @{ $files_of{ident $self} };
134 }
135 }
136 package File::Hierarchy::File;
138 {
139 # Objects of this class have the following attributes...
140 my %name_of; # the name of the file
141 # Constructor takes name of file...
143 sub new {
144 my ($class, $filename) = @_;
145 # Bless a scalar to instantiate the new object...
147 my $new_object = bless \do{my $anon_scalar}, $class;
148 # Initialize the object's "name" attribute...
150 $name_of{ident $new_object} = $filename;
151 return $new_object;
153 }
154 # Retrieve name of file...
156 sub get_name {
157 my ($self) = @_;
158 return $name_of{ident $self};
160 }
161 }
162 Unlike a hash-based class, each of these inside-out class is specified
164 inside a surrounding code block:
165 package File::Hierarchy;
167 {
168 # [Class specification here]
169 }
170 package File::Hierarchy::File;
172 {
173 # [Class specification here]
174 }
175 That block is vital, because it creates a limited scope, to which any
177 lexical variables that are declared as part of the class will automati‐
178 cally be restricted.
179 The next difference between the two versions of the classes is that
181 each attribute of all the objects in the class is now stored in a sepa‐
182 rate single hash:
183 # Objects of this class have the following attributes...
185 my %root_of; # The root directory of the file hierarchy
187 my %files_of; # Array storing object for each file in root directory
188 This is 90 degrees to the usual hash-based approach. In hash-based
190 classes, all the attributes of one object are stored in a single hash;
191 in inside-out classes, one attribute from all objects is stored in a
192 single hash. Diagrammatically:
193 Hash-based:
195 Attribute 1 Attribute 2
196 Object A { attr1 => $valA1, attr2 => $val2 }
198 Object B { attr1 => $valB1, attr2 => $val2 }
200 Object C { attr1 => $valB1, attr2 => $val2 }
202 Inside-out:
204 Object A Object B Object C
205 Attribute 1 { 19817 => $valA1, 172616 => $valB1, 67142 => $valC1 }
207 Attribute 2 { 19817 => $valA2, 172616 => $valB2, 67142 => $valC3 }
209 Attribute 3 { 19817 => $valA3, 172616 => $valB3, 67142 => $valC3 }
211 So the attributes belonging to each object are distributed across a set
213 of predeclared hashes, rather than being squashed together into one
214 anonymous hash.
215 This is a significant improvement. By telling Perl what attributes you
217 expect to use, you enable the compiler to check--via use strict--that
218 you do indeed use only those attributes.
219 That's because of the third difference in the two approaches. Each
221 attribute of a hash-based object is stored in an entry in the object's
222 hash: "$self->{name}". In other words, the name of a hash-based
223 attribute is symbolic: specified by the string value of a hash key. In
224 contrast, each attribute of an inside-out object is stored in an entry
225 of the attribute's hash: $name_of{ident $self}. So the name of an
226 inside-out attribute isn't symbolic; it's a hard-coded variable name.
227 With hash-based objects, if an attribute name is accidentally mis‐
229 spelled in some method:
230 sub set_name {
232 my ($self, $new_name) = @_;
233 $self->{naem} = $new_name; # Oops!
235 return;
237 }
238 then the $self hash will obligingly--and silently!--create a new entry
240 in the hash, with the key 'naem', then assign the new name to it. But
241 since every other method in the class correctly refers to the attribute
242 as "$self-"{name}>, assigning the new value to "$self-"{naem}> effec‐
243 tively makes that assigned value "vanish".
244 With inside-out objects, however, an object's "name" attribute is
246 stored as an entry in the class's lexical %name_of hash. If the
247 attribute name is misspelled then you're attempting to refer to an
248 entirely different hash: %naem_of. Like so:
249 sub set_name {
251 my ($self, $new_name) = @_;
252 $naem_of{ident $self} = $new_name; # Kaboom!
254 return;
256 }
257 But, since there's no such hash declared in the scope, use strict will
259 complain (with extreme prejudice):
260 Global symbol "%naem_of" requires explicit package name at Hierarchy.pm line 86
262 Not only is that consistency check now automatic, it's also performed
264 at compile time.
265 The next difference is even more important and beneficial. Instead of
267 blessing an empty anonymous hash as the new object:
268 my $new_object = bless {}, $class;
270 the inside-out constructor blesses an empty anonymous scalar:
272 my $new_object = bless \do{my $anon_scalar}, $class;
274 That odd-looking "\do{my $anon_scalar}" construct is needed because
276 there's no built-in syntax in Perl for creating a reference to an
277 anonymous scalar; you have to roll-your-own.
278 The anonymous scalar is immediately passed to bless, which anoints it
280 as an object of the appropriate class. The resulting object reference
281 is then stored in $new_object.
282 Once the object exists, it's used to create a unique key ("ident
284 $new_object") under which each attribute that belongs to the object
285 will be stored (e.g. $root_of{ident $new_object} or $name_of{ident
286 $self}). The "ident()" utility that produces this unique key is pro‐
287 vided by the Class::Std module and is identical in effect to the
288 "refaddr()" function in the standard Scalar::Util module.
289 To recap: every inside-out object is a blessed scalar, and has--intrin‐
291 sic to it--a unique identifying integer. That integer can be obtained
292 from the object reference itself, and then used to access a unique
293 entry for the object in each of the class's attribute hashes.
294 This means that every inside-out object is nothing more than an unin‐
296 tialized scalar. When your constructor passes a new inside-out object
297 back to the client code, all that comes back is an empty scalar, which
298 makes it impossible for that client code to gain direct access to the
299 object's internal state.
300 Of the several popular methods of reliably enforcing encapsulation in
302 Perl, inside-out objects are also by far the cheapest. The run-time
303 performance of inside-out classes is effectively identical to that of
304 regular hash-based classes. In particular, in both schemes, every
305 attribute access requires only a single hash look-up. The only appre‐
306 ciable difference in speed occurs when an inside-out object is
307 destroyed.
308 Hash-based classes usually don't even have destructors. When the
310 object's reference count decrements to zero, the hash is automatically
311 reclaimed, and any data structures stored inside the hash are likewise
312 cleaned up. This works so well that many OO Perl programmers find they
313 never need to write a "DESTROY()" method; Perl's built-in garbage col‐
314 lection handles everything just fine. In fact, the only time a destruc‐
315 tor is needed is when objects have to manage resources outside that are
316 not actually located inside the object, resources that need to be sepa‐
317 rately deallocated.
318 But the whole point of an inside-out object is that its attributes are
320 stored in allocated hashes that are not actually located inside the
321 object. That's precisely how it achieves secure encapsulation: by not
322 sending the attributes out into the client code.
323 Unfortunately, that means when an inside-out object is eventually
325 garbage collected, the only storage that is reclaimed is the single
326 blessed scalar implementing the object. The object's attributes are
327 entirely unaffected by the object's deallocation, because the
328 attributes are not inside the object, nor are they referred to by it in
329 any way.
330 Instead, the attributes are referred to by the various attribute hashes
332 in which they're stored. And since those hashes will continue to exist
333 until the end of the program, the defunct object's orphaned attributes
334 will likewise continue to exist, safely nestled inside their respective
335 hashes, but now untended by any object. In other words, when an inside-
336 out object dies, its associated attribute hashes leak memory.
337 The solution is simple. Every inside-out class has to provide a
339 destructor that "manually" cleans up the attributes of the object being
340 destructed:
341 package File::Hierarchy;
343 {
344 # Objects of this class have the following attributes...
345 my %root_of; # The root directory of the file hierarchy
346 my %files_of; # Array storing object for each file in root directory
347 # Constructor takes path of file system root directory...
349 sub new {
350 # As before
351 }
352 # Retrieve files from root directory...
354 sub get_files {
355 # As before
356 }
357 # Clean up attributes when object is destroyed...
359 sub DESTROY {
360 my ($self) = @_;
361 delete $root_of{ident $self};
363 delete $files_of{ident $self};
364 }
365 }
366 The obligation to provide a destructor like this in every inside-out
368 class can be mildly irritating, but it is still a very small price to
369 pay for the considerable benefits that the inside-out approach other‐
370 wise provides for free. And the irritation can easily be eliminated by
371 using the appropriate class construction tools. See below.
372 Automating Inside-Out Classes
374 Perhaps the most annoying part about building classes in Perl (no mat‐
376 ter how the objects are implemented) is that the basic structure of
377 every class is more or less identical. For example, the implementation
378 of the "File::Hierarchy::File" class used in "File::Hierarchy" looks
379 like this:
380 package File::Hierarchy::File;
382 {
383 # Objects of this class have the following attributes...
384 my %name_of; # the name of the file
385 # Constructor takes name of file...
387 sub new {
388 my ($class, $filename) = @_;
389 # Bless a scalar to instantiate the new object...
391 my $new_object = bless \do{my $anon_scalar}, $class;
392 # Initialize the object's "name" attribute...
394 $name_of{ident $new_object} = $filename;
395 return $new_object;
397 }
398 # Retrieve name of file...
400 sub get_name {
401 my ($self) = @_;
402 return $name_of{ident $self};
404 }
405 # Clean up attributes when object is destroyed...
407 sub DESTROY {
408 my ($self) = @_;
409 delete $name_of{ident $self};
411 }
412 }
413 Apart from the actual names of the attributes, and their accessor meth‐
415 ods, that's exactly the same structure, and even the same code, as in
416 the "File::Hierarchy" class.
417 Indeed, the standard infrastructure of every inside-out class looks
419 exactly the same. So it makes sense not to have to rewrite that stan‐
420 dard infrastructure code in every separate class.
421 That's precisely what is module does: it implements the necessary in‐
423 frastructure for inside-out objects. See below.
424
426 Exported subroutines
427 "ident()"
429 Class::Std always exports a subroutine called "ident()". This sub‐
430 routine returns a unique integer ID for any object passed to it.
431 Non-exported subroutines
433 "Class::Std::initialize()"
435 This subroutine sets up all the infrastructure to support your
436 Class::Std- based class. It is usually called automatically in a
437 "CHECK" block, or (if the "CHECK" block fails to run -- under
438 "mod_perl" or "require Class::Std" or "eval "..."") during the
439 first constructor call made to a Class::Std-based object.
440 In rare circumstances, you may need to call this subroutine
442 directly yourself. Specifically, if you set up cumulative,
443 restricted, private, or automethodical class methods (see below),
444 and call any of them before you create any objects, then you need
445 to call "Class::Std::initialize()" first.
446 Methods created automatically
448 The following subroutines are installed in any class that uses the
450 Class::Std module.
451 "new()"
453 Every class that loads the Class::Std module automatically has a
454 "new()" constructor, which returns an inside-out object (i.e. a
455 blessed scalar).
456 $obj = MyClass->new();
458 The constructor can be passed a single argument to initialize the
460 object. This argument must be a hash reference.
461 $obj = MyClass->new({ name=>'Foo', location=>'bar' });
463 See the subsequent descriptions of the "BUILD()" and "START()"
465 methods and ":ATTR()" trait, for an explanation of how the contents
466 of this optional hash can be used to initialize the object.
467 It is almost always an error to implement your own "new()" in any
469 class that uses Class::Std. You almost certainly want to write a
470 "BUILD()" or "START()" method instead. See below.
471 "DESTROY()"
473 Every class that loads the Class::Std module automatically has a
474 "DESTROY()" destructor, which automatically cleans up any
475 attributes declared with the ":ATTR()" trait (see below).
476 It is almost always an error to write your own "DESTROY()" in any
478 class that uses Class::Std. You almost certainly want to write your
479 own "DEMOLISH()" instead. See below.
480 "AUTOLOAD()"
482 Every class that loads the Class::Std module automatically has an
483 "AUTOLOAD()" method, which implements the "AUTOMETHOD()" mechanism
484 described below.
485 It is almost always an error to write your own "AUTOLOAD()" in any
487 class that uses Class::Std. You almost certainly want to write your
488 own "AUTOMETHOD()" instead.
489 "_DUMP()"
491 This method returns a string that represents the internal state
492 (i.e. the attribute values) of the object on which it's called.
493 Only those attributes which are marked with an ":ATTR" (see below)
494 are reported. Attribute names are reported only if they can be
495 ascertained from an ":init_arg", ":get", or ":set" option within
496 the ":ATTR()".
497 Note that "_DUMP()" is not designed to support full serializa‐
499 tion/deserialization of objects. See the separate
500 Class::Std::Storable module (on CPAN) for that.
501 Methods that can be supplied by the developer
503 The following subroutines can be specified as standard methods of a
505 Class::Std class.
506 "BUILD()"
508 When the "new()" constructor of a Class::Std class is called, it
509 automatically calls every method named "BUILD()" in all the classes
510 in the new object's hierarchy. That is, when the constructor is
511 called, it walks the class's inheritance tree (from base classes
512 downwards) and calls every "BUILD()" method it finds along the way.
513 This means that, to initialize any class, you merely need to pro‐
515 vide a "BUILD()" method for that class. You don't have to worry
516 about ensuring that any ancestral "BUILD()" methods also get
517 called; the constructor will take care of that.
518 Each "BUILD()" method is called with three arguments: the invocant
520 object, the identifier number of that object, and a reference to (a
521 customized version of) the hash of arguments that was originally
522 passed to the constructor:
523 sub BUILD {
525 my ($self, $ident, $args_ref) = @_;
526 ...
527 }
528 The argument hash is a "customized version" because the module
530 automatically does some fancy footwork to ensure that the arguments
531 are the ones appropriate to the class itself. That's because
532 there's a potential for collisions when Class::Std classes are used
533 in a hierarchy.
534 One of the great advantages of using inside-out classes instead of
536 hash-based classes is that an inside-out base class and an inside-
537 out derived class can then each have an attribute of exactly the
538 same name, which are stored in separate lexical hashes in separate
539 scopes. In a hash-based object that's impossible, because the sin‐
540 gle hash can't have two attributes with the same key.
541 But that very advantage also presents something of a problem when
543 constructor arguments are themselves passed by hash. If two or more
544 classes in the name hierarchy do happen to have attributes of the
545 same name, the constructor will need two or more initializers with
546 the name key. Which a single hash can't provide.
547 The solution is to allow initializer values to be partitioned into
549 distinct sets, each uniquely named, and which are then passed to
550 the appropriate base class. The easiest way to accomplish that is
551 to pass in a hash of hashes, where each top level key is the name
552 of one of the base classes, and the corresponding value is a hash
553 of initializers specifically for that base class.
554 For example:
556 package Client;
558 use Class::Std::Utils;
559 {
560 my %client_num_of :ATTR; # Every client has a basic ID number
561 my %name_of :ATTR;
562 sub BUILD {
564 my ($self, $ident, $arg_ref) = @_;
565 $client_num_of{$ident} = $arg_ref->{'Client'}{client_num};
567 $name_of{$ident} = $arg_ref->{'Client'}{client_name};
568 }
569 }
570 package Client::Corporate;
572 use base qw( Client );
573 use Class::Std::Utils;
574 {
575 my %client_num_of; # Corporate clients have an additional ID number
576 my %corporation_of;
577 my %position_of;
578 sub BUILD {
580 my ($self, $ident, $arg_ref) = @_;
581 $client_num_of{$ident}
583 = $arg_ref->{'Client::Corporate'}{client_num};
584 $corporation_of{$ident}
585 = $arg_ref->{'Client::Corporate'}{corp_name};
586 $position_of{$ident}
587 = $arg_ref->{'Client::Corporate'}{position};
588 }
589 }
590 # and later...
592 my $new_client
594 = Client::Corporate->new( {
595 'Client' => {
596 client_num => '124C1',
597 client_name => 'Humperdinck',
598 },
599 'Client::Corporate' => {
600 client_num => 'F_1692',
601 corp_name => 'Florin',
602 position => 'CEO',
603 },
604 });
605 Now each class's "BUILD()" method picks out only the initializer
607 sub-hash whose key is that class's own name. Since every class name
608 is different, the top-level keys of this multi-level initializer
609 hash are guaranteed to be unique. And since no single class can
610 have two identically named attributes, the keys of each second-
611 level hash will be unique as well. If two classes in the hierarchy
612 both need an initializer of the same name (e.g. 'client_num'),
613 those two hash entries will now be in separate sub-hashes, so they
614 will never clash.
615 Class::Std provides an even more sophisticated variation on this
617 functionality, which is generally much more convenient for the
618 users of classes. Classes that use Class::Std infrastructure allow
619 both general and class-specific initializers in the initialization
620 hash. Clients only need to specify classes for those initializers
621 whose names actually are ambiguous. Any other arguments can just be
622 passed directly in the top-level hash:
623 my $new_client
625 = Client::Corporate->new( {
626 client_name => 'Humperdinck',
627 corp_name => 'Florin',
628 position => 'CEO',
629 'Client' => { client_num => '124C1' },
631 'Client::Corporate' => { client_num => 'F_1692' },
632 });
633 Class::Std also makes it easy for each class's "BUILD()" to access
635 these class-specific initializer values. Before each "BUILD()" is
636 invoked, the nested hash whose key is the same as the class name is
637 flattened back into the initializer hash itself. That is,
638 "Client::BUILD()" is passed the hash:
639 {
641 client_name => 'Humperdinck',
642 corp_name => 'Florin',
643 position => 'CEO',
644 client_num => '124C1', # Flattened from 'Client' nested subhash
645 'Client' => { client_num => '124C1' },
647 'Client::Corporate' => { client_num => 'F_1692' },
648 }
649 whereas "Client::Corporate::BUILD()" is passed the hash:
651 {
653 client_name => 'Humperdinck',
654 corp_name => 'Florin',
655 position => 'CEO',
656 client_num => 'F_1692', # Flattened from 'Client::Corporate' subhash
657 'Client' => { client_num => '124C1' },
659 'Client::Corporate' => { client_num => 'F_1692' },
660 }
661 This means that the "BUILD()" method for each class can just assume
663 that the correct class-specific initializer values will available
664 at the top level of the hash. For example:
665 sub Client::BUILD {
667 my ($self, $ident, $arg_ref) = @_;
668 $client_num_of{$ident} = $arg_ref->{client_num}; # '124C1'
670 $name_of{$ident} = $arg_ref->{client_name};
671 }
672 sub Client::Corporate::BUILD {
674 my ($self, $ident, $arg_ref) = @_;
675 $client_num_of{$ident} = $arg_ref->{client_num}; # 'F_1692'
677 $corporation_of{$ident} = $arg_ref->{corp_name};
678 $position_of{$ident} = $arg_ref->{position};
679 }
680 Both classes use the "$arg_ref->{client_num}" initializer value,
682 but Class::Std automatically arranges for that value to be the
683 right one for each class.
684 Also see the ":ATTR()" marker (described below) for a simpler way
686 of initializing attributes.
687 "START()"
689 Once all the "BUILD()" methods of a class have been called and any
690 initialization values or defaults have been subsequently applied to
691 uninitialized attributes, Class::Std arranges for any "START()"
692 methods in the class's hierarchy to be called befre the constructor
693 finishes. That is, after the build and default initialization pro‐
694 cesses are complete, the constructor walks down the class's inheri‐
695 tance tree a second time and calls every "START()" method it finds
696 along the way.
697 As with "BUILD()", each "START()" method is called with three argu‐
699 ments: the invocant object, the identifier number of that object,
700 and a reference to (a customized version of) the hash of arguments
701 that was originally passed to the constructor.
702 The main difference between a "BUILD()" method and a "START()"
704 method is that a "BUILD()" method runs before any attribute of the
705 class is auto-initialized or default-initialized, whereas a
706 "START()" method runs after all the attributes of the class
707 (including attributes in derived classes) have been initialized in
708 some way. So if you want to pre-empt the initialization process,
709 write a "BUILD()". But if you want to do something with the newly
710 created and fully initialized object, write a "START()" instead. Of
711 course, any class can define both a "BUILD()" and a "START()"
712 method, if that happens to be appropriate.
713 "DEMOLISH()"
715 The "DESTROY()" method that is automatically provided by Class::Std
716 ensures that all the marked attributes (see the ":ATTR()" marker
717 below) of an object, from all the classes in its inheritance hier‐
718 archy, are automatically cleaned up.
719 But, if a class requires other destructor behaviours (e.g. closing
721 filehandles, decrementing allocation counts, etc.) then you may
722 need to specify those explicitly.
723 Whenever an object of a Class::Std class is destroyed, the
725 "DESTROY()" method supplied by Class::Std automatically calls every
726 method named "DEMOLISH()" in all the classes in the new object's
727 hierarchy. That is, when the destructor is called, it walks the
728 class's inheritance tree (from derived classes upwards) and calls
729 every "DEMOLISH()" method it finds along the way.
730 This means that, to clean up any class, you merely need to provide
732 a "DEMOLISH()" method for that class. You don't have to worry about
733 ensuring that any ancestral "DEMOLISH()" methods also get called;
734 the destructor will take care of that.
735 Each "DEMOLISH()" method is called with two arguments: the invocant
737 object, and the identifier number of that object. For example:
738 sub DEMOLISH {
740 my ($self, $ident) = @_;
741 $filehandle_of{$ident}->flush();
743 $filehandle_of{$ident}->close();
744 }
745 Note that the attributes of the object are cleaned up after the
747 "DEMOLISH()" method is complete, so they may still be used within
748 that method.
749 "AUTOMETHOD()"
751 There is a significant problem with Perl's built-in "AUTOLOAD"
752 mechanism: there's no way for a particular "AUTOLOAD()" to say
753 "no".
754 If two or more classes in a class hierarchy have separate
756 "AUTOLOAD()" methods, then the one belonging to the left-most-
757 depth-first class in the inheritance tree will always be invoked in
758 preference to any others. If it can't handle a particular call,
759 the call will probably fail catastrophically. This means that
760 derived classes can't always be used in place of base classes (a
761 feature known as "Liskov substitutability") because their inherited
762 autoloading behaviour may be pre-empted by some other unrelated
763 base class on their left in the hierarchy.
764 Class::Std provides a mechanism that solves this problem: the
766 "AUTOMETHOD" method. An AUTOMETHOD() is expected to return either a
767 handler subroutine that implements the requested method functional‐
768 ity, or else an "undef" to indicate that it doesn't know how to
769 handle the request. Class::Std then coordinates every
770 "AUTOMETHOD()" in an object's hierarchy, trying each one in turn
771 until one of them produces a suitable handler.
772 The advantage of this approach is that the first "AUTOMETHOD()"
774 that's invoked doesn't have to disenfranchise every other
775 "AUTOMETHOD()" in the hierarchy. If the first one can't handle a
776 particular method call, it simply declines it and Class::Std tries
777 the next candidate instead.
778 Using "AUTOMETHOD()" instead of "AUTOLOAD()" makes a class cleaner,
780 more robust, and less disruptive in class hierarchies. For exam‐
781 ple:
782 package Phonebook;
784 use Class::Std;
785 {
786 my %entries_of : ATTR;
787 # Any method call is someone's name:
789 # so store their phone number or get it...
790 sub AUTOMETHOD {
791 my ($self, $ident, $number) = @_;
792 my $subname = $_; # Requested subroutine name is passed via $_
794 # Return failure if not a get_<name> or set_<name>
796 # (Next AUTOMETHOD() in hierarchy will then be tried instead)...
797 my ($mode, $name) = $subname =~ m/\A ([gs]et)_(.*) \z/xms
798 or return;
799 # If get_<name>, return a handler that just returns the old number...
801 return sub { return $entries_of{$ident}->{$name}; }
802 if $mode eq 'get';
803 # Otherwise, set_<name>, so return a handler that
805 # updates the entry and then returns the old number...
806 return sub {
807 $entries_of{$ident}->{$name} = $number;
808 return;
809 };
810 }
811 }
812 # and later...
814 my $lbb = Phonebook->new();
816 $lbb->set_Jenny(867_5309);
818 $lbb->set_Glenn(736_5000);
819 print $lbb->get_Jenny(), "\n";
821 print $lbb->get_Glenn(), "\n";
822 Note that, unlike "AUTOLOAD()", an "AUTOMETHOD()" is called with
824 both the invocant and the invocant's unique "ident" number, fol‐
825 lowed by the actual arguments that were passed to the method.
826 Note too that the name of the method being called is passed as $_
828 instead of $AUTOLOAD, and does not have the class name prepended to
829 it, so you don't have to strip that name off the front like almost
830 everyone almost always does in their "AUTOLOAD()". If your
831 "AUTOMETHOD()" also needs to access the $_ from the caller's scope,
832 that's still available as $CALLER::_.
833 Variable traits that can be ascribed
835 The following markers can be added to the definition of any hash used
837 as an attribute storage within a Class::Std class
838 ":ATTR()"
840 This marker can be used to indicate that a lexical hash is being
841 used to store one particular attribute of all the objects of the
842 class. That is:
843 package File::Hierarchy;
845 {
846 my %root_of :ATTR;
847 my %files_of :ATTR;
848 # etc.
850 }
851 package File::Hierarchy::File;
853 {
854 my %name_of; :ATTR;
855 # etc.
857 }
858 Adding the ":ATTR" marker to an attribute hash ensures that the
860 corresponding attribute belonging to each object of the class is
861 automatically cleaned up when the object is destroyed.
862 The ":ATTR" marker can also be given a number of options which
864 automate other attribute-related behaviours. Each of these options
865 consists of a key/value pair, which may be specified in either Perl
866 5 "fat comma" syntax ( "key => 'value'" ) or in one of the Perl 6
867 option syntaxes ( ":key<value>" or ":key('value')" or
868 ":key«value»").
869 Note that, due to a limitation in Perl itself, the complete ":ATTR"
871 marker, including its options must appear on a single line. inter‐
872 polate variables into the option values
873 ":ATTR( :init_arg<initializer_key> )"
875 This option tells Class::Std which key in the constructor's
876 initializer hash holds the value with which the marked
877 attribute should be initialized. That is, instead of writing:
878 my %rank_of :ATTR;
880 sub BUILD {
882 my ($self, $ident, $arg_ref) = @_;
883 $rank_of{$ident} = $arg_ref->{rank};
885 }
886 you can achieve the same initialization, by having Class::Std
888 automatically pull that entry out of the hash and store it in
889 the right attribute:
890 my %rank_of :ATTR( :init_arg<rank> );
892 # No BUILD() method required
894 ":ATTR( :default<compile_time_default_value> )"
896 If a marked attribute is not initialized (either directly
897 within a "BUILD()", or automatically via an ":init_arg"
898 option), the constructor supplied by Class::Std checks to see
899 if a default value was specified for that attribute. If so,
900 that value is assigned to the attribute.
901 So you could replace:
903 my %seen_of :ATTR;
905 sub BUILD {
907 my ($self, $ident, $arg_ref) = @_;
908 $seen_of{$ident} = 0; # Not seen yet
910 }
911 with:
913 my %seen_of :ATTR( :default(0) );
915 # No BUILD() required
917 Note that only literal strings and numbers can be used as
919 default values. A common mistake is to write:
920 my %seen_of :ATTR( :default($some_variable) );
922 But variables like this aren't interpolated into ":ATTR" mark‐
924 ers (this is a limitation of Perl, not Class::Std).
925 If your attribute needs something more complex, you will have
927 to default initialize it in a "START()" method:
928 my %seen_of :ATTR;
930 sub START {
932 my ($self, $id, $args_ref) = @_;
933 if (!defined $seen_of{$id}) {
935 $seen_of{$id} = $some_variable;
936 }
937 }
938 ":ATTR( :get<name> )"
940 If the ":get" option is specified, a read accessor is created
941 for the corresponding attribute. The name of the accessor is
942 "get_" followed by whatever name is specified as the value of
943 the ":get" option. For example, instead of:
944 my %current_count_of :ATTR;
946 sub get_count {
948 my ($self) = @_;
949 return $current_count_of{ident($self)};
951 }
952 you can just write:
954 my %count_of :ATTR( :get<count> );
956 Note that there is no way to prevent Class::Std adding the ini‐
958 tial "get_" to each accessor name it creates. That's what
959 "standard" means. See Chapter 15 of Perl Best Practices
960 (O'Reilly, 2005) for a full discussion on why accessors should
961 be named this way.
962 ":ATTR( :set<name> )"
964 If the ":set" option is specified, a write accessor is created
965 for the corresponding attribute. The name of the accessor is
966 "set_" followed by whatever name is specified as the value of
967 the ":set" option. For example, instead of:
968 my %current_count_of :ATTR;
970 sub set_count {
972 my ($self, $new_value) = @_;
973 croak "Missing new value in call to 'set_count' method"
975 unless @_ == 2;
976 $current_count_of{ident($self)} = $new_value;
978 }
979 you can just write:
981 my %count_of :ATTR( :set<count> );
983 Note that there is no way to prevent Class::Std adding the ini‐
985 tial "set_" to each accessor name it creates. Nor is there any
986 way to create a combined "getter/setter" accessor. See Chapter
987 15 of Perl Best Practices (O'Reilly, 2005) for a full discus‐
988 sion on why accessors should be named and implemented this way.
989 ":ATTR( :name<name> )"
991 Specifying the ":name" option is merely a convenient shorthand
992 for specifying all three of ":get", ":set", and ":init_arg".
993 You can, of course, specify two or more arguments in a single
995 ":ATTR()" specification:
996 my %rank_of : ATTR( :init_arg<starting_rank> :get<rank> :set<rank> );
998 ":ATTRS()"
1000 This is just another name for the ":ATTR" marker (see above). The
1001 plural form is convenient when you want to specify a series of
1002 attribute hashes in the same statement:
1003 my (
1005 %name_of,
1006 %rank_of,
1007 %snum_of,
1008 %age_of,
1009 %unit_of,
1010 %assignment_of,
1011 %medals_of,
1012 ) : ATTRS;
1013 Method traits that can be ascribed
1015 The following markers can be added to the definition of any subroutine
1017 used as a method within a Class::Std class
1018 ":RESTRICTED()"
1020 ":PRIVATE()"
1021 Occasionally, it is useful to be able to create subroutines that
1022 can only be accessed within a class's own hierarchy (that is, by
1023 derived classes). And sometimes it's even more useful to be able to
1024 create methods that can only be called within a class itself.
1025 Typically these types of methods are utility methods: subroutines
1027 that provide some internal service for a class, or a class hierar‐
1028 chy. Class::Std supports the creation of these kinds of methods by
1029 providing two special markers: ":RESTRICTED()" and ":PRIVATE()".
1030 Methods marked ":RESTRICTED()" are modified at the end of the com‐
1032 pilation phase so that they throw an exception when called from
1033 outside a class's hierarchy. Methods marked ":PRIVATE()" are modi‐
1034 fied so that they throw an exception when called from outside the
1035 class in which they're declared.
1036 For example:
1038 package DogTag;
1040 use Class::Std;
1041 {
1042 my %ID_of : ATTR;
1043 my %rank_of : ATTR;
1044 my $ID_num = 0;
1046 sub _allocate_next_ID : RESTRICTED {
1048 my ($self) = @_;
1049 $ID_of{ident $self} = $ID_num++;
1050 return;
1051 }
1052 sub _check_rank : PRIVATE {
1054 my ($rank) = @_;
1055 return $rank if $VALID_RANK{$rank};
1056 croak "Unknown rank ($rank) specified";
1057 }
1058 sub BUILD {
1060 my ($self, $ident, $arg_ref) = @_;
1061 $self->_allocate_next_ID();
1063 $rank_of{$ident} = _check_rank($arg_ref->{rank});
1064 }
1065 }
1066 Of course, this code would run exactly the same without the
1068 ":RESTRICTED()" and ":PRIVATE()" markers, but they ensure that any
1069 attempt to call the two subroutines inappropriately:
1070 package main;
1072 my $dogtag = DogTag->new({ rank => 'PFC' });
1074 $dogtag->_allocate_next_ID();
1076 is suitably punished:
1078 Can't call restricted method DogTag::_allocate_next_ID() from class main
1080 ":CUMULATIVE()"
1082 One of the most important advantages of using the "BUILD()" and
1083 "DEMOLISH()" mechanisms supplied by Class::Std is that those meth‐
1084 ods don't require nested calls to their ancestral methods, via the
1085 "SUPER" pseudo-class. The constructor and destructor provided by
1086 Class::Std take care of the necessary redispatching automatically.
1087 Each "BUILD()" method can focus solely on its own responsibilities;
1088 it doesn't have to also help orchestrate the cumulative constructor
1089 effects across the class hierarchy by remembering to call
1090 "$self->SUPER::BUILD()".
1091 Moreover, calls via "SUPER" can only ever call the method of
1093 exactly one ancestral class, which is not sufficient under multiple
1094 inheritance.
1095 Class::Std provides a different way of creating methods whose
1097 effects accumulate through a class hierarchy, in the same way as
1098 those of "BUILD()" and "DEMOLISH()" do. Specifically, the module
1099 allows you to define your own "cumulative methods".
1100 An ordinary non-cumulative method hides any method of the same name
1102 inherited from any base class, so when a non-cumulative method is
1103 called, only the most-derived version of it is ever invoked. In
1104 contrast, a cumulative method doesn't hide ancestral methods of the
1105 same name; it assimilates them. When a cumulative method is called,
1106 the most-derived version of it is invoked, then any parental ver‐
1107 sions, then any grandparental versions, etc. etc, until every cumu‐
1108 lative method of the same name throughout the entire hierarchy has
1109 been called.
1110 For example, you could define a cumulative "describe()" method to
1112 the various classes in a simple class hierarchy like so:
1113 package Wax::Floor;
1115 use Class::Std;
1116 {
1117 my %name_of :ATTR( init_arg => 'name' );
1118 my %patent_of :ATTR( init_arg => 'patent' );
1119 sub describe :CUMULATIVE {
1121 my ($self) = @_;
1122 print "The floor wax $name_of{ident $self} ",
1124 "(patent: $patent_of{ident $self})\n";
1125 return;
1127 }
1128 }
1129 package Topping::Dessert;
1131 use Class::Std;
1132 {
1133 my %name_of :ATTR( init_arg => 'name' );
1134 my %flavour_of :ATTR( init_arg => 'flavour' );
1135 sub describe :CUMULATIVE {
1137 my ($self) = @_;
1138 print "The dessert topping $name_of{ident $self} ",
1140 "with that great $flavour_of{ident $self} taste!\n";
1141 return;
1143 }
1144 }
1145 package Shimmer;
1147 use base qw( Wax::Floor Topping::Dessert );
1148 use Class::Std;
1149 {
1150 my %name_of :ATTR( init_arg => 'name' );
1151 my %patent_of :ATTR( init_arg => 'patent' );
1152 sub describe :CUMULATIVE {
1154 my ($self) = @_;
1155 print "New $name_of{ident $self} ",
1157 "(patent: $patent_of{ident $self})\n",
1158 "Combining...\n";
1159 return;
1161 }
1162 }
1163 Because the various "describe()" methods are marked as being cumu‐
1165 lative, a subsequent call to:
1166 my $product
1168 = Shimmer->new({
1169 name => 'Shimmer',
1170 patent => 1562516251,
1171 flavour => 'Vanilla',
1172 });
1173 $product->describe();
1175 will work its way up through the classes of Shimmer's inheritance
1177 tree (in the same order as a destructor call would), calling each
1178 "describe()" method it finds along the way. So the single call to
1179 "describe()" would invoke the corresponding method in each class,
1180 producing:
1181 New Shimmer (patent: 1562516251)
1183 Combining...
1184 The floor wax Shimmer (patent: 1562516251)
1185 The dessert topping Shimmer with that great Vanilla taste!
1186 Note that the accumulation of "describe()" methods is hierarchical,
1188 and dynamic in nature. That is, each class only sees those cumula‐
1189 tive methods that are defined in its own package or in one of its
1190 ancestors. So calling the same "describe()" on a base class
1191 object:
1192 my $wax
1194 = Wax::Floor->new({ name=>'Shimmer ', patent=>1562516251 });
1195 $wax->describe();
1197 only invokes the corresponding cumulative methods from that point
1199 on up the hierarchy, and hence only prints:
1200 The floor wax Shimmer (patent: 1562516251)
1202 Cumulative methods also accumulate their return values. In a list
1204 context, they return a (flattened) list that accumulates the lists
1205 returned by each individual method invoked.
1206 In a scalar context, a set of cumulative methods returns an object
1208 that, in a string context, concatenates individual scalar returns
1209 to produce a single string. When used as an array reference that
1210 same scalar-context-return object acts like an array of the list
1211 context values. When used as a hash reference, the object acts like
1212 a hash whose keys are the classnames from the object's hierarchy,
1213 and whose corresponding values are the return values of the cumula‐
1214 tive method from that class.
1215 For example, if the classes each have a cumulative method that
1217 returns their list of sales features:
1218 package Wax::Floor;
1220 use Class::Std;
1221 {
1222 sub feature_list :CUMULATIVE {
1223 return ('Long-lasting', 'Non-toxic', 'Polymer-based');
1224 }
1225 }
1226 package Topping::Dessert;
1228 use Class::Std;
1229 {
1230 sub feature_list :CUMULATIVE {
1231 return ('Low-carb', 'Non-dairy', 'Sugar-free');
1232 }
1233 }
1234 package Shimmer;
1236 use Class::Std;
1237 use base qw( Wax::Floor Topping::Dessert );
1238 {
1239 sub feature_list :CUMULATIVE {
1240 return ('Multi-purpose', 'Time-saving', 'Easy-to-use');
1241 }
1242 }
1243 then calling feature_list() in a list context:
1245 my @features = Shimmer->feature_list();
1247 print "Shimmer is the @features alternative!\n";
1248 would produce a concatenated list of features, which could then be
1250 interpolated into a suitable sales-pitch:
1251 Shimmer is the Multi-purpose Time-saving Easy-to-use
1253 Long-lasting Non-toxic Polymer-based Low-carb Non-dairy
1254 Sugar-free alternative!
1255 It's also possible to specify a set of cumulative methods that
1257 start at the base class(es) of the hierarchy and work downwards,
1258 the way BUILD() does. To get that effect, you simply mark each
1259 method with :CUMULATIVE(BASE FIRST), instead of just :CUMULATIVE.
1260 For example:
1261 package Wax::Floor;
1263 use Class::Std;
1264 {
1265 sub active_ingredients :CUMULATIVE(BASE FIRST) {
1266 return "\tparadichlorobenzene, cyanoacrylate, peanuts\n";
1267 }
1268 }
1269 package Topping::Dessert;
1271 use Class::Std;
1272 {
1273 sub active_ingredients :CUMULATIVE(BASE FIRST) {
1274 return "\tsodium hypochlorite, isobutyl ketone, ethylene glycol\n";
1275 }
1276 }
1277 package Shimmer;
1279 use Class::Std;
1280 use base qw( Wax::Floor Topping::Dessert );
1281 {
1283 sub active_ingredients :CUMULATIVE(BASE FIRST) {
1284 return "\taromatic hydrocarbons, xylene, methyl mercaptan\n";
1285 }
1286 }
1287 So a scalar-context call to active_ingredients():
1289 my $ingredients = Shimmer->active_ingredients();
1291 print "May contain trace amounts of:\n$ingredients";
1292 would start in the base classes and work downwards, concatenating
1294 base- class ingredients before those of the derived class, to pro‐
1295 duce:
1296 May contain trace amounts of:
1298 paradichlorobenzene, cyanoacrylate, peanuts
1299 sodium hypochlorite, isobutyl ketone, ethylene glycol
1300 aromatic hydrocarbons, xylene, methyl mercaptan
1301 Or, you could treat the return value as a hash:
1303 print Data::Dumper::Dumper \%{$ingredients};
1305 and see which ingredients came from where:
1307 $VAR1 = {
1309 'Shimmer'
1310 => 'aromatic hydrocarbons, xylene, methyl mercaptan',
1311 'Topping::Dessert'
1313 => 'sodium hypochlorite, isobutyl ketone, ethylene glycol',
1314 'Wax::Floor'
1316 => 'Wax: paradichlorobenzene, hydrogen peroxide, cyanoacrylate',
1317 };
1318 Note that you can't specify both ":CUMULATIVE" and ":CUMULA‐
1320 TIVE(BASE FIRST)" on methods of the same name in the same hierar‐
1321 chy. The resulting set of methods would have no well-defined invo‐
1322 cation order, so Class::Std throws a compile-time exception
1323 instead.
1324 ":STRINGIFY"
1326 If you define a method and add the ":STRINGIFY" marker then that
1327 method is used whenever an object of the corresponding class needs
1328 to be coerced to a string. In other words, instead of:
1329 # Convert object to a string...
1331 sub as_str {
1332 ...
1333 }
1334 # Convert object to a string automatically in string contexts...
1336 use overload (
1337 q{""} => 'as_str',
1338 fallback => 1,
1339 );
1340 you can just write:
1342 # Convert object to a string (automatically in string contexts)...
1344 sub as_str : STRINGIFY {
1345 ...
1346 }
1347 ":NUMERIFY"
1349 If you define a method and add the ":NUMERIFY" marker then that
1350 method is used whenever an object of the corresponding class needs
1351 to be coerced to a number. In other words, instead of:
1352 # Convert object to a number...
1354 sub as_num {
1355 ...
1356 }
1357 # Convert object to a string automatically in string contexts...
1359 use overload (
1360 q{0+} => 'as_num',
1361 fallback => 1,
1362 );
1363 you can just write:
1365 # Convert object to a number (automatically in numeric contexts)...
1367 sub as_num : NUMERIFY {
1368 ...
1369 }
1370 ":BOOLIFY"
1372 If you define a method and add the ":BOOLIFY" marker then that
1373 method is used whenever an object of the corresponding class needs
1374 to be coerced to a boolean value. In other words, instead of:
1375 # Convert object to a boolean...
1377 sub as_bool {
1378 ...
1379 }
1380 # Convert object to a boolean automatically in boolean contexts...
1382 use overload (
1383 q{bool} => 'as_bool',
1384 fallback => 1,
1385 );
1386 you can just write:
1388 # Convert object to a boolean (automatically in boolean contexts)...
1390 sub as_bool : BOOLIFY {
1391 ...
1392 }
1393 ":SCALARIFY"
1395 ":ARRAYIFY"
1396 ":HASHIFY"
1397 ":GLOBIFY"
1398 ":CODIFY"
1399 If a method is defined with one of these markers, then it is auto‐
1400 matically called whenever an object of that class is treated as a
1401 reference of the corresponding type.
1402 For example, instead of:
1404 sub as_hash {
1406 my ($self) = @_;
1407 return {
1409 age => $age_of{ident $self},
1410 shoesize => $shoe_of{ident $self},
1411 };
1412 }
1413 use overload (
1415 '%{}' => 'as_hash',
1416 fallback => 1,
1417 );
1418 you can just write:
1420 sub as_hash : HASHIFY {
1422 my ($self) = @_;
1423 return {
1425 age => $age_of{ident $self},
1426 shoesize => $shoe_of{ident $self},
1427 };
1428 }
1429 Likewise for methods that allow an object to be treated as a scalar
1431 reference (":SCALARIFY"), a array reference (":ARRAYIFY"), a sub‐
1432 routine reference (":CODIFY"), or a typeglob reference (":GLOB‐
1433 IFY").
1434
1436 Can't find class %s
1437 You tried to call the Class::Std::new() constructor on a class that
1438 isn't built using Class::Std. Did you forget to write "use
1439 Class::Std" after the package declaration?
1440 Argument to %s->new() must be hash reference
1442 The constructors created by Class::Std require all initializer val‐
1443 ues to be passed in a hash, but you passed something that wasn't a
1444 hash. Put your constructor arguments in a hash.
1445 Missing initializer label for %s: %s
1447 You specified that one or more attributes had initializer values
1448 (using the "init" argument inside the attribute's "ATTR" marker),
1449 but then failed to pass in the corresponding initialization value.
1450 Often this happens because the initialization value was passed, but
1451 the key specifying the attribute name was misspelled.
1452 Can't make anonymous subroutine cumulative
1454 You attempted to use the ":CUMULATIVE" marker on an anonymous sub‐
1455 routine. But that marker can only be applied to the named methods
1456 of a class. Convert the anonymous subroutine to a named subroutine,
1457 or find some other way to make it interoperate with other methods.
1458 Conflicting definitions for cumulative method: %s
1460 You defined a ":CUMULATIVE" and a ":CUMULATIVE(BASE FIRST)" method
1461 of the same name in two classes within the same hierarchy. Since
1462 methods can only be called going strictly up through the hierarchy
1463 or going strictly down through the hierarchy, specifying both
1464 directions is obviously a mistake. Either rename one of the meth‐
1465 ods, or decide whether they should accumulate upwards or downwards.
1466 Missing new value in call to 'set_%s' method
1468 You called an attribute setter method without providing a new value
1469 for the attribute. Often this happens because you passed an array
1470 that happened to be empty. Make sure you pass an actual value.
1471 Can't locate %s method "%s" via package %s
1473 You attempted to call a method on an object but no such method is
1474 defined anywhere in the object's class hierarchy. Did you misspell
1475 the method name, or perhaps misunderstand which class the object
1476 belongs to?
1477 %s method %s declared but not defined
1479 A method was declared with a ":RESTRICTED" or ":PRIVATE", like so:
1480 sub foo :RESTRICTED;
1482 sub bar :PRIVATE;
1483 But the actual subroutine was not defined by the end of the compi‐
1485 lation phase, when the module needed it so it could be rewritten to
1486 restrict or privatize it.
1487 Can't call restricted method %s from class %s
1489 The specified method was declared with a ":RESTRICTED" marker but
1490 subsequently called from outside its class hierarchy. Did you call
1491 the wrong method, or the right method from the wrong place?
1492 Can't call private method %s from class %s
1494 The specified method was declared with a ":PRIVATE" marker but sub‐
1495 sequently called from outside its own class. Did you call the wrong
1496 method, or the right method from the wrong place?
1497 Internal error: %s
1499 Your code is okay, but it uncovered a bug in the Class::Std module.
1500 "BUGS AND LIMITATIONS" explains how to report the problem.
1501
1503 Class::Std requires no configuration files or environment variables.
1504
1506 Class::Std depends on the following modules:
1507 · version
1509 · Scalar::Util
1511 · Data::Dumper
1513
1515 Incompatible with the Attribute::Handlers module, since both define
1516 meta-attributes named :ATTR.
1517
1519 · Does not handle threading (including "fork()" under Windows).
1520 · ":ATTR" declarations must all be on the same line (due to a limita‐
1522 tion in Perl itself).
1523 · ":ATTR" declarations cannot include variables, since these are not
1525 interpolated into the declaration (a limitation in Perl itself).
1526 Please report any bugs or feature requests to
1528 "bug-class-std@rt.cpan.org", or through the web interface at
1529 <http://rt.cpan.org>.
1530
1532 Inside-out objects are gaining in popularity and there are now many
1533 other modules that implement frameworks for building inside-out
1534 classes. These include:
1535 Object::InsideOut
1537 Array-based objects, with support for threading. Many excellent
1538 features (especially thread-safety), but slightly less secure than
1539 Class::Std, due to non-encapsulation of attribute data addressing.
1540 Class::InsideOut
1542 A minimalist approach to building inside-out classes.
1543 Lexical::Attributes
1545 Uses source filters to provide a near-Perl 6 approach to declaring
1546 inside-out classes.
1547 Class::Std::Storable
1549 Adds serialization/deserialization to Class::Std.
1550
1552 Damian Conway "<DCONWAY@cpan.org>"
1553
1555 Copyright (c) 2005, Damian Conway "<DCONWAY@cpan.org>". All rights
1556 reserved.
1557 Portions of the documentation from "Perl Best Practices" copyright (c)
1559 2005 by O'Reilly Media, Inc. and reprinted with permission.
1560 This module is free software; you can redistribute it and/or modify it
1562 under the same terms as Perl itself.
1563
1565 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
1566 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
1567 WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
1568 PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
1569 EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
1570 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
1571 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
1572 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
1573 NECESSARY SERVICING, REPAIR, OR CORRECTION.
1574 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
1576 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
1577 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
1578 TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CON‐
1579 SEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFT‐
1580 WARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
1581 INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
1582 THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER
1583 OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
1584perl v5.8.8 2007-03-23 Class::Std(3)