[inseparable changes from match from perl-5.003_97b to perl-5.003_97c]
[perl.git] / pod / perltoot.pod
1 =head1 NAME
2
3 perltoot - Tom's object-oriented tutorial for perl
4
5 =head1 DESCRIPTION
6
7 Object-oriented programming is a big seller these days.  Some managers
8 would rather have objects than sliced bread.  Why is that?  What's so
9 special about an object?  Just what I<is> an object anyway?
10
11 An object is nothing but a way of tucking away complex behaviours into
12 a neat little easy-to-use bundle.  (This is what professors call
13 abstraction.) Smart people who have nothing to do but sit around for
14 weeks on end figuring out really hard problems make these nifty
15 objects that even regular people can use. (This is what professors call
16 software reuse.)  Users (well, programmers) can play with this little
17 bundle all they want, but they aren't to open it up and mess with the
18 insides.  Just like an expensive piece of hardware, the contract says
19 that you void the warranty if you muck with the cover.  So don't do that.
20
21 The heart of objects is the class, a protected little private namespace
22 full of data and functions.  A class is a set of related routines that
23 addresses some problem area.  You can think of it as a user-defined type.
24 The Perl package mechanism, also used for more traditional modules,
25 is used for class modules as well.  Objects "live" in a class, meaning
26 that they belong to some package.
27
28 More often than not, the class provides the user with little bundles.
29 These bundles are objects.  They know whose class they belong to,
30 and how to behave.  Users ask the class to do something, like "give
31 me an object."  Or they can ask one of these objects to do something.
32 Asking a class to do something for you is calling a I<class method>.
33 Asking an object to do something for you is calling an I<object method>.
34 Asking either a class (usually) or an object (sometimes) to give you
35 back an object is calling a I<constructor>, which is just a
36 kind of method.
37
38 That's all well and good, but how is an object different from any other
39 Perl data type?  Just what is an object I<really>; that is, what's its
40 fundamental type?  The answer to the first question is easy.  An object
41 is different from any other data type in Perl in one and only one way:
42 you may dereference it using not merely string or numeric subscripts
43 as with simple arrays and hashes, but with named subroutine calls.
44 In a word, with I<methods>.
45
46 The answer to the second question is that it's a reference, and not just
47 any reference, mind you, but one whose referent has been I<bless>()ed
48 into a particular class (read: package).  What kind of reference?  Well,
49 the answer to that one is a bit less concrete.  That's because in Perl
50 the designer of the class can employ any sort of reference they'd like
51 as the underlying intrinsic data type.  It could be a scalar, an array,
52 or a hash reference.  It could even be a code reference.  But because
53 of its inherent flexibility, an object is usually a hash reference.
54
55 =head1 Creating a Class
56
57 Before you create a class, you need to decide what to name it.  That's
58 because the class (package) name governs the name of the file used to
59 house it, just as with regular modules.  Then, that class (package)
60 should provide one or more ways to generate objects.  Finally, it should
61 provide mechanisms to allow users of its objects to indirectly manipulate
62 these objects from a distance.
63
64 For example, let's make a simple Person class module.  It gets stored in
65 the file Person.pm.  If it were called a Happy::Person class, it would
66 be stored in the file Happy/Person.pm, and its package would become
67 Happy::Person instead of just Person.  (On a personal computer not
68 running Unix or Plan 9, but something like MacOS or VMS, the directory
69 separator may be different, but the principle is the same.)  Do not assume
70 any formal relationship between modules based on their directory names.
71 This is merely a grouping convenience, and has no effect on inheritance,
72 variable accessibility, or anything else.
73
74 For this module we aren't going to use Exporter, because we're
75 a well-behaved class module that doesn't export anything at all.
76 In order to manufacture objects, a class needs to have a I<constructor
77 method>.  A constructor gives you back not just a regular data type,
78 but a brand-new object in that class.  This magic is taken care of by
79 the bless() function, whose sole purpose is to enable its referent to
80 be used as an object.  Remember: being an object really means nothing
81 more than that methods may now be called against it.
82
83 While a constructor may be named anything you'd like, most Perl
84 programmers seem to like to call theirs new().  However, new() is not
85 a reserved word, and a class is under no obligation to supply such.
86 Some programmers have also been known to use a function with
87 the same name as the class as the constructor.
88
89 =head2 Object Representation
90
91 By far the most common mechanism used in Perl to represent a Pascal
92 record, a C struct, or a C++ class an anonymous hash.  That's because a
93 hash has an arbitrary number of data fields, each conveniently accessed by
94 an arbitrary name of your own devising.
95
96 If you were just doing a simple
97 struct-like emulation, you would likely go about it something like this:
98
99     $rec = {
100         name  => "Jason",
101         age   => 23,
102         peers => [ "Norbert", "Rhys", "Phineas"],
103     };
104
105 If you felt like it, you could add a bit of visual distinction
106 by up-casing the hash keys:
107
108     $rec = {
109         NAME  => "Jason",
110         AGE   => 23,
111         PEERS => [ "Norbert", "Rhys", "Phineas"],
112     };
113
114 And so you could get at C<$rec-E<gt>{NAME}> to find "Jason", or
115 C<@{ $rec-E<gt>{PEERS} }> to get at "Norbert", "Rhys", and "Phineas".
116 (Have you ever noticed how many 23-year-old programmers seem to
117 be named "Jason" these days? :-)
118
119 This same model is often used for classes, although it is not considered
120 the pinnacle of programming propriety for folks from outside the
121 class to come waltzing into an object, brazenly accessing its data
122 members directly.  Generally speaking, an object should be considered
123 an opaque cookie that you use I<object methods> to access.  Visually,
124 methods look like you're dereffing a reference using a function name
125 instead of brackets or braces.
126
127 =head2 Class Interface
128
129 Some languages provide a formal syntactic interface to a class's methods,
130 but Perl does not.  It relies on you to read the documentation of each
131 class.  If you try to call an undefined method on an object, Perl won't
132 complain, but the program will trigger an exception while it's running.
133 Likewise, if you call a method expecting a prime number as its argument
134 with a non-prime one instead, you can't expect the compiler to catch this.
135 (Well, you can expect it all you like, but it's not going to happen.)
136
137 Let's suppose you have a well-educated user of your Person class,
138 someone who has read the docs that explain the prescribed
139 interface.  Here's how they might use the Person class:
140
141     use Person;
142
143     $him = Person->new();
144     $him->name("Jason");
145     $him->age(23);
146     $him->peers( "Norbert", "Rhys", "Phineas" );
147
148     push @All_Recs, $him;  # save object in array for later
149
150     printf "%s is %d years old.\n", $him->name, $him->age;
151     print "His peers are: ", join(", ", $him->peers), "\n";
152
153     printf "Last rec's name is %s\n", $All_Recs[-1]->name;
154
155 As you can see, the user of the class doesn't know (or at least, has no
156 business paying attention to the fact) that the object has one particular
157 implementation or another.  The interface to the class and its objects
158 is exclusively via methods, and that's all the user of the class should
159 ever play with.
160
161 =head2 Constructors and Instance Methods
162
163 Still, I<someone> has to know what's in the object.  And that someone is
164 the class.  It implements methods that the programmer uses to access
165 the object.  Here's how to implement the Person class using the standard
166 hash-ref-as-an-object idiom.  We'll make a class method called new() to
167 act as the constructor, and three object methods called name(), age(), and
168 peers() to get at per-object data hidden away in our anonymous hash.
169
170     package Person;
171     use strict;
172
173     ##################################################
174     ## the object constructor (simplistic version)  ##
175     ##################################################
176     sub new {
177         my $self  = {};
178         $self->{NAME}   = undef;
179         $self->{AGE}    = undef;
180         $self->{PEERS}  = [];
181         bless($self);           # but see below
182         return $self;
183     }
184
185     ##############################################
186     ## methods to access per-object data        ##
187     ##                                          ##
188     ## With args, they set the value.  Without  ##
189     ## any, they only retrieve it/them.         ##
190     ##############################################
191
192     sub name {
193         my $self = shift;
194         if (@_) { $self->{NAME} = shift }
195         return $self->{NAME};
196     }
197
198     sub age {
199         my $self = shift;
200         if (@_) { $self->{AGE} = shift }
201         return $self->{AGE};
202     }
203
204     sub peers {
205         my $self = shift;
206         if (@_) { @{ $self->{PEERS} } = @_ }
207         return @{ $self->{PEERS} };
208     }
209
210     1;  # so the require or use succeeds
211
212 We've created three methods to access an object's data, name(), age(),
213 and peers().  These are all substantially similar.  If called with an
214 argument, they set the appropriate field; otherwise they return the
215 value held by that field, meaning the value of that hash key.
216
217 =head2 Planning for the Future: Better Constructors
218
219 Even though at this point you may not even know what it means, someday
220 you're going to worry about inheritance.  (You can safely ignore this
221 for now and worry about it later if you'd like.)  To ensure that this
222 all works out smoothly, you must use the double-argument form of bless().
223 The second argument is the class into which the referent will be blessed.
224 By not assuming our own class as the default second argument and instead
225 using the class passed into us, we make our constructor inheritable.
226
227 While we're at it, let's make our constructor a bit more flexible.
228 Rather than being uniquely a class method, we'll set it up so that
229 it can be called as either a class method I<or> an object
230 method.  That way you can say:
231
232     $me  = Person->new();
233     $him = $me->new();
234
235 To do this, all we have to do is check whether what was passed in
236 was a reference or not.  If so, we were invoked as an object method,
237 and we need to extract the package (class) using the ref() function.
238 If not, we just use the string passed in as the package name
239 for blessing our referent.
240
241     sub new {
242         my $proto = shift;
243         my $class = ref($proto) || $proto;
244         my $self  = {};
245         $self->{NAME}   = undef;
246         $self->{AGE}    = undef;
247         $self->{PEERS}  = [];
248         bless ($self, $class);
249         return $self;
250     }
251
252 That's about all there is for constructors.  These methods bring objects
253 to life, returning neat little opaque bundles to the user to be used in
254 subsequent method calls.
255
256 =head2 Destructors
257
258 Every story has a beginning and an end.  The beginning of the object's
259 story is its constructor, explicitly called when the object comes into
260 existence.  But the ending of its story is the I<destructor>, a method
261 implicitly called when an object leaves this life.  Any per-object
262 clean-up code is placed in the destructor, which must (in Perl) be called
263 DESTROY.
264
265 If constructors can have arbitrary names, then why not destructors?
266 Because while a constructor is explicitly called, a destructor is not.
267 Destruction happens automatically via Perl's garbage collection (GC)
268 system, which is a quick but somewhat lazy reference-based GC system.
269 To know what to call, Perl insists that the destructor be named DESTROY.
270
271 Why is DESTROY in all caps?  Perl on occasion uses purely uppercase
272 function names as a convention to indicate that the function will
273 be automatically called by Perl in some way.  Others that are called
274 implicitly include BEGIN, END, AUTOLOAD, plus all methods used by
275 tied objects, described in L<perltie>.
276
277 In really good object-oriented programming languages, the user doesn't
278 care when the destructor is called.  It just happens when it's supposed
279 to.  In low-level languages without any GC at all, there's no way to
280 depend on this happening at the right time, so the programmer must
281 explicitly call the destructor to clean up memory and state, crossing
282 their fingers that it's the right time to do so.   Unlike C++, an
283 object destructor is nearly never needed in Perl, and even when it is,
284 explicit invocation is uncalled for.  In the case of our Person class,
285 we don't need a destructor because Perl takes care of simple matters
286 like memory deallocation.
287
288 The only situation where Perl's reference-based GC won't work is
289 when there's a circularity in the data structure, such as:
290
291     $this->{WHATEVER} = $this;
292
293 In that case, you must delete the self-reference manually if you expect
294 your program not to leak memory.  While admittedly error-prone, this is
295 the best we can do right now.  Nonetheless, rest assured that when your
296 program is finished, its objects' destructors are all duly called.
297 So you are guaranteed that an object I<eventually> gets properly
298 destroyed, except in the unique case of a program that never exits.
299 (If you're running Perl embedded in another application, this full GC
300 pass happens a bit more frequently--whenever a thread shuts down.)
301
302 =head2 Other Object Methods
303
304 The methods we've talked about so far have either been constructors or
305 else simple "data methods", interfaces to data stored in the object.
306 These are a bit like an object's data members in the C++ world, except
307 that strangers don't access them as data.  Instead, they should only
308 access the object's data indirectly via its methods.  This is an
309 important rule: in Perl, access to an object's data should I<only>
310 be made through methods.
311
312 Perl doesn't impose restrictions on who gets to use which methods.
313 The public-versus-private distinction is by convention, not syntax.
314 (Well, unless you use the Alias module described below in
315 L</"Data Members as Variables">.)  Occasionally you'll see method names beginning or ending
316 with an underscore or two.  This marking is a convention indicating
317 that the methods are private to that class alone and sometimes to its
318 closest acquaintances, its immediate subclasses.  But this distinction
319 is not enforced by Perl itself.  It's up to the programmer to behave.
320
321 There's no reason to limit methods to those that simply access data.
322 Methods can do anything at all.  The key point is that they're invoked
323 against an object or a class.  Let's say we'd like object methods that
324 do more than fetch or set one particular field.
325
326     sub exclaim {
327         my $self = shift;
328         return sprintf "Hi, I'm %s, age %d, working with %s",
329             $self->{NAME}, $self->{AGE}, join(", ", $self->{PEERS});
330     }
331
332 Or maybe even one like this:
333
334     sub happy_birthday {
335         my $self = shift;
336         return ++$self->{AGE};
337     }
338
339 Some might argue that one should go at these this way:
340
341     sub exclaim {
342         my $self = shift;
343         return sprintf "Hi, I'm %s, age %d, working with %s",
344             $self->name, $self->age, join(", ", $self->peers);
345     }
346
347     sub happy_birthday {
348         my $self = shift;
349         return $self->age( $self->age() + 1 );
350     }
351
352 But since these methods are all executing in the class itself, this
353 may not be critical.  There are tradeoffs to be made.  Using direct
354 hash access is faster (about an order of magnitude faster, in fact), and
355 it's more convenient when you want to interpolate in strings.  But using
356 methods (the external interface) internally shields not just the users of
357 your class but even you yourself from changes in your data representation.
358
359 =head1 Class Data
360
361 What about "class data", data items common to each object in a class?
362 What would you want that for?  Well, in your Person class, you might
363 like to keep track of the total people alive.  How do you implement that?
364
365 You I<could> make it a global variable called $Person::Census.  But about
366 only reason you'd do that would be if you I<wanted> people to be able to
367 get at your class data directly.  They could just say $Person::Census
368 and play around with it.  Maybe this is ok in your design scheme.
369 You might even conceivably want to make it an exported variable.  To be
370 exportable, a variable must be a (package) global.  If this were a
371 traditional module rather than an object-oriented one, you might do that.
372
373 While this approach is expected in most traditional modules, it's
374 generally considered rather poor form in most object modules.  In an
375 object module, you should set up a protective veil to separate interface
376 from implementation.  So provide a class method to access class data
377 just as you provide object methods to access object data.
378
379 So, you I<could> still keep $Census as a package global and rely upon
380 others to honor the contract of the module and therefore not play around
381 with its implementation.  You could even be supertricky and make $Census a
382 tied object as described in L<perltie>, thereby intercepting all accesses.
383
384 But more often than not, you just want to make your class data a
385 file-scoped lexical.  To do so, simply put this at the top of the file:
386
387     my $Census = 0;
388
389 Even though the scope of a my() normally expires when the block in which
390 it was declared is done (in this case the whole file being required or
391 used), Perl's deep binding of lexical variables guarantees that the
392 variable will not be deallocated, remaining accessible to functions
393 declared within that scope.  This doesn't work with global variables
394 given temporary values via local(), though.
395
396 Irrespective of whether you leave $Census a package global or make
397 it instead a file-scoped lexical, you should make these
398 changes to your Person::new() constructor:
399
400     sub new {
401         my $proto = shift;
402         my $class = ref($proto) || $proto;
403         my $self  = {};
404         $Census++;
405         $self->{NAME}   = undef;
406         $self->{AGE}    = undef;
407         $self->{PEERS}  = [];
408         bless ($self, $class);
409         return $self;
410     }
411
412     sub population {
413         return $Census;
414     }
415
416 Now that we've done this, we certainly do need a destructor so that
417 when Person is destroyed, the $Census goes down.  Here's how
418 this could be done:
419
420     sub DESTROY { --$Census }
421
422 Notice how there's no memory to deallocate in the destructor?  That's
423 something that Perl takes care of for you all by itself.
424
425 =head2 Accessing Class Data
426
427 It turns out that this is not really a good way to go about handling
428 class data.  A good scalable rule is that I<you must never reference class
429 data directly from an object method>.  Otherwise you aren't building a
430 scalable, inheritable class.  The object must be the rendezvous point
431 for all operations, especially from an object method.  The globals
432 (class data) would in some sense be in the "wrong" package in your
433 derived classes.  In Perl, methods execute in the context of the class
434 they were defined in, I<not> that of the object that triggered them.
435 Therefore, namespace visibility of package globals in methods is unrelated
436 to inheritance.
437
438 Got that?  Maybe not.  Ok, let's say that some other class "borrowed"
439 (well, inherited) the DESTROY method as it was defined above.  When those
440 objects are destroyed, the original $Census variable will be altered,
441 not the one in the new class's package namespace.  Perhaps this is what
442 you want, but probably it isn't.
443
444 Here's how to fix this.  We'll store a reference to the data in the
445 value accessed by the hash key "_CENSUS".  Why the underscore?  Well,
446 mostly because an initial underscore already conveys strong feelings
447 of magicalness to a C programmer.  It's really just a mnemonic device
448 to remind ourselves that this field is special and not to be used as
449 a public data member in the same way that NAME, AGE, and PEERS are.
450 (Because we've been developing this code under the strict pragma, prior
451 to perl version 5.004 we'll have to quote the field name.)
452
453     sub new {
454         my $proto = shift;
455         my $class = ref($proto) || $proto;
456         my $self  = {};
457         $self->{NAME}     = undef;
458         $self->{AGE}      = undef;
459         $self->{PEERS}    = [];
460         # "private" data
461         $self->{"_CENSUS"} = \$Census;
462         bless ($self, $class);
463         ++ ${ $self->{"_CENSUS"} };
464         return $self;
465     }
466
467     sub population {
468         my $self = shift;
469         if (ref $self) {
470             return ${ $self->{"_CENSUS"} };
471         } else {
472             return $Census;
473         }
474     }
475
476     sub DESTROY {
477         my $self = shift;
478         -- ${ $self->{"_CENSUS"} };
479     }
480
481 =head2 Debugging Methods
482
483 It's common for a class to have a debugging mechanism.  For example,
484 you might want to see when objects are created or destroyed.  To do that,
485 add a debugging variable as a file-scoped lexical.  For this, we'll pull
486 in the standard Carp module to emit our warnings and fatal messages.
487 That way messages will come out with the caller's filename and
488 line number instead of our own; if we wanted them to be from our own
489 perspective, we'd just use die() and warn() directly instead of croak()
490 and carp() respectively.
491
492     use Carp;
493     my $Debugging = 0;
494
495 Now add a new class method to access the variable.
496
497     sub debug {
498         my $class = shift;
499         if (ref $class)  { confess "Class method called as object method" }
500         unless (@_ == 1) { confess "usage: CLASSNAME->debug(level)" }
501         $Debugging = shift;
502     }
503
504 Now fix up DESTROY to murmur a bit as the moribund object expires:
505
506     sub DESTROY {
507         my $self = shift;
508         if ($Debugging) { carp "Destroying $self " . $self->name }
509         -- ${ $self->{"_CENSUS"} };
510     }
511
512 One could conceivably make a per-object debug state.  That
513 way you could call both of these:
514
515     Person->debug(1);   # entire class
516     $him->debug(1);     # just this object
517
518 To do so, we need our debugging method to be a "bimodal" one, one that
519 works on both classes I<and> objects.  Therefore, adjust the debug()
520 and DESTROY methods as follows:
521
522     sub debug {
523         my $self = shift;
524         confess "usage: thing->debug(level)"    unless @_ == 1;
525         my $level = shift;
526         if (ref($self))  {
527             $self->{"_DEBUG"} = $level;         # just myself
528         } else {
529             $Debugging        = $level;         # whole class
530         }
531     }
532
533     sub DESTROY {
534         my $self = shift;
535         if ($Debugging || $self->{"_DEBUG"}) {
536             carp "Destroying $self " . $self->name;
537         }
538         -- ${ $self->{"_CENSUS"} };
539     }
540
541 What happens if a derived class (which we'll call Employee) inherits
542 methods from this Person base class?  Then C<Employee-E<gt>debug()>, when called
543 as a class method, manipulates $Person::Debugging not $Employee::Debugging.
544
545 =head2 Class Destructors
546
547 The object destructor handles the death of each distinct object.  But sometimes
548 you want a bit of cleanup when the entire class is shut down, which
549 currently only happens when the program exits.  To make such a
550 I<class destructor>, create a function in that class's package named
551 END.  This works just like the END function in traditional modules,
552 meaning that it gets called whenever your program exits unless it execs
553 or dies of an uncaught signal.  For example,
554
555     sub END {
556         if ($Debugging) {
557             print "All persons are going away now.\n";
558         }
559     }
560
561 When the program exits, all the class destructors (END functions) are
562 be called in the opposite order that they were loaded in (LIFO order).
563
564 =head2 Documenting the Interface
565
566 And there you have it: we've just shown you the I<implementation> of this
567 Person class.  Its I<interface> would be its documentation.  Usually this
568 means putting it in pod ("plain old documentation") format right there
569 in the same file.  In our Person example, we would place the following
570 docs anywhere in the Person.pm file.  Even though it looks mostly like
571 code, it's not.  It's embedded documentation such as would be used by
572 the pod2man, pod2html, or pod2text programs.  The Perl compiler ignores
573 pods entirely, just as the translators ignore code.  Here's an example of
574 some pods describing the informal interface:
575
576     =head1 NAME
577
578     Person - class to implement people
579
580     =head1 SYNOPSIS
581
582      use Person;
583
584      #################
585      # class methods #
586      #################
587      $ob    = Person->new;
588      $count = Person->population;
589
590      #######################
591      # object data methods #
592      #######################
593
594      ### get versions ###
595          $who   = $ob->name;
596          $years = $ob->age;
597          @pals  = $ob->peers;
598
599      ### set versions ###
600          $ob->name("Jason");
601          $ob->age(23);
602          $ob->peers( "Norbert", "Rhys", "Phineas" );
603
604      ########################
605      # other object methods #
606      ########################
607
608      $phrase = $ob->exclaim;
609      $ob->happy_birthday;
610
611     =head1 DESCRIPTION
612
613     The Person class implements dah dee dah dee dah....
614
615 That's all there is to the matter of interface versus implementation.
616 A programmer who opens up the module and plays around with all the private
617 little shiny bits that were safely locked up behind the interface contract
618 has voided the warranty, and you shouldn't worry about their fate.
619
620 =head1 Aggregation
621
622 Suppose you later want to change the class to implement better names.
623 Perhaps you'd like to support both given names (called Christian names,
624 irrespective of one's religion) and family names (called surnames), plus
625 nicknames and titles.  If users of your Person class have been properly
626 accessing it through its documented interface, then you can easily change
627 the underlying implementation.  If they haven't, then they lose and
628 it's their fault for breaking the contract and voiding their warranty.
629
630 To do this, we'll make another class, this one called Fullname.  What's
631 the Fullname class look like?  To answer that question, you have to
632 first figure out how you want to use it.  How about we use it this way:
633
634     $him = Person->new();
635     $him->fullname->title("St");
636     $him->fullname->christian("Thomas");
637     $him->fullname->surname("Aquinas");
638     $him->fullname->nickname("Tommy");
639     printf "His normal name is %s\n", $him->name;
640     printf "But his real name is %s\n", $him->fullname->as_string;
641
642 Ok.  To do this, we'll change Person::new() so that it supports
643 a full name field this way:
644
645     sub new {
646         my $proto = shift;
647         my $class = ref($proto) || $proto;
648         my $self  = {};
649         $self->{FULLNAME} = Fullname->new();
650         $self->{AGE}      = undef;
651         $self->{PEERS}    = [];
652         $self->{"_CENSUS"} = \$Census;
653         bless ($self, $class);
654         ++ ${ $self->{"_CENSUS"} };
655         return $self;
656     }
657
658     sub fullname {
659         my $self = shift;
660         return $self->{FULLNAME};
661     }
662
663 Then to support old code, define Person::name() this way:
664
665     sub name {
666         my $self = shift;
667         return $self->{FULLNAME}->nickname(@_)
668           ||   $self->{FULLNAME}->christian(@_);
669     }
670
671 Here's the Fullname class.  We'll use the same technique
672 of using a hash reference to hold data fields, and methods
673 by the appropriate name to access them:
674
675     package Fullname;
676     use strict;
677
678     sub new {
679         my $proto = shift;
680         my $class = ref($proto) || $proto;
681         my $self  = {
682             TITLE       => undef,
683             CHRISTIAN   => undef,
684             SURNAME     => undef,
685             NICK        => undef,
686         };
687         bless ($self, $class);
688         return $self;
689     }
690
691     sub christian {
692         my $self = shift;
693         if (@_) { $self->{CHRISTIAN} = shift }
694         return $self->{CHRISTIAN};
695     }
696
697     sub surname {
698         my $self = shift;
699         if (@_) { $self->{SURNAME} = shift }
700         return $self->{SURNAME};
701     }
702
703     sub nickname {
704         my $self = shift;
705         if (@_) { $self->{NICK} = shift }
706         return $self->{NICK};
707     }
708
709     sub title {
710         my $self = shift;
711         if (@_) { $self->{TITLE} = shift }
712         return $self->{TITLE};
713     }
714
715     sub as_string {
716         my $self = shift;
717         my $name = join(" ", @$self{'CHRISTIAN', 'SURNAME'});
718         if ($self->{TITLE}) {
719             $name = $self->{TITLE} . " " . $name;
720         }
721         return $name;
722     }
723
724     1;
725
726 Finally, here's the test program:
727
728     #!/usr/bin/perl -w
729     use strict;
730     use Person;
731     sub END { show_census() }
732
733     sub show_census ()  {
734         printf "Current population: %d\n", Person->population;
735     }
736
737     Person->debug(1);
738
739     show_census();
740
741     my $him = Person->new();
742
743     $him->fullname->christian("Thomas");
744     $him->fullname->surname("Aquinas");
745     $him->fullname->nickname("Tommy");
746     $him->fullname->title("St");
747     $him->age(1);
748
749     printf "%s is really %s.\n", $him->name, $him->fullname;
750     printf "%s's age: %d.\n", $him->name, $him->age;
751     $him->happy_birthday;
752     printf "%s's age: %d.\n", $him->name, $him->age;
753
754     show_census();
755
756 =head1 Inheritance
757
758 Object-oriented programming systems all support some notion of
759 inheritance.  Inheritance means allowing one class to piggy-back on
760 top of another one so you don't have to write the same code again and
761 again.  It's about software reuse, and therefore related to Laziness,
762 the principal virtue of a programmer.  (The import/export mechanisms in
763 traditional modules are also a form of code reuse, but a simpler one than
764 the true inheritance that you find in object modules.)
765
766 Sometimes the syntax of inheritance is built into the core of the
767 language, and sometimes it's not.  Perl has no special syntax for
768 specifying the class (or classes) to inherit from.  Instead, it's all
769 strictly in the semantics.  Each package can have a variable called @ISA,
770 which governs (method) inheritance.  If you try to call a method on an
771 object or class, and that method is not found in that object's package,
772 Perl then looks to @ISA for other packages to go looking through in
773 search of the missing method.
774
775 Like the special per-package variables recognized by Exporter (such as
776 @EXPORT, @EXPORT_OK, @EXPORT_FAIL, %EXPORT_TAGS, and $VERSION), the @ISA
777 array I<must> be a package-scoped global and not a file-scoped lexical
778 created via my().  Most classes have just one item in their @ISA array.
779 In this case, we have what's called "single inheritance", or SI for short.
780
781 Consider this class:
782
783     package Employee;
784     use Person;
785     @ISA = ("Person");
786     1;
787
788 Not a lot to it, eh?  All it's doing so far is loading in another
789 class and stating that this one will inherit methods from that
790 other class if need be.  We have given it none of its own methods.
791 We rely upon an Employee to behave just like a Person.
792
793 Setting up an empty class like this is called the "empty subclass test";
794 that is, making a derived class that does nothing but inherit from a
795 base class.  If the original base class has been designed properly,
796 then the new derived class can be used as a drop-in replacement for the
797 old one.  This means you should be able to write a program like this:
798
799     use Employee
800     my $empl = Employee->new();
801     $empl->name("Jason");
802     $empl->age(23);
803     printf "%s is age %d.\n", $empl->name, $empl->age;
804
805 By proper design, we mean always using the two-argument form of bless(),
806 avoiding direct access of global data, and not exporting anything.  If you
807 look back at the Person::new() function we defined above, we were careful
808 to do that.  There's a bit of package data used in the constructor,
809 but the reference to this is stored on the object itself and all other
810 methods access package data via that reference, so we should be ok.
811
812 What do we mean by the Person::new() function -- isn't that actually
813 a method?  Well, in principle, yes.  A method is just a function that
814 expects as its first argument a class name (package) or object
815 (blessed reference).   Person::new() is the function that both the
816 C<Person-E<gt>new()> method and the C<Employee-E<gt>new()> method end
817 up calling.  Understand that while a method call looks a lot like a
818 function call, they aren't really quite the same, and if you treat them
819 as the same, you'll very soon be left with nothing but broken programs.
820 First, the actual underlying calling conventions are different: method
821 calls get an extra argument.  Second, function calls don't do inheritance,
822 but methods do.
823
824         Method Call             Resulting Function Call
825         -----------             ------------------------
826         Person->new()           Person::new("Person")
827         Employee->new()         Person::new("Employee")
828
829 So don't use function calls when you mean to call a method.
830
831 If an employee is just a Person, that's not all too very interesting.
832 So let's add some other methods.  We'll give our employee
833 data fields to access their salary, their employee ID, and their
834 start date.
835
836 If you're getting a little tired of creating all these nearly identical
837 methods just to get at the object's data, do not despair.  Later,
838 we'll describe several different convenience mechanisms for shortening
839 this up.  Meanwhile, here's the straight-forward way:
840
841     sub salary {
842         my $self = shift;
843         if (@_) { $self->{SALARY} = shift }
844         return $self->{SALARY};
845     }
846
847     sub id_number {
848         my $self = shift;
849         if (@_) { $self->{ID} = shift }
850         return $self->{ID};
851     }
852
853     sub start_date {
854         my $self = shift;
855         if (@_) { $self->{START_DATE} = shift }
856         return $self->{START_DATE};
857     }
858
859 =head2 Overridden Methods
860
861 What happens when both a derived class and its base class have the same
862 method defined?  Well, then you get the derived class's version of that
863 method.  For example, let's say that we want the peers() method called on
864 an employee to act a bit differently.  Instead of just returning the list
865 of peer names, let's return slightly different strings.  So doing this:
866
867     $empl->peers("Peter", "Paul", "Mary");
868     printf "His peers are: %s\n", join(", ", $empl->peers);
869
870 will produce:
871
872     His peers are: PEON=PETER, PEON=PAUL, PEON=MARY
873
874 To do this, merely add this definition into the Employee.pm file:
875
876     sub peers {
877         my $self = shift;
878         if (@_) { @{ $self->{PEERS} } = @_ }
879         return map { "PEON=\U$_" } @{ $self->{PEERS} };
880     }
881
882 There, we've just demonstrated the high-falutin' concept known in certain
883 circles as I<polymorphism>.  We've taken on the form and behaviour of
884 an existing object, and then we've altered it to suit our own purposes.
885 This is a form of Laziness.  (Getting polymorphed is also what happens
886 when the wizard decides you'd look better as a frog.)
887
888 Every now and then you'll want to have a method call trigger both its
889 derived class (also known as "subclass") version as well as its base class
890 (also known as "superclass") version.  In practice, constructors and
891 destructors are likely to want to do this, and it probably also makes
892 sense in the debug() method we showed previously.
893
894 To do this, add this to Employee.pm:
895
896     use Carp;
897     my $Debugging = 0;
898
899     sub debug {
900         my $self = shift;
901         confess "usage: thing->debug(level)"    unless @_ == 1;
902         my $level = shift;
903         if (ref($self))  {
904             $self->{"_DEBUG"} = $level;
905         } else {
906             $Debugging = $level;            # whole class
907         }
908         Person::debug($self, $Debugging);   # don't really do this
909     }
910
911 As you see, we turn around and call the Person package's debug() function.
912 But this is far too fragile for good design.  What if Person doesn't
913 have a debug() function, but is inheriting I<its> debug() method
914 from elsewhere?  It would have been slightly better to say
915
916     Person->debug($Debugging);
917
918 But even that's got too much hard-coded.  It's somewhat better to say
919
920     $self->Person::debug($Debugging);
921
922 Which is a funny way to say to start looking for a debug() method up
923 in Person.  This strategy is more often seen on overridden object methods
924 than on overridden class methods.
925
926 There is still something a bit off here.  We've hard-coded our
927 superclass's name.  This in particular is bad if you change which classes
928 you inherit from, or add others.  Fortunately, the pseudoclass SUPER
929 comes to the rescue here.
930
931     $self->SUPER::debug($Debugging);
932
933 This way it starts looking in my class's @ISA.  This only makes sense
934 from I<within> a method call, though.  Don't try to access anything
935 in SUPER:: from anywhere else, because it doesn't exist outside
936 an overridden method call.
937
938 Things are getting a bit complicated here.  Have we done anything
939 we shouldn't?  As before, one way to test whether we're designing
940 a decent class is via the empty subclass test.  Since we already have
941 an Employee class that we're trying to check, we'd better get a new
942 empty subclass that can derive from Employee.  Here's one:
943
944     package Boss;
945     use Employee;        # :-)
946     @ISA = qw(Employee);
947
948 And here's the test program:
949
950     #!/usr/bin/perl -w
951     use strict;
952     use Boss;
953     Boss->debug(1);
954
955     my $boss = Boss->new();
956
957     $boss->fullname->title("Don");
958     $boss->fullname->surname("Pichon Alvarez");
959     $boss->fullname->christian("Federico Jesus");
960     $boss->fullname->nickname("Fred");
961
962     $boss->age(47);
963     $boss->peers("Frank", "Felipe", "Faust");
964
965     printf "%s is age %d.\n", $boss->fullname, $boss->age;
966     printf "His peers are: %s\n", join(", ", $boss->peers);
967
968 Running it, we see that we're still ok.  If you'd like to dump out your
969 object in a nice format, somewhat like the way the 'x' command works in
970 the debugger, you could use the Data::Dumper module from CPAN this way:
971
972     use Data::Dumper;
973     print "Here's the boss:\n";
974     print Dumper($boss);
975
976 Which shows us something like this:
977
978     Here's the boss:
979     $VAR1 = bless( {
980          _CENSUS => \1,
981          FULLNAME => bless( {
982                               TITLE => 'Don',
983                               SURNAME => 'Pichon Alvarez',
984                               NICK => 'Fred',
985                               CHRISTIAN => 'Federico Jesus'
986                             }, 'Fullname' ),
987          AGE => 47,
988          PEERS => [
989                     'Frank',
990                     'Felipe',
991                     'Faust'
992                   ]
993        }, 'Boss' );
994
995 Hm.... something's missing there.  What about the salary, start date,
996 and ID fields?  Well, we never set them to anything, even undef, so they
997 don't show up in the hash's keys.  The Employee class has no new() method
998 of its own, and the new() method in Person doesn't know about Employees.
999 (Nor should it: proper OO design dictates that a subclass be allowed to
1000 know about its immediate superclass, but never vice-versa.)  So let's
1001 fix up Employee::new() this way:
1002
1003     sub new {
1004         my $proto = shift;
1005         my $class = ref($proto) || $proto;
1006         my $self  = $class->SUPER::new();
1007         $self->{SALARY}        = undef;
1008         $self->{ID}            = undef;
1009         $self->{START_DATE}    = undef;
1010         bless ($self, $class);          # reconsecrate
1011         return $self;
1012     }
1013
1014 Now if you dump out an Employee or Boss object, you'll find
1015 that new fields show up there now.
1016
1017 =head2 Multiple Inheritance
1018
1019 Ok, at the risk of confusing beginners and annoying OO gurus, it's
1020 time to confess that Perl's object system includes that controversial
1021 notion known as multiple inheritance, or MI for short.  All this means
1022 is that rather than having just one parent class who in turn might
1023 itself have a parent class, etc., that you can directly inherit from
1024 two or more parents.  It's true that some uses of MI can get you into
1025 trouble, although hopefully not quite so much trouble with Perl as with
1026 dubiously-OO languages like C++.
1027
1028 The way it works is actually pretty simple: just put more than one package
1029 name in your @ISA array.  When it comes time for Perl to go finding
1030 methods for your object, it looks at each of these packages in order.
1031 Well, kinda.  It's actually a fully recursive, depth-first order.
1032 Consider a bunch of @ISA arrays like this:
1033
1034     @First::ISA    = qw( Alpha );
1035     @Second::ISA   = qw( Beta );
1036     @Third::ISA    = qw( First Second );
1037
1038 If you have an object of class Third:
1039
1040     my $ob = Third->new();
1041     $ob->spin();
1042
1043 How do we find a spin() method (or a new() method for that matter)?
1044 Because the search is depth-first, classes will be looked up
1045 in the following order: Third, First, Alpha, Second, and Beta.
1046
1047 In practice, few class modules have been seen that actually
1048 make use of MI.  One nearly always chooses simple containership of
1049 one class within another over MI.  That's why our Person
1050 object I<contained> a Fullname object.  That doesn't mean
1051 it I<was> one.
1052
1053 However, there is one particular area where MI in Perl is rampant:
1054 borrowing another class's class methods.  This is rather common,
1055 especially with some bundled "objectless" classes,
1056 like Exporter, DynaLoader, AutoLoader, and SelfLoader.  These classes
1057 do not provide constructors; they exist only so you may inherit their
1058 class methods.  (It's not entirely clear why inheritance was done
1059 here rather than traditional module importation.)
1060
1061 For example, here is the POSIX module's @ISA:
1062
1063     package POSIX;
1064     @ISA = qw(Exporter DynaLoader);
1065
1066 The POSIX module isn't really an object module, but then,
1067 neither are Exporter or DynaLoader.  They're just lending their
1068 classes' behaviours to POSIX.
1069
1070 Why don't people use MI for object methods much?  One reason is that
1071 it can have complicated side-effects.  For one thing, your inheritance
1072 graph (no longer a tree) might converge back to the same base class.
1073 Although Perl guards against recursive inheritance, merely having parents
1074 who are related to each other via a common ancestor, incestuous though
1075 it sounds, is not forbidden.  What if in our Third class shown above we
1076 wanted its new() method to also call both overridden constructors in its
1077 two parent classes?  The SUPER notation would only find the first one.
1078 Also, what about if the Alpha and Beta classes both had a common ancestor,
1079 like Nought?  If you kept climbing up the inheritance tree calling
1080 overridden methods, you'd end up calling Nought::new() twice,
1081 which might well be a bad idea.
1082
1083 =head2 UNIVERSAL: The Root of All Objects
1084
1085 Wouldn't it be convenient if all objects were rooted at some ultimate
1086 base class?  That way you could give every object common methods without
1087 having to go and add it to each and every @ISA.  Well, it turns out that
1088 you can.  You don't see it, but Perl tacitly and irrevocably assumes
1089 that there's an extra element at the end of @ISA: the class UNIVERSAL.
1090 In version 5.003, there were no predefined methods there, but you could put
1091 whatever you felt like into it.
1092
1093 However, as of version 5.004 (or some subversive releases, like 5.003_08),
1094 UNIVERSAL has some methods in it already.  These are builtin to your Perl
1095 binary, so they don't take any extra time to load.  Predefined methods
1096 include isa(), can(), and VERSION().  isa() tells you whether an object or
1097 class "is" another one without having to traverse the hierarchy yourself:
1098
1099    $has_io = $fd->isa("IO::Handle");
1100    $itza_handle = IO::Socket->isa("IO::Handle");
1101
1102 The can() method, called against that object or class, reports back
1103 whether its string argument is a callable method name in that class.
1104 In fact, it gives you back a function reference to that method:
1105
1106    $his_print_method = $obj->can('as_string');
1107
1108 Finally, the VERSION method checks whether the class (or the object's
1109 class) has a package global called $VERSION that's high enough, as in:
1110
1111     Some_Module->VERSION(3.0);
1112     $his_vers = $ob->VERSION();
1113
1114 However, we don't usually call VERSION ourselves.  (Remember that an all
1115 uppercase function name is a Perl convention that indicates that the
1116 function will be automatically used by Perl in some way.)  In this case,
1117 it happens when you say
1118
1119     use Some_Module 3.0;
1120
1121 If you wanted to add version checking to your Person class explained
1122 above, just add this to Person.pm:
1123
1124     use vars qw($VERSION);
1125     $VERSION = '1.1';
1126
1127 and then in Employee.pm could you can say
1128
1129     use Employee 1.1;
1130
1131 And it would make sure that you have at least that version number or
1132 higher available.   This is not the same as loading in that exact version
1133 number.  No mechanism currently exists for concurrent installation of
1134 multiple versions of a module.  Lamentably.
1135
1136 =head1 Alternate Object Representations
1137
1138 Nothing requires objects to be implemented as hash references.  An object
1139 can be any sort of reference so long as its referent has been suitably
1140 blessed.  That means scalar, array, and code references are also fair
1141 game.
1142
1143 A scalar would work if the object has only one datum to hold.  An array
1144 would work for most cases, but makes inheritance a bit dodgy because
1145 you have to invent new indices for the derived classes.
1146
1147 =head2 Arrays as Objects
1148
1149 If the user of your class honors the contract and sticks to the advertised
1150 interface, then you can change its underlying interface if you feel
1151 like it.  Here's another implementation that conforms to the same
1152 interface specification.  This time we'll use an array reference
1153 instead of a hash reference to represent the object.
1154
1155     package Person;
1156     use strict;
1157
1158     my($NAME, $AGE, $PEERS) = ( 0 .. 2 );
1159
1160     ############################################
1161     ## the object constructor (array version) ##
1162     ############################################
1163     sub new {
1164         my $self = [];
1165         $self->[$NAME]   = undef;  # this is unnecessary
1166         $self->[$AGE]    = undef;  # as is this
1167         $self->[$PEERS]  = [];     # but this isn't, really
1168         bless($self);
1169         return $self;
1170     }
1171
1172     sub name {
1173         my $self = shift;
1174         if (@_) { $self->[$NAME] = shift }
1175         return $self->[$NAME];
1176     }
1177
1178     sub age {
1179         my $self = shift;
1180         if (@_) { $self->[$AGE] = shift }
1181         return $self->[$AGE];
1182     }
1183
1184     sub peers {
1185         my $self = shift;
1186         if (@_) { @{ $self->[$PEERS] } = @_ }
1187         return @{ $self->[$PEERS] };
1188     }
1189
1190     1;  # so the require or use succeeds
1191
1192 You might guess that the array access would be a lot faster than the
1193 hash access, but they're actually comparable.  The array is a I<little>
1194 bit faster, but not more than ten or fifteen percent, even when you
1195 replace the variables above like $AGE with literal numbers, like 1.
1196 A bigger difference between the two approaches can be found in memory use.
1197 A hash representation takes up more memory than an array representation
1198 because you have to allocate memory for the keys as well as for the values.
1199 However, it really isn't that bad, especially since as of version 5.004,
1200 memory is only allocated once for a given hash key, no matter how many
1201 hashes have that key.  It's expected that sometime in the future, even
1202 these differences will fade into obscurity as more efficient underlying
1203 representations are devised.
1204
1205 Still, the tiny edge in speed (and somewhat larger one in memory)
1206 is enough to make some programmers choose an array representation
1207 for simple classes.  There's still a little problem with
1208 scalability, though, because later in life when you feel
1209 like creating subclasses, you'll find that hashes just work
1210 out better.
1211
1212 =head2 Closures as Objects
1213
1214 Using a code reference to represent an object offers some fascinating
1215 possibilities.  We can create a new anonymous function (closure) who
1216 alone in all the world can see the object's data.  This is because we
1217 put the data into an anonymous hash that's lexically visible only to
1218 the closure we create, bless, and return as the object.  This object's
1219 methods turn around and call the closure as a regular subroutine call,
1220 passing it the field we want to affect.  (Yes,
1221 the double-function call is slow, but if you wanted fast, you wouldn't
1222 be using objects at all, eh? :-)
1223
1224 Use would be similar to before:
1225
1226     use Person;
1227     $him = Person->new();
1228     $him->name("Jason");
1229     $him->age(23);
1230     $him->peers( [ "Norbert", "Rhys", "Phineas" ] );
1231     printf "%s is %d years old.\n", $him->name, $him->age;
1232     print "His peers are: ", join(", ", @{$him->peers}), "\n";
1233
1234 but the implementation would be radically, perhaps even sublimely
1235 different:
1236
1237     package Person;
1238
1239     sub new {
1240          my $that  = shift;
1241          my $class = ref($that) || $that;
1242          my $self = {
1243             NAME  => undef,
1244             AGE   => undef,
1245             PEERS => [],
1246          };
1247          my $closure = sub {
1248             my $field = shift;
1249             if (@_) { $self->{$field} = shift }
1250             return    $self->{$field};
1251         };
1252         bless($closure, $class);
1253         return $closure;
1254     }
1255
1256     sub name   { &{ $_[0] }("NAME",  @_[ 1 .. $#_ ] ) }
1257     sub age    { &{ $_[0] }("AGE",   @_[ 1 .. $#_ ] ) }
1258     sub peers  { &{ $_[0] }("PEERS", @_[ 1 .. $#_ ] ) }
1259
1260     1;
1261
1262 Because this object is hidden behind a code reference, it's probably a bit
1263 mysterious to those whose background is more firmly rooted in standard
1264 procedural or object-based programming languages than in functional
1265 programming languages whence closures derive.  The object
1266 created and returned by the new() method is itself not a data reference
1267 as we've seen before.  It's an anonymous code reference that has within
1268 it access to a specific version (lexical binding and instantiation)
1269 of the object's data, which are stored in the private variable $self.
1270 Although this is the same function each time, it contains a different
1271 version of $self.
1272
1273 When a method like C<$him-E<gt>name("Jason")> is called, its implicit
1274 zeroth argument is the invoking object--just as it is with all method
1275 calls.  But in this case, it's our code reference (something like a
1276 function pointer in C++, but with deep binding of lexical variables).
1277 There's not a lot to be done with a code reference beyond calling it, so
1278 that's just what we do when we say C<&{$_[0]}>.  This is just a regular
1279 function call, not a method call.  The initial argument is the string
1280 "NAME", and any remaining arguments are whatever had been passed to the
1281 method itself.
1282
1283 Once we're executing inside the closure that had been created in new(),
1284 the $self hash reference suddenly becomes visible.  The closure grabs
1285 its first argument ("NAME" in this case because that's what the name()
1286 method passed it), and uses that string to subscript into the private
1287 hash hidden in its unique version of $self.
1288
1289 Nothing under the sun will allow anyone outside the executing method to
1290 be able to get at this hidden data.  Well, nearly nothing.  You I<could>
1291 single step through the program using the debugger and find out the
1292 pieces while you're in the method, but everyone else is out of luck.
1293
1294 There, if that doesn't excite the Scheme folks, then I just don't know
1295 what will.  Translation of this technique into C++, Java, or any other
1296 braindead-static language is left as a futile exercise for aficionados
1297 of those camps.
1298
1299 You could even add a bit of nosiness via the caller() function and
1300 make the closure refuse to operate unless called via its own package.
1301 This would no doubt satisfy certain fastidious concerns of programming
1302 police and related puritans.
1303
1304 If you were wondering when Hubris, the third principle virtue of a
1305 programmer, would come into play, here you have it. (More seriously,
1306 Hubris is just the pride in craftsmanship that comes from having written
1307 a sound bit of well-designed code.)
1308
1309 =head1 AUTOLOAD: Proxy Methods
1310
1311 Autoloading is a way to intercept calls to undefined methods.  An autoload
1312 routine may choose to create a new function on the fly, either loaded
1313 from disk or perhaps just eval()ed right there.  This define-on-the-fly
1314 strategy is why it's called autoloading.
1315
1316 But that's only one possible approach.  Another one is to just
1317 have the autoloaded method itself directly provide the
1318 requested service.  When used in this way, you may think
1319 of autoloaded methods as "proxy" methods.
1320
1321 When Perl tries to call an undefined function in a particular package
1322 and that function is not defined, it looks for a function in
1323 that same package called AUTOLOAD.  If one exists, it's called
1324 with the same arguments as the original function would have had.
1325 The fully-qualified name of the function is stored in that package's
1326 global variable $AUTOLOAD.  Once called, the function can do anything
1327 it would like, including defining a new function by the right name, and
1328 then doing a really fancy kind of C<goto> right to it, erasing itself
1329 from the call stack.
1330
1331 What does this have to do with objects?  After all, we keep talking about
1332 functions, not methods.  Well, since a method is just a function with
1333 an extra argument and some fancier semantics about where it's found,
1334 we can use autoloading for methods, too.  Perl doesn't start looking
1335 for an AUTOLOAD method until it has exhausted the recursive hunt up
1336 through @ISA, though.  Some programmers have even been known to define
1337 a UNIVERSAL::AUTOLOAD method to trap unresolved method calls to any
1338 kind of object.
1339
1340 =head2 Autoloaded Data Methods
1341
1342 You probably began to get a little suspicious about the duplicated
1343 code way back earlier when we first showed you the Person class, and
1344 then later the Employee class.  Each method used to access the
1345 hash fields looked virtually identical.  This should have tickled
1346 that great programming virtue, Impatience, but for the time,
1347 we let Laziness win out, and so did nothing.  Proxy methods can cure
1348 this.
1349
1350 Instead of writing a new function every time we want a new data field,
1351 we'll use the autoload mechanism to generate (actually, mimic) methods on
1352 the fly.  To verify that we're accessing a valid member, we will check
1353 against an C<_permitted> (pronounced "under-permitted") field, which
1354 is a reference to a file-scoped lexical (like a C file static) hash of permitted fields in this record
1355 called %fields.  Why the underscore?  For the same reason as the _CENSUS
1356 field we once used: as a marker that means "for internal use only".
1357
1358 Here's what the module initialization code and class
1359 constructor will look like when taking this approach:
1360
1361     package Person;
1362     use Carp;
1363     use vars qw($AUTOLOAD);  # it's a package global
1364
1365     my %fields = (
1366         name        => undef,
1367         age         => undef,
1368         peers       => undef,
1369     );
1370
1371     sub new {
1372         my $that  = shift;
1373         my $class = ref($that) || $that;
1374         my $self  = {
1375             _permitted => \%fields,
1376             %fields,
1377         };
1378         bless $self, $class;
1379         return $self;
1380     }
1381
1382 If we wanted our record to have default values, we could fill those in
1383 where current we have C<undef> in the %fields hash.
1384
1385 Notice how we saved a reference to our class data on the object itself?
1386 Remember that it's important to access class data through the object
1387 itself instead of having any method reference %fields directly, or else
1388 you won't have a decent inheritance.
1389
1390 The real magic, though, is going to reside in our proxy method, which
1391 will handle all calls to undefined methods for objects of class Person
1392 (or subclasses of Person).  It has to be called AUTOLOAD.  Again, it's
1393 all caps because it's called for us implicitly by Perl itself, not by
1394 a user directly.
1395
1396     sub AUTOLOAD {
1397         my $self = shift;
1398         my $type = ref($self)
1399                     or croak "$self is not an object";
1400
1401         my $name = $AUTOLOAD;
1402         $name =~ s/.*://;   # strip fully-qualified portion
1403
1404         unless (exists $self->{_permitted}->{$name} ) {
1405             croak "Can't access `$name' field in class $type";
1406         }
1407
1408         if (@_) {
1409             return $self->{$name} = shift;
1410         } else {
1411             return $self->{$name};
1412         }
1413     }
1414
1415 Pretty nifty, eh?  All we have to do to add new data fields
1416 is modify %fields.  No new functions need be written.
1417
1418 I could have avoided the C<_permitted> field entirely, but I
1419 wanted to demonstrate how to store a reference to class data on the
1420 object so you wouldn't have to access that class data
1421 directly from an object method.
1422
1423 =head2 Inherited Autoloaded Data Methods
1424
1425 But what about inheritance?  Can we define our Employee
1426 class similarly?  Yes, so long as we're careful enough.
1427
1428 Here's how to be careful:
1429
1430     package Employee;
1431     use Person;
1432     use strict;
1433     use vars qw(@ISA);
1434     @ISA = qw(Person);
1435
1436     my %fields = (
1437         id          => undef,
1438         salary      => undef,
1439     );
1440
1441     sub new {
1442         my $that  = shift;
1443         my $class = ref($that) || $that;
1444         my $self = bless $that->SUPER::new(), $class;
1445         my($element);
1446         foreach $element (keys %fields) {
1447             $self->{_permitted}->{$element} = $fields{$element};
1448         }
1449         @{$self}{keys %fields} = values %fields;
1450         return $self;
1451     }
1452
1453 Once we've done this, we don't even need to have an
1454 AUTOLOAD function in the Employee package, because
1455 we'll grab Person's version of that via inheritance,
1456 and it will all work out just fine.
1457
1458 =head1 Metaclassical Tools
1459
1460 Even though proxy methods can provide a more convenient approach to making
1461 more struct-like classes than tediously coding up data methods as
1462 functions, it still leaves a bit to be desired.  For one thing, it means
1463 you have to handle bogus calls that you don't mean to trap via your proxy.
1464 It also means you have to be quite careful when dealing with inheritance,
1465 as detailed above.
1466
1467 Perl programmers have responded to this by creating several different
1468 class construction classes.  These metaclasses are classes
1469 that create other classes.  A couple worth looking at are
1470 Class::Struct and Alias.  These and other related metaclasses can be
1471 found in the modules directory on CPAN.
1472
1473 =head2 Class::Struct
1474
1475 One of the older ones is Class::Struct.  In fact, its syntax and
1476 interface were sketched out long before perl5 even solidified into a
1477 real thing.  What it does is provide you a way to "declare" a class
1478 as having objects whose fields are of a specific type.  The function
1479 that does this is called, not surprisingly enough, struct().  Because
1480 structures or records are not base types in Perl, each time you want to
1481 create a class to provide a record-like data object, you yourself have
1482 to define a new() method, plus separate data-access methods for each of
1483 that record's fields.  You'll quickly become bored with this process.
1484 The Class::Struct::struct() function alleviates this tedium.
1485
1486 Here's a simple example of using it:
1487
1488     use Class::Struct qw(struct);
1489     use Jobbie;  # user-defined; see below
1490
1491     struct 'Fred' => {
1492         one        => '$',
1493         many       => '@',
1494         profession => Jobbie,  # calls Jobbie->new()
1495     };
1496
1497     $ob = Fred->new;
1498     $ob->one("hmmmm");
1499
1500     $ob->many(0, "here");
1501     $ob->many(1, "you");
1502     $ob->many(2, "go");
1503     print "Just set: ", $ob->many(2), "\n";
1504
1505     $ob->profession->salary(10_000);
1506
1507 You can declare types in the struct to be basic Perl types, or
1508 user-defined types (classes).  User types will be initialized by calling
1509 that class's new() method.
1510
1511 Here's a real-world example of using struct generation.  Let's say you
1512 wanted to override Perl's idea of gethostbyname() and gethostbyaddr() so
1513 that they would return objects that acted like C structures.  We don't
1514 care about high-falutin' OO gunk.  All we want is for these objects to
1515 act like structs in the C sense.
1516
1517     use Socket;
1518     use Net::hostent;
1519     $h = gethostbyname("perl.com");  # object return
1520     printf "perl.com's real name is %s, address %s\n",
1521         $h->name, inet_ntoa($h->addr);
1522
1523 Here's how to do this using the Class::Struct module.
1524 The crux is going to be this call:
1525
1526     struct 'Net::hostent' => [          # note bracket
1527         name       => '$',
1528         aliases    => '@',
1529         addrtype   => '$',
1530         'length'   => '$',
1531         addr_list  => '@',
1532      ];
1533
1534 Which creates object methods of those names and types.
1535 It even creates a new() method for us.
1536
1537 We could also have implemented our object this way:
1538
1539     struct 'Net::hostent' => {          # note brace
1540         name       => '$',
1541         aliases    => '@',
1542         addrtype   => '$',
1543         'length'   => '$',
1544         addr_list  => '@',
1545      };
1546
1547 and then Class::Struct would have used an anonymous hash as the object
1548 type, instead of an anonymous array.  The array is faster and smaller,
1549 but the hash works out better if you eventually want to do inheritance.
1550 Since for this struct-like object we aren't planning on inheritance,
1551 this time we'll opt for better speed and size over better flexibility.
1552
1553 Here's the whole implementation:
1554
1555     package Net::hostent;
1556     use strict;
1557
1558     BEGIN {
1559         use Exporter   ();
1560         use vars       qw(@EXPORT @EXPORT_OK %EXPORT_TAGS);
1561         @EXPORT      = qw(gethostbyname gethostbyaddr gethost);
1562         @EXPORT_OK   = qw(
1563                            $h_name         @h_aliases
1564                            $h_addrtype     $h_length
1565                            @h_addr_list    $h_addr
1566                        );
1567         %EXPORT_TAGS = ( FIELDS => [ @EXPORT_OK, @EXPORT ] );
1568     }
1569     use vars      @EXPORT_OK;
1570
1571     # Class::Struct forbids use of @ISA
1572     sub import { goto &Exporter::import }
1573
1574     use Class::Struct qw(struct);
1575     struct 'Net::hostent' => [
1576        name        => '$',
1577        aliases     => '@',
1578        addrtype    => '$',
1579        'length'    => '$',
1580        addr_list   => '@',
1581     ];
1582
1583     sub addr { shift->addr_list->[0] }
1584
1585     sub populate (@) {
1586         return unless @_;
1587         my $hob = new();  # Class::Struct made this!
1588         $h_name     =    $hob->[0]              = $_[0];
1589         @h_aliases  = @{ $hob->[1] } = split ' ', $_[1];
1590         $h_addrtype =    $hob->[2]              = $_[2];
1591         $h_length   =    $hob->[3]              = $_[3];
1592         $h_addr     =                             $_[4];
1593         @h_addr_list = @{ $hob->[4] } =         @_[ (4 .. $#_) ];
1594         return $hob;
1595     }
1596
1597     sub gethostbyname ($)  { populate(CORE::gethostbyname(shift)) }
1598
1599     sub gethostbyaddr ($;$) {
1600         my ($addr, $addrtype);
1601         $addr = shift;
1602         require Socket unless @_;
1603         $addrtype = @_ ? shift : Socket::AF_INET();
1604         populate(CORE::gethostbyaddr($addr, $addrtype))
1605     }
1606
1607     sub gethost($) {
1608         if ($_[0] =~ /^\d+(?:\.\d+(?:\.\d+(?:\.\d+)?)?)?$/) {
1609            require Socket;
1610            &gethostbyaddr(Socket::inet_aton(shift));
1611         } else {
1612            &gethostbyname;
1613         }
1614     }
1615
1616     1;
1617
1618 We've snuck in quite a fair bit of other concepts besides just dynamic
1619 class creation, like overriding core functions, import/export bits,
1620 function prototyping, short-cut function call via C<&whatever>, and
1621 function replacement with C<goto &whatever>.  These all mostly make
1622 sense from the perspective of a traditional module, but as you can see,
1623 we can also use them in an object module.
1624
1625 You can look at other object-based, struct-like overrides of core
1626 functions in the 5.004 release of Perl in File::stat, Net::hostent,
1627 Net::netent, Net::protoent, Net::servent, Time::gmtime, Time::localtime,
1628 User::grent, and User::pwent.  These modules have a final component
1629 that's all lowercase, by convention reserved for compiler pragmas,
1630 because they affect the compilation and change a builtin function.
1631 They also have the type names that a C programmer would most expect.
1632
1633 =head2 Data Members as Variables
1634
1635 If you're used to C++ objects, then you're accustomed to being able to
1636 get at an object's data members as simple variables from within a method.
1637 The Alias module provides for this, as well as a good bit more, such
1638 as the possibility of private methods that the object can call but folks
1639 outside the class cannot.
1640
1641 Here's an example of creating a Person using the Alias module.
1642 When you update these magical instance variables, you automatically
1643 update value fields in the hash.  Convenient, eh?
1644
1645     package Person;
1646
1647     # this is the same as before...
1648     sub new {
1649          my $that  = shift;
1650          my $class = ref($that) || $that;
1651          my $self = {
1652             NAME  => undef,
1653             AGE   => undef,
1654             PEERS => [],
1655         };
1656         bless($self, $class);
1657         return $self;
1658     }
1659
1660     use Alias qw(attr);
1661     use vars qw($NAME $AGE $PEERS);
1662
1663     sub name {
1664         my $self = attr shift;
1665         if (@_) { $NAME = shift; }
1666         return    $NAME;
1667     }
1668
1669     sub age {
1670         my $self = attr shift;
1671         if (@_) { $AGE = shift; }
1672         return    $AGE;
1673     }
1674
1675     sub peers {
1676         my $self = attr shift;
1677         if (@_) { @PEERS = @_; }
1678         return    @PEERS;
1679     }
1680
1681     sub exclaim {
1682         my $self = attr shift;
1683         return sprintf "Hi, I'm %s, age %d, working with %s",
1684             $NAME, $AGE, join(", ", @PEERS);
1685     }
1686
1687     sub happy_birthday {
1688         my $self = attr shift;
1689         return ++$AGE;
1690     }
1691
1692 The need for the C<use vars> declaration is because what Alias does
1693 is play with package globals with the same name as the fields.  To use
1694 globals while C<use strict> is in effect, you have to predeclare them.
1695 These package variables are localized to the block enclosing the attr()
1696 call just as if you'd used a local() on them.  However, that means that
1697 they're still considered global variables with temporary values, just
1698 as with any other local().
1699
1700 It would be nice to combine Alias with
1701 something like Class::Struct or Class::MethodMaker.
1702
1703 =head2 NOTES
1704
1705 =head2 Object Terminology
1706
1707 In the various OO literature, it seems that a lot of different words
1708 are used to describe only a few different concepts.  If you're not
1709 already an object programmer, then you don't need to worry about all
1710 these fancy words.  But if you are, then you might like to know how to
1711 get at the same concepts in Perl.
1712
1713 For example, it's common to call an object an I<instance> of a class
1714 and to call those objects' methods I<instance methods>.  Data fields
1715 peculiar to each object are often called I<instance data> or I<object
1716 attributes>, and data fields common to all members of that class are
1717 I<class data>, I<class attributes>, or I<static data members>.
1718
1719 Also, I<base class>, I<generic class>, and I<superclass> all describe
1720 the same notion, whereas I<derived class>, I<specific class>, and
1721 I<subclass> describe the other related one.
1722
1723 C++ programmers have I<static methods> and I<virtual methods>,
1724 but Perl only has I<class methods> and I<object methods>.
1725 Actually, Perl only has methods.  Whether a method gets used
1726 as a class or object method is by usage only.  You could accidentally
1727 call a class method (one expecting a string argument) on an
1728 object (one expecting a reference), or vice versa.
1729
1730 Z<>From the C++ perspective, all methods in Perl are virtual.
1731 This, by the way, is why they are never checked for function
1732 prototypes in the argument list as regular builtin and user-defined
1733 functions can be.
1734
1735 Because a class is itself something of an object, Perl's classes can be
1736 taken as describing both a "class as meta-object" (also called I<object
1737 factory>) philosophy and the "class as type definition" (I<declaring>
1738 behaviour, not I<defining> mechanism) idea.  C++ supports the latter
1739 notion, but not the former.
1740
1741 =head1 SEE ALSO
1742
1743 The following manpages will doubtless provide more
1744 background for this one:
1745 L<perlmod>,
1746 L<perlref>,
1747 L<perlobj>,
1748 L<perlbot>,
1749 L<perltie>,
1750 and
1751 L<overload>.
1752
1753 =head1 COPYRIGHT
1754
1755 I I<really> hate to have to say this, but recent unpleasant
1756 experiences have mandated its inclusion:
1757
1758     Copyright 1996 Tom Christiansen.  All Rights Reserved.
1759
1760 This work derives in part from the second edition of I<Programming Perl>.
1761 Although destined for release as a manpage with the standard Perl
1762 distribution, it is not public domain (nor is any of Perl and its docset:
1763 publishers beware).  It's expected to someday make its way into a revision
1764 of the Camel Book.  While it is copyright by me with all rights reserved,
1765 permission is granted to freely distribute verbatim copies of this
1766 document provided that no modifications outside of formatting be made,
1767 and that this notice remain intact.  You are permitted and encouraged to
1768 use its code and derivatives thereof in your own source code for fun or
1769 for profit as you see fit.  But so help me, if in six months I find some
1770 book out there with a hacked-up version of this material in it claiming to
1771 be written by someone else, I'll tell all the world that you're a jerk.
1772 Furthermore, your lawyer will meet my lawyer (or O'Reilly's) over lunch
1773 to arrange for you to receive your just deserts.  Count on it.
1774
1775 =head2 Acknowledgments
1776
1777 Thanks to
1778 Larry Wall,
1779 Roderick Schertler,
1780 Gurusamy Sarathy,
1781 Dean Roehrich,
1782 Raphael Manfredi,
1783 Brent Halsey,
1784 Greg Bacon,
1785 Brad Appleton,
1786 and many others for their helpful comments.