1Class::Std(3)         User Contributed Perl Documentation        Class::Std(3)
2
3
4

NAME

6       Class::Std - Support for creating standard "inside-out" classes
7

VERSION

9       This document describes Class::Std version 0.013
10

SYNOPSIS

12           package MyClass;
13           use Class::Std;
14
15           # Create storage for object attributes...
16           my %name : ATTR;
17           my %rank : ATTR;
18           my %snum : ATTR;
19
20           my %public_data : ATTR;
21
22           # Handle initialization of objects of this class...
23           sub BUILD {
24               my ($self, $obj_ID, $arg_ref) = @_;
25
26               $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
31           # Handle cleanup of objects of this class...
32           sub DEMOLISH {
33               my ($self, $obj_ID) = @_;
34
35               _recycle_serial_num( $snum{$obj_ID} );
36           }
37
38           # Handle unknown method calls...
39           sub AUTOMETHOD {
40               my ($self, $obj_ID, @other_args) = @_;
41
42               # 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
50               warn "Can't call $method_name on ", ref $self, " object";
51
52               return;   # The call is declined by not returning a sub ref
53           }
54

DESCRIPTION

56       This module provides tools that help to implement the "inside out
57       object" class structure in a convenient and standard way.
58
59       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
63   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
69       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
75           for my $file ( get_file_objs() ) {
76               print $file->{name}, "\n";
77           }
78
79       instead of using the official interface:
80
81           for my $file ( get_file_objs() ) {
82               print $file->get_name(), "\n";
83           }
84
85       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
92       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
98       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
102           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
108               # Constructor takes path of file system root directory...
109               sub new {
110                   my ($class, $root) = @_;
111
112                   # Bless a scalar to instantiate the new object...
113                   my $new_object = bless \do{my $anon_scalar}, $class;
114
115                   # Initialize the object's "root" attribute...
116                   $root_of{ident $new_object} = $root;
117
118                   return $new_object;
119               }
120
121               # Retrieve files from root directory...
122               sub get_files {
123                   my ($self) = @_;
124
125                   # 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
131                   # Flatten the "files" attribute's array to produce a file list...
132                   return @{ $files_of{ident $self} };
133               }
134           }
135
136           package File::Hierarchy::File;
137           {
138               # Objects of this class have the following attributes...
139               my %name_of;  # the name of the file
140
141               # Constructor takes name of file...
142               sub new {
143                   my ($class, $filename) = @_;
144
145                   # Bless a scalar to instantiate the new object...
146                   my $new_object = bless \do{my $anon_scalar}, $class;
147
148                   # Initialize the object's "name" attribute...
149                   $name_of{ident $new_object} = $filename;
150
151                   return $new_object;
152               }
153
154               # Retrieve name of file...
155               sub get_name {
156                   my ($self) = @_;
157
158                   return $name_of{ident $self};
159               }
160           }
161
162       Unlike a hash-based class, each of these inside-out class is specified
163       inside a surrounding code block:
164
165           package File::Hierarchy;
166           {
167               # [Class specification here]
168           }
169
170           package File::Hierarchy::File;
171           {
172               # [Class specification here]
173           }
174
175       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
179       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
183           # Objects of this class have the following attributes...
184
185           my %root_of;   # The root directory of the file hierarchy
186           my %files_of;  # Array storing object for each file in root directory
187
188       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
193           Hash-based:
194                            Attribute 1      Attribute 2
195
196            Object A    { attr1 => $valA1,  attr2 => $val2 }
197
198            Object B    { attr1 => $valB1,  attr2 => $val2 }
199
200            Object C    { attr1 => $valB1,  attr2 => $val2 }
201
202
203
204           Inside-out:
205                             Object A           Object B          Object C
206
207           Attribute 1  { 19817 => $valA1,  172616 => $valB1,  67142 => $valC1 }
208
209           Attribute 2  { 19817 => $valA2,  172616 => $valB2,  67142 => $valC3 }
210
211           Attribute 3  { 19817 => $valA3,  172616 => $valB3,  67142 => $valC3 }
212
213       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
217       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
221       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
229       With hash-based objects, if an attribute name is accidentally
230       misspelled in some method:
231
232           sub set_name {
233               my ($self, $new_name) = @_;
234
235               $self->{naem} = $new_name;             # Oops!
236
237               return;
238           }
239
240       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
246       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
251           sub set_name {
252               my ($self, $new_name) = @_;
253
254               $naem_of{ident $self} = $new_name;     # Kaboom!
255
256               return;
257           }
258
259       But, since there's no such hash declared in the scope, use strict will
260       complain (with extreme prejudice):
261
262           Global symbol "%naem_of" requires explicit package name at Hierarchy.pm line 86
263
264       Not only is that consistency check now automatic, it's also performed
265       at compile time.
266
267       The next difference is even more important and beneficial. Instead of
268       blessing an empty anonymous hash as the new object:
269
270           my $new_object = bless {}, $class;
271
272       the inside-out constructor blesses an empty anonymous scalar:
273
274           my $new_object = bless \do{my $anon_scalar}, $class;
275
276       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
280       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
284       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
291       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
296       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
302       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
310       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
320       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
325       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
332       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
339       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
343           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
349               # Constructor takes path of file system root directory...
350               sub new {
351                   # As before
352               }
353
354               # Retrieve files from root directory...
355               sub get_files {
356                   # As before
357               }
358
359               # Clean up attributes when object is destroyed...
360               sub DESTROY {
361                   my ($self) = @_;
362
363                   delete $root_of{ident $self};
364                   delete $files_of{ident $self};
365               }
366           }
367
368       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
375   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
382           package File::Hierarchy::File;
383           {
384               # Objects of this class have the following attributes...
385               my %name_of;  # the name of the file
386
387               # Constructor takes name of file...
388               sub new {
389                   my ($class, $filename) = @_;
390
391                   # Bless a scalar to instantiate the new object...
392                   my $new_object = bless \do{my $anon_scalar}, $class;
393
394                   # Initialize the object's "name" attribute...
395                   $name_of{ident $new_object} = $filename;
396
397                   return $new_object;
398               }
399
400               # Retrieve name of file...
401               sub get_name {
402                   my ($self) = @_;
403
404                   return $name_of{ident $self};
405               }
406
407               # Clean up attributes when object is destroyed...
408               sub DESTROY {
409                   my ($self) = @_;
410
411                   delete $name_of{ident $self};
412               }
413           }
414
415       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
419       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
423       That's precisely what this module does: it implements the necessary
424       infrastructure for inside-out objects. See below.
425

