NAME

       UNIVERSAL - base class for ALL classes (blessed references)

SYNOPSIS

           my $obj_is_io    = $fd->isa("IO::Handle");
           my $cls_is_io    = Class->isa("IO::Handle");

           my $obj_does_log = $obj->DOES("Logger");
           my $cls_does_log = Class->DOES("Logger");

           my $obj_sub      = $obj->can("print");
           my $cls_sub      = Class->can("print");

           my $eval_sub     = eval { $ref->can("fandango") };
           my $ver          = $obj->VERSION;

           # but never do this!
           my $is_io        = UNIVERSAL::isa($fd, "IO::Handle");
           my $sub          = UNIVERSAL::can($obj, "print");

DESCRIPTION

       "UNIVERSAL" is the base class from which all blessed references inherit.  See perlobj.

       "UNIVERSAL" provides the following methods:

       "$obj->isa( TYPE )"
       "CLASS->isa( TYPE )"
       "eval { VAL->isa( TYPE ) }"
           Where

           "TYPE"
               is a package name

           $obj
               is a blessed reference or a package name

           "CLASS"
               is a package name

           "VAL"
               is any of the above or an unblessed reference

           When used as an instance or class method ("$obj->isa( TYPE )"), "isa" returns true if $obj is blessed
           into package "TYPE" or inherits from package "TYPE".

           When  used  as a class method ("CLASS->isa( TYPE )", sometimes referred to as a static method), "isa"
           returns true if "CLASS" inherits from (or is itself) the name of the package "TYPE" or inherits  from
           package "TYPE".

           If  you're  not sure what you have (the "VAL" case), wrap the method call in an "eval" block to catch
           the exception if "VAL" is undefined or an unblessed reference. The "isa" operator is  an  alternative
           that simply returns false in this case, so the "eval" is not needed.

           If  you  want  to be sure that you're calling "isa" as a method, not a class, check the invocand with
           "blessed" from Scalar::Util first:

             use Scalar::Util 'blessed';

             if ( blessed( $obj ) && $obj->isa("Some::Class") ) {
                 ...
             }

       "$obj->DOES( ROLE )"
       "CLASS->DOES( ROLE )"
           "DOES" checks if the object or class performs the role "ROLE".  A role is a named group  of  specific
           behavior  (often methods of particular names and signatures), similar to a class, but not necessarily
           a complete class by itself.  For example, logging or serialization may be roles.

           "DOES" and "isa" are similar, in that if either is true, you know that the object or class  on  which
           you  call  the method can perform specific behavior.  However, "DOES" is different from "isa" in that
           it does not care how the invocand performs the operations, merely that it  does.   ("isa"  of  course
           mandates  an  inheritance  relationship.   Other  relationships  include aggregation, delegation, and
           mocking.)

           By default, classes in Perl only perform the "UNIVERSAL" role, as well as the role of all classes  in
           their inheritance.  In other words, by default "DOES" responds identically to "isa".

           There  is  a relationship between roles and classes, as each class implies the existence of a role of
           the same name.  There is also a relationship between inheritance and roles, in that a  subclass  that
           inherits  from an ancestor class implicitly performs any roles its parent performs.  Thus you can use
           "DOES" in place of "isa" safely, as it will return true in all places where "isa"  will  return  true
           (provided that any overridden "DOES" and "isa" methods behave appropriately).

       "$obj->can( METHOD )"
       "CLASS->can( METHOD )"
       "eval { VAL->can( METHOD ) }"
           "can"  checks  if  the  object  or  class has a method called "METHOD". If it does, then it returns a
           reference to the sub.  If it does not, then it returns undef.  This  includes  methods  inherited  or
           imported by $obj, "CLASS", or "VAL".

           "can"  cannot  know  whether  an object will be able to provide a method through AUTOLOAD (unless the
           object's class has overridden "can" appropriately), so a return value of undef does  not  necessarily
           mean  the  object  will not be able to handle the method call. To get around this some module authors
           use a forward declaration (see perlsub) for methods they will handle via AUTOLOAD. For  such  'dummy'
           subs,  "can"  will  still  return  a  code  reference,  which,  when called, will fall through to the
           AUTOLOAD. If no suitable AUTOLOAD is provided, calling the coderef will cause an error.

           You may call "can" as a class (static) method or an object method.

           Again, the same rule about having a valid invocand applies -- use an "eval" block or "blessed" if you
           need to be extra paranoid.

       "VERSION ( [ REQUIRE ] )"
           "VERSION" will return the value of the variable $VERSION in the package the object is  blessed  into.
           If "REQUIRE" is given then it will do a comparison and die if the package version is not greater than
           or  equal  to "REQUIRE", or if either $VERSION or "REQUIRE" is not a "lax" version number (as defined
           by the version module).

           The return from "VERSION" will actually be the stringified version object using the package  $VERSION
           scalar,  which  is  guaranteed to be equivalent but may not be precisely the contents of the $VERSION
           scalar.  If you want the actual contents of $VERSION, use $CLASS::VERSION instead.

           "VERSION" can be called as either a class (static) method or an object method.

WARNINGS

       NOTE: "can" directly uses Perl's internal code for method lookup, and "isa" uses a  very  similar  method
       and  cache-ing  strategy. This may cause strange effects if the Perl code dynamically changes @ISA in any
       package.

       You may add other methods to the UNIVERSAL class via Perl or XS code.  You do not need to "use UNIVERSAL"
       to make these methods available to your program (and you should not do so).

EXPORTS

       None.

       Previous versions of this documentation suggested using "isa" as a function to determine the  type  of  a
       reference:

         $yes = UNIVERSAL::isa($h, "HASH");
         $yes = UNIVERSAL::isa("Foo", "Bar");

       The  problem  is  that  this code would never call an overridden "isa" method in any class.  Instead, use
       "reftype" from Scalar::Util for the first case:

         use Scalar::Util 'reftype';

         $yes = reftype( $h ) eq "HASH";

       and the method form of "isa" for the second:

         $yes = Foo->isa("Bar");

perl v5.38.2                                       2025-04-08                                   UNIVERSAL(3perl)