```{index} single: UNIVERSAL ``` # UNIVERSAL base class for ALL classes (blessed references) ## SYNOPSIS ```perl 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](https://perldoc.perl.org/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](core/perlop.md) 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` on an instance, not a class, check the invocant with `blessed` from [Scalar::Util](Scalar/Util.md) first: ```perl 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 invocant 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](core/perlsub.md)) 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 invocant 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](version.md) 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 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: ```perl $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](Scalar/Util.md) for the first case: ```perl use Scalar::Util 'reftype'; $yes = reftype( $h ) eq "HASH"; ``` and the method form of `isa` for the second: ```perl $yes = Foo->isa("Bar"); ```