1PERLOBJ(1)             Perl Programmers Reference Guide             PERLOBJ(1)
2
3
4

NAME

6       perlobj - Perl objects
7

DESCRIPTION

9       First you need to understand what references are in Perl.  See perlref
10       for that.  Second, if you still find the following reference work too
11       complicated, a tutorial on object-oriented programming in Perl can be
12       found in perltoot and perltooc.
13
14       If you're still with us, then here are three very simple definitions
15       that you should find reassuring.
16
17       1.  An object is simply a reference that happens to know which class it
18           belongs to.
19
20       2.  A class is simply a package that happens to provide methods to deal
21           with object references.
22
23       3.  A method is simply a subroutine that expects an object reference
24           (or a package name, for class methods) as the first argument.
25
26       We'll cover these points now in more depth.
27
28   An Object is Simply a Reference
29       Unlike say C++, Perl doesn't provide any special syntax for
30       constructors.  A constructor is merely a subroutine that returns a
31       reference to something "blessed" into a class, generally the class that
32       the subroutine is defined in.  Here is a typical constructor:
33
34           package Critter;
35           sub new { bless {} }
36
37       That word "new" isn't special.  You could have written a construct this
38       way, too:
39
40           package Critter;
41           sub spawn { bless {} }
42
43       This might even be preferable, because the C++ programmers won't be
44       tricked into thinking that "new" works in Perl as it does in C++.  It
45       doesn't.  We recommend that you name your constructors whatever makes
46       sense in the context of the problem you're solving.  For example,
47       constructors in the Tk extension to Perl are named after the widgets
48       they create.
49
50       One thing that's different about Perl constructors compared with those
51       in C++ is that in Perl, they have to allocate their own memory.  (The
52       other things is that they don't automatically call overridden base-
53       class constructors.)  The "{}" allocates an anonymous hash containing
54       no key/value pairs, and returns it  The bless() takes that reference
55       and tells the object it references that it's now a Critter, and returns
56       the reference.  This is for convenience, because the referenced object
57       itself knows that it has been blessed, and the reference to it could
58       have been returned directly, like this:
59
60           sub new {
61               my $self = {};
62               bless $self;
63               return $self;
64           }
65
66       You often see such a thing in more complicated constructors that wish
67       to call methods in the class as part of the construction:
68
69           sub new {
70               my $self = {};
71               bless $self;
72               $self->initialize();
73               return $self;
74           }
75
76       If you care about inheritance (and you should; see "Modules: Creation,
77       Use, and Abuse" in perlmodlib), then you want to use the two-arg form
78       of bless so that your constructors may be inherited:
79
80           sub new {
81               my $class = shift;
82               my $self = {};
83               bless $self, $class;
84               $self->initialize();
85               return $self;
86           }
87
88       Or if you expect people to call not just "CLASS->new()" but also
89       "$obj->new()", then use something like the following.  (Note that using
90       this to call new() on an instance does not automatically perform any
91       copying.  If you want a shallow or deep copy of an object, you'll have
92       to specifically allow for that.)  The initialize() method used will be
93       of whatever $class we blessed the object into:
94
95           sub new {
96               my $this = shift;
97               my $class = ref($this) || $this;
98               my $self = {};
99               bless $self, $class;
100               $self->initialize();
101               return $self;
102           }
103
104       Within the class package, the methods will typically deal with the
105       reference as an ordinary reference.  Outside the class package, the
106       reference is generally treated as an opaque value that may be accessed
107       only through the class's methods.
108
109       Although a constructor can in theory re-bless a referenced object
110       currently belonging to another class, this is almost certainly going to
111       get you into trouble.  The new class is responsible for all cleanup
112       later.  The previous blessing is forgotten, as an object may belong to
113       only one class at a time.  (Although of course it's free to inherit
114       methods from many classes.)  If you find yourself having to do this,
115       the parent class is probably misbehaving, though.
116
117       A clarification:  Perl objects are blessed.  References are not.
118       Objects know which package they belong to.  References do not.  The
119       bless() function uses the reference to find the object.  Consider the
120       following example:
121
122           $a = {};
123           $b = $a;
124           bless $a, BLAH;
125           print "\$b is a ", ref($b), "\n";
126
127       This reports $b as being a BLAH, so obviously bless() operated on the
128       object and not on the reference.
129
130   A Class is Simply a Package
131       Unlike say C++, Perl doesn't provide any special syntax for class
132       definitions.  You use a package as a class by putting method
133       definitions into the class.
134
135       There is a special array within each package called @ISA, which says
136       where else to look for a method if you can't find it in the current
137       package.  This is how Perl implements inheritance.  Each element of the
138       @ISA array is just the name of another package that happens to be a
139       class package.  The classes are searched for missing methods in depth-
140       first, left-to-right order by default (see mro for alternative search
141       order and other in-depth information).  The classes accessible through
142       @ISA are known as base classes of the current class.
143
144       All classes implicitly inherit from class "UNIVERSAL" as their last
145       base class.  Several commonly used methods are automatically supplied
146       in the UNIVERSAL class; see "Default UNIVERSAL methods" or UNIVERSAL
147       for more details.
148
149       If a missing method is found in a base class, it is cached in the
150       current class for efficiency.  Changing @ISA or defining new
151       subroutines invalidates the cache and causes Perl to do the lookup
152       again.
153
154       If neither the current class, its named base classes, nor the UNIVERSAL
155       class contains the requested method, these three places are searched
156       all over again, this time looking for a method named AUTOLOAD().  If an
157       AUTOLOAD is found, this method is called on behalf of the missing
158       method, setting the package global $AUTOLOAD to be the fully qualified
159       name of the method that was intended to be called.
160
161       If none of that works, Perl finally gives up and complains.
162
163       If you want to stop the AUTOLOAD inheritance say simply
164
165               sub AUTOLOAD;
166
167       and the call will die using the name of the sub being called.
168
169       Perl classes do method inheritance only.  Data inheritance is left up
170       to the class itself.  By and large, this is not a problem in Perl,
171       because most classes model the attributes of their object using an
172       anonymous hash, which serves as its own little namespace to be carved
173       up by the various classes that might want to do something with the
174       object.  The only problem with this is that you can't sure that you
175       aren't using a piece of the hash that isn't already used.  A reasonable
176       workaround is to prepend your fieldname in the hash with the package
177       name.
178
179           sub bump {
180               my $self = shift;
181               $self->{ __PACKAGE__ . ".count"}++;
182           }
183
184   A Method is Simply a Subroutine
185       Unlike say C++, Perl doesn't provide any special syntax for method
186       definition.  (It does provide a little syntax for method invocation
187       though.  More on that later.)  A method expects its first argument to
188       be the object (reference) or package (string) it is being invoked on.
189       There are two ways of calling methods, which we'll call class methods
190       and instance methods.
191
192       A class method expects a class name as the first argument.  It provides
193       functionality for the class as a whole, not for any individual object
194       belonging to the class.  Constructors are often class methods, but see
195       perltoot and perltooc for alternatives.  Many class methods simply
196       ignore their first argument, because they already know what package
197       they're in and don't care what package they were invoked via.  (These
198       aren't necessarily the same, because class methods follow the
199       inheritance tree just like ordinary instance methods.)  Another typical
200       use for class methods is to look up an object by name:
201
202           sub find {
203               my ($class, $name) = @_;
204               $objtable{$name};
205           }
206
207       An instance method expects an object reference as its first argument.
208       Typically it shifts the first argument into a "self" or "this"
209       variable, and then uses that as an ordinary reference.
210
211           sub display {
212               my $self = shift;
213               my @keys = @_ ? @_ : sort keys %$self;
214               foreach $key (@keys) {
215                   print "\t$key => $self->{$key}\n";
216               }
217           }
218
219   Method Invocation
220       For various historical and other reasons, Perl offers two equivalent
221       ways to write a method call.  The simpler and more common way is to use
222       the arrow notation:
223
224           my $fred = Critter->find("Fred");
225           $fred->display("Height", "Weight");
226
227       You should already be familiar with the use of the "->" operator with
228       references.  In fact, since $fred above is a reference to an object,
229       you could think of the method call as just another form of
230       dereferencing.
231
232       Whatever is on the left side of the arrow, whether a reference or a
233       class name, is passed to the method subroutine as its first argument.
234       So the above code is mostly equivalent to:
235
236           my $fred = Critter::find("Critter", "Fred");
237           Critter::display($fred, "Height", "Weight");
238
239       How does Perl know which package the subroutine is in?  By looking at
240       the left side of the arrow, which must be either a package name or a
241       reference to an object, i.e. something that has been blessed to a
242       package.  Either way, that's the package where Perl starts looking.  If
243       that package has no subroutine with that name, Perl starts looking for
244       it in any base classes of that package, and so on.
245
246       If you need to, you can force Perl to start looking in some other
247       package:
248
249           my $barney = MyCritter->Critter::find("Barney");
250           $barney->Critter::display("Height", "Weight");
251
252       Here "MyCritter" is presumably a subclass of "Critter" that defines its
253       own versions of find() and display().  We haven't specified what those
254       methods do, but that doesn't matter above since we've forced Perl to
255       start looking for the subroutines in "Critter".
256
257       As a special case of the above, you may use the "SUPER" pseudo-class to
258       tell Perl to start looking for the method in the packages named in the
259       current class's @ISA list.
260
261           package MyCritter;
262           use base 'Critter';    # sets @MyCritter::ISA = ('Critter');
263
264           sub display {
265               my ($self, @args) = @_;
266               $self->SUPER::display("Name", @args);
267           }
268
269       It is important to note that "SUPER" refers to the superclass(es) of
270       the current package and not to the superclass(es) of the object. Also,
271       the "SUPER" pseudo-class can only currently be used as a modifier to a
272       method name, but not in any of the other ways that class names are
273       normally used, eg:
274
275           something->SUPER::method(...);      # OK
276           SUPER::method(...);                 # WRONG
277           SUPER->method(...);                 # WRONG
278
279       Instead of a class name or an object reference, you can also use any
280       expression that returns either of those on the left side of the arrow.
281       So the following statement is valid:
282
283           Critter->find("Fred")->display("Height", "Weight");
284
285       and so is the following:
286
287           my $fred = (reverse "rettirC")->find(reverse "derF");
288
289       The right side of the arrow typically is the method name, but a simple
290       scalar variable containing either the method name or a subroutine
291       reference can also be used.
292
293       If the right side of the arrow is a scalar containing a reference to a
294       subroutine, then this is equivalent to calling the referenced
295       subroutine directly with the class name or object on the left side of
296       the arrow as its first argument. No lookup is done and there is no
297       requirement that the subroutine be defined in any package related to
298       the class name or object on the left side of the arrow.
299
300       For example, the following calls to $display are equivalent:
301
302           my $display = sub { my $self = shift; ... };
303           $fred->$display("Height", "Weight");
304           $display->($fred, "Height", "Weight");
305
306   Indirect Object Syntax
307       The other way to invoke a method is by using the so-called "indirect
308       object" notation.  This syntax was available in Perl 4 long before
309       objects were introduced, and is still used with filehandles like this:
310
311          print STDERR "help!!!\n";
312
313       The same syntax can be used to call either object or class methods.
314
315          my $fred = find Critter "Fred";
316          display $fred "Height", "Weight";
317
318       Notice that there is no comma between the object or class name and the
319       parameters.  This is how Perl can tell you want an indirect method call
320       instead of an ordinary subroutine call.
321
322       But what if there are no arguments?  In that case, Perl must guess what
323       you want.  Even worse, it must make that guess at compile time.
324       Usually Perl gets it right, but when it doesn't you get a function call
325       compiled as a method, or vice versa.  This can introduce subtle bugs
326       that are hard to detect.
327
328       For example, a call to a method "new" in indirect notation -- as C++
329       programmers are wont to make -- can be miscompiled into a subroutine
330       call if there's already a "new" function in scope.  You'd end up
331       calling the current package's "new" as a subroutine, rather than the
332       desired class's method.  The compiler tries to cheat by remembering
333       bareword "require"s, but the grief when it messes up just isn't worth
334       the years of debugging it will take you to track down such subtle bugs.
335
336       There is another problem with this syntax: the indirect object is
337       limited to a name, a scalar variable, or a block, because it would have
338       to do too much lookahead otherwise, just like any other postfix
339       dereference in the language.  (These are the same quirky rules as are
340       used for the filehandle slot in functions like "print" and "printf".)
341       This can lead to horribly confusing precedence problems, as in these
342       next two lines:
343
344           move $obj->{FIELD};                 # probably wrong!
345           move $ary[$i];                      # probably wrong!
346
347       Those actually parse as the very surprising:
348
349           $obj->move->{FIELD};                # Well, lookee here
350           $ary->move([$i]);                   # Didn't expect this one, eh?
351
352       Rather than what you might have expected:
353
354           $obj->{FIELD}->move();              # You should be so lucky.
355           $ary[$i]->move;                     # Yeah, sure.
356
357       To get the correct behavior with indirect object syntax, you would have
358       to use a block around the indirect object:
359
360           move {$obj->{FIELD}};
361           move {$ary[$i]};
362
363       Even then, you still have the same potential problem if there happens
364       to be a function named "move" in the current package.  The "->"
365       notation suffers from neither of these disturbing ambiguities, so we
366       recommend you use it exclusively.  However, you may still end up having
367       to read code using the indirect object notation, so it's important to
368       be familiar with it.
369
370   Default UNIVERSAL methods
371       The "UNIVERSAL" package automatically contains the following methods
372       that are inherited by all other classes:
373
374       isa(CLASS)
375           "isa" returns true if its object is blessed into a subclass of
376           "CLASS"
377
378       DOES(ROLE)
379           "DOES" returns true if its object claims to perform the role
380           "ROLE".  By default, this is equivalent to "isa".
381
382       can(METHOD)
383           "can" checks to see if its object has a method called "METHOD", if
384           it does then a reference to the sub is returned, if it does not
385           then "undef" is returned.
386
387       VERSION( [NEED] )
388           "VERSION" returns the version number of the class (package).  If
389           the NEED argument is given then it will check that the current
390           version (as defined by the $VERSION variable in the given package)
391           not less than NEED; it will die if this is not the case.  This
392           method is called automatically by the "VERSION" form of "use".
393
394               use Package 1.2 qw(some imported subs);
395               # implies:
396               Package->VERSION(1.2);
397
398   Destructors
399       When the last reference to an object goes away, the object is
400       automatically destroyed.  (This may even be after you exit, if you've
401       stored references in global variables.)  If you want to capture control
402       just before the object is freed, you may define a DESTROY method in
403       your class.  It will automatically be called at the appropriate moment,
404       and you can do any extra cleanup you need to do.  Perl passes a
405       reference to the object under destruction as the first (and only)
406       argument.  Beware that the reference is a read-only value, and cannot
407       be modified by manipulating $_[0] within the destructor.  The object
408       itself (i.e.  the thingy the reference points to, namely "${$_[0]}",
409       "@{$_[0]}", "%{$_[0]}" etc.) is not similarly constrained.
410
411       Since DESTROY methods can be called at unpredictable times, it is
412       important that you localise any global variables that the method may
413       update.  In particular, localise $@ if you use "eval {}" and localise
414       $? if you use "system" or backticks.
415
416       If you arrange to re-bless the reference before the destructor returns,
417       perl will again call the DESTROY method for the re-blessed object after
418       the current one returns.  This can be used for clean delegation of
419       object destruction, or for ensuring that destructors in the base
420       classes of your choosing get called.  Explicitly calling DESTROY is
421       also possible, but is usually never needed.
422
423       Do not confuse the previous discussion with how objects CONTAINED in
424       the current one are destroyed.  Such objects will be freed and
425       destroyed automatically when the current object is freed, provided no
426       other references to them exist elsewhere.
427
428   Summary
429       That's about all there is to it.  Now you need just to go off and buy a
430       book about object-oriented design methodology, and bang your forehead
431       with it for the next six months or so.
432
433   Two-Phased Garbage Collection
434       For most purposes, Perl uses a fast and simple, reference-based garbage
435       collection system.  That means there's an extra dereference going on at
436       some level, so if you haven't built your Perl executable using your C
437       compiler's "-O" flag, performance will suffer.  If you have built Perl
438       with "cc -O", then this probably won't matter.
439
440       A more serious concern is that unreachable memory with a non-zero
441       reference count will not normally get freed.  Therefore, this is a bad
442       idea:
443
444           {
445               my $a;
446               $a = \$a;
447           }
448
449       Even thought $a should go away, it can't.  When building recursive data
450       structures, you'll have to break the self-reference yourself explicitly
451       if you don't care to leak.  For example, here's a self-referential node
452       such as one might use in a sophisticated tree structure:
453
454           sub new_node {
455               my $class = shift;
456               my $node  = {};
457               $node->{LEFT} = $node->{RIGHT} = $node;
458               $node->{DATA} = [ @_ ];
459               return bless $node => $class;
460           }
461
462       If you create nodes like that, they (currently) won't go away unless
463       you break their self reference yourself.  (In other words, this is not
464       to be construed as a feature, and you shouldn't depend on it.)
465
466       Almost.
467
468       When an interpreter thread finally shuts down (usually when your
469       program exits), then a rather costly but complete mark-and-sweep style
470       of garbage collection is performed, and everything allocated by that
471       thread gets destroyed.  This is essential to support Perl as an
472       embedded or a multithreadable language.  For example, this program
473       demonstrates Perl's two-phased garbage collection:
474
475           #!/usr/bin/perl
476           package Subtle;
477
478           sub new {
479               my $test;
480               $test = \$test;
481               warn "CREATING " . \$test;
482               return bless \$test;
483           }
484
485           sub DESTROY {
486               my $self = shift;
487               warn "DESTROYING $self";
488           }
489
490           package main;
491
492           warn "starting program";
493           {
494               my $a = Subtle->new;
495               my $b = Subtle->new;
496               $$a = 0;  # break selfref
497               warn "leaving block";
498           }
499
500           warn "just exited block";
501           warn "time to die...";
502           exit;
503
504       When run as /foo/test, the following output is produced:
505
506           starting program at /foo/test line 18.
507           CREATING SCALAR(0x8e5b8) at /foo/test line 7.
508           CREATING SCALAR(0x8e57c) at /foo/test line 7.
509           leaving block at /foo/test line 23.
510           DESTROYING Subtle=SCALAR(0x8e5b8) at /foo/test line 13.
511           just exited block at /foo/test line 26.
512           time to die... at /foo/test line 27.
513           DESTROYING Subtle=SCALAR(0x8e57c) during global destruction.
514
515       Notice that "global destruction" bit there?  That's the thread garbage
516       collector reaching the unreachable.
517
518       Objects are always destructed, even when regular refs aren't.  Objects
519       are destructed in a separate pass before ordinary refs just to prevent
520       object destructors from using refs that have been themselves
521       destructed.  Plain refs are only garbage-collected if the destruct
522       level is greater than 0.  You can test the higher levels of global
523       destruction by setting the PERL_DESTRUCT_LEVEL environment variable,
524       presuming "-DDEBUGGING" was enabled during perl build time.  See
525       "PERL_DESTRUCT_LEVEL" in perlhack for more information.
526
527       A more complete garbage collection strategy will be implemented at a
528       future date.
529
530       In the meantime, the best solution is to create a non-recursive
531       container class that holds a pointer to the self-referential data
532       structure.  Define a DESTROY method for the containing object's class
533       that manually breaks the circularities in the self-referential
534       structure.
535

SEE ALSO

537       A kinder, gentler tutorial on object-oriented programming in Perl can
538       be found in perltoot, perlboot and perltooc.  You should also check out
539       perlbot for other object tricks, traps, and tips, as well as perlmodlib
540       for some style guides on constructing both modules and classes.
541
542
543
544perl v5.10.1                      2009-04-14                        PERLOBJ(1)
Impressum