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