This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
doubled words in pods (from Simon Cozens
[perl5.git] / pod / perltootc.pod
CommitLineData
19799a22
GS
1=head1 NAME
2
3perltootc - Tom's OO Tutorial for Class Data in Perl
4
5=head1 DESCRIPTION
6
7When designing an object class, you are sometimes faced with the situation
8of wanting common state shared by all objects of that class.
9Such I<class attributes> act somewhat like global variables for the entire
10class, but unlike program-wide globals, class attributes have meaning only to
11the class itself.
12
13Here are a few examples where class attributes might come in handy:
14
15=over
16
17=item *
18
19to keep a count of the objects you've created, or how many are
20still extant.
21
22=item *
23
24to extract the name or file descriptor for a logfile used by a debugging
25method.
26
27=item *
28
29to access collective data, like the total amount of cash dispensed by
30all ATMs in a network in a given day.
31
32=item *
33
34to access the last object created by a class, or the most accessed object,
35or to retrieve a list of all objects.
36
37=back
38
39Unlike a true global, class attributes should not be accessed directly.
40Instead, their state should be inspected, and perhaps altered, only
41through the mediated access of I<class methods>. These class attributes
42accessor methods are similar in spirit and function to accessors used
43to manipulate the state of instance attributes on an object. They provide a
44clear firewall between interface and implementation.
45
46You should allow access to class attributes through either the class
47name or any object of that class. If we assume that $an_object is of
48type Some_Class, and the &Some_Class::population_count method accesses
49class attributes, then these two invocations should both be possible,
50and almost certainly equivalent.
51
52 Some_Class->population_count()
53 $an_object->population_count()
54
55The question is, where do you store the state which that method accesses?
56Unlike more restrictive languages like C++, where these are called
57static data members, Perl provides no syntactic mechanism to declare
58class attributes, any more than it provides a syntactic mechanism to
59declare instance attributes. Perl provides the developer with a broad
60set of powerful but flexible features that can be uniquely crafted to
61the particular demands of the situation.
62
63A class in Perl is typically implemented in a module. A module consists
64of two complementary feature sets: a package for interfacing with the
65outside world, and a lexical file scope for privacy. Either of these
66two mechanisms can be used to implement class attributes. That means you
67get to decide whether to put your class attributes in package variables
68or to put them in lexical variables.
69
70And those aren't the only decisions to make. If you choose to use package
71variables, you can make your class attribute accessor methods either ignorant
72of inheritance or sensitive to it. If you choose lexical variables,
73you can elect to permit access to them from anywhere in the entire file
74scope, or you can limit direct data access exclusively to the methods
75implementing those attributes.
76
77=head1 Class Data as Package Variables
78
79Because a class in Perl is really just a package, using package variables
80to hold class attributes is the most natural choice. This makes it simple
81for each class to have its own class attributes. Let's say you have a class
82called Some_Class that needs a couple of different attributes that you'd
83like to be global to the entire class. The simplest thing to do is to
84use package variables like $Some_Class::CData1 and $Some_Class::CData2
85to hold these attributes. But we certainly don't want to encourage
86outsiders to touch those data directly, so we provide methods
87to mediate access.
88
89In the accessor methods below, we'll for now just ignore the first
90argument--that part to the left of the arrow on method invocation, which
91is either a class name or an object reference.
92
93 package Some_Class;
94 sub CData1 {
95 shift; # XXX: ignore calling class/object
96 $Some_Class::CData1 = shift if @_;
97 return $Some_Class::CData1;
98 }
99 sub CData2 {
100 shift; # XXX: ignore calling class/object
101 $Some_Class::CData2 = shift if @_;
102 return $Some_Class::CData2;
103 }
104
105This technique is highly legible and should be completely straightforward
106to even the novice Perl programmer. By fully qualifying the package
107variables, they stand out clearly when reading the code. Unfortunately,
108if you misspell one of these, you've introduced an error that's hard
109to catch. It's also somewhat disconcerting to see the class name itself
110hard-coded in so many places.
111
112Both these problems can be easily fixed. Just add the C<use strict>
113pragma, then pre-declare your package variables. (The C<our> operator
87275199 114will be new in 5.6, and will work for package globals just like C<my>
19799a22
GS
115works for scoped lexicals.)
116
117 package Some_Class;
118 use strict;
87275199 119 our($CData1, $CData2); # our() is new to perl5.6
19799a22
GS
120 sub CData1 {
121 shift; # XXX: ignore calling class/object
122 $CData1 = shift if @_;
123 return $CData1;
124 }
125 sub CData2 {
126 shift; # XXX: ignore calling class/object
127 $CData2 = shift if @_;
128 return $CData2;
129 }
130
131
132As with any other global variable, some programmers prefer to start their
133package variables with capital letters. This helps clarity somewhat, but
134by no longer fully qualifying the package variables, their significance
135can be lost when reading the code. You can fix this easily enough by
136choosing better names than were used here.
137
138=head2 Putting All Your Eggs in One Basket
139
140Just as the mindless enumeration of accessor methods for instance attributes
141grows tedious after the first few (see L<perltoot>), so too does the
142repetition begin to grate when listing out accessor methods for class
143data. Repetition runs counter to the primary virtue of a programmer:
144Laziness, here manifesting as that innate urge every programmer feels
145to factor out duplicate code whenever possible.
146
147Here's what to do. First, make just one hash to hold all class attributes.
148
149 package Some_Class;
150 use strict;
87275199 151 our %ClassData = ( # our() is new to perl5.6
19799a22
GS
152 CData1 => "",
153 CData2 => "",
154 );
155
156Using closures (see L<perlref>) and direct access to the package symbol
157table (see L<perlmod>), now clone an accessor method for each key in
158the %ClassData hash. Each of these methods is used to fetch or store
159values to the specific, named class attribute.
160
161 for my $datum (keys %ClassData) {
162 no strict "refs"; # to register new methods in package
163 *$datum = sub {
164 shift; # XXX: ignore calling class/object
165 $ClassData{$datum} = shift if @_;
166 return $ClassData{$datum};
167 }
168 }
169
170It's true that you could work out a solution employing an &AUTOLOAD
171method, but this approach is unlikely to prove satisfactory. Your
172function would have to distinguish between class attributes and object
173attributes; it could interfere with inheritance; and it would have to
174careful about DESTROY. Such complexity is uncalled for in most cases,
175and certainly in this one.
176
177You may wonder why we're rescinding strict refs for the loop. We're
178manipulating the package's symbol table to introduce new function names
179using symbolic references (indirect naming), which the strict pragma
180would otherwise forbid. Normally, symbolic references are a dodgy
181notion at best. This isn't just because they can be used accidentally
182when you aren't meaning to. It's also because for most uses
183to which beginning Perl programmers attempt to put symbolic references,
184we have much better approaches, like nested hashes or hashes of arrays.
185But there's nothing wrong with using symbolic references to manipulate
186something that is meaningful only from the perspective of the package
106325ad 187symbol table, like method names or package variables. In other
19799a22
GS
188words, when you want to refer to the symbol table, use symbol references.
189
190Clustering all the class attributes in one place has several advantages.
191They're easy to spot, initialize, and change. The aggregation also
192makes them convenient to access externally, such as from a debugger
193or a persistence package. The only possible problem is that we don't
194automatically know the name of each class's class object, should it have
195one. This issue is addressed below in L<"The Eponymous Meta-Object">.
196
197=head2 Inheritance Concerns
198
199Suppose you have an instance of a derived class, and you access class
200data using an inherited method call. Should that end up referring
201to the base class's attributes, or to those in the derived class?
202How would it work in the earlier examples? The derived class inherits
203all the base class's methods, including those that access class attributes.
204But what package are the class attributes stored in?
205
206The answer is that, as written, class attributes are stored in the package into
207which those methods were compiled. When you invoke the &CData1 method
208on the name of the derived class or on one of that class's objects, the
209version shown above is still run, so you'll access $Some_Class::CData1--or
210in the method cloning version, C<$Some_Class::ClassData{CData1}>.
211
212Think of these class methods as executing in the context of their base
213class, not in that of their derived class. Sometimes this is exactly
214what you want. If Feline subclasses Carnivore, then the population of
215Carnivores in the world should go up when a new Feline is born.
216But what if you wanted to figure out how many Felines you have apart
217from Carnivores? The current approach doesn't support that.
218
219You'll have to decide on a case-by-case basis whether it makes any sense
220for class attributes to be package-relative. If you want it to be so,
221then stop ignoring the first argument to the function. Either it will
222be a package name if the method was invoked directly on a class name,
223or else it will be an object reference if the method was invoked on an
224object reference. In the latter case, the ref() function provides the
225class of that object.
226
227 package Some_Class;
228 sub CData1 {
229 my $obclass = shift;
230 my $class = ref($obclass) || $obclass;
231 my $varname = $class . "::CData1";
232 no strict "refs"; # to access package data symbolically
233 $$varname = shift if @_;
234 return $$varname;
235 }
236
237And then do likewise for all other class attributes (such as CData2,
238etc.) that you wish to access as package variables in the invoking package
239instead of the compiling package as we had previously.
240
241Once again we temporarily disable the strict references ban, because
242otherwise we couldn't use the fully-qualified symbolic name for
243the package global. This is perfectly reasonable: since all package
244variables by definition live in a package, there's nothing wrong with
245accessing them via that package's symbol table. That's what it's there
246for (well, somewhat).
247
248What about just using a single hash for everything and then cloning
249methods? What would that look like? The only difference would be the
250closure used to produce new method entries for the class's symbol table.
251
252 no strict "refs";
253 *$datum = sub {
254 my $obclass = shift;
255 my $class = ref($obclass) || $obclass;
256 my $varname = $class . "::ClassData";
257 $varname->{$datum} = shift if @_;
258 return $varname->{$datum};
259 }
260
261=head2 The Eponymous Meta-Object
262
263It could be argued that the %ClassData hash in the previous example is
264neither the most imaginative nor the most intuitive of names. Is there
265something else that might make more sense, be more useful, or both?
266
267As it happens, yes, there is. For the "class meta-object", we'll use
268a package variable of the same name as the package itself. Within the
269scope of a package Some_Class declaration, we'll use the eponymously
270named hash %Some_Class as that class's meta-object. (Using an eponymously
271named hash is somewhat reminiscent of classes that name their constructors
272eponymously in the Python or C++ fashion. That is, class Some_Class would
273use &Some_Class::Some_Class as a constructor, probably even exporting that
274name as well. The StrNum class in Recipe 13.14 in I<The Perl Cookbook>
275does this, if you're looking for an example.)
276
277This predictable approach has many benefits, including having a well-known
278identifier to aid in debugging, transparent persistence,
279or checkpointing. It's also the obvious name for monadic classes and
280translucent attributes, discussed later.
281
282Here's an example of such a class. Notice how the name of the
283hash storing the meta-object is the same as the name of the package
284used to implement the class.
285
286 package Some_Class;
287 use strict;
288
289 # create class meta-object using that most perfect of names
87275199 290 our %Some_Class = ( # our() is new to perl5.6
19799a22
GS
291 CData1 => "",
292 CData2 => "",
293 );
294
295 # this accessor is calling-package-relative
296 sub CData1 {
297 my $obclass = shift;
298 my $class = ref($obclass) || $obclass;
299 no strict "refs"; # to access eponymous meta-object
300 $class->{CData1} = shift if @_;
301 return $class->{CData1};
302 }
303
304 # but this accessor is not
305 sub CData2 {
306 shift; # XXX: ignore calling class/object
307 no strict "refs"; # to access eponymous meta-object
308 __PACKAGE__ -> {CData2} = shift if @_;
309 return __PACKAGE__ -> {CData2};
310 }
311
312In the second accessor method, the __PACKAGE__ notation was used for
313two reasons. First, to avoid hardcoding the literal package name
314in the code in case we later want to change that name. Second, to
315clarify to the reader that what matters here is the package currently
316being compiled into, not the package of the invoking object or class.
317If the long sequence of non-alphabetic characters bothers you, you can
318always put the __PACKAGE__ in a variable first.
319
320 sub CData2 {
321 shift; # XXX: ignore calling class/object
322 no strict "refs"; # to access eponymous meta-object
323 my $class = __PACKAGE__;
324 $class->{CData2} = shift if @_;
325 return $class->{CData2};
326 }
327
328Even though we're using symbolic references for good not evil, some
329folks tend to become unnerved when they see so many places with strict
330ref checking disabled. Given a symbolic reference, you can always
331produce a real reference (the reverse is not true, though). So we'll
332create a subroutine that does this conversion for us. If invoked as a
333function of no arguments, it returns a reference to the compiling class's
334eponymous hash. Invoked as a class method, it returns a reference to
335the eponymous hash of its caller. And when invoked as an object method,
336this function returns a reference to the eponymous hash for whatever
337class the object belongs to.
338
339 package Some_Class;
340 use strict;
341
87275199 342 our %Some_Class = ( # our() is new to perl5.6
19799a22
GS
343 CData1 => "",
344 CData2 => "",
345 );
346
347 # tri-natured: function, class method, or object method
348 sub _classobj {
349 my $obclass = shift || __PACKAGE__;
350 my $class = ref($obclass) || $obclass;
351 no strict "refs"; # to convert sym ref to real one
352 return \%$class;
353 }
354
355 for my $datum (keys %{ _classobj() } ) {
356 # turn off strict refs so that we can
357 # register a method in the symbol table
358 no strict "refs";
359 *$datum = sub {
360 use strict "refs";
361 my $self = shift->_classobj();
362 $self->{$datum} = shift if @_;
363 return $self->{$datum};
364 }
365 }
366
367=head2 Indirect References to Class Data
368
369A reasonably common strategy for handling class attributes is to store
370a reference to each package variable on the object itself. This is
371a strategy you've probably seen before, such as in L<perltoot> and
372L<perlbot>, but there may be variations in the example below that you
373haven't thought of before.
374
375 package Some_Class;
87275199 376 our($CData1, $CData2); # our() is new to perl5.6
19799a22
GS
377
378 sub new {
379 my $obclass = shift;
380 return bless my $self = {
381 ObData1 => "",
382 ObData2 => "",
383 CData1 => \$CData1,
384 CData2 => \$CData2,
385 } => (ref $obclass || $obclass);
386 }
387
388 sub ObData1 {
389 my $self = shift;
390 $self->{ObData1} = shift if @_;
391 return $self->{ObData1};
392 }
393
394 sub ObData2 {
395 my $self = shift;
396 $self->{ObData2} = shift if @_;
397 return $self->{ObData2};
398 }
399
400 sub CData1 {
401 my $self = shift;
402 my $dataref = ref $self
403 ? $self->{CData1}
404 : \$CData1;
405 $$dataref = shift if @_;
406 return $$dataref;
407 }
408
409 sub CData2 {
410 my $self = shift;
411 my $dataref = ref $self
412 ? $self->{CData2}
413 : \$CData2;
414 $$dataref = shift if @_;
415 return $$dataref;
416 }
417
418As written above, a derived class will inherit these methods, which
419will consequently access package variables in the base class's package.
420This is not necessarily expected behavior in all circumstances. Here's an
421example that uses a variable meta-object, taking care to access the
422proper package's data.
423
424 package Some_Class;
425 use strict;
426
87275199 427 our %Some_Class = ( # our() is new to perl5.6
19799a22
GS
428 CData1 => "",
429 CData2 => "",
430 );
431
432 sub _classobj {
433 my $self = shift;
434 my $class = ref($self) || $self;
435 no strict "refs";
436 # get (hard) ref to eponymous meta-object
437 return \%$class;
438 }
439
440 sub new {
441 my $obclass = shift;
442 my $classobj = $obclass->_classobj();
443 bless my $self = {
444 ObData1 => "",
445 ObData2 => "",
446 CData1 => \$classobj->{CData1},
447 CData2 => \$classobj->{CData2},
448 } => (ref $obclass || $obclass);
449 return $self;
450 }
451
452 sub ObData1 {
453 my $self = shift;
454 $self->{ObData1} = shift if @_;
455 return $self->{ObData1};
456 }
457
458 sub ObData2 {
459 my $self = shift;
460 $self->{ObData2} = shift if @_;
461 return $self->{ObData2};
462 }
463
464 sub CData1 {
465 my $self = shift;
466 $self = $self->_classobj() unless ref $self;
467 my $dataref = $self->{CData1};
468 $$dataref = shift if @_;
469 return $$dataref;
470 }
471
472 sub CData2 {
473 my $self = shift;
474 $self = $self->_classobj() unless ref $self;
475 my $dataref = $self->{CData2};
476 $$dataref = shift if @_;
477 return $$dataref;
478 }
479
480Not only are we now strict refs clean, using an eponymous meta-object
481seems to make the code cleaner. Unlike the previous version, this one
482does something interesting in the face of inheritance: it accesses the
483class meta-object in the invoking class instead of the one into which
484the method was initially compiled.
485
486You can easily access data in the class meta-object, making
487it easy to dump the complete class state using an external mechanism such
488as when debugging or implementing a persistent class. This works because
489the class meta-object is a package variable, has a well-known name, and
490clusters all its data together. (Transparent persistence
491is not always feasible, but it's certainly an appealing idea.)
492
493There's still no check that object accessor methods have not been
494invoked on a class name. If strict ref checking is enabled, you'd
495blow up. If not, then you get the eponymous meta-object. What you do
496with--or about--this is up to you. The next two sections demonstrate
497innovative uses for this powerful feature.
498
499=head2 Monadic Classes
500
501Some of the standard modules shipped with Perl provide class interfaces
502without any attribute methods whatsoever. The most commonly used module
503not numbered amongst the pragmata, the Exporter module, is a class with
504neither constructors nor attributes. Its job is simply to provide a
505standard interface for modules wishing to export part of their namespace
506into that of their caller. Modules use the Exporter's &import method by
507setting their inheritance list in their package's @ISA array to mention
508"Exporter". But class Exporter provides no constructor, so you can't
509have several instances of the class. In fact, you can't have any--it
510just doesn't make any sense. All you get is its methods. Its interface
511contains no statefulness, so state data is wholly superfluous.
512
513Another sort of class that pops up from time to time is one that supports
514a unique instance. Such classes are called I<monadic classes>, or less
515formally, I<singletons> or I<highlander classes>.
516
517If a class is monadic, where do you store its state, that is,
518its attributes? How do you make sure that there's never more than
519one instance? While you could merely use a slew of package variables,
520it's a lot cleaner to use the eponymously named hash. Here's a complete
521example of a monadic class:
522
523 package Cosmos;
524 %Cosmos = ();
525
526 # accessor method for "name" attribute
527 sub name {
528 my $self = shift;
529 $self->{name} = shift if @_;
530 return $self->{name};
531 }
532
533 # read-only accessor method for "birthday" attribute
534 sub birthday {
535 my $self = shift;
536 die "can't reset birthday" if @_; # XXX: croak() is better
537 return $self->{birthday};
538 }
539
540 # accessor method for "stars" attribute
541 sub stars {
542 my $self = shift;
543 $self->{stars} = shift if @_;
544 return $self->{stars};
545 }
546
547 # oh my - one of our stars just went out!
548 sub supernova {
549 my $self = shift;
550 my $count = $self->stars();
551 $self->stars($count - 1) if $count > 0;
552 }
553
554 # constructor/initializer method - fix by reboot
555 sub bigbang {
556 my $self = shift;
557 %$self = (
558 name => "the world according to tchrist",
559 birthday => time(),
560 stars => 0,
561 );
562 return $self; # yes, it's probably a class. SURPRISE!
563 }
564
565 # After the class is compiled, but before any use or require
566 # returns, we start off the universe with a bang.
567 __PACKAGE__ -> bigbang();
568
569Hold on, that doesn't look like anything special. Those attribute
570accessors look no different than they would if this were a regular class
571instead of a monadic one. The crux of the matter is there's nothing
572that says that $self must hold a reference to a blessed object. It merely
573has to be something you can invoke methods on. Here the package name
574itself, Cosmos, works as an object. Look at the &supernova method. Is that
575a class method or an object method? The answer is that static analysis
576cannot reveal the answer. Perl doesn't care, and neither should you.
577In the three attribute methods, C<%$self> is really accessing the %Cosmos
578package variable.
579
580If like Stephen Hawking, you posit the existence of multiple, sequential,
581and unrelated universes, then you can invoke the &bigbang method yourself
582at any time to start everything all over again. You might think of
583&bigbang as more of an initializer than a constructor, since the function
584doesn't allocate new memory; it only initializes what's already there.
585But like any other constructor, it does return a scalar value to use
586for later method invocations.
587
588Imagine that some day in the future, you decide that one universe just
589isn't enough. You could write a new class from scratch, but you already
590have an existing class that does what you want--except that it's monadic,
591and you want more than just one cosmos.
592
593That's what code reuse via subclassing is all about. Look how short
594the new code is:
595
596 package Multiverse;
597 use Cosmos;
598 @ISA = qw(Cosmos);
599
600 sub new {
601 my $protoverse = shift;
602 my $class = ref($protoverse) || $protoverse;
603 my $self = {};
604 return bless($self, $class)->bigbang();
605 }
606 1;
607
608Because we were careful to be good little creators when we designed our
609Cosmos class, we can now reuse it without touching a single line of code
610when it comes time to write our Multiverse class. The same code that
611worked when invoked as a class method continues to work perfectly well
612when invoked against separate instances of a derived class.
613
614The astonishing thing about the Cosmos class above is that the value
615returned by the &bigbang "constructor" is not a reference to a blessed
616object at all. It's just the class's own name. A class name is, for
617virtually all intents and purposes, a perfectly acceptable object.
618It has state, behavior, and identify, the three crucial components
619of an object system. It even manifests inheritance, polymorphism,
620and encapsulation. And what more can you ask of an object?
621
622To understand object orientation in Perl, it's important to recognize the
623unification of what other programming languages might think of as class
624methods and object methods into just plain methods. "Class methods"
625and "object methods" are distinct only in the compartmentalizing mind
626of the Perl programmer, not in the Perl language itself.
627
628Along those same lines, a constructor is nothing special either, which
629is one reason why Perl has no pre-ordained name for them. "Constructor"
630is just an informal term loosely used to describe a method that returns
631a scalar value that you can make further method calls against. So long
632as it's either a class name or an object reference, that's good enough.
633It doesn't even have to be a reference to a brand new object.
634
635You can have as many--or as few--constructors as you want, and you can
636name them whatever you care to. Blindly and obediently using new()
637for each and every constructor you ever write is to speak Perl with
638such a severe C++ accent that you do a disservice to both languages.
639There's no reason to insist that each class have but one constructor,
640or that that constructor be named new(), or that that constructor be
641used solely as a class method and not an object method.
642
643The next section shows how useful it can be to further distance ourselves
644from any formal distinction between class method calls and object method
645calls, both in constructors and in accessor methods.
646
647=head2 Translucent Attributes
648
649A package's eponymous hash can be used for more than just containing
650per-class, global state data. It can also serve as a sort of template
651containing default settings for object attributes. These default
652settings can then be used in constructors for initialization of a
653particular object. The class's eponymous hash can also be used to
654implement I<translucent attributes>. A translucent attribute is one
655that has a class-wide default. Each object can set its own value for the
c47ff5f1
GS
656attribute, in which case C<< $object->attribute() >> returns that value.
657But if no value has been set, then C<< $object->attribute() >> returns
19799a22
GS
658the class-wide default.
659
660We'll apply something of a copy-on-write approach to these translucent
661attributes. If you're just fetching values from them, you get
662translucency. But if you store a new value to them, that new value is
663set on the current object. On the other hand, if you use the class as
664an object and store the attribute value directly on the class, then the
665meta-object's value changes, and later fetch operations on objects with
666uninitialized values for those attributes will retrieve the meta-object's
667new values. Objects with their own initialized values, however, won't
668see any change.
669
670Let's look at some concrete examples of using these properties before we
671show how to implement them. Suppose that a class named Some_Class
672had a translucent data attribute called "color". First you set the color
673in the meta-object, then you create three objects using a constructor
674that happens to be named &spawn.
675
676 use Vermin;
677 Vermin->color("vermilion");
678
679 $ob1 = Vermin->spawn(); # so that's where Jedi come from
680 $ob2 = Vermin->spawn();
681 $ob3 = Vermin->spawn();
682
683 print $obj3->color(); # prints "vermilion"
684
685Each of these objects' colors is now "vermilion", because that's the
686meta-object's value that attribute, and these objects do not have
687individual color values set.
688
689Changing the attribute on one object has no effect on other objects
690previously created.
691
692 $ob3->color("chartreuse");
693 print $ob3->color(); # prints "chartreuse"
694 print $ob1->color(); # prints "vermilion", translucently
695
696If you now use $ob3 to spawn off another object, the new object will
697take the color its parent held, which now happens to be "chartreuse".
698That's because the constructor uses the invoking object as its template
699for initializing attributes. When that invoking object is the
700class name, the object used as a template is the eponymous meta-object.
701When the invoking object is a reference to an instantiated object, the
702&spawn constructor uses that existing object as a template.
703
704 $ob4 = $ob3->spawn(); # $ob3 now template, not %Vermin
705 print $ob4->color(); # prints "chartreuse"
706
707Any actual values set on the template object will be copied to the
708new object. But attributes undefined in the template object, being
709translucent, will remain undefined and consequently translucent in the
710new one as well.
711
712Now let's change the color attribute on the entire class:
713
714 Vermin->color("azure");
715 print $ob1->color(); # prints "azure"
716 print $ob2->color(); # prints "azure"
717 print $ob3->color(); # prints "chartreuse"
718 print $ob4->color(); # prints "chartreuse"
719
720That color change took effect only in the first pair of objects, which
721were still translucently accessing the meta-object's values. The second
722pair had per-object initialized colors, and so didn't change.
723
724One important question remains. Changes to the meta-object are reflected
725in translucent attributes in the entire class, but what about
726changes to discrete objects? If you change the color of $ob3, does the
727value of $ob4 see that change? Or vice-versa. If you change the color
728of $ob4, does then the value of $ob3 shift?
729
730 $ob3->color("amethyst");
731 print $ob3->color(); # prints "amethyst"
732 print $ob4->color(); # hmm: "chartreuse" or "amethyst"?
733
734While one could argue that in certain rare cases it should, let's not
735do that. Good taste aside, we want the answer to the question posed in
736the comment above to be "chartreuse", not "amethyst". So we'll treat
737these attributes similar to the way process attributes like environment
738variables, user and group IDs, or the current working directory are
739treated across a fork(). You can change only yourself, but you will see
740those changes reflected in your unspawned children. Changes to one object
87275199 741will propagate neither up to the parent nor down to any existing child objects.
19799a22
GS
742Those objects made later, however, will see the changes.
743
744If you have an object with an actual attribute value, and you want to
745make that object's attribute value translucent again, what do you do?
746Let's design the class so that when you invoke an accessor method with
747C<undef> as its argument, that attribute returns to translucency.
748
749 $ob4->color(undef); # back to "azure"
750
751Here's a complete implementation of Vermin as described above.
752
753 package Vermin;
754
755 # here's the class meta-object, eponymously named.
756 # it holds all class attributes, and also all instance attributes
757 # so the latter can be used for both initialization
758 # and translucency.
759
87275199 760 our %Vermin = ( # our() is new to perl5.6
19799a22
GS
761 PopCount => 0, # capital for class attributes
762 color => "beige", # small for instance attributes
763 );
764
765 # constructor method
766 # invoked as class method or object method
767 sub spawn {
768 my $obclass = shift;
769 my $class = ref($obclass) || $obclass;
770 my $self = {};
771 bless($self, $class);
772 $class->{PopCount}++;
773 # init fields from invoking object, or omit if
774 # invoking object is the class to provide translucency
775 %$self = %$obclass if ref $obclass;
776 return $self;
777 }
778
779 # translucent accessor for "color" attribute
780 # invoked as class method or object method
781 sub color {
782 my $self = shift;
783 my $class = ref($self) || $self;
784
785 # handle class invocation
786 unless (ref $self) {
787 $class->{color} = shift if @_;
788 return $class->{color}
789 }
790
791 # handle object invocation
792 $self->{color} = shift if @_;
793 if (defined $self->{color}) { # not exists!
794 return $self->{color};
795 } else {
796 return $class->{color};
797 }
798 }
799
800 # accessor for "PopCount" class attribute
801 # invoked as class method or object method
802 # but uses object solely to locate meta-object
803 sub population {
804 my $obclass = shift;
805 my $class = ref($obclass) || $obclass;
806 return $class->{PopCount};
807 }
808
809 # instance destructor
810 # invoked only as object method
811 sub DESTROY {
812 my $self = shift;
813 my $class = ref $self;
814 $class->{PopCount}--;
815 }
816
817Here are a couple of helper methods that might be convenient. They aren't
818accessor methods at all. They're used to detect accessibility of data
819attributes. The &is_translucent method determines whether a particular
820object attribute is coming from the meta-object. The &has_attribute
821method detects whether a class implements a particular property at all.
822It could also be used to distinguish undefined properties from non-existent
823ones.
824
825 # detect whether an object attribute is translucent
826 # (typically?) invoked only as object method
827 sub is_translucent {
828 my($self, $attr) = @_;
829 return !defined $self->{$attr};
830 }
831
832 # test for presence of attribute in class
833 # invoked as class method or object method
834 sub has_attribute {
835 my($self, $attr) = @_;
836 my $class = ref $self if $self;
837 return exists $class->{$attr};
838 }
839
840If you prefer to install your accessors more generically, you can make
841use of the upper-case versus lower-case convention to register into the
842package appropriate methods cloned from generic closures.
843
844 for my $datum (keys %{ +__PACKAGE__ }) {
845 *$datum = ($datum =~ /^[A-Z]/)
846 ? sub { # install class accessor
847 my $obclass = shift;
848 my $class = ref($obclass) || $obclass;
849 return $class->{$datum};
850 }
851 : sub { # install translucent accessor
852 my $self = shift;
853 my $class = ref($self) || $self;
854 unless (ref $self) {
855 $class->{$datum} = shift if @_;
856 return $class->{$datum}
857 }
858 $self->{$datum} = shift if @_;
859 return defined $self->{$datum}
860 ? $self -> {$datum}
861 : $class -> {$datum}
862 }
863 }
864
865Translations of this closure-based approach into C++, Java, and Python
866have been left as exercises for the reader. Be sure to send us mail as
867soon as you're done.
868
869=head1 Class Data as Lexical Variables
870
871=head2 Privacy and Responsibility
872
873Unlike conventions used by some Perl programmers, in the previous
874examples, we didn't prefix the package variables used for class attributes
875with an underscore, nor did we do so for the names of the hash keys used
876for instance attributes. You don't need little markers on data names to
877suggest nominal privacy on attribute variables or hash keys, because these
878are B<already> notionally private! Outsiders have no business whatsoever
879playing with anything within a class save through the mediated access of
880its documented interface; in other words, through method invocations.
881And not even through just any method, either. Methods that begin with
882an underscore are traditionally considered off-limits outside the class.
883If outsiders skip the documented method interface to poke around the
884internals of your class and end up breaking something, that's not your
885fault--it's theirs.
886
887Perl believes in individual responsibility rather than mandated control.
888Perl respects you enough to let you choose your own preferred level of
889pain, or of pleasure. Perl believes that you are creative, intelligent,
890and capable of making your own decisions--and fully expects you to
891take complete responsibility for your own actions. In a perfect world,
892these admonitions alone would suffice, and everyone would be intelligent,
893responsible, happy, and creative. And careful. One probably shouldn't
894forget careful, and that's a good bit harder to expect. Even Einstein
895would take wrong turns by accident and end up lost in the wrong part
896of town.
897
898Some folks get the heebie-jeebies when they see package variables
899hanging out there for anyone to reach over and alter them. Some folks
900live in constant fear that someone somewhere might do something wicked.
901The solution to that problem is simply to fire the wicked, of course.
902But unfortunately, it's not as simple as all that. These cautious
903types are also afraid that they or others will do something not so
904much wicked as careless, whether by accident or out of desperation.
905If we fire everyone who ever gets careless, pretty soon there won't be
906anybody left to get any work done.
907
908Whether it's needless paranoia or sensible caution, this uneasiness can
909be a problem for some people. We can take the edge off their discomfort
910by providing the option of storing class attributes as lexical variables
911instead of as package variables. The my() operator is the source of
912all privacy in Perl, and it is a powerful form of privacy indeed.
913
914It is widely perceived, and indeed has often been written, that Perl
915provides no data hiding, that it affords the class designer no privacy
916nor isolation, merely a rag-tag assortment of weak and unenforcible
917social conventions instead. This perception is demonstrably false and
918easily disproven. In the next section, we show how to implement forms
919of privacy that are far stronger than those provided in nearly any
920other object-oriented language.
921
922=head2 File-Scoped Lexicals
923
924A lexical variable is visible only through the end of its static scope.
925That means that the only code able to access that variable is code
926residing textually below the my() operator through the end of its block
927if it has one, or through the end of the current file if it doesn't.
928
929Starting again with our simplest example given at the start of this
930document, we replace our() variables with my() versions.
931
932 package Some_Class;
933 my($CData1, $CData2); # file scope, not in any package
934 sub CData1 {
935 shift; # XXX: ignore calling class/object
936 $CData1 = shift if @_;
937 return $CData1;
938 }
939 sub CData2 {
940 shift; # XXX: ignore calling class/object
941 $CData2 = shift if @_;
942 return $CData2;
943 }
944
945So much for that old $Some_Class::CData1 package variable and its brethren!
946Those are gone now, replaced with lexicals. No one outside the
947scope can reach in and alter the class state without resorting to the
948documented interface. Not even subclasses or superclasses of
949this one have unmediated access to $CData1. They have to invoke the &CData1
950method against Some_Class or an instance thereof, just like anybody else.
951
952To be scrupulously honest, that last statement assumes you haven't packed
953several classes together into the same file scope, nor strewn your class
954implementation across several different files. Accessibility of those
955variables is based uniquely on the static file scope. It has nothing to
956do with the package. That means that code in a different file but
957the same package (class) could not access those variables, yet code in the
958same file but a different package (class) could. There are sound reasons
959why we usually suggest a one-to-one mapping between files and packages
960and modules and classes. You don't have to stick to this suggestion if
961you really know what you're doing, but you're apt to confuse yourself
962otherwise, especially at first.
963
964If you'd like to aggregate your class attributes into one lexically scoped,
965composite structure, you're perfectly free to do so.
966
967 package Some_Class;
968 my %ClassData = (
969 CData1 => "",
970 CData2 => "",
971 );
972 sub CData1 {
973 shift; # XXX: ignore calling class/object
974 $ClassData{CData1} = shift if @_;
975 return $ClassData{CData1};
976 }
977 sub CData2 {
978 shift; # XXX: ignore calling class/object
979 $ClassData{CData2} = shift if @_;
980 return $ClassData{CData2};
981 }
982
983To make this more scalable as other class attributes are added, we can
984again register closures into the package symbol table to create accessor
985methods for them.
986
987 package Some_Class;
988 my %ClassData = (
989 CData1 => "",
990 CData2 => "",
991 );
992 for my $datum (keys %ClassData) {
993 no strict "refs";
994 *$datum = sub {
995 shift; # XXX: ignore calling class/object
996 $ClassData{$datum} = shift if @_;
997 return $ClassData{$datum};
998 };
999 }
1000
1001Requiring even your own class to use accessor methods like anybody else is
1002probably a good thing. But demanding and expecting that everyone else,
1003be they subclass or superclass, friend or foe, will all come to your
1004object through mediation is more than just a good idea. It's absolutely
1005critical to the model. Let there be in your mind no such thing as
1006"public" data, nor even "protected" data, which is a seductive but
1007ultimately destructive notion. Both will come back to bite at you.
1008That's because as soon as you take that first step out of the solid
1009position in which all state is considered completely private, save from the
1010perspective of its own accessor methods, you have violated the envelope.
1011And, having pierced that encapsulating envelope, you shall doubtless
1012someday pay the price when future changes in the implementation break
1013unrelated code. Considering that avoiding this infelicitous outcome was
1014precisely why you consented to suffer the slings and arrows of obsequious
1015abstraction by turning to object orientation in the first place, such
1016breakage seems unfortunate in the extreme.
1017
1018=head2 More Inheritance Concerns
1019
1020Suppose that Some_Class were used as a base class from which to derive
1021Another_Class. If you invoke a &CData method on the derived class or
1022on an object of that class, what do you get? Would the derived class
1023have its own state, or would it piggyback on its base class's versions
1024of the class attributes?
1025
1026The answer is that under the scheme outlined above, the derived class
1027would B<not> have its own state data. As before, whether you consider
1028this a good thing or a bad one depends on the semantics of the classes
1029involved.
1030
1031The cleanest, sanest, simplest way to address per-class state in a
1032lexical is for the derived class to override its base class's version
1033of the method that accesses the class attributes. Since the actual method
1034called is the one in the object's derived class if this exists, you
1035automatically get per-class state this way. Any urge to provide an
1036unadvertised method to sneak out a reference to the %ClassData hash
1037should be strenuously resisted.
1038
1039As with any other overridden method, the implementation in the
1040derived class always has the option of invoking its base class's
1041version of the method in addition to its own. Here's an example:
1042
1043 package Another_Class;
1044 @ISA = qw(Some_Class);
1045
1046 my %ClassData = (
1047 CData1 => "",
1048 );
1049
1050 sub CData1 {
1051 my($self, $newvalue) = @_;
1052 if (@_ > 1) {
1053 # set locally first
1054 $ClassData{CData1} = $newvalue;
1055
1056 # then pass the buck up to the first
1057 # overridden version, if there is one
1058 if ($self->can("SUPER::CData1")) {
1059 $self->SUPER::CData1($newvalue);
1060 }
1061 }
1062 return $ClassData{CData1};
1063 }
1064
1065Those dabbling in multiple inheritance might be concerned
1066about there being more than one override.
1067
1068 for my $parent (@ISA) {
1069 my $methname = $parent . "::CData1";
1070 if ($self->can($methname)) {
1071 $self->$methname($newvalue);
1072 }
1073 }
1074
1075Because the &UNIVERSAL::can method returns a reference
1076to the function directly, you can use this directly
1077for a significant performance improvement:
1078
1079 for my $parent (@ISA) {
1080 if (my $coderef = $self->can($parent . "::CData1")) {
1081 $self->$coderef($newvalue);
1082 }
1083 }
1084
1085=head2 Locking the Door and Throwing Away the Key
1086
1087As currently implemented, any code within the same scope as the
1088file-scoped lexical %ClassData can alter that hash directly. Is that
1089ok? Is it acceptable or even desirable to allow other parts of the
1090implementation of this class to access class attributes directly?
1091
1092That depends on how careful you want to be. Think back to the Cosmos
1093class. If the &supernova method had directly altered $Cosmos::Stars or
1094C<$Cosmos::Cosmos{stars}>, then we wouldn't have been able to reuse the
1095class when it came to inventing a Multiverse. So letting even the class
1096itself access its own class attributes without the mediating intervention of
1097properly designed accessor methods is probably not a good idea after all.
1098
1099Restricting access to class attributes from the class itself is usually
1100not enforcible even in strongly object-oriented languages. But in Perl,
1101you can.
1102
1103Here's one way:
1104
1105 package Some_Class;
1106
1107 { # scope for hiding $CData1
1108 my $CData1;
1109 sub CData1 {
1110 shift; # XXX: unused
1111 $CData1 = shift if @_;
1112 return $CData1;
1113 }
1114 }
1115
1116 { # scope for hiding $CData2
1117 my $CData2;
1118 sub CData2 {
1119 shift; # XXX: unused
1120 $CData2 = shift if @_;
1121 return $CData2;
1122 }
1123 }
1124
1125No one--absolutely no one--is allowed to read or write the class
1126attributes without the mediation of the managing accessor method, since
1127only that method has access to the lexical variable it's managing.
87275199 1128This use of mediated access to class attributes is a form of privacy far
19799a22
GS
1129stronger than most OO languages provide.
1130
1131The repetition of code used to create per-datum accessor methods chafes
1132at our Laziness, so we'll again use closures to create similar
1133methods.
1134
1135 package Some_Class;
1136
1137 { # scope for ultra-private meta-object for class attributes
1138 my %ClassData = (
1139 CData1 => "",
1140 CData2 => "",
1141 );
1142
1143 for my $datum (keys %ClassData ) {
1144 no strict "refs";
1145 *$datum = sub {
1146 use strict "refs";
1147 my ($self, $newvalue) = @_;
1148 $ClassData{$datum} = $newvalue if @_ > 1;
1149 return $ClassData{$datum};
1150 }
1151 }
1152
1153 }
1154
1155The closure above can be modified to take inheritance into account using
1156the &UNIVERSAL::can method and SUPER as shown previously.
1157
1158=head2 Translucency Revisited
1159
87275199
GS
1160The Vermin class demonstrates translucency using a package variable,
1161eponymously named %Vermin, as its meta-object. If you prefer to
19799a22
GS
1162use absolutely no package variables beyond those necessary to appease
1163inheritance or possibly the Exporter, this strategy is closed to you.
1164That's too bad, because translucent attributes are an appealing
1165technique, so it would be valuable to devise an implementation using
1166only lexicals.
1167
1168There's a second reason why you might wish to avoid the eponymous
1169package hash. If you use class names with double-colons in them, you
1170would end up poking around somewhere you might not have meant to poke.
1171
1172 package Vermin;
1173 $class = "Vermin";
1174 $class->{PopCount}++;
1175 # accesses $Vermin::Vermin{PopCount}
1176
1177 package Vermin::Noxious;
1178 $class = "Vermin::Noxious";
1179 $class->{PopCount}++;
1180 # accesses $Vermin::Noxious{PopCount}
1181
1182In the first case, because the class name had no double-colons, we got
1183the hash in the current package. But in the second case, instead of
1184getting some hash in the current package, we got the hash %Noxious in
1185the Vermin package. (The noxious vermin just invaded another package and
1186sprayed their data around it. :-) Perl doesn't support relative packages
1187in its naming conventions, so any double-colons trigger a fully-qualified
1188lookup instead of just looking in the current package.
1189
1190In practice, it is unlikely that the Vermin class had an existing
1191package variable named %Noxious that you just blew away. If you're
1192still mistrustful, you could always stake out your own territory
1193where you know the rules, such as using Eponymous::Vermin::Noxious or
1194Hieronymus::Vermin::Boschious or Leave_Me_Alone::Vermin::Noxious as class
1195names instead. Sure, it's in theory possible that someone else has
1196a class named Eponymous::Vermin with its own %Noxious hash, but this
1197kind of thing is always true. There's no arbiter of package names.
1198It's always the case that globals like @Cwd::ISA would collide if more
1199than one class uses the same Cwd package.
1200
1201If this still leaves you with an uncomfortable twinge of paranoia,
1202we have another solution for you. There's nothing that says that you
1203have to have a package variable to hold a class meta-object, either for
1204monadic classes or for translucent attributes. Just code up the methods
1205so that they access a lexical instead.
1206
1207Here's another implementation of the Vermin class with semantics identical
1208to those given previously, but this time using no package variables.
1209
1210 package Vermin;
1211
1212
1213 # Here's the class meta-object, eponymously named.
1214 # It holds all class data, and also all instance data
1215 # so the latter can be used for both initialization
1216 # and translucency. it's a template.
1217 my %ClassData = (
1218 PopCount => 0, # capital for class attributes
1219 color => "beige", # small for instance attributes
1220 );
1221
1222 # constructor method
1223 # invoked as class method or object method
1224 sub spawn {
1225 my $obclass = shift;
1226 my $class = ref($obclass) || $obclass;
1227 my $self = {};
1228 bless($self, $class);
1229 $ClassData{PopCount}++;
1230 # init fields from invoking object, or omit if
1231 # invoking object is the class to provide translucency
1232 %$self = %$obclass if ref $obclass;
1233 return $self;
1234 }
1235
1236 # translucent accessor for "color" attribute
1237 # invoked as class method or object method
1238 sub color {
1239 my $self = shift;
1240
1241 # handle class invocation
1242 unless (ref $self) {
1243 $ClassData{color} = shift if @_;
1244 return $ClassData{color}
1245 }
1246
1247 # handle object invocation
1248 $self->{color} = shift if @_;
1249 if (defined $self->{color}) { # not exists!
1250 return $self->{color};
1251 } else {
1252 return $ClassData{color};
1253 }
1254 }
1255
1256 # class attribute accessor for "PopCount" attribute
1257 # invoked as class method or object method
1258 sub population {
1259 return $ClassData{PopCount};
1260 }
1261
1262 # instance destructor; invoked only as object method
1263 sub DESTROY {
1264 $ClassData{PopCount}--;
1265 }
1266
1267 # detect whether an object attribute is translucent
1268 # (typically?) invoked only as object method
1269 sub is_translucent {
1270 my($self, $attr) = @_;
1271 $self = \%ClassData if !ref $self;
1272 return !defined $self->{$attr};
1273 }
1274
1275 # test for presence of attribute in class
1276 # invoked as class method or object method
1277 sub has_attribute {
1278 my($self, $attr) = @_;
1279 return exists $ClassData{$attr};
1280 }
1281
1282=head1 NOTES
1283
1284Inheritance is a powerful but subtle device, best used only after careful
1285forethought and design. Aggregation instead of inheritance is often a
1286better approach.
1287
1288We use the hypothetical our() syntax for package variables. It works
1289like C<use vars>, but looks like my(). It should be in this summer's
87275199 1290major release (5.6) of perl--we hope.
19799a22
GS
1291
1292You can't use file-scoped lexicals in conjunction with the SelfLoader
1293or the AutoLoader, because they alter the lexical scope in which the
1294module's methods wind up getting compiled.
1295
1296The usual mealy-mouthed package-mungeing doubtless applies to setting
c47ff5f1
GS
1297up names of object attributes. For example, C<< $self->{ObData1} >>
1298should probably be C<< $self->{ __PACKAGE__ . "_ObData1" } >>, but that
19799a22
GS
1299would just confuse the examples.
1300
1301=head1 SEE ALSO
1302
1303L<perltoot>, L<perlobj>, L<perlmod>, and L<perlbot>.
1304
1305The Tie::SecureHash module from CPAN is worth checking out.
1306
1307=head1 AUTHOR AND COPYRIGHT
1308
1309Copyright (c) 1999 Tom Christiansen.
1310All rights reserved.
1311
1312When included as part of the Standard Version of Perl, or as part of
1313its complete documentation whether printed or otherwise, this work
1314may be distributed only under the terms of Perl's Artistic License.
1315Any distribution of this file or derivatives thereof I<outside>
1316of that package require that special arrangements be made with
1317copyright holder.
1318
1319Irrespective of its distribution, all code examples in this file
1320are hereby placed into the public domain. You are permitted and
1321encouraged to use this code in your own programs for fun
1322or for profit as you see fit. A simple comment in the code giving
1323credit would be courteous but is not required.
1324
1325=head1 ACKNOWLEDGEMENTS
1326
1327Russ Albery, Jon Orwant, Randy Ray, Larry Rosler, Nat Torkington,
1328and Stephen Warren all contributed suggestions and corrections to this
1329piece. Thanks especially to Damian Conway for his ideas and feedback,
1330and without whose indirect prodding I might never have taken the time
1331to show others how much Perl has to offer in the way of objects once
1332you start thinking outside the tiny little box that today's "popular"
1333object-oriented languages enforce.
1334
1335=head1 HISTORY
1336
1337Last edit: Fri May 21 15:47:56 MDT 1999