summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/pods/perlobj.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods/perlobj.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlobj.pod1049
1 files changed, 0 insertions, 1049 deletions
diff --git a/Master/tlpkg/tlperl/lib/pods/perlobj.pod b/Master/tlpkg/tlperl/lib/pods/perlobj.pod
deleted file mode 100644
index 015b1c966c0..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlobj.pod
+++ /dev/null
@@ -1,1049 +0,0 @@
-=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 object reference
-
-=head1 DESCRIPTION
-
-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 object-oriented (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>.
-
-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 data structure that knows to which class it
-belongs.
-
-=item 2.
-
-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 a reference to an object
-(or a package name, for class methods) as the first argument.
-
-=back
-
-Let's look at each of these principles in depth.
-
-=head2 An Object is Simply a Data Structure
-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. Objects are
-merely Perl data structures (hashes, arrays, scalars, filehandles,
-etc.) that have been explicitly associated with a particular class.
-
-That explicit association is created by the built-in C<bless> function,
-which is typically used within the I<constructor> subroutine of the
-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:
-
- package File;
-
- sub load {
- my $class = shift;
-
- return bless {}, $class;
- }
-
-The modern convention for OO modules is to always use C<new> as the
-name for the constructor, but there is no requirement to do so. Any
-subroutine that blesses a data structure into a class is a valid
-constructor in Perl.
-
-In the previous examples, the C<{}> code creates a reference to an
-empty anonymous hash. The C<bless> function then takes that reference
-and associates the hash with the class in C<$class>. In the simplest
-case, the C<$class> variable will end up containing the string "File".
-
-We can also use a variable to store a reference to the data structure
-that is being blessed as our object:
-
- sub new {
- my $class = shift;
-
- my $self = {};
- bless $self, $class;
-
- return $self;
- }
-
-Once we've blessed the hash referred to by C<$self> we can start
-calling methods on it. This is useful if you want to put object
-initialization in its own separate method:
-
- sub new {
- my $class = shift;
-
- my $self = {};
- bless $self, $class;
-
- $self->_initialize();
-
- return $self;
- }
-
-Since the object is also a hash, you can treat it as one, using it to
-store data associated with the object. Typically, code inside the class
-can treat the hash as an accessible data structure, 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.
-
-Note, however, that (unlike most other OO languages) Perl does not
-ensure or enforce encapsulation in any way. If you want objects to
-actually I<be> opaque you need to arrange for that yourself. This can
-be done in a varierty of ways, including using L<"Inside-Out objects">
-or modules from CPAN.
-
-=head3 Objects Are Blessed; Variables Are Not
-
-When we bless something, we are not blessing the variable which
-contains a reference to that thing, nor are we blessing the reference
-that the variable stores; we are blessing the thing that the variable
-refers to (sometimes known as the I<referent>). This is best
-demonstrated with this code:
-
- use Scalar::Util 'blessed';
-
- my $foo = {};
- my $bar = $foo;
-
- bless $foo, 'Class';
- print blessed( $bar ); # prints "Class"
-
- $bar = "some other value";
- print blessed( $bar ); # prints undef
-
-When we call C<bless> on a variable, we are actually blessing the
-underlying data structure that the variable refers to. We are not
-blessing the reference itself, nor the variable that contains that
-reference. That's why the second call to C<blessed( $bar )> returns
-false. At that point C<$bar> is no longer storing a reference to an
-object.
-
-You will sometimes see older books or documentation mention "blessing a
-reference" or describe an object as a "blessed reference", but this is
-incorrect. It isn't the reference that is blessed as an object; it's
-the thing the reference refers to (i.e. the referent).
-
-=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 may expect a
-reference to an object or the name of a class as the first argument.
-This is purely a matter of convention, so a class may contain both
-methods and subroutines which I<don't> operate on an object or class.
-
-Each package contains a special array 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. Much older code also uses the L<base> pragma. 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.
-
-However the parent classes are set, the package's C<@ISA> variable will
-contain a list of those parents. This is simply a list of scalars, each
-of which is a string that corresponds to a package name.
-
-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()>.
-The C<UNIVERSAL> class will I<never> appear in a package's C<@ISA>
-variable.
-
-Perl I<only> provides method inheritance as a built-in feature.
-Attribute inheritance is left up the class to implement. See the
-L</Writing Accessors> 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:
-
- 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<< -> >>
-
-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.
-
- my $pod = File->new( 'perlobj.pod', $data );
- $pod->save();
-
-The C<< -> >> syntax is also used when dereferencing a reference. It
-looks like the same operator, but these are two different operations.
-
-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>
-variable is passed as the first argument to C<speak()>.
-
-Just as with any Perl subroutine, all of the arguments passed in C<@_>
-are aliases to the original argument. This includes the object itself.
-If you assign directly to C<$_[0]> you will change the contents of the
-variable that holds the reference to the object. We recommend that you
-don't do this unless you know exactly what you're doing.
-
-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 that package. If the left hand side is an object, then Perl
-looks for the method in the package that the object has been blessed
-into.
-
-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.
-
-=head2 Inheritance
-X<inheritance>
-
-We already talked about the special C<@ISA> array and the L<parent>
-pragma.
-
-When a class inherits from another class, any methods defined in the
-parent class are available to 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.
-
- package File::MP3;
- use parent 'File'; # sets @File::MP3::ISA = ('File');
-
- my $mp3 = File::MP3->new( 'Andvari.mp3', $data );
- $mp3->save();
-
-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 cannot find a C<save()> method anywhere in
-the inheritance hierarchy, it will die.
-
-In this case, it finds a C<save()> method 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.
-
-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.
-
- sub save {
- my $self = shift;
-
- say 'Prepare to rock';
- $self->SUPER::save();
- }
-
-The C<SUPER> modifier can I<only> be used for method calls. You can't
-use it for regular subroutine calls or class methods:
-
- SUPER::save($thing); # FAIL: looks for save() sub in package SUPER
-
- SUPER->save($thing); # FAIL: looks for save() method in class
- # SUPER
-
- $thing->SUPER::save(); # Okay: looks for save() method in parent
- # classes
-
-
-=head3 How SUPER is Resolved
-X<SUPER>
-
-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 methods at different levels within a deep
-inheritance hierarchy each correctly call their respective parent
-methods.
-
- package A;
-
- sub new {
- return bless {}, shift;
- }
-
- sub speak {
- my $self = shift;
-
- $self->SUPER::speak();
-
- say 'A';
- }
-
- package B;
-
- use parent 'A';
-
- sub speak {
- my $self = shift;
-
- $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 output:
-
- 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()> and expect it to correctly look in the
-parent class of C<B> (i.e the class the method call is in), not in the
-parent class of C<C> (i.e. the class the object belongs to).
-
-There are rare 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
-gives you enough rope to hang yourself with if you ask for it.
-
-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, if necessary, in 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, grandparents, etc. 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.
-
- SharedGreatGrandParent
- / \
- PaternalGrandparent MaternalGrandparent
- \ /
- Father Mother
- \ /
- Child
-
-So given the diagram above, Perl will search C<Child>, C<Father>,
-C<PaternalGrandparent>, C<SharedGreatGrandParent>, C<Mother>, and
-finally C<MaternalGrandparent>. This may be a problem because now we're
-looking in C<SharedGreatGrandParent> I<before> we've checked all its
-derived classes (i.e. before we tried C<Mother> and
-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, "C3" order ensures that shared parent classes are never searched
-before child classes, so Perl will now search: C<Child>, C<Father>,
-C<PaternalGrandparent>, C<Mother> C<MaternalGrandparent>, and finally
-C<SharedGreatGrandParent>. Note however that this is not
-"breadth-first" searching: All the C<Father> ancestors (except the
-common ancestor) are searched before any of the C<Mother> ancestors are
-considered.
-
-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 reference to 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.
-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 Attributes
-X<attribute>
-
-An attribute is a piece of data belonging to a particular object.
-Unlike most object-oriented languages, Perl provides no special syntax
-or support for declaring and manipulating attributes.
-
-Attributes are often stored in the object itself. For example, if the
-object is an anonymous hash, we can store the attribute values in the
-hash using the attribute name as the key.
-
-While it's possible to refer directly to these hash keys outside of the
-class, it's considered a best practice to wrap all access to the
-attribute with accessor methods.
-
-This has several advantages. Accessors make it easier to change the
-implementation of an object later while still preserving the original
-API.
-
-An accessor lets you add additional code around attribute access. For
-example, you could apply a default to an attribute that wasn't set in
-the constructor, or you could validate that a new value for the
-attribute is acceptable.
-
-Finally, using accessors makes inheritance much simpler. Subclasses can
-use the accessors rather than having to know how a parent class is
-implemented internally.
-
-=head3 Writing Accessors
-X<accessor>
-
-As with constructors, Perl provides no special accessor declaration
-syntax, so classes must provide explicitly written accessor methods.
-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 tedious. 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 C<<
-$object->method() >> usage 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();
-
-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.
-
-=head3 Class Names as Strings
-
-Perl also lets you use a scalar containing a string as a class name:
-
- my $class = 'File';
-
- my $file = $class->new( $path, $data );
-
-Again, this allows for very dynamic code.
-
-=head3 Subroutine References as Methods
-
-You can also use a subroutine reference as a method:
-
- my $sub = sub {
- my $self = shift;
-
- $self->save();
- };
-
- $file->$sub();
-
-This is exactly equivalent to writing C<< $sub->($file) >>. You may see
-this idiom in the wild combined with a call to C<can>:
-
- if ( my $meth = $object->can('foo') ) {
- $object->$meth();
- }
-
-=head3 Deferencing Method Call
-
-Perl also lets you use a dereferenced scalar reference in a method
-call. That's a mouthful, so let's look at some code:
-
- $file->${ \'save' };
- $file->${ returns_scalar_ref() };
- $file->${ \( returns_scalar() ) };
- $file->${ returns_sub_ref() };
-
-This works if the dereference produces a string I<or> a subroutine
-reference.
-
-=head3 Method Calls on Filehandles
-
-Under the hood, Perl filehandles are instances of the C<IO::Handle> or
-C<IO::File> class. Once you have an open filehandle, you can call
-methods on it. Additionally, you can call methods on the C<STDIN>,
-C<STDOUT>, and C<STDERR> filehandles.
-
- open my $fh, '>', 'path/to/file';
- $fh->autoflush();
- $fh->print('content');
-
- STDOUT->autoflush();
-
-=head2 Invoking Class Methods
-X<invocation>
-
-Because Perl allows you to use barewords for package names and
-subroutine names, it sometimes interprets a bareword's meaning
-incorrectly. For example, the construct C<< Class->new() >> can be
-interpreted as either C<< 'Class'->new() >> or C<< Class()->new() >>.
-In English, that second interpretation reads as "call a subroutine
-named Class(), then call new() as a method on the return value of
-Class()". If there is a subroutine named C<Class()> in the current
-namespace, Perl will always interpret C<< Class->new() >> as the second
-alternative: a call to C<new()> on the object returned by a call to
-C<Class()>
-
-You can force Perl to use the first interpretation (i.e. as a method
-call on the class named "Class") in two ways. First, you can append a
-C<::> to the class name:
-
- Class::->new()
-
-Perl will always interpret this as a method call.
-
-Alternatively, you can 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 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 provided by the C<File> class 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, what
-barewords it has previously seen, and other input. 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.
-
-You can force Perl to interpret the bareword as a class name by
-appending "::" to it, like we saw earlier:
-
- my $file = new File:: $path, $data;
-
-=head2 C<bless>, C<blessed>, and C<ref>
-
-As we saw earlier, an object is simply a data structure that has been
-blessed into a class via the C<bless> function. The C<bless> function
-can take either one or two arguments:
-
- my $object = bless {}, $class;
- my $object = bless {};
-
-In the first form, the anonymous hash is being blessed into the class
-in C<$class>. In the second form, the anonymous hash is blessed into
-the current package.
-
-The second form is strongly 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 refers to 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 ( defined blessed($thing) ) { ... }
-
-If C<$thing> refers to an object, then this function returns the name
-of the package the object has been blessed into. If C<$thing> doesn't
-contain a reference to a blessed object, the C<blessed> function
-returns C<undef>.
-
-Note that C<blessed($thing)> will also return false if C<$thing> has
-been blessed into a class named "0". This is a possible, but quite
-pathological. Don't create a class named "0" unless you know what
-you're doing.
-
-Similarly, Perl's built-in C<ref> function treats a reference to a
-blessed object specially. If you call C<ref($thing)> and C<$thing>
-holds a reference to 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
-reference, we recommend that you use C<defined blessed($object)>, 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>.
-
-If you override this method, it should never throw an exception.
-
-=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>.
-
-You can also override C<DOES> directly in your own classes. If you
-override this method, it should never throw an exception.
-
-=item can($method)
-X<can>
-
-The C<can> method checks to see if the class or object it was called on
-has a method named C<$method>. This checks for the method in the class
-and all of its parents. If the method exists, then a reference to the
-subroutine is returned. If it does not then C<undef> is returned.
-
-If your class responds to method calls via C<AUTOLOAD>, you may want to
-overload C<can> to return a subroutine reference for methods which your
-C<AUTOLOAD> method handles.
-
-If you override this method, it should never throw an exception.
-
-=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
-
-=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 defines an
-C<AUTOLOAD> method, that C<AUTOLOAD> method is called instead.
-
-C<AUTOLOAD> is called as a regular method, and the caller will not know
-the difference. Whatever value your C<AUTOLOAD> method returns is
-returned 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 under C<strict
-'vars'>, 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;
-
- # Remove qualifier from original method name...
- my $called = $AUTOLOAD =~ s/.*:://r;
-
- # Is there an attribute of that name?
- die "No such attribute: $called"
- unless exists $self->{$called};
-
- # If so, return it...
- return $self->{$called};
- }
-
- sub DESTROY { } # see below
-
-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. However, you may see this as a way to
-provide accessors in older Perl code. 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 reference 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 scalar goes out of
-scope. If you store the object in a package 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
-define a C<DESTROY> method in your class. This method will always be
-called by Perl at the appropriate time, unless the method is empty.
-
-This is called just like any other method, with the object as the first
-argument. It does not receive any additional arguments. However, the
-C<$_[0]> variable will be read-only in the destructor, so you cannot
-assign a value to it.
-
-If your C<DESTROY> method throws an error, this error will be ignored.
-It will not be sent to C<STDERR> and it will not cause the program to
-die. However, if your destructor is running inside an C<eval {}> block,
-then the error will change the value of C<$@>.
-
-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<$?>.
-
-If you define an C<AUTOLOAD> in your class, then Perl will call your
-C<AUTOLOAD> to handle the C<DESTROY> method. You can prevent this by
-defining an empty C<DESTROY>, like we did in the autoloading example.
-You can also check the value of C<$AUTOLOAD> and return without doing
-anything when called to handle C<DESTROY>.
-
-=head3 Global Destruction
-
-The order in which objects are destroyed during the global destruction
-before the program exits is unpredictable. This means that any objects
-contained by your object may already have been destroyed. You should
-check that a contained object is defined before calling a method on it:
-
- 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 global destruction 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
-the global destruction phase on older versions of Perl, you can use the
-C<Devel::GlobalDestruction> module on CPAN.
-
-If your C<DESTROY> method issues a warning during global destruction,
-the Perl interpreter will append the string " during global
-destruction" the warning.
-
-During global destruction, Perl will always garbage collect objects
-before unblessed references. See L<perlhacktips/PERL_DESTRUCT_LEVEL>
-for more information about global destruction.
-
-=head2 Non-Hash Objects
-
-All the examples so far have shown objects based on a blessed hash.
-However, it's possible to bless any type of data structure or referent,
-including scalars, globs, and subroutines. 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 outside of
-the object's reference, indexed on a unique property of the object,
-such as its memory address, rather than in the object itself. This has
-the advantage of enforcing the encapsulation of object attributes,
-since their data is not stored 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 universal
-adoption. 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;
-
- use strict;
- use warnings;
-
- use Hash::Util::FieldHash 'fieldhash';
-
- fieldhash my %time_for;
-
- sub new {
- my $class = shift;
-
- my $self = bless \( my $object ), $class;
-
- $time_for{$self} = time;
-
- return $self;
- }
-
- sub epoch {
- my $self = shift;
-
- return $time_for{$self};
- }
-
- my $time = Time->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
-
-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.
-