X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FUNIVERSAL.pm;h=8808271ef9837032d1c129544ec3b0eaf5e1f1b2;hb=8af3c3489f0c9ca8d37ebae27991ac4f34dfdb2f;hp=92b4fcd352a812ab290ee32ed4009c79d31f33a6;hpb=ea8fae293543a7d3ec6f09254a20517959143189;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/lib/UNIVERSAL.pm b/lib/UNIVERSAL.pm
index 92b4fcd..8808271 100644
--- a/lib/UNIVERSAL.pm
+++ b/lib/UNIVERSAL.pm
@@ -1,6 +1,6 @@
 package UNIVERSAL;
 
-our $VERSION = '1.00';
+our $VERSION = '1.02';
 
 # UNIVERSAL should not contain any extra subs/methods beyond those
 # that it exists to define. The use of Exporter below is a historical
@@ -9,9 +9,15 @@ our $VERSION = '1.00';
 # Exporter.  It's bad enough that all classes have a import() method
 # whenever UNIVERSAL.pm is loaded.
 require Exporter;
-*import = \&Exporter::import;
 @EXPORT_OK = qw(isa can VERSION);
 
+# Make sure that even though the import method is called, it doesn't do
+# anything unless its called on UNIVERSAL
+sub import {
+    return unless $_[0] eq __PACKAGE__;
+    goto &Exporter::import;
+}
+
 1;
 __END__
 
@@ -41,20 +47,42 @@ C<UNIVERSAL> provides the following methods and functions:
 
 =over 4
 
-=item $obj->isa( TYPE ), CLASS->isa( TYPE ), isa( VAL, TYPE )
+=item C<< $obj->isa( TYPE ) >>
+
+=item C<< CLASS->isa( TYPE ) >> 
+
+=item C<isa( VAL, TYPE )>
+
+Where
+
+=over 4
+
+=item C<TYPE>
+
+is a package name
+
+=item C<$obj>
 
-    C<TYPE> is a package name
-    $obj is a blessed reference or a string containing a package name
-    C<CLASS> is a package name
-    C<VAL> is any of the above or an unblessed reference
+is a blessed reference or a string containing a package name
 
-When used as an instance or class method (C<$obj->isa( TYPE )>), C<isa>
-returns I<true> if $obj is blessed into package C<TYPE> or inherits from
-package C<TYPE>.
+=item C<CLASS>
 
-When used as a class method (C<CLASS->isa( TYPE )>; sometimes referred to as a
-static method), C<isa> returns I<true> if C<CLASS> inherits from (or is itself)
-the name of the package C<TYPE> or inherits from package C<TYPE>.
+is a package name
+
+=item C<VAL>
+
+is any of the above or an unblessed reference
+
+=back
+
+When used as an instance or class method (C<< $obj->isa( TYPE ) >>),
+C<isa> returns I<true> if $obj is blessed into package C<TYPE> or
+inherits from package C<TYPE>.
+
+When used as a class method (C<< CLASS->isa( TYPE ) >>: sometimes
+referred to as a static method), C<isa> returns I<true> if C<CLASS>
+inherits from (or is itself) the name of the package C<TYPE> or
+inherits from package C<TYPE>.
 
 When used as a function, like
 
@@ -67,11 +95,15 @@ or
    require UNIVERSAL ;
    $yes = UNIVERSAL::isa $a, "ARRAY";
 
-, C<isa> returns I<true> in the same cases as above and also if C<VAL> is an
+C<isa> returns I<true> in the same cases as above and also if C<VAL> is an
 unblessed reference to a perl variable of type C<TYPE>, such as "HASH",
 "ARRAY", or "Regexp".
 
-=item $obj->can( METHOD ), CLASS->can( METHOD ), can( VAL, METHOD )
+=item C<< $obj->can( METHOD ) >>
+
+=item C<< CLASS->can( METHOD ) >>
+
+=item C<can( VAL, METHOD )>
 
 C<can> checks if the object or class 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
@@ -95,24 +127,27 @@ has a method called C<METHOD>, C<can> returns a reference to the subroutine.
 If C<VAL> is not a blessed reference, or if it does not have a method
 C<METHOD>, I<undef> is returned.
 
-=item VERSION ( [ REQUIRE ] )
+=item C<VERSION ( [ REQUIRE ] )>
 
 C<VERSION> will return the value of the variable C<$VERSION> in the
 package the object is blessed into. If C<REQUIRE> is given then
 it will do a comparison and die if the package version is not
 greater than or equal to C<REQUIRE>.
 
-C<VERSION> can be called as either a class (static) method, an object method or
-or a function.
+C<VERSION> can be called as either a class (static) method, an object
+method or a function.
 
 
 =back
 
-These subroutines should I<not> be imported via S<C<use UNIVERSAL qw(...)>>.
-If you want simple local access to them you can do
+=head1 EXPORTS
 
-  *isa = \&UNIVERSAL::isa;
+None by default.
 
-to import isa into your package.
+You may request the import of all three functions (C<isa>, C<can>, and
+C<VERSION>), however it isn't usually necessary to do so.  Perl magically
+makes these functions act as methods on all objects.  The one exception is
+C<isa>, which is useful as a function when operating on non-blessed
+references.
 
 =cut