Change 24909: [PATCH pod/perlfunc.pod pod/perlobj.pod pod/perltooc.pod] Recommend Against UNIVERSAL:: Methods as Functions, take 2

[Rafael Garcia-Suarez]

Change 24909 by rgs@bloom on 2005/06/20 11:45:02

Subject: [PATCH pod/perlfunc.pod pod/perlobj.pod pod/perltooc.pod] Recommend Against UNIVERSAL:: Methods as Functions, take 2
From: chromatic <chro...@wgz.org>
Date: Sat, 18 Jun 2005 12:15:41 -0700
Message-Id: <1119122141.21521.9.camel@localhost>

Affected files ...

... //depot/perl/pod/perlfunc.pod#475 edit
... //depot/perl/pod/perlobj.pod#29 edit
... //depot/perl/pod/perltooc.pod#7 edit

Differences ...

==== //depot/perl/pod/perlfunc.pod#475 (text) ====
Index: perl/pod/perlfunc.pod
--- perl/pod/perlfunc.pod#474~24849~ Wed Jun 15 06:55:50 2005
+++ perl/pod/perlfunc.pod Mon Jun 20 04:45:02 2005
@@ -1162,9 +1162,11 @@
is sometimes preferable to matching particular string values of $@ using
regular expressions. Here's an example:

+ use Scalar::Util 'blessed';
+
eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) };
if ($@) {
- if (ref($@) && UNIVERSAL::isa($@,"Some::Module::Exception")) {
+ if (blessed($@) && $@->isa("Some::Module::Exception")) {
# handle Some::Module::Exception
}
else {
@@ -4199,9 +4201,6 @@
}
unless (ref($r)) {
print "r is not a reference at all.\n";
- }
- if (UNIVERSAL::isa($r, "HASH")) { # for subclassing
- print "r is a reference to something that isa hash.\n";
}

See also L<perlref>.

==== //depot/perl/pod/perlobj.pod#29 (text) ====
Index: perl/pod/perlobj.pod
--- perl/pod/perlobj.pod#28~22654~ Mon Apr 5 08:24:49 2004
+++ perl/pod/perlobj.pod Mon Jun 20 04:45:02 2005
@@ -373,18 +373,19 @@

C<isa> returns I<true> if its object is blessed into a subclass of C<CLASS>

-You can also call C<UNIVERSAL::isa> as a subroutine with two arguments.
-The first does not need to be an object or even a reference. This
-allows you to check what a reference points to, or whether
-something is a reference of a given type. Example
+You can also call C<UNIVERSAL::isa> as a subroutine with two arguments. Of
+course, this will do the wrong thing if someone has overridden C<isa> in a
+class, so don't do it.

- if(UNIVERSAL::isa($ref, 'ARRAY')) {
- #...
- }
+If you need to determine whether you've received a valid invocant, use the
+C<blessed> function from L<Scalar::Util>:

-To determine if a reference is a blessed object, you can write
+ if (blessed($ref) && $ref->isa( 'Some::Class')) {
+ # ...
+ }

- print "It's an object\n" if UNIVERSAL::isa($val, 'UNIVERSAL');
+C<blessed> returns the name of the package the argument has been
+blessed into, or C<undef>.

=item can(METHOD)

@@ -392,21 +393,9 @@
if it does then a reference to the sub is returned, if it does not then
I<undef> is returned.

-C<UNIVERSAL::can> can also be called as a subroutine with two arguments.
-It'll always return I<undef> if its first argument isn't an object or a
-class name. So here's another way to check if a reference is a
-blessed object
-
- print "It's still an object\n" if UNIVERSAL::can($val, 'can');
-
-You can also use the C<blessed> function of Scalar::Util:
-
- use Scalar::Util 'blessed';
-
- my $blessing = blessed $suspected_object;
-
-C<blessed> returns the name of the package the argument has been
-blessed into, or C<undef>.
+C<UNIVERSAL::can> can also be called as a subroutine with two arguments. It'll
+always return I<undef> if its first argument isn't an object or a class name.
+The same caveats for calling C<UNIVERSAL::isa> directly apply here, too.

=item VERSION( [NEED] )

==== //depot/perl/pod/perltooc.pod#7 (text) ====
Index: perl/pod/perltooc.pod
--- perl/pod/perltooc.pod#6~23496~ Fri Nov 12 12:47:19 2004
+++ perl/pod/perltooc.pod Mon Jun 20 04:45:02 2005
@@ -1089,7 +1089,10 @@
if (my $coderef = $self->can($parent . "::CData1")) {
$self->$coderef($newvalue);
}
- }
+ }
+
+If you override C<UNIVERSAL::can> in your own classes, be sure to return the
+reference appropriately.

=head2 Locking the Door and Throwing Away the Key

End of Patch.