lib/UNIVERSAL.pm

   1 package UNIVERSAL;
   2
   3 our $VERSION = '1.17';
   4
   5 # UNIVERSAL.pm should not contain any methods/subs, they
   6 # are all defined in universal.c
   7
   8 1;
   9 __END__
  10
  11 =head1 NAME
  12
  13 UNIVERSAL - base class for ALL classes (blessed references)
  14
  15 =head1 SYNOPSIS
  16
  17     my $obj_is_io    = $fd->isa("IO::Handle");
  18     my $cls_is_io    = Class->isa("IO::Handle");
  19
  20     my $obj_does_log = $obj->DOES("Logger");
  21     my $cls_does_log = Class->DOES("Logger");
  22
  23     my $obj_sub      = $obj->can("print");
  24     my $cls_sub      = Class->can("print");
  25
  26     my $eval_sub     = eval { $ref->can("fandango") };
  27     my $ver          = $obj->VERSION;
  28
  29     # but never do this!
  30     my $is_io        = UNIVERSAL::isa($fd, "IO::Handle");
  31     my $sub          = UNIVERSAL::can($obj, "print");
  32
  33 =head1 DESCRIPTION
  34
  35 C<UNIVERSAL> is the base class from which all blessed references inherit.
  36 See L<perlobj>.
  37
  38 C<UNIVERSAL> provides the following methods:
  39
  40 =over 4
  41
  42 =item C<< $obj->isa( TYPE ) >>
  43
  44 =item C<< CLASS->isa( TYPE ) >>
  45
  46 =item C<< eval { VAL->isa( TYPE ) } >>
  47
  48 Where
  49
  50 =over 4
  51
  52 =item C<TYPE>
  53
  54 is a package name
  55
  56 =item C<$obj>
  57
  58 is a blessed reference or a package name
  59
  60 =item C<CLASS>
  61
  62 is a package name
  63
  64 =item C<VAL>
  65
  66 is any of the above or an unblessed reference
  67
  68 =back
  69
  70 When used as an instance or class method (C<< $obj->isa( TYPE ) >>),
  71 C<isa> returns I<true> if $obj is blessed into package C<TYPE> or
  72 inherits from package C<TYPE>.
  73
  74 When used as a class method (C<< CLASS->isa( TYPE ) >>, sometimes
  75 referred to as a static method), C<isa> returns I<true> if C<CLASS>
  76 inherits from (or is itself) the name of the package C<TYPE> or
  77 inherits from package C<TYPE>.
  78
  79 If you're not sure what you have (the C<VAL> case), wrap the method call in an
  80 C<eval> block to catch the exception if C<VAL> is undefined or an unblessed
  81 reference. The L<C<isa> operator|perlop/"Class Instance Operator"> is an
  82 alternative that simply returns false in this case, so the C<eval> is not
  83 needed.
  84
  85 If you want to be sure that you're calling C<isa> on an instance, not a class,
  86 check the invocant with C<blessed> from L<Scalar::Util> first:
  87
  88   use Scalar::Util 'blessed';
  89
  90   if ( blessed( $obj ) && $obj->isa("Some::Class") ) {
  91       ...
  92   }
  93
  94 =item C<< $obj->DOES( ROLE ) >>
  95
  96 =item C<< CLASS->DOES( ROLE ) >>
  97
  98 C<DOES> checks if the object or class performs the role C<ROLE>.  A role is a
  99 named group of specific behavior (often methods of particular names and
 100 signatures), similar to a class, but not necessarily a complete class by
 101 itself.  For example, logging or serialization may be roles.
 102
 103 C<DOES> and C<isa> are similar, in that if either is true, you know that the
 104 object or class on which you call the method can perform specific behavior.
 105 However, C<DOES> is different from C<isa> in that it does not care I<how> the
 106 invocand performs the operations, merely that it does.  (C<isa> of course
 107 mandates an inheritance relationship.  Other relationships include aggregation,
 108 delegation, and mocking.)
 109
 110 By default, classes in Perl only perform the C<UNIVERSAL> role, as well as the
 111 role of all classes in their inheritance.  In other words, by default C<DOES>
 112 responds identically to C<isa>.
 113
 114 There is a relationship between roles and classes, as each class implies the
 115 existence of a role of the same name.  There is also a relationship between
 116 inheritance and roles, in that a subclass that inherits from an ancestor class
 117 implicitly performs any roles its parent performs.  Thus you can use C<DOES> in
 118 place of C<isa> safely, as it will return true in all places where C<isa> will
 119 return true (provided that any overridden C<DOES> I<and> C<isa> methods behave
 120 appropriately).
 121
 122 =item C<< $obj->can( METHOD ) >>
 123
 124 =item C<< CLASS->can( METHOD ) >>
 125
 126 =item C<< eval { VAL->can( METHOD ) } >>
 127
 128 C<can> checks if the object or class has a method called C<METHOD>. If it does,
 129 then it returns a reference to the sub.  If it does not, then it returns
 130 I<undef>.  This includes methods inherited or imported by C<$obj>, C<CLASS>, or
 131 C<VAL>.
 132
 133 C<can> cannot know whether an object will be able to provide a method through
 134 AUTOLOAD (unless the object's class has overridden C<can> appropriately), so a
 135 return value of I<undef> does not necessarily mean the object will not be able
 136 to handle the method call. To get around this some module authors use a forward
 137 declaration (see L<perlsub>) for methods they will handle via AUTOLOAD. For
 138 such 'dummy' subs, C<can> will still return a code reference, which, when
 139 called, will fall through to the AUTOLOAD. If no suitable AUTOLOAD is provided,
 140 calling the coderef will cause an error.
 141
 142 You may call C<can> as a class (static) method or an object method.
 143
 144 Again, the same rule about having a valid invocand applies -- use an C<eval>
 145 block or C<blessed> if you need to be extra paranoid.
 146
 147 =item C<VERSION ( [ REQUIRE ] )>
 148
 149 C<VERSION> will return the value of the variable C<$VERSION> in the
 150 package the object is blessed into. If C<REQUIRE> is given then
 151 it will do a comparison and die if the package version is not
 152 greater than or equal to C<REQUIRE>, or if either C<$VERSION> or C<REQUIRE>
 153 is not a "lax" version number (as defined by the L<version> module).
 154
 155 The return from C<VERSION> will actually be the stringified version object
 156 using the package C<$VERSION> scalar, which is guaranteed to be equivalent
 157 but may not be precisely the contents of the C<$VERSION> scalar.  If you want
 158 the actual contents of C<$VERSION>, use C<$CLASS::VERSION> instead.
 159
 160 C<VERSION> can be called as either a class (static) method or an object
 161 method.
 162
 163 =back
 164
 165 =head1 WARNINGS
 166
 167 B<NOTE:> C<can> directly uses Perl's internal code for method lookup, and
 168 C<isa> uses a very similar method and cache-ing strategy. This may cause
 169 strange effects if the Perl code dynamically changes @ISA in any package.
 170
 171 You may add other methods to the UNIVERSAL class via Perl or XS code.
 172 You do not need to C<use UNIVERSAL> to make these methods
 173 available to your program (and you should not do so).
 174
 175 =head1 EXPORTS
 176
 177 None.
 178
 179 Previous versions of this documentation suggested using C<isa> as
 180 a function to determine the type of a reference:
 181
 182   $yes = UNIVERSAL::isa($h, "HASH");
 183   $yes = UNIVERSAL::isa("Foo", "Bar");
 184
 185 The problem is that this code would I<never> call an overridden C<isa> method in
 186 any class.  Instead, use C<reftype> from L<Scalar::Util> for the first case:
 187
 188   use Scalar::Util 'reftype';
 189
 190   $yes = reftype( $h ) eq "HASH";
 191
 192 and the method form of C<isa> for the second:
 193
 194   $yes = Foo->isa("Bar");
 195
 196 =cut