1*0Sstevel@tonic-gatepackage UNIVERSAL; 2*0Sstevel@tonic-gate 3*0Sstevel@tonic-gateour $VERSION = '1.01'; 4*0Sstevel@tonic-gate 5*0Sstevel@tonic-gate# UNIVERSAL should not contain any extra subs/methods beyond those 6*0Sstevel@tonic-gate# that it exists to define. The use of Exporter below is a historical 7*0Sstevel@tonic-gate# accident that can't be fixed without breaking code. Note that we 8*0Sstevel@tonic-gate# *don't* set @ISA here, don't want all classes/objects inheriting from 9*0Sstevel@tonic-gate# Exporter. It's bad enough that all classes have a import() method 10*0Sstevel@tonic-gate# whenever UNIVERSAL.pm is loaded. 11*0Sstevel@tonic-gaterequire Exporter; 12*0Sstevel@tonic-gate*import = \&Exporter::import; 13*0Sstevel@tonic-gate@EXPORT_OK = qw(isa can VERSION); 14*0Sstevel@tonic-gate 15*0Sstevel@tonic-gate1; 16*0Sstevel@tonic-gate__END__ 17*0Sstevel@tonic-gate 18*0Sstevel@tonic-gate=head1 NAME 19*0Sstevel@tonic-gate 20*0Sstevel@tonic-gateUNIVERSAL - base class for ALL classes (blessed references) 21*0Sstevel@tonic-gate 22*0Sstevel@tonic-gate=head1 SYNOPSIS 23*0Sstevel@tonic-gate 24*0Sstevel@tonic-gate $is_io = $fd->isa("IO::Handle"); 25*0Sstevel@tonic-gate $is_io = Class->isa("IO::Handle"); 26*0Sstevel@tonic-gate 27*0Sstevel@tonic-gate $sub = $obj->can("print"); 28*0Sstevel@tonic-gate $sub = Class->can("print"); 29*0Sstevel@tonic-gate 30*0Sstevel@tonic-gate use UNIVERSAL qw( isa can VERSION ); 31*0Sstevel@tonic-gate $yes = isa $ref, "HASH" ; 32*0Sstevel@tonic-gate $sub = can $ref, "fandango" ; 33*0Sstevel@tonic-gate $ver = VERSION $obj ; 34*0Sstevel@tonic-gate 35*0Sstevel@tonic-gate=head1 DESCRIPTION 36*0Sstevel@tonic-gate 37*0Sstevel@tonic-gateC<UNIVERSAL> is the base class which all bless references will inherit from, 38*0Sstevel@tonic-gatesee L<perlobj>. 39*0Sstevel@tonic-gate 40*0Sstevel@tonic-gateC<UNIVERSAL> provides the following methods and functions: 41*0Sstevel@tonic-gate 42*0Sstevel@tonic-gate=over 4 43*0Sstevel@tonic-gate 44*0Sstevel@tonic-gate=item C<< $obj->isa( TYPE ) >> 45*0Sstevel@tonic-gate 46*0Sstevel@tonic-gate=item C<< CLASS->isa( TYPE ) >> 47*0Sstevel@tonic-gate 48*0Sstevel@tonic-gate=item C<isa( VAL, TYPE )> 49*0Sstevel@tonic-gate 50*0Sstevel@tonic-gateWhere 51*0Sstevel@tonic-gate 52*0Sstevel@tonic-gate=over 4 53*0Sstevel@tonic-gate 54*0Sstevel@tonic-gate=item C<TYPE> 55*0Sstevel@tonic-gate 56*0Sstevel@tonic-gateis a package name 57*0Sstevel@tonic-gate 58*0Sstevel@tonic-gate=item C<$obj> 59*0Sstevel@tonic-gate 60*0Sstevel@tonic-gateis a blessed reference or a string containing a package name 61*0Sstevel@tonic-gate 62*0Sstevel@tonic-gate=item C<CLASS> 63*0Sstevel@tonic-gate 64*0Sstevel@tonic-gateis a package name 65*0Sstevel@tonic-gate 66*0Sstevel@tonic-gate=item C<VAL> 67*0Sstevel@tonic-gate 68*0Sstevel@tonic-gateis any of the above or an unblessed reference 69*0Sstevel@tonic-gate 70*0Sstevel@tonic-gate=back 71*0Sstevel@tonic-gate 72*0Sstevel@tonic-gateWhen used as an instance or class method (C<< $obj->isa( TYPE ) >>), 73*0Sstevel@tonic-gateC<isa> returns I<true> if $obj is blessed into package C<TYPE> or 74*0Sstevel@tonic-gateinherits from package C<TYPE>. 75*0Sstevel@tonic-gate 76*0Sstevel@tonic-gateWhen used as a class method (C<< CLASS->isa( TYPE ) >>: sometimes 77*0Sstevel@tonic-gatereferred to as a static method), C<isa> returns I<true> if C<CLASS> 78*0Sstevel@tonic-gateinherits from (or is itself) the name of the package C<TYPE> or 79*0Sstevel@tonic-gateinherits from package C<TYPE>. 80*0Sstevel@tonic-gate 81*0Sstevel@tonic-gateWhen used as a function, like 82*0Sstevel@tonic-gate 83*0Sstevel@tonic-gate use UNIVERSAL qw( isa ) ; 84*0Sstevel@tonic-gate $yes = isa $h, "HASH"; 85*0Sstevel@tonic-gate $yes = isa "Foo", "Bar"; 86*0Sstevel@tonic-gate 87*0Sstevel@tonic-gateor 88*0Sstevel@tonic-gate 89*0Sstevel@tonic-gate require UNIVERSAL ; 90*0Sstevel@tonic-gate $yes = UNIVERSAL::isa $a, "ARRAY"; 91*0Sstevel@tonic-gate 92*0Sstevel@tonic-gateC<isa> returns I<true> in the same cases as above and also if C<VAL> is an 93*0Sstevel@tonic-gateunblessed reference to a perl variable of type C<TYPE>, such as "HASH", 94*0Sstevel@tonic-gate"ARRAY", or "Regexp". 95*0Sstevel@tonic-gate 96*0Sstevel@tonic-gate=item C<< $obj->can( METHOD ) >> 97*0Sstevel@tonic-gate 98*0Sstevel@tonic-gate=item C<< CLASS->can( METHOD ) >> 99*0Sstevel@tonic-gate 100*0Sstevel@tonic-gate=item C<can( VAL, METHOD )> 101*0Sstevel@tonic-gate 102*0Sstevel@tonic-gateC<can> checks if the object or class has a method called C<METHOD>. If it does 103*0Sstevel@tonic-gatethen a reference to the sub is returned. If it does not then I<undef> is 104*0Sstevel@tonic-gatereturned. This includes methods inherited or imported by C<$obj>, C<CLASS>, or 105*0Sstevel@tonic-gateC<VAL>. 106*0Sstevel@tonic-gate 107*0Sstevel@tonic-gateC<can> cannot know whether an object will be able to provide a method 108*0Sstevel@tonic-gatethrough AUTOLOAD, so a return value of I<undef> does not necessarily mean 109*0Sstevel@tonic-gatethe object will not be able to handle the method call. To get around 110*0Sstevel@tonic-gatethis some module authors use a forward declaration (see L<perlsub>) 111*0Sstevel@tonic-gatefor methods they will handle via AUTOLOAD. For such 'dummy' subs, C<can> 112*0Sstevel@tonic-gatewill still return a code reference, which, when called, will fall through 113*0Sstevel@tonic-gateto the AUTOLOAD. If no suitable AUTOLOAD is provided, calling the coderef 114*0Sstevel@tonic-gatewill cause an error. 115*0Sstevel@tonic-gate 116*0Sstevel@tonic-gateC<can> can be called as a class (static) method, an object method, or a 117*0Sstevel@tonic-gatefunction. 118*0Sstevel@tonic-gate 119*0Sstevel@tonic-gateWhen used as a function, if C<VAL> is a blessed reference or package name which 120*0Sstevel@tonic-gatehas a method called C<METHOD>, C<can> returns a reference to the subroutine. 121*0Sstevel@tonic-gateIf C<VAL> is not a blessed reference, or if it does not have a method 122*0Sstevel@tonic-gateC<METHOD>, I<undef> is returned. 123*0Sstevel@tonic-gate 124*0Sstevel@tonic-gate=item C<VERSION ( [ REQUIRE ] )> 125*0Sstevel@tonic-gate 126*0Sstevel@tonic-gateC<VERSION> will return the value of the variable C<$VERSION> in the 127*0Sstevel@tonic-gatepackage the object is blessed into. If C<REQUIRE> is given then 128*0Sstevel@tonic-gateit will do a comparison and die if the package version is not 129*0Sstevel@tonic-gategreater than or equal to C<REQUIRE>. 130*0Sstevel@tonic-gate 131*0Sstevel@tonic-gateC<VERSION> can be called as either a class (static) method, an object 132*0Sstevel@tonic-gatemethod or a function. 133*0Sstevel@tonic-gate 134*0Sstevel@tonic-gate 135*0Sstevel@tonic-gate=back 136*0Sstevel@tonic-gate 137*0Sstevel@tonic-gate=head1 EXPORTS 138*0Sstevel@tonic-gate 139*0Sstevel@tonic-gateNone by default. 140*0Sstevel@tonic-gate 141*0Sstevel@tonic-gateYou may request the import of all three functions (C<isa>, C<can>, and 142*0Sstevel@tonic-gateC<VERSION>), however it isn't usually necessary to do so. Perl magically 143*0Sstevel@tonic-gatemakes these functions act as methods on all objects. The one exception is 144*0Sstevel@tonic-gateC<isa>, which is useful as a function when operating on non-blessed 145*0Sstevel@tonic-gatereferences. 146*0Sstevel@tonic-gate 147*0Sstevel@tonic-gate=cut 148