+=encoding utf8
+
+=for comment
+Consistent formatting of this file is achieved with:
+ perl ./Porting/podtidy pod/perlobj.pod
+
=head1 NAME
+X<object> X<OOP>
-perlobj - Perl objects
+perlobj - Perl object reference
=head1 DESCRIPTION
-First of all, you need to understand what references are in Perl. See
-L<perlref> for that.
+This document provides a reference for Perl's object orientation
+features. If you're looking for an introduction to object-oriented
+programming in Perl, please see L<perlootut>.
+
+In order to understand Perl objects, you first need to understand
+references in Perl. See L<perlref> for details.
+
+This document describes all of Perl's OO features from the ground up.
+If you're just looking to write some object-oriented code of your own,
+you are probably better served by using one of the object systems from
+CPAN described in L<perlootut>.
-Here are three very simple definitions that you should find reassuring.
+If you're looking to write your own object system, or you need to
+maintain code which implements objects from scratch then this document
+will help you understand exactly how Perl does object orientation.
+
+There are a few basic principles which define object oriented Perl:
=over 4
=item 1.
-An object is simply a reference that happens to know which class it
-belongs to.
+An object is simply a reference that knows which class it belongs to.
=item 2.
-A class is simply a package that happens to provide methods to deal
-with object references.
+A class is simply a package. A class provides methods that expect to
+operate on objects.
=item 3.
-A method is simply a subroutine that expects an object reference (or
-a package name, for class methods) as the first argument.
+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.
+Let's look at each of these principles in depth.
=head2 An Object is Simply a Reference
+X<object> X<bless> X<constructor> X<new>
+
+Unlike many other languages which support object orientation, Perl does
+not provide any special syntax for constructing an object. A
+constructor is just a subroutine that returns a reference which has
+been "blessed" into a class.
+
+Here is a simple constructor:
+
+ package File;
+
+ sub new {
+ my $class = shift;
+
+ return bless {}, $class;
+ }
+
+The name C<new> isn't special. We could name our constructor something
+else:
+
+ sub load {
+ my $class = shift;
+
+ return bless {}, $class;
+ }
-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 {} }
-
-The C<{}> constructs a reference to an anonymous hash containing no
-key/value pairs. 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 its reference to it could have been returned
-directly, like this:
-
- sub new {
- my $self = {};
- bless $self;
- return $self;
- }
-
-In fact, 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<perlmod/"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-E<gt>new()> but also
-C<$obj-E<gt>new()>, then use something like this. 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.
-
-A constructor may re-bless a referenced object currently belonging to
-another class, but then 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.)
-
-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.
+The modern convention for OO modules is to use C<new> as the
+constructor, but you are free to use the name if that works best for
+your class.
+
+The C<{}> code creates an empty anonymous hash reference. The C<bless>
+function takes that reference and associates it with the class in
+C<$class>. In the simplest case, the C<$class> variable will end up
+containing the string "Critter".
+
+We can also call bless on a named variable:
+
+ sub new {
+ my $class = shift;
+
+ my $self = {};
+ bless $self, $class;
+
+ return $self;
+ }
+
+Once we've blessed C<$self> we can start calling methods on it. This is
+useful if you want to break out object initialization to its own
+method:
+
+ sub new {
+ my $class = shift;
+
+ my $self = {};
+ bless $self, $class;
+
+ $self->_initialize();
+
+ return $self;
+ }
+
+Since the object is also a hash reference, you can treat it as one,
+using it store data associated with the object. Typically, code inside
+the class can treat the hash as reference, while code outside the class
+should always treat the object as opaque. This is called
+B<encapsulation>. Encapsulation means that the user of an object does
+not have to know how it is implemented. The user simply calls
+documented methods on the object.
=head2 A Class is Simply a Package
+X<class> X<package> X<@ISA> X<inheritance>
+
+Perl does not provide any special syntax for class definitions. A
+package is simply a namespace containing variables and subroutines. The
+only difference is that in a class, the subroutines expect an object or
+class as the first argument.
-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 (depth first) for missing
-methods in the order that they occur in @ISA. The classes accessible
-through @ISA are known as base classes of the current class.
-
-If a missing method is found in one of the base classes, 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 a method isn't found, but an AUTOLOAD routine is found, then
-that is called on behalf of the missing method.
-
-If neither a method nor an AUTOLOAD routine is found in @ISA, then one
-last try is made for the method (or an AUTOLOAD routine) in a class
-called UNIVERSAL. (Several commonly used methods are automatically
-supplied in the UNIVERSAL class; see L<"Default UNIVERSAL methods"> for
-more details.) If that doesn't work, Perl finally gives up and
-complains.
-
-Perl classes do only method inheritance. 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.
+Each package contains a special array reference called C<@ISA>. The
+C<@ISA> array contains a list of that class's parent classes, if any.
+This array is examined when Perl does method resolution, which we will
+cover later.
+
+It is possible to manually set C<@ISA>, and you may see this in older
+Perl code. For new code, we recommend that you use the L<parent> pragma
+to declare your parents. This pragma will take care of setting C<@ISA>.
+It will also load the parent classes and make sure that the package
+doesn't inherit from itself.
+
+All classes inherit from the L<UNIVERSAL> class implicitly. The
+L<UNIVERSAL> class is implemented by the Perl core, and provides
+several default methods, such as C<isa()>, C<can()>, and C<VERSION()>.
+X<UNIVERSAL> X<base class> X<class, base>
+
+Perl I<only> provides method inheritance as a built-in feature.
+Attribute inheritance is left up the class to implement. See the
+L</Attributes> section for details.
=head2 A Method is Simply a Subroutine
+X<method>
+
+Perl does not provide any special syntax for defining a method. A
+method is simply a regular subroutine, and is declared with C<sub>.
+What makes a method special is that it expects to receive either an
+object or a class name as its first argument.
+
+Perl I<does> provide special syntax for method invocation, the C<< ->
+>> operator. We will cover this in more detail later.
+
+Most methods you write will expect to operate on objects:
-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 or package it is being invoked on. There are just two
-types of methods, which we'll call class and instance.
-(Sometimes you'll hear these called static and virtual, in honor of
-the two C++ method types they most closely resemble.)
-
-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 typically class
-methods. 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";
- }
- }
+ sub save {
+ my $self = shift;
+
+ open my $fh, '>', $self->path()
+ or die $!;
+ print {$fh} $self->data()
+ or die $!;
+ close $fh
+ or die $!;
+ }
=head2 Method Invocation
+X<invocation> X<method> X<arrow> X<< -> >>
-There are two ways to invoke a method, one of which you're already
-familiar with, and the other of which will look familiar. Perl 4
-already had an "indirect object" syntax that you use when you say
+Calling a method on an object is written as C<< $object->method >>. The
+left hand side of the method invocation (or arrow) operator is the
+object (or class name), and the right hand side is the method name.
- print STDERR "help!!!\n";
+ my $pod = File->new( 'perlobj.pod', $data );
+ $pod->save();
-This same syntax can be used to call either class or instance methods.
-We'll use the two methods defined above, the class method to lookup
-an object reference and the instance method to print out its attributes.
+The C<< -> >> operator is also used when dereferencing a reference.
+It's the same operator, but it has two different uses.
- $fred = find Critter "Fred";
- display $fred 'Height', 'Weight';
+When you call a method, the thing on the left side of the arrow is
+passed as the first argument to the method. That means when we call C<<
+Critter->new() >>, the C<new()> method receives the string C<"Critter">
+as its first argument. When we call C<< $fred->speak() >>, the C<$fred>
+object is passed as the first argument to C<speak()>
-These could be combined into one statement by using a BLOCK in the
-indirect object slot:
+Perl knows what package the method is in by looking at the left side of
+the arrow. If the left hand side is a package name, it looks for the
+method in the package. If the left hand side is an object, then Perl
+can tell what class that object has been blessed into.
- display {find Critter "Fred"} 'Height', 'Weight';
+If the left hand side is neither a package name nor an object, then the
+method call will cause an error, but see the section on L</Method Call
+Variations> for more nuances.
-For C++ fans, there's also a syntax using -E<gt> notation that does exactly
-the same thing. The parentheses are required if there are any arguments.
+=head2 Inheritance
+X<inheritance>
- $fred = Critter->find("Fred");
- $fred->display('Height', 'Weight');
+We already talked about the special C<@ISA> array and the L<parent>
+pragma.
-or in one statement,
+When a class inherits from another class, any methods defined in the
+parent class are available in the child class. If you attempt to call a
+method on an object that isn't defined in its own class, Perl will also
+look for that method in any parent classes it may have.
- Critter->find("Fred")->display('Height', 'Weight');
+ package File::MP3;
+ use parent 'File'; # sets @File::MP3::ISA = ('File');
-There are times when one syntax is more readable, and times when the
-other syntax is more readable. The indirect object syntax is less
-cluttered, but it has the same ambiguity as ordinary list operators.
-Indirect object method calls are parsed using the same rule as list
-operators: "If it looks like a function, it is a function". (Presuming
-for the moment that you think two words in a row can look like a
-function name. C++ programmers seem to think so with some regularity,
-especially when the first word is "new".) Thus, the parentheses of
+ my $mp3 = File::MP3->new( 'Andvari.mp3', $data );
+ $mp3->save();
- new Critter ('Barney', 1.5, 70)
+Since we didn't define a C<save()> method in the C<File::MP3> class,
+Perl will look at the C<File::MP3> class's parent classes to find the
+C<save()> method. If Perl could not find a C<save()> method anywhere in
+the inheritance hierarchy, it would die.
-are assumed to surround ALL the arguments of the method call, regardless
-of what comes after. Saying
+In this case, it finds it in the C<File> class. Note that the object
+passed to C<save()> in this case is still a C<File::MP3> object, even
+though the method is found in the C<File> class.
- new Critter ('Bam' x 2), 1.4, 45
+We can override a parent's method in a child class. When we do so, we
+can still call the parent class's method with the C<SUPER>
+pseudo-class.
-would be equivalent to
+ sub save {
+ my $self = shift;
- Critter->new('Bam' x 2), 1.4, 45
+ say 'Prepare to rock';
+ $self->SUPER::save();
+ }
-which is unlikely to do what you want.
+The C<SUPER> modifier can I<only> be used for method calls. You can't
+use it for regular subroutine calls:
-There are times when you wish to specify which class's method to use.
-In this case, you can call your method as an ordinary subroutine
-call, being sure to pass the requisite first argument explicitly:
+ # XXX - This will not work!
+ SUPER::save($thing);
+ # This won't work either!
+ SUPER->save($thing);
- $fred = MyCritter::find("Critter", "Fred");
- MyCritter::display($fred, 'Height', 'Weight');
+=head3 How SUPER is Resolved
+X<SUPER>
-Note however, that this does not do any inheritance. If you wish
-merely to specify that Perl should I<START> looking for a method in a
-particular package, use an ordinary method call, but qualify the method
-name with the package like this:
+The C<SUPER> pseudo-class is resolved from the package where the call
+is made. It is I<not> resolved based on the object's class. This is
+important, because it lets an inheritance hierarchy several levels deep
+all call their parent methods.
- $fred = Critter->MyCritter::find("Fred");
- $fred->MyCritter::display('Height', 'Weight');
+ package A;
-If you're trying to control where the method search begins I<and> you're
-executing in the class itself, then you may use the SUPER pseudo class,
-which says to start looking in your base class's @ISA list without having
-to name it explicitly:
+ sub new {
+ return bless {}, shift;
+ }
- $self->SUPER::display('Height', 'Weight');
+ sub speak {
+ my $self = shift;
-Please note that the C<SUPER::> construct is meaningful I<only> within the
-class.
+ $self->SUPER::speak();
-Sometimes you want to call a method when you don't know the method name
-ahead of time. You can use the arrow form, replacing the method name
-with a simple scalar variable containing the method name:
+ say 'A';
+ }
- $method = $fast ? "findfirst" : "findbest";
- $fred->$method(@args);
+ package B;
-=head2 Default UNIVERSAL methods
+ use parent 'A';
-The C<UNIVERSAL> package automatically contains the following methods that
-are inherited by all other classes:
+ sub speak {
+ my $self = shift;
-=over 4
+ $self->SUPER::speak();
+
+ say 'B';
+ }
+
+ package C;
+
+ use parent 'B';
+
+ sub speak {
+ my $self = shift;
+
+ $self->SUPER::speak();
+
+ say 'C';
+ }
+
+ my $c = C->new();
+ $c->speak();
+
+In this example, we will get the following outupt:
+
+ A
+ B
+ C
+
+This demonstrates how C<SUPER> is resolved. Even though the object is
+blessed into the C<C> class, the C<speak()> method in the C<B> class
+can still call C<SUPER::speak()>.
+
+There are cases where this package-based resolution can be a problem.
+If you copy a subroutine from one package to another, C<SUPER>
+resolution will be done based on the original package.
+
+=head3 Multiple Inheritance
+X<multiple inheritance>
+
+Multiple inheritance often indicates a design problem, but Perl always
+give you enough rope to hang yourself with.
+
+To declare multiple parents, you simply need to pass multiple class
+names to C<use parent>:
+
+ package MultiChild;
+
+ use parent 'Parent1', 'Parent2';
+
+=head3 Method Resolution Order
+X<method resolution order> X<mro>
+
+Method resolution order only matters in the case of multiple
+inheritance. In the case of single inheritance, Perl simply looks up
+the inheritance chain to find a method:
+
+ Grandparent
+ |
+ Parent
+ |
+ Child
+
+If we call a method on a C<Child> object and that method is not defined
+in the C<Child> class, Perl will look for that method. in the C<Parent>
+class and then the C<Grandparent> class.
+
+If Perl cannot find the method in any of these classes, it will die
+with an error message.
+
+When a class has multiple parents, the method lookup order becomes more
+complicated.
+
+By default, Perl does a depth-first left-to-right search for a method.
+That means it starts with the first parent in the C<@ISA> array, and
+then searches all of its parents and so on. If it fails to find the
+method, it then goes to the next parent in the original class's C<@ISA>
+array and searches from there.
+
+ PaternalGrandparent MaternalGrandparent
+ \ /
+ Father Mother
+ \ /
+ Child
+
+So given the diagram above, Perl will search C<Child>, C<Father>,
+C<PaternalGrandparent>, C<Mother>, and finally C<MaternalGrandparent>
+
+It is possible to ask for a different method resolution order with the
+L<mro> pragma.
+
+ package Child;
+
+ use mro 'c3';
+ use parent 'Father', 'Mother';
+
+This pragma lets you switch to the "C3" resolution order. In simple
+terms, this is a breadth-first order, so Perl will search C<Child>,
+C<Father>, C<Mother>, C<PaternalGrandparent>, and finally
+C<MaternalGrandparent>.
+
+The C3 order also lets you call methods in sibling classes with the
+C<next> pseudo-class. See the L<mro> documentation for more details on
+this feature.
+
+=head3 Method Resolution Caching
+
+When Perl searches for a method, it caches the lookup so that future
+calls to the method do not need to search for it again. Changing a
+class's parent class or adding subroutines to a class will invalidate
+the cache for that class.
+
+The L<mro> pragma provides some functions for manipulating the method
+cache directly.
+
+=head2 Writing Constructors
+X<constructor>
+
+As we mentioned earlier, Perl provides no special constructor syntax.
+This means that a class must implement its own constructor. A
+constructor is simply a class method that returns a new object.
+
+The constructor can also accept additional parameters that define the
+object. Let's write a real constructor for the C<File> class we used
+earlier:
+
+ package File;
+
+ sub new {
+ my $class = shift;
+ my ( $path, $data ) = @_;
+
+ my $self = bless {
+ path => $path,
+ data => $data,
+ }, $class;
+
+ return $self;
+ }
+
+As you can see, we've stored the path and file data in the object
+itself. Remember, under the hood, this object is still just a hash
+reference. Later, we'll write accessors to manipulate this data.
+
+For our File::MP3 class, we can check to make sure that the path we're
+given ends with ".mp3":
+
+ package File::MP3;
+
+ sub new {
+ my $class = shift;
+ my ( $path, $data ) = @_;
+
+ die "You cannot create a File::MP3 without an mp3 extension\n"
+ unless $path =~ /\.mp3\z/;
+
+ return $class->SUPER::new(@_);
+ }
+
+This constructor lets its parent class do the actual object
+construction.
+
+=head2 Writing Accessors
+X<accessor>
+
+As with constructors, Perl provides no special accessor declaration
+syntax, so classes must write them by hand. There are two common types
+of accessors, read-only and read-write.
+
+A simple read-only accessor simply gets the value of a single
+attribute:
+
+ sub path {
+ my $self = shift;
+
+ return $self->{path};
+ }
+
+A read-write accessor will allow the caller to set the value as well as
+get it:
+
+ sub path {
+ my $self = shift;
+
+ if (@_) {
+ $self->{path} = shift;
+ }
+
+ return $self->{path};
+ }
+
+=head2 An Aside About Smarter and Safer Code
+
+Our constructor and accessors are not very smart. They don't check that
+a C<$path> is defined, nor do they check that a C<$path> is a valid
+filesystem path.
+
+Doing these checks by hand can quickly become tedious. Writing a bunch
+of accessors by hand is also incredibly tedioud. There are a lot of
+modules on CPAN that can help you write safer and more concise code,
+including the modules we recommend in L<perlootut>.
+
+=head2 Method Call Variations
+X<method>
+
+Perl supports several other ways to call methods besides the typical
+C<< $object->method() >> pattern we've seen so far.
+
+=head3 Method Names as Strings
+
+Perl lets you use a scalar variable containing a string as a method
+name:
+
+ my $file = File->new( $path, $data );
+
+ my $method = 'save';
+ $file->$method();
-=item isa ( CLASS )
+This works exactly like calling C<< $file->save() >>. This can be very
+useful for writing dynamic code. For example, it allows you to pass a
+method name to be called as a parameter to another method.
-C<isa> returns I<true> if its object is blessed into a sub-class of C<CLASS>
+=head3 Class Names as Strings
-C<isa> is also exportable and can be called as a sub with two arguments. This
-allows the ability to check what a reference points to. Example
+Perl also lets you use a scalar containing a string as a class name:
- use UNIVERSAL qw(isa);
+ my $class = 'File';
- if(isa($ref, 'ARRAY')) {
- ...
- }
+ my $file = $class->new( $path, $data );
-=item can ( METHOD )
+Again, this allows for very dynamic code.
-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
-I<undef> is returned.
+=head3 Subroutine References as Methods
-=item VERSION ( [ VERSION ] )
+You can also call subroutine reference as a method:
-C<VERSION> returns the VERSION number of the class (package). If
-an argument is given then it will check that the current version is not
-less that the given argument. This method is normally called as a class
-method. This method is also called when the C<VERSION> form of C<use> is
-used.
+ my $sub = sub {
+ my $self = shift;
- use A 1.2 qw(some imported subs);
-
- A->VERSION( 1.2 );
+ $self->save();
+ };
-=item class ()
+ $file->$sub();
-C<class> returns the class name of its object.
+This is exactly equivalent to writing C<< $sub->($file) >>. You may see
+this idiom in the wild combined with a call to C<can>:
-=item is_instance ()
+ if ( my $meth = $object->can('foo') ) {
+ $object->$meth();
+ }
-C<is_instance> returns true if its object is an instance of some
-class, false if its object is the class (package) itself. Example
+=head2 Invoking Class Methods
+X<invocation>
- A->is_instance(); # False
-
- $var = 'A';
- $var->is_instance(); # False
-
- $ref = bless [], 'A';
- $ref->is_instance(); # True
+Because Perl allows you to use barewords for package names and
+subroutine names, it can sometimes guess wrong about what you intend a
+bareword to be. The construct C<< Class->new() >> can be interpreted as
+C<< Class()->new() >>. In English, that reads as "call a subroutine
+named Class(), then call new() as a method on the return value".
+
+You can force Perl to interpret this as a class method call in two
+ways. First, you can append a C<::> to the class name:
+
+ Class::->new()
+
+Perl will always interpret this as a method call. You can also quote
+the class name:
+
+ 'Class'->new()
+
+Of course, if the class name is in a scalar Perl will do the right
+thing as well:
+
+ my $class = 'Class';
+ $class->new();
+
+=head3 Indirect Object Syntax
+X<indirect object>
+
+B<Outside of the file handle case, use of this syntax is discouraged,
+as it can confuse the Perl interpreter. See below for more details.>
+
+Perl suports another method invocation syntax called "indirect object"
+notation.
+
+This notation is quite common when used with file handles:
+
+ print $fh $data;
+
+This is really like calling C<< $fh->print($data) >>. This syntax is
+called "indirect" because the method comes before the object it is
+being invoked on.
+
+This syntax can be used with any class or object method:
+
+ my $file = new File $path, $data;
+ save $file;
+
+We recommend that you avoid this syntax, for several reasons.
+
+First, it can be confusing to read. In the above example, it's not
+clear if C<save> is a method or simply a subroutine that expects a file
+object as its first argument.
+
+When used with class methods, the problem is even worse. Because Perl
+allows subroutine names to be written as barewords, Perl has to guess
+whether the bareword after the method is a class name or subroutine
+name. In other words, Perl can resolve the syntax as either C<<
+File->new( $path, $data ) >> B<or> C<< new( File( $path, $data ) ) >>.
+
+To parse this code, Perl uses a heuristic based on what package names
+it has seen, what subroutines exist in the current package, and what
+barewords it has seen previously. Needless to say, heuristics can
+produce very surprising results!
+
+Older documentation (and some CPAN modules) encouraged this syntax,
+particularly for constructors, so you may still find it in the wild.
+However, we encourage you to avoid using it in new code.
+
+=head2 C<bless>, C<blessed>, and C<ref>
+
+As we saw earlier, an object is simply a reference that has been
+blessed into a class with the C<bless> function. The C<bless> function
+has can take either one or two arguments:
+
+ my $object = bless {}, $class;
+ my $object = bless {};
+
+In the first form, the anonymous hash reference is being blessed into
+the class in C<$class>. In the second form, the reference is blessed
+into the current package.
+
+The second form is discouraged, because it breaks the ability of a
+subclass to reuse the parent's constructor, but you may still run
+across it in existing code.
+
+If you want to know whether a particular scalar is an object, you can
+use the C<blessed> function exported by L<Scalar::Util>, which is
+shipped with the Perl core.
+
+ use Scalar::Util 'blessed';
+
+ if ( blessed($thing) ) { ... }
+
+If the C<$thing> has been blessed, then this function returns the name
+of the package the object has been blessed into. Note that the example
+above will return false if C<$thing> has been blessed into a class
+named "0". If the C<$thing> is not a blessed reference, the C<blessed>
+function returns false.
+
+Similarly, Perl's built in C<ref> function treats a blessed reference
+specially. If you call C<ref($thing)> and C<$thing> is an object, it
+will return the name of the class that the object has been blessed
+into.
+
+If you simply want to check that a variable contains an object, we
+recommend that you use C<blessed>, since C<ref> returns true values for
+all references, not just objects.
+
+=head2 The UNIVERSAL Class
+X<UNIVERSAL>
+
+All classes automatically inherit from the L<UNIVERSAL> class, which is
+built in to the Perl core. This class provides a number of methods, all
+of which can be called on either a class or an object. You can also
+choose to override some of these methods in your class. If you do so,
+we recommend that you follow the built in semantics described below.
+
+=over 4
+
+=item isa($class)
+X<isa>
+
+The C<isa> method returns I<true> if the object is a member of the
+class in C<$class>, or a member of a subclass of C<$class>.
+
+=item DOES($role)
+X<DOES>
+
+The C<DOES> method returns I<true> if its object claims to perform the
+role C<$role>. By default, this is equivalent to C<isa>. This method is
+provided for use by object system extensions that implement roles, like
+C<Moose> and C<Role::Tiny>.
+
+=item can($method)
+X<can>
+
+The C<can> method checks to see if its object has a method called
+C<$method>. If it does, then a reference to the subroutine is returned.
+If it does not then C<undef> is returned.
+
+This will return true if the object's class or any of it's parent
+classes contain C<$method>.
+
+If your class responds to method calls via C<AUTOLOAD>, you may want to
+overload C<can> to respond true for methods which C<AUTOLOAD> handles.
+
+=item VERSION($need)
+X<VERSION>
+
+The C<VERSION> method returns the version number of the class
+(package).
+
+If the C<$need> argument is given then it will check that the current
+version (as defined by the $VERSION variable in the package) is greater
+than or equal to C<$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);
+
+We recommend that you use this method to access another package's
+version, rather than looking directly at C<$Package::VERSION>. The
+package you are looking at could have overridden the C<VERSION> method.
+
+We also recommend using this method to check whether a module has a
+sufficient version. The internal implementation uses the L<version>
+module to make sure that different types of version numbers are
+compared correctly.
=back
-B<NOTE:> C<can> directly uses Perl's internal code for method lookup, and
-C<isa> uses a very similar method and cache-ing strategy. This may cause
-strange effects if the Perl code dynamically changes @ISA in any package.
-
-You may add other methods to the UNIVERSAL class via Perl or XS code.
-
-=head2 Destructors
-
-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 doesn't do nested destruction for you. If your constructor
-re-blessed a reference from one of your base classes, your DESTROY may
-need to call DESTROY for any base classes that need it. But this applies
-to only re-blessed objects--an object reference that is merely
-I<CONTAINED> in the current object will be freed and destroyed
-automatically when the current object is freed.
-
-=head2 WARNING
-
-An 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. The left side of -E<gt> is not so
-limited, because it's an infix operator, not a postfix operator.
-
-That means that below, A and B are equivalent to each other, and C and D
-are equivalent, but AB and CD are different:
-
- A: method $obref->{"fieldname"}
- B: (method $obref)->{"fieldname"}
- C: $obref->{"fieldname"}->method()
- D: method {$obref->{"fieldname"}}
-
-=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
-
-For most purposes, Perl uses a fast and simple reference-based
-garbage collection system. For this reason, 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 $self = shift;
- my $class = ref($self) || $self;
- 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
-multi-threadable 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</tmp/test>, the following output is produced:
-
- starting program at /tmp/test line 18.
- CREATING SCALAR(0x8e5b8) at /tmp/test line 7.
- CREATING SCALAR(0x8e57c) at /tmp/test line 7.
- leaving block at /tmp/test line 23.
- DESTROYING Subtle=SCALAR(0x8e5b8) at /tmp/test line 13.
- just exited block at /tmp/test line 26.
- time to die... at /tmp/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 and in fact
-are destructed in a separate pass before ordinary refs just to try 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.
-
-A more complete garbage collection strategy will be implemented
-at a future date.
+=head2 AUTOLOAD
+X<AUTOLOAD>
+
+If you call a method that doesn't exist in a class, Perl will throw an
+error. However, if that class or any of its parent classes defined an
+C<AUTOLOAD> method, that method will be called instead.
+
+This is called as a regular method, and the caller will not know the
+difference. Whatever value your C<AUTOLOAD> method returns is given to
+the caller.
+
+The fully qualified method name that was called is available in the
+C<$AUTOLOAD> package global for your class. Since this is a global, if
+you want to refer to do it without a package name prefix, you need to
+declare it.
+
+ # XXX - this is a terrible way to implement accessors, but it makes for a
+ # simple example.
+ our $AUTOLOAD;
+ sub AUTOLOAD {
+ my $self = shift;
+
+ ( my $called = $AUTOLOAD ) =~ s/.*:://;
+
+ return if $called eq 'DESTROY';
+
+ die "No such attribute: $called"
+ unless exists $self->{$called};
+
+ return $self->{$called};
+ }
+
+Without the C<our $AUTOLOAD> declaration, this code will not compile
+under the L<strict> pragma.
+
+As the comment says, this is not a good way to implement accessors.
+It's slow and too clever by far. See L<perlootut> for recommendations
+on OO coding in Perl.
+
+If your class does have an C<AUTOLOAD> method, we strongly recommend
+that you override C<can> in your class as well. Your overridden C<can>
+method should return a subroutine reference for any method that your
+C<AUTOLOAD> responds to.
+
+=head2 Destructors
+X<destructor> X<DESTROY>
+
+When the last refernce to an object goes away, the object is destroyed.
+If you only have one reference to an object stored in a lexical scalar,
+the object is destroyed when that lexical goes out of scope. If you
+store the object in a global, that object may not go out of scope until
+the program exits.
+
+If you want to do something when the object is destroyed, you can
+defined a C<DESTROY> method in your class. This method will always be
+called by Perl at the appropriate time.
+
+This is called just like any other method, with the object as the first
+argument. It does not receive any additional arguments.
+
+Because C<DESTROY> methods can be called at any time, you should
+localize any global variables you might update in your C<DESTROY>. In
+particular, if you use C<eval {}> you should localize C<$@>, and if you
+use C<system> or backticks, you should localize C<$?>.
+
+As we saw in the C<AUTOLOAD> example, if you define an C<AUTOLOAD>
+method, this will be called for the C<DESTROY> method, so you need to
+handle this case in your C<AUTOLOAD>.
+
+The order in which objects are destroyed when the program exits is
+unpredictable. This means that any objects contained by your object may
+already have been destroyed. This means you should check that they are
+defined before calling methods on them:
+
+ sub DESTROY {
+ my $self = shift;
+
+ $self->{handle}->close() if $self->{handle};
+ }
+
+You can use the C<${^GLOBAL_PHASE}> variable to detect if you are
+currently in the program exit phase:
+
+ sub DESTROY {
+ my $self = shift;
+
+ return if ${^GLOBAL_PHASE} eq 'DESTRUCT';
+
+ $self->{handle}->close();
+ }
+
+Note that this variable was added in Perl 5.14.0. If you want to detect
+program exit on older versions of Perl, you can use the
+C<Devel::GlobalDestruction> module on CPAN.
+
+=head2 Non-Hashref Objects
+
+All the examples so far have shown objects based on a blessed hash
+reference. However, it's possible to bless any type of reference,
+including scalar refs, glob refs, and code refs. You may see this sort
+of thing when looking at code in the wild.
+
+Here's an example of a module as a blessed scalar:
+
+ package Time;
+
+ use strict;
+ use warnings;
+
+ sub new {
+ my $class = shift;
+
+ my $time = time;
+ return bless \$time, $class;
+ }
+
+ sub epoch {
+ my $self = shift;
+ return ${ $self };
+ }
+
+ my $time = Time->new();
+ print $time->epoch();
+
+=head2 Inside-Out objects
+
+In the past, the Perl community experimented with a technique called
+"inside-out objects". An inside-out object stores its data in a lexical
+class variable, indexed on a unique property of the object, such as its
+memory address, rather than in the object itself.
+
+This technique was popular for a while (and was recommended in Damian
+Conway's I<Perl Best Practices>), but never achieved wide adoption due
+to additional complexity. The L<Object::InsideOut> module on CPAN
+provides a comprehensive implementation of this technique, and you may
+see it or other inside-out modules in the wild.
+
+Here is a simple example of the technique, using the
+L<Hash::Util::FieldHash> core module. This module was added to the core
+to support inside-out object implementations.
+
+ package Time::InsideOut;
+
+ use strict;
+ use warnings;
+
+ use Hash::Util::FieldHash 'fieldhash';
+
+ fieldhash my %TIME;
+
+ sub new {
+ my $class = shift;
+ my $self = bless \( my $empty ), $class;
+ $TIME{$self} = time;
+
+ $self;
+ }
+
+ sub epoch {
+ my $self = shift;
+
+ $TIME{$self};
+ }
+
+ my $time = Time::InsideOut->new;
+ print $time->epoch;
+
+=head2 Pseudo-hashes
+
+The pseudo-hash feature was an experimental feature introduced in
+earlier versions of Perl and removed in 5.10.0. A pseudo-hash is an
+array reference which can be accessed using named keys like a hash. You
+may run in to some code in the wild which uses it. See the L<fields>
+pragma for more information.
=head1 SEE ALSO
-You should also check out L<perlbot> for other object tricks, traps, and tips,
-as well as L<perlmod> for some style guides on constructing both modules
-and classes.
+A kinder, gentler tutorial on object-oriented programming in Perl can
+be found in L<perlootut>. You should also check out L<perlmodlib> for
+some style guides on constructing both modules and classes.
+
https://perl5.git.perl.org / perl5.git / blobdiff