diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods/perlobj.pod')
| -rw-r--r-- | Master/tlpkg/tlperl/lib/pods/perlobj.pod | 595 |
1 files changed, 595 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/pods/perlobj.pod b/Master/tlpkg/tlperl/lib/pods/perlobj.pod new file mode 100644 index 00000000000..fdecd84a688 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/pods/perlobj.pod @@ -0,0 +1,595 @@ +=head1 NAME +X<object> X<OOP> + +perlobj - Perl objects + +=head1 DESCRIPTION + +First you need to understand what references are in Perl. +See L<perlref> for that. Second, if you still find the following +reference work too complicated, a tutorial on object-oriented programming +in Perl can be found in L<perltoot> and L<perltooc>. + +If you're still with us, then +here are three very simple definitions that you should find reassuring. + +=over 4 + +=item 1. + +An object is simply a reference that happens to know which class it +belongs to. + +=item 2. + +A class is simply a package that happens to provide methods to deal +with object references. + +=item 3. + +A method is simply a subroutine that expects an object reference (or +a package name, for class methods) as the first argument. + +=back + +We'll cover these points now in more depth. + +=head2 An Object is Simply a Reference +X<object> X<bless> X<constructor> X<new> + +Unlike say C++, Perl doesn't provide any special syntax for +constructors. A constructor is merely a subroutine that returns a +reference to something "blessed" into a class, generally the +class that the subroutine is defined in. Here is a typical +constructor: + + package Critter; + sub new { bless {} } + +That word C<new> isn't special. You could have written +a construct this way, too: + + package Critter; + sub spawn { bless {} } + +This might even be preferable, because the C++ programmers won't +be tricked into thinking that C<new> works in Perl as it does in C++. +It doesn't. We recommend that you name your constructors whatever +makes sense in the context of the problem you're solving. For example, +constructors in the Tk extension to Perl are named after the widgets +they create. + +One thing that's different about Perl constructors compared with those in +C++ is that in Perl, they have to allocate their own memory. (The other +things is that they don't automatically call overridden base-class +constructors.) The C<{}> allocates an anonymous hash containing no +key/value pairs, and returns it The bless() takes that reference and +tells the object it references that it's now a Critter, and returns +the reference. This is for convenience, because the referenced object +itself knows that it has been blessed, and the reference to it could +have been returned directly, like this: + + sub new { + my $self = {}; + bless $self; + return $self; + } + +You often see such a thing in more complicated constructors +that wish to call methods in the class as part of the construction: + + sub new { + my $self = {}; + bless $self; + $self->initialize(); + return $self; + } + +If you care about inheritance (and you should; see +L<perlmodlib/"Modules: Creation, Use, and Abuse">), +then you want to use the two-arg form of bless +so that your constructors may be inherited: + + sub new { + my $class = shift; + my $self = {}; + bless $self, $class; + $self->initialize(); + return $self; + } + +Or if you expect people to call not just C<< CLASS->new() >> but also +C<< $obj->new() >>, then use something like the following. (Note that using +this to call new() on an instance does not automatically perform any +copying. If you want a shallow or deep copy of an object, you'll have to +specifically allow for that.) The initialize() method used will be of +whatever $class we blessed the object into: + + sub new { + my $this = shift; + my $class = ref($this) || $this; + my $self = {}; + bless $self, $class; + $self->initialize(); + return $self; + } + +Within the class package, the methods will typically deal with the +reference as an ordinary reference. Outside the class package, +the reference is generally treated as an opaque value that may +be accessed only through the class's methods. + +Although a constructor can in theory re-bless a referenced object +currently belonging to another class, this is almost certainly going +to get you into trouble. The new class is responsible for all +cleanup later. The previous blessing is forgotten, as an object +may belong to only one class at a time. (Although of course it's +free to inherit methods from many classes.) If you find yourself +having to do this, the parent class is probably misbehaving, though. + +A clarification: Perl objects are blessed. References are not. Objects +know which package they belong to. References do not. The bless() +function uses the reference to find the object. Consider +the following example: + + $a = {}; + $b = $a; + bless $a, BLAH; + print "\$b is a ", ref($b), "\n"; + +This reports $b as being a BLAH, so obviously bless() +operated on the object and not on the reference. + +=head2 A Class is Simply a Package +X<class> X<package> X<@ISA> X<inheritance> + +Unlike say C++, Perl doesn't provide any special syntax for class +definitions. You use a package as a class by putting method +definitions into the class. + +There is a special array within each package called @ISA, which says +where else to look for a method if you can't find it in the current +package. This is how Perl implements inheritance. Each element of the +@ISA array is just the name of another package that happens to be a +class package. The classes are searched for missing methods in +depth-first, left-to-right order by default (see L<mro> for alternative +search order and other in-depth information). The classes accessible +through @ISA are known as base classes of the current class. + +All classes implicitly inherit from class C<UNIVERSAL> as their +last base class. Several commonly used methods are automatically +supplied in the UNIVERSAL class; see L<"Default UNIVERSAL methods"> or +L<UNIVERSAL|UNIVERSAL> for more details. +X<UNIVERSAL> X<base class> X<class, base> + +If a missing method is found in a base class, it is cached +in the current class for efficiency. Changing @ISA or defining new +subroutines invalidates the cache and causes Perl to do the lookup again. + +If neither the current class, its named base classes, nor the UNIVERSAL +class contains the requested method, these three places are searched +all over again, this time looking for a method named AUTOLOAD(). If an +AUTOLOAD is found, this method is called on behalf of the missing method, +setting the package global $AUTOLOAD to be the fully qualified name of +the method that was intended to be called. +X<AUTOLOAD> + +If none of that works, Perl finally gives up and complains. + +If you want to stop the AUTOLOAD inheritance say simply +X<AUTOLOAD> + + sub AUTOLOAD; + +and the call will die using the name of the sub being called. + +Perl classes do method inheritance only. Data inheritance is left up +to the class itself. By and large, this is not a problem in Perl, +because most classes model the attributes of their object using an +anonymous hash, which serves as its own little namespace to be carved up +by the various classes that might want to do something with the object. +The only problem with this is that you can't sure that you aren't using +a piece of the hash that isn't already used. A reasonable workaround +is to prepend your fieldname in the hash with the package name. +X<inheritance, method> X<inheritance, data> + + sub bump { + my $self = shift; + $self->{ __PACKAGE__ . ".count"}++; + } + +=head2 A Method is Simply a Subroutine +X<method> + +Unlike say C++, Perl doesn't provide any special syntax for method +definition. (It does provide a little syntax for method invocation +though. More on that later.) A method expects its first argument +to be the object (reference) or package (string) it is being invoked +on. There are two ways of calling methods, which we'll call class +methods and instance methods. + +A class method expects a class name as the first argument. It +provides functionality for the class as a whole, not for any +individual object belonging to the class. Constructors are often +class methods, but see L<perltoot> and L<perltooc> for alternatives. +Many class methods simply ignore their first argument, because they +already know what package they're in and don't care what package +they were invoked via. (These aren't necessarily the same, because +class methods follow the inheritance tree just like ordinary instance +methods.) Another typical use for class methods is to look up an +object by name: + + sub find { + my ($class, $name) = @_; + $objtable{$name}; + } + +An instance method expects an object reference as its first argument. +Typically it shifts the first argument into a "self" or "this" variable, +and then uses that as an ordinary reference. + + sub display { + my $self = shift; + my @keys = @_ ? @_ : sort keys %$self; + foreach $key (@keys) { + print "\t$key => $self->{$key}\n"; + } + } + +=head2 Method Invocation +X<invocation> X<method> X<arrow> X<< -> >> + +For various historical and other reasons, Perl offers two equivalent +ways to write a method call. The simpler and more common way is to use +the arrow notation: + + my $fred = Critter->find("Fred"); + $fred->display("Height", "Weight"); + +You should already be familiar with the use of the C<< -> >> operator with +references. In fact, since C<$fred> above is a reference to an object, +you could think of the method call as just another form of +dereferencing. + +Whatever is on the left side of the arrow, whether a reference or a +class name, is passed to the method subroutine as its first argument. +So the above code is mostly equivalent to: + + my $fred = Critter::find("Critter", "Fred"); + Critter::display($fred, "Height", "Weight"); + +How does Perl know which package the subroutine is in? By looking at +the left side of the arrow, which must be either a package name or a +reference to an object, i.e. something that has been blessed to a +package. Either way, that's the package where Perl starts looking. If +that package has no subroutine with that name, Perl starts looking for +it in any base classes of that package, and so on. + +If you need to, you I<can> force Perl to start looking in some other package: + + my $barney = MyCritter->Critter::find("Barney"); + $barney->Critter::display("Height", "Weight"); + +Here C<MyCritter> is presumably a subclass of C<Critter> that defines +its own versions of find() and display(). We haven't specified what +those methods do, but that doesn't matter above since we've forced Perl +to start looking for the subroutines in C<Critter>. + +As a special case of the above, you may use the C<SUPER> pseudo-class to +tell Perl to start looking for the method in the packages named in the +current class's C<@ISA> list. +X<SUPER> + + package MyCritter; + use base 'Critter'; # sets @MyCritter::ISA = ('Critter'); + + sub display { + my ($self, @args) = @_; + $self->SUPER::display("Name", @args); + } + +It is important to note that C<SUPER> refers to the superclass(es) of the +I<current package> and not to the superclass(es) of the object. Also, the +C<SUPER> pseudo-class can only currently be used as a modifier to a method +name, but not in any of the other ways that class names are normally used, +eg: +X<SUPER> + + something->SUPER::method(...); # OK + SUPER::method(...); # WRONG + SUPER->method(...); # WRONG + +Instead of a class name or an object reference, you can also use any +expression that returns either of those on the left side of the arrow. +So the following statement is valid: + + Critter->find("Fred")->display("Height", "Weight"); + +and so is the following: + + my $fred = (reverse "rettirC")->find(reverse "derF"); + +The right side of the arrow typically is the method name, but a simple +scalar variable containing either the method name or a subroutine +reference can also be used. + +If the right side of the arrow is a scalar containing a reference +to a subroutine, then this is equivalent to calling the referenced +subroutine directly with the class name or object on the left side +of the arrow as its first argument. No lookup is done and there is +no requirement that the subroutine be defined in any package related +to the class name or object on the left side of the arrow. + +For example, the following calls to $display are equivalent: + + my $display = sub { my $self = shift; ... }; + $fred->$display("Height", "Weight"); + $display->($fred, "Height", "Weight"); + +=head2 Indirect Object Syntax +X<indirect object syntax> X<invocation, indirect> X<indirect> + +The other way to invoke a method is by using the so-called "indirect +object" notation. This syntax was available in Perl 4 long before +objects were introduced, and is still used with filehandles like this: + + print STDERR "help!!!\n"; + +The same syntax can be used to call either object or class methods. + + my $fred = find Critter "Fred"; + display $fred "Height", "Weight"; + +Notice that there is no comma between the object or class name and the +parameters. This is how Perl can tell you want an indirect method call +instead of an ordinary subroutine call. + +But what if there are no arguments? In that case, Perl must guess what +you want. Even worse, it must make that guess I<at compile time>. +Usually Perl gets it right, but when it doesn't you get a function +call compiled as a method, or vice versa. This can introduce subtle bugs +that are hard to detect. + +For example, a call to a method C<new> in indirect notation (as C++ +programmers are wont to make) can be miscompiled into a subroutine +call if there's already a C<new> function in scope. You'd end up +calling the current package's C<new> as a subroutine, rather than the +desired class's method. The compiler tries to cheat by remembering +bareword C<require>s, but the grief when it messes up just isn't worth the +years of debugging it will take you to track down such subtle bugs. + +There is another problem with this syntax: the indirect object is +limited to a name, a scalar variable, or a block, because it would have +to do too much lookahead otherwise, just like any other postfix +dereference in the language. (These are the same quirky rules as are +used for the filehandle slot in functions like C<print> and C<printf>.) +This can lead to horribly confusing precedence problems, as in these +next two lines: + + move $obj->{FIELD}; # probably wrong! + move $ary[$i]; # probably wrong! + +Those actually parse as the very surprising: + + $obj->move->{FIELD}; # Well, lookee here + $ary->move([$i]); # Didn't expect this one, eh? + +Rather than what you might have expected: + + $obj->{FIELD}->move(); # You should be so lucky. + $ary[$i]->move; # Yeah, sure. + +To get the correct behavior with indirect object syntax, you would have +to use a block around the indirect object: + + move {$obj->{FIELD}}; + move {$ary[$i]}; + +Even then, you still have the same potential problem if there happens to +be a function named C<move> in the current package. B<The C<< -> >> +notation suffers from neither of these disturbing ambiguities, so we +recommend you use it exclusively.> However, you may still end up having +to read code using the indirect object notation, so it's important to be +familiar with it. + +=head2 Default UNIVERSAL methods +X<UNIVERSAL> + +The C<UNIVERSAL> package automatically contains the following methods that +are inherited by all other classes: + +=over 4 + +=item isa(CLASS) +X<isa> + +C<isa> returns I<true> if its object is blessed into a subclass of C<CLASS> + +=item DOES(ROLE) +X<DOES> + +C<DOES> returns I<true> if its object claims to perform the role C<ROLE>. By +default, this is equivalent to C<isa>. + +=item can(METHOD) +X<can> + +C<can> checks to see if its object has a method called C<METHOD>, +if it does then a reference to the sub is returned, if it does not then +C<undef> is returned. + +=item VERSION( [NEED] ) +X<VERSION> + +C<VERSION> returns the version number of the class (package). If the +NEED argument is given then it will check that the current version (as +defined by the $VERSION variable in the given package) not less than +NEED; it will die if this is not the case. This method is called automatically +by the C<VERSION> form of C<use>. + + use Package 1.2 qw(some imported subs); + # implies: + Package->VERSION(1.2); + +=back + +=head2 Destructors +X<destructor> X<DESTROY> + +When the last reference to an object goes away, the object is +automatically destroyed. (This may even be after you exit, if you've +stored references in global variables.) If you want to capture control +just before the object is freed, you may define a DESTROY method in +your class. It will automatically be called at the appropriate moment, +and you can do any extra cleanup you need to do. Perl passes a reference +to the object under destruction as the first (and only) argument. Beware +that the reference is a read-only value, and cannot be modified by +manipulating C<$_[0]> within the destructor. The object itself (i.e. +the thingy the reference points to, namely C<${$_[0]}>, C<@{$_[0]}>, +C<%{$_[0]}> etc.) is not similarly constrained. + +Since DESTROY methods can be called at unpredictable times, it is +important that you localise any global variables that the method may +update. In particular, localise C<$@> if you use C<eval {}> and +localise C<$?> if you use C<system> or backticks. + +If you arrange to re-bless the reference before the destructor returns, +perl will again call the DESTROY method for the re-blessed object after +the current one returns. This can be used for clean delegation of +object destruction, or for ensuring that destructors in the base classes +of your choosing get called. Explicitly calling DESTROY is also possible, +but is usually never needed. + +DESTROY is subject to AUTOLOAD lookup, just like any other method. Hence, if +your class has an AUTOLOAD method, but does not need any DESTROY actions, +you probably want to provide a DESTROY method anyway, to prevent an +expensive call to AUTOLOAD each time an object is freed. As this technique +makes empty DESTROY methods common, the implementation is optimised so that +a DESTROY method that is an empty or constant subroutine, and hence could +have no side effects anyway, is not actually called. +X<AUTOLOAD> X<DESTROY> + +Do not confuse the previous discussion with how objects I<CONTAINED> in the current +one are destroyed. Such objects will be freed and destroyed automatically +when the current object is freed, provided no other references to them exist +elsewhere. + +=head2 Summary + +That's about all there is to it. Now you need just to go off and buy a +book about object-oriented design methodology, and bang your forehead +with it for the next six months or so. + +=head2 Two-Phased Garbage Collection +X<garbage collection> X<GC> X<circular reference> +X<reference, circular> X<DESTROY> X<destructor> + +For most purposes, Perl uses a fast and simple, reference-based +garbage collection system. That means there's an extra +dereference going on at some level, so if you haven't built +your Perl executable using your C compiler's C<-O> flag, performance +will suffer. If you I<have> built Perl with C<cc -O>, then this +probably won't matter. + +A more serious concern is that unreachable memory with a non-zero +reference count will not normally get freed. Therefore, this is a bad +idea: + + { + my $a; + $a = \$a; + } + +Even thought $a I<should> go away, it can't. When building recursive data +structures, you'll have to break the self-reference yourself explicitly +if you don't care to leak. For example, here's a self-referential +node such as one might use in a sophisticated tree structure: + + sub new_node { + my $class = shift; + my $node = {}; + $node->{LEFT} = $node->{RIGHT} = $node; + $node->{DATA} = [ @_ ]; + return bless $node => $class; + } + +If you create nodes like that, they (currently) won't go away unless you +break their self reference yourself. (In other words, this is not to be +construed as a feature, and you shouldn't depend on it.) + +Almost. + +When an interpreter thread finally shuts down (usually when your program +exits), then a rather costly but complete mark-and-sweep style of garbage +collection is performed, and everything allocated by that thread gets +destroyed. This is essential to support Perl as an embedded or a +multithreadable language. For example, this program demonstrates Perl's +two-phased garbage collection: + + #!/usr/bin/perl + package Subtle; + + sub new { + my $test; + $test = \$test; + warn "CREATING " . \$test; + return bless \$test; + } + + sub DESTROY { + my $self = shift; + warn "DESTROYING $self"; + } + + package main; + + warn "starting program"; + { + my $a = Subtle->new; + my $b = Subtle->new; + $$a = 0; # break selfref + warn "leaving block"; + } + + warn "just exited block"; + warn "time to die..."; + exit; + +When run as F</foo/test>, the following output is produced: + + starting program at /foo/test line 18. + CREATING SCALAR(0x8e5b8) at /foo/test line 7. + CREATING SCALAR(0x8e57c) at /foo/test line 7. + leaving block at /foo/test line 23. + DESTROYING Subtle=SCALAR(0x8e5b8) at /foo/test line 13. + just exited block at /foo/test line 26. + time to die... at /foo/test line 27. + DESTROYING Subtle=SCALAR(0x8e57c) during global destruction. + +Notice that "global destruction" bit there? That's the thread +garbage collector reaching the unreachable. + +Objects are always destructed, even when regular refs aren't. Objects +are destructed in a separate pass before ordinary refs just to +prevent object destructors from using refs that have been themselves +destructed. Plain refs are only garbage-collected if the destruct level +is greater than 0. You can test the higher levels of global destruction +by setting the PERL_DESTRUCT_LEVEL environment variable, presuming +C<-DDEBUGGING> was enabled during perl build time. +See L<perlhack/PERL_DESTRUCT_LEVEL> for more information. + +A more complete garbage collection strategy will be implemented +at a future date. + +In the meantime, the best solution is to create a non-recursive container +class that holds a pointer to the self-referential data structure. +Define a DESTROY method for the containing object's class that manually +breaks the circularities in the self-referential structure. + +=head1 SEE ALSO + +A kinder, gentler tutorial on object-oriented programming in Perl can +be found in L<perltoot>, L<perlboot> and L<perltooc>. You should +also check out L<perlbot> for other object tricks, traps, and tips, as +well as L<perlmodlib> for some style guides on constructing both +modules and classes. |