From 2898ff73ee9d2c2fdd5b62a95fd4d2077d27bd9f Mon Sep 17 00:00:00 2001 From: Dave Rolsky Date: Tue, 14 Feb 2012 11:05:51 -0600 Subject: Small updates for perlobj.pod Fixed some typos. Improved some wording. Clarified some points. --- pod/perlobj.pod | 76 +++++++++++++++++++++++++++++++++------------------------ 1 file changed, 44 insertions(+), 32 deletions(-) diff --git a/pod/perlobj.pod b/pod/perlobj.pod index f1cd681f34..015b1c966c 100644 --- a/pod/perlobj.pod +++ b/pod/perlobj.pod @@ -377,7 +377,7 @@ resolution will be done based on the original package. X Multiple inheritance often indicates a design problem, but Perl always -give you enough rope to hang yourself with if you really need to. +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: @@ -425,7 +425,7 @@ class's C<@ISA> array and searches from there. So given the diagram above, Perl will search C, C, C, C, C, and -finally C This is a problem because now we're +finally C. This may be a problem because now we're looking in C I we've checked all its derived classes (i.e. before we tried C and C). @@ -439,8 +439,8 @@ L pragma. use parent 'Father', 'Mother'; This pragma lets you switch to the "C3" resolution order. In simple -terms, "C3" order ensures that parent classes are never searched before -child classes, so Perl will now search: C, C, +terms, "C3" order ensures that shared parent classes are never searched +before child classes, so Perl will now search: C, C, C, C C, and finally C. Note however that this is not "breadth-first" searching: All the C ancestors (except the @@ -534,15 +534,15 @@ 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 the inner details of the -object. +use the accessors rather than having to know how a parent class is +implemented internally. =head3 Writing Accessors X 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. +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: @@ -580,8 +580,8 @@ including the modules we recommend in L. =head2 Method Call Variations X -Perl supports several other ways to call methods besides the typical -C<< $object->method() >> pattern we've seen so far. +Perl supports several other ways to call methods besides the C<< +$object->method() >> usage we've seen so far. =head3 Method Names as Strings @@ -634,6 +634,7 @@ 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 a subroutine reference. @@ -655,14 +656,15 @@ C, and C filehandles. X 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. For example, the construct C<< Class->new() >> can be +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". If -there is a subroutine named C in the current namespace, Perl -will always interpret Cnew()> as the second alterative: a call -to C on the object returned by a call to C +named Class(), then call new() as a method on the return value of +Class()". If there is a subroutine named C in the current +namespace, Perl will always interpret C<< Class->new() >> as the second +alternative: a call to C on the object returned by a call to +C 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 @@ -700,8 +702,8 @@ This syntax can be used with any class or object method: 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 is a method or simply a subroutine that expects a file -object as its first argument. +clear if C is a method provided by the C 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 @@ -746,13 +748,17 @@ is shipped with the Perl core. use Scalar::Util 'blessed'; - if ( blessed($thing) ) { ... } + 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. Note that the example -above will return false if C<$thing> has been blessed into a class -named "0". If C<$thing> doesn't contain a reference to a blessed -object, the C function returns false (specifically: C). +of the package the object has been blessed into. If C<$thing> doesn't +contain a reference to a blessed object, the C function +returns C. + +Note that C 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 function treats a reference to a blessed object specially. If you call C and C<$thing> @@ -780,6 +786,8 @@ X The C method returns I 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 @@ -788,7 +796,8 @@ role C<$role>. By default, this is equivalent to C. This method is provided for use by object system extensions that implement roles, like C and C. -You can also override C directly in your own classes. +You can also override C directly in your own classes. If you +override this method, it should never throw an exception. =item can($method) X @@ -802,6 +811,8 @@ If your class responds to method calls via C, you may want to overload C to return a subroutine reference for methods which your C method handles. +If you override this method, it should never throw an exception. + =item VERSION($need) X @@ -832,12 +843,12 @@ compared correctly. X 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 method, that method will be called instead. +error. However, if that class or any of its parent classes defines an +C method, that C method is called instead. -This is called as a regular method, and the caller will not know the -difference. Whatever value your C method returns is given to -the caller. +C is called as a regular method, and the caller will not know +the difference. Whatever value your C 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 @@ -866,9 +877,10 @@ you want to refer to do it without a package name prefix under C declaration, this code will not compile under the L pragma. -As the comment says, this is not a good way to implement accessors. -It's slow and too clever by far. See L for recommendations -on OO coding in Perl. +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 for +recommendations on OO coding in Perl. If your class does have an C method, we strongly recommend that you override C in your class as well. Your overridden C -- cgit v1.2.1