INTERFACE

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
432   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
440           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
446   Methods created automatically
447       The following subroutines are installed in any class that uses the
448       Class::Std module.
449
450       "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
455               $obj = MyClass->new();
456
457           The constructor can be passed a single argument to initialize the
458           object. This argument must be a hash reference.
459
460               $obj = MyClass->new({ name=>'Foo', location=>'bar' });
461
462           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
466           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
470       "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
475           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
479       "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
484           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
488       "_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
496           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
500   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
504       "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
511           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
516           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
521               sub BUILD {
522                   my ($self, $ident, $args_ref) = @_;
523                   ...
524               }
525
526           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
532           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
539           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
545           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
552           For example:
553
554               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
560                   sub BUILD {
561                       my ($self, $ident, $arg_ref) = @_;
562
563                       $client_num_of{$ident} = $arg_ref->{'Client'}{client_num};
564                       $name_of{$ident}       = $arg_ref->{'Client'}{client_name};
565                   }
566               }
567
568               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
576                   sub BUILD {
577                       my ($self, $ident, $arg_ref) = @_;
578
579                       $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
588               # and later...
589
590               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
603           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
613           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
621               my $new_client
622                   = Client::Corporate->new( {
623                       client_name => 'Humperdinck',
624                       corp_name   => 'Florin',
625                       position    => 'CEO',
626
627                       'Client'            => { client_num  => '124C1'  },
628                       'Client::Corporate' => { client_num  => 'F_1692' },
629                   });
630
631           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
637               {
638                   client_name => 'Humperdinck',
639                   corp_name   => 'Florin',
640                   position    => 'CEO',
641                   client_num  => '124C1',   # Flattened from 'Client' nested subhash
642
643                   'Client'            => { client_num  => '124C1'  },
644                   'Client::Corporate' => { client_num  => 'F_1692' },
645               }
646
647           whereas "Client::Corporate::BUILD()" is passed the hash:
648
649               {
650                   client_name => 'Humperdinck',
651                   corp_name   => 'Florin',
652                   position    => 'CEO',
653                   client_num  => 'F_1692',   # Flattened from 'Client::Corporate' subhash
654
655                   'Client'            => { client_num  => '124C1'  },
656                   'Client::Corporate' => { client_num  => 'F_1692' },
657               }
658
659           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
663                   sub Client::BUILD {
664                       my ($self, $ident, $arg_ref) = @_;
665
666                       $client_num_of{$ident} = $arg_ref->{client_num};    # '124C1'
667                       $name_of{$ident}       = $arg_ref->{client_name};
668                   }
669
670                   sub Client::Corporate::BUILD {
671                       my ($self, $ident, $arg_ref) = @_;
672
673                       $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
678           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
682           Also see the ":ATTR()" marker (described below) for a simpler way
683           of initializing attributes.
684
685       "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
695           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
700           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
711       "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
717           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
721           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
728           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
733           Each "DEMOLISH()" method is called with two arguments: the invocant
734           object, and the identifier number of that object. For example:
735
736               sub DEMOLISH {
737                   my ($self, $ident) = @_;
738
739                   $filehandle_of{$ident}->flush();
740                   $filehandle_of{$ident}->close();
741               }
742
743           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
747       "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
752           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
762           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
770           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
776           Using "AUTOMETHOD()" instead of "AUTOLOAD()" makes a class cleaner,
777           more robust, and less disruptive in class hierarchies.  For
778           example:
779
780               package Phonebook;
781               use Class::Std;
782               {
783                   my %entries_of : ATTR;
784
785                   # 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
790                       my $subname = $_;   # Requested subroutine name is passed via $_
791
792                       # 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
797                       # 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
801                       # 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
810               # and later...
811
812               my $lbb = Phonebook->new();
813
814               $lbb->set_Jenny(867_5309);
815               $lbb->set_Glenn(736_5000);
816
817               print $lbb->get_Jenny(), "\n";
818               print $lbb->get_Glenn(), "\n";
819
820           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
824           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
831   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
835       ":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
840               package File::Hierarchy;
841               {
842                   my %root_of  :ATTR;
843                   my %files_of :ATTR;
844
845                   # etc.
846               }
847
848               package File::Hierarchy::File;
849               {
850                   my %name_of;  :ATTR;
851
852                   # etc.
853               }
854
855           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
859           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
866           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
870           ":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
875                   my %rank_of :ATTR;
876
877                   sub BUILD {
878                       my ($self, $ident, $arg_ref) = @_;
879
880                       $rank_of{$ident} = $arg_ref->{rank};
881                   }
882
883               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
887                   my %rank_of :ATTR( :init_arg<rank> );
888
889                   # No BUILD() method required
890
891           ":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
898               So you could replace:
899
900                   my %seen_of :ATTR;
901
902                   sub BUILD {
903                       my ($self, $ident, $arg_ref) = @_;
904
905                       $seen_of{$ident} = 0;  # Not seen yet
906                   }
907
908               with:
909
910                   my %seen_of :ATTR( :default(0) );
911
912                   # No BUILD() required
913
914               Note that only literal strings and numbers can be used as
915               default values. A common mistake is to write:
916
917                   my %seen_of :ATTR( :default($some_variable) );
918
919               But variables like this aren't interpolated into ":ATTR"
920               markers (this is a limitation of Perl, not Class::Std).
921
922               If your attribute needs something more complex, you will have
923               to default initialize it in a "START()" method:
924
925                   my %seen_of :ATTR;
926
927                   sub START {
928                       my ($self, $id, $args_ref) = @_;
929
930                       if (!defined $seen_of{$id}) {
931                           $seen_of{$id} = $some_variable;
932                       }
933                   }
934
935           ":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
941                   my %current_count_of :ATTR;
942
943                   sub get_count {
944                       my ($self) = @_;
945
946                       return $current_count_of{ident($self)};
947                   }
948
949               you can just write:
950
951                   my %count_of :ATTR( :get<count> );
952
953               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
959           ":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
965                   my %current_count_of :ATTR;
966
967                   sub set_count {
968                       my ($self, $new_value) = @_;
969
970                       croak "Missing new value in call to 'set_count' method"
971                           unless @_ == 2;
972
973                       $current_count_of{ident($self)} = $new_value;
974                   }
975
976               you can just write:
977
978                   my %count_of :ATTR( :set<count> );
979
980               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
987           ":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
991           You can, of course, specify two or more arguments in a single
992           ":ATTR()" specification:
993
994               my %rank_of : ATTR( :init_arg<starting_rank>  :get<rank>  :set<rank> );
995
996       ":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
1001               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
1011   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
1015       ":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
1022           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
1028           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
1034           For example:
1035
1036               package DogTag;
1037               use Class::Std;
1038               {
1039                   my %ID_of   : ATTR;
1040                   my %rank_of : ATTR;
1041
1042                   my $ID_num = 0;
1043
1044                   sub _allocate_next_ID : RESTRICTED {
1045                       my ($self) = @_;
1046                       $ID_of{ident $self} = $ID_num++;
1047                       return;
1048                   }
1049
1050                   sub _check_rank : PRIVATE {
1051                       my ($rank) = @_;
1052                       return $rank if $VALID_RANK{$rank};
1053                       croak "Unknown rank ($rank) specified";
1054                   }
1055
1056                   sub BUILD {
1057                       my ($self, $ident, $arg_ref) = @_;
1058
1059                       $self->_allocate_next_ID();
1060                       $rank_of{$ident} = _check_rank($arg_ref->{rank});
1061                   }
1062               }
1063
1064           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
1068               package main;
1069
1070               my $dogtag = DogTag->new({ rank => 'PFC' });
1071
1072               $dogtag->_allocate_next_ID();
1073
1074           is suitably punished:
1075
1076               Can't call restricted method DogTag::_allocate_next_ID() from class main
1077
1078       ":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
1089           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
1093           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
1098           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
1108           For example, you could define a cumulative "describe()" method to
1109           the various classes in a simple class hierarchy like so:
1110
1111               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
1117                   sub describe :CUMULATIVE {
1118                       my ($self) = @_;
1119
1120                       print "The floor wax $name_of{ident $self} ",
1121                             "(patent: $patent_of{ident $self})\n";
1122
1123                       return;
1124                   }
1125               }
1126
1127               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
1133                   sub describe :CUMULATIVE {
1134                       my ($self) = @_;
1135
1136                       print "The dessert topping $name_of{ident $self} ",
1137                             "with that great $flavour_of{ident $self} taste!\n";
1138
1139                       return;
1140                   }
1141               }
1142
1143               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
1150                   sub describe :CUMULATIVE {
1151                       my ($self) = @_;
1152
1153                       print "New $name_of{ident $self} ",
1154                             "(patent: $patent_of{ident $self})\n",
1155                             "Combining...\n";
1156
1157                       return;
1158                   }
1159               }
1160
1161           Because the various "describe()" methods are marked as being
1162           cumulative, a subsequent call to:
1163
1164               my $product
1165                   = Shimmer->new({
1166                         name    => 'Shimmer',
1167                         patent  => 1562516251,
1168                         flavour => 'Vanilla',
1169                     });
1170
1171               $product->describe();
1172
1173           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
1179               New Shimmer (patent: 1562516251)
1180               Combining...
1181               The floor wax Shimmer (patent: 1562516251)
1182               The dessert topping Shimmer with that great Vanilla taste!
1183
1184           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
1190               my $wax
1191                   = Wax::Floor->new({ name=>'Shimmer ', patent=>1562516251 });
1192
1193               $wax->describe();
1194
1195           only invokes the corresponding cumulative methods from that point
1196           on up the hierarchy, and hence only prints:
1197
1198               The floor wax Shimmer (patent: 1562516251)
1199
1200           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
1204           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
1213           For example, if the classes each have a cumulative method that
1214           returns their list of sales features:
1215
1216               package Wax::Floor;
1217               use Class::Std;
1218               {
1219                   sub feature_list :CUMULATIVE {
1220                       return ('Long-lasting', 'Non-toxic', 'Polymer-based');
1221                   }
1222               }
1223
1224               package Topping::Dessert;
1225               use Class::Std;
1226               {
1227                   sub feature_list :CUMULATIVE {
1228                       return ('Low-carb', 'Non-dairy', 'Sugar-free');
1229                   }
1230               }
1231
1232               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
1241           then calling feature_list() in a list context:
1242
1243               my @features = Shimmer->feature_list();
1244               print "Shimmer is the @features alternative!\n";
1245
1246           would produce a concatenated list of features, which could then be
1247           interpolated into a suitable sales-pitch:
1248
1249               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
1253           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
1259               package Wax::Floor;
1260               use Class::Std;
1261               {
1262                   sub active_ingredients :CUMULATIVE(BASE FIRST) {
1263                       return "\tparadichlorobenzene, cyanoacrylate, peanuts\n";
1264                   }
1265               }
1266
1267               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
1275               package Shimmer;
1276               use Class::Std;
1277               use base qw( Wax::Floor  Topping::Dessert );
1278
1279               {
1280                   sub active_ingredients :CUMULATIVE(BASE FIRST) {
1281                       return "\taromatic hydrocarbons, xylene, methyl mercaptan\n";
1282                   }
1283               }
1284
1285           So a scalar-context call to active_ingredients():
1286
1287               my $ingredients = Shimmer->active_ingredients();
1288               print "May contain trace amounts of:\n$ingredients";
1289
1290           would start in the base classes and work downwards, concatenating
1291           base- class ingredients before those of the derived class, to
1292           produce:
1293
1294               May contain trace amounts of:
1295                   paradichlorobenzene, cyanoacrylate, peanuts
1296                   sodium hypochlorite, isobutyl ketone, ethylene glycol
1297                   aromatic hydrocarbons, xylene, methyl mercaptan
1298
1299           Or, you could treat the return value as a hash:
1300
1301               print Data::Dumper::Dumper \%{$ingredients};
1302
1303           and see which ingredients came from where:
1304
1305               $VAR1 = {
1306                  'Shimmer'
1307                       => 'aromatic hydrocarbons, xylene, methyl mercaptan',
1308
1309                  'Topping::Dessert'
1310                       => 'sodium hypochlorite, isobutyl ketone, ethylene glycol',
1311
1312                   'Wax::Floor'
1313                       => 'Wax: paradichlorobenzene,  hydrogen peroxide, cyanoacrylate',
1314               };
1315
1316           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
1322       ":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
1327               # Convert object to a string...
1328               sub as_str {
1329                   ...
1330               }
1331
1332               # Convert object to a string automatically in string contexts...
1333               use overload (
1334                   q{""}    => 'as_str',
1335                   fallback => 1,
1336               );
1337
1338           you can just write:
1339
1340               # Convert object to a string (automatically in string contexts)...
1341               sub as_str : STRINGIFY {
1342                   ...
1343               }
1344
1345       ":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
1350               # Convert object to a number...
1351               sub as_num {
1352                   ...
1353               }
1354
1355               # Convert object to a string automatically in string contexts...
1356               use overload (
1357                   q{0+}    => 'as_num',
1358                   fallback => 1,
1359               );
1360
1361           you can just write:
1362
1363               # Convert object to a number (automatically in numeric contexts)...
1364               sub as_num : NUMERIFY {
1365                   ...
1366               }
1367
1368       ":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
1373               # Convert object to a boolean...
1374               sub as_bool {
1375                   ...
1376               }
1377
1378               # Convert object to a boolean automatically in boolean contexts...
1379               use overload (
1380                   q{bool}    => 'as_bool',
1381                   fallback => 1,
1382               );
1383
1384           you can just write:
1385
1386               # Convert object to a boolean (automatically in boolean contexts)...
1387               sub as_bool : BOOLIFY {
1388                   ...
1389               }
1390
1391       ":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
1400           For example, instead of:
1401
1402               sub as_hash {
1403                   my ($self) = @_;
1404
1405                   return {
1406                       age      => $age_of{ident $self},
1407                       shoesize => $shoe_of{ident $self},
1408                   };
1409               }
1410
1411               use overload (
1412                   '%{}'    => 'as_hash',
1413                   fallback => 1,
1414               );
1415
1416           you can just write:
1417
1418               sub as_hash : HASHIFY {
1419                   my ($self) = @_;
1420
1421                   return {
1422                       age      => $age_of{ident $self},
1423                       shoesize => $shoe_of{ident $self},
1424                   };
1425               }
1426
1427           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

DIAGNOSTICS

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
1438       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
1443       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
1450       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
1457       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
1466       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
1471       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
1477       %s method %s declared but not defined
1478           A method was declared with a ":RESTRICTED" or ":PRIVATE", like so:
1479
1480               sub foo :RESTRICTED;
1481               sub bar :PRIVATE;
1482
1483           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
1487       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
1492       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
1497       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

CONFIGURATION AND ENVIRONMENT

1502       Class::Std requires no configuration files or environment variables.
1503

DEPENDENCIES

1505       Class::Std depends on the following modules:
1506
1507       •   version
1508
1509       •   Scalar::Util
1510
1511       •   Data::Dumper
1512

INCOMPATIBILITIES

1514       Incompatible with the Attribute::Handlers module, since both define
1515       meta-attributes named :ATTR.
1516

BUGS AND LIMITATIONS

1518       •   Does not handle threading (including "fork()" under Windows).
1519
1520       •   ":ATTR" declarations must all be on the same line (due to a
1521           limitation in Perl itself).
1522
1523       •   ":ATTR" declarations cannot include variables, since these are not
1524           interpolated into the declaration (a limitation in Perl itself).
1525
1526       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

ALTERNATIVES

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
1535       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
1540       Class::InsideOut
1541           A minimalist approach to building inside-out classes.
1542
1543       Lexical::Attributes
1544           Uses source filters to provide a near-Perl 6 approach to declaring
1545           inside-out classes.
1546
1547       Class::Std::Storable
1548           Adds serialization/deserialization to Class::Std.
1549

AUTHOR

1551       Damian Conway  "<DCONWAY@cpan.org>"
1552
1554       Copyright (c) 2005, Damian Conway "<DCONWAY@cpan.org>". All rights
1555       reserved.
1556
1557       Portions of the documentation from "Perl Best Practices" copyright (c)
1558       2005 by O'Reilly Media, Inc. and reprinted with permission.
1559
1560       This module is free software; you can redistribute it and/or modify it
1561       under the same terms as Perl itself.
1562

DISCLAIMER OF WARRANTY

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
1574       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.
1584
1585
1586
1587perl v5.34.0                      2022-01-21                     Class::Std(3)
Impressum