.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "UNIVERSAL 3perl"
.TH UNIVERSAL 3perl 2023-11-30 "perl v5.38.2" "Perl Programmers Reference Guide"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
UNIVERSAL \- base class for ALL classes (blessed references)
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&    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");
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\f(CW\*(C`UNIVERSAL\*(C'\fR is the base class from which all blessed references inherit.
See perlobj.
.PP
\&\f(CW\*(C`UNIVERSAL\*(C'\fR provides the following methods:
.ie n .IP """$obj\->isa( TYPE )""" 4
.el .IP "\f(CW$obj\->isa( TYPE )\fR" 4
.IX Item "$obj->isa( TYPE )"
.PD 0
.ie n .IP """CLASS\->isa( TYPE )""" 4
.el .IP "\f(CWCLASS\->isa( TYPE )\fR" 4
.IX Item "CLASS->isa( TYPE )"
.ie n .IP """eval { VAL\->isa( TYPE ) }""" 4
.el .IP "\f(CWeval { VAL\->isa( TYPE ) }\fR" 4
.IX Item "eval { VAL->isa( TYPE ) }"
.PD
Where
.RS 4
.ie n .IP """TYPE""" 4
.el .IP \f(CWTYPE\fR 4
.IX Item "TYPE"
is a package name
.ie n .IP $obj 4
.el .IP \f(CW$obj\fR 4
.IX Item "$obj"
is a blessed reference or a package name
.ie n .IP """CLASS""" 4
.el .IP \f(CWCLASS\fR 4
.IX Item "CLASS"
is a package name
.ie n .IP """VAL""" 4
.el .IP \f(CWVAL\fR 4
.IX Item "VAL"
is any of the above or an unblessed reference
.RE
.RS 4
.Sp
When used as an instance or class method (\f(CW\*(C`$obj\->isa( TYPE )\*(C'\fR),
\&\f(CW\*(C`isa\*(C'\fR returns \fItrue\fR if \f(CW$obj\fR is blessed into package \f(CW\*(C`TYPE\*(C'\fR or
inherits from package \f(CW\*(C`TYPE\*(C'\fR.
.Sp
When used as a class method (\f(CW\*(C`CLASS\->isa( TYPE )\*(C'\fR, sometimes
referred to as a static method), \f(CW\*(C`isa\*(C'\fR returns \fItrue\fR if \f(CW\*(C`CLASS\*(C'\fR
inherits from (or is itself) the name of the package \f(CW\*(C`TYPE\*(C'\fR or
inherits from package \f(CW\*(C`TYPE\*(C'\fR.
.Sp
If you're not sure what you have (the \f(CW\*(C`VAL\*(C'\fR case), wrap the method call in an
\&\f(CW\*(C`eval\*(C'\fR block to catch the exception if \f(CW\*(C`VAL\*(C'\fR is undefined or an unblessed
reference. The \f(CW\*(C`isa\*(C'\fR operator is an
alternative that simply returns false in this case, so the \f(CW\*(C`eval\*(C'\fR is not
needed.
.Sp
If you want to be sure that you're calling \f(CW\*(C`isa\*(C'\fR as a method, not a class,
check the invocand with \f(CW\*(C`blessed\*(C'\fR from Scalar::Util first:
.Sp
.Vb 1
\&  use Scalar::Util \*(Aqblessed\*(Aq;
\&
\&  if ( blessed( $obj ) && $obj\->isa("Some::Class") ) {
\&      ...
\&  }
.Ve
.RE
.ie n .IP """$obj\->DOES( ROLE )""" 4
.el .IP "\f(CW$obj\->DOES( ROLE )\fR" 4
.IX Item "$obj->DOES( ROLE )"
.PD 0
.ie n .IP """CLASS\->DOES( ROLE )""" 4
.el .IP "\f(CWCLASS\->DOES( ROLE )\fR" 4
.IX Item "CLASS->DOES( ROLE )"
.PD
\&\f(CW\*(C`DOES\*(C'\fR checks if the object or class performs the role \f(CW\*(C`ROLE\*(C'\fR.  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.
.Sp
\&\f(CW\*(C`DOES\*(C'\fR and \f(CW\*(C`isa\*(C'\fR 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, \f(CW\*(C`DOES\*(C'\fR is different from \f(CW\*(C`isa\*(C'\fR in that it does not care \fIhow\fR the
invocand performs the operations, merely that it does.  (\f(CW\*(C`isa\*(C'\fR of course
mandates an inheritance relationship.  Other relationships include aggregation,
delegation, and mocking.)
.Sp
By default, classes in Perl only perform the \f(CW\*(C`UNIVERSAL\*(C'\fR role, as well as the
role of all classes in their inheritance.  In other words, by default \f(CW\*(C`DOES\*(C'\fR
responds identically to \f(CW\*(C`isa\*(C'\fR.
.Sp
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 \f(CW\*(C`DOES\*(C'\fR in
place of \f(CW\*(C`isa\*(C'\fR safely, as it will return true in all places where \f(CW\*(C`isa\*(C'\fR will
return true (provided that any overridden \f(CW\*(C`DOES\*(C'\fR \fIand\fR \f(CW\*(C`isa\*(C'\fR methods behave
appropriately).
.ie n .IP """$obj\->can( METHOD )""" 4
.el .IP "\f(CW$obj\->can( METHOD )\fR" 4
.IX Item "$obj->can( METHOD )"
.PD 0
.ie n .IP """CLASS\->can( METHOD )""" 4
.el .IP "\f(CWCLASS\->can( METHOD )\fR" 4
.IX Item "CLASS->can( METHOD )"
.ie n .IP """eval { VAL\->can( METHOD ) }""" 4
.el .IP "\f(CWeval { VAL\->can( METHOD ) }\fR" 4
.IX Item "eval { VAL->can( METHOD ) }"
.PD
\&\f(CW\*(C`can\*(C'\fR checks if the object or class has a method called \f(CW\*(C`METHOD\*(C'\fR. If it does,
then it returns a reference to the sub.  If it does not, then it returns
\&\fIundef\fR.  This includes methods inherited or imported by \f(CW$obj\fR, \f(CW\*(C`CLASS\*(C'\fR, or
\&\f(CW\*(C`VAL\*(C'\fR.
.Sp
\&\f(CW\*(C`can\*(C'\fR cannot know whether an object will be able to provide a method through
AUTOLOAD (unless the object's class has overridden \f(CW\*(C`can\*(C'\fR appropriately), so a
return value of \fIundef\fR 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, \f(CW\*(C`can\*(C'\fR 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.
.Sp
You may call \f(CW\*(C`can\*(C'\fR as a class (static) method or an object method.
.Sp
Again, the same rule about having a valid invocand applies \-\- use an \f(CW\*(C`eval\*(C'\fR
block or \f(CW\*(C`blessed\*(C'\fR if you need to be extra paranoid.
.ie n .IP """VERSION ( [ REQUIRE ] )""" 4
.el .IP "\f(CWVERSION ( [ REQUIRE ] )\fR" 4
.IX Item "VERSION ( [ REQUIRE ] )"
\&\f(CW\*(C`VERSION\*(C'\fR will return the value of the variable \f(CW$VERSION\fR in the
package the object is blessed into. If \f(CW\*(C`REQUIRE\*(C'\fR is given then
it will do a comparison and die if the package version is not
greater than or equal to \f(CW\*(C`REQUIRE\*(C'\fR, or if either \f(CW$VERSION\fR or \f(CW\*(C`REQUIRE\*(C'\fR
is not a "lax" version number (as defined by the version module).
.Sp
The return from \f(CW\*(C`VERSION\*(C'\fR will actually be the stringified version object
using the package \f(CW$VERSION\fR scalar, which is guaranteed to be equivalent
but may not be precisely the contents of the \f(CW$VERSION\fR scalar.  If you want
the actual contents of \f(CW$VERSION\fR, use \f(CW$CLASS::VERSION\fR instead.
.Sp
\&\f(CW\*(C`VERSION\*(C'\fR can be called as either a class (static) method or an object
method.
.SH WARNINGS
.IX Header "WARNINGS"
\&\fBNOTE:\fR \f(CW\*(C`can\*(C'\fR directly uses Perl's internal code for method lookup, and
\&\f(CW\*(C`isa\*(C'\fR uses a very similar method and cache-ing strategy. This may cause
strange effects if the Perl code dynamically changes \f(CW@ISA\fR in any package.
.PP
You may add other methods to the UNIVERSAL class via Perl or XS code.
You do not need to \f(CW\*(C`use UNIVERSAL\*(C'\fR to make these methods
available to your program (and you should not do so).
.SH EXPORTS
.IX Header "EXPORTS"
None.
.PP
Previous versions of this documentation suggested using \f(CW\*(C`isa\*(C'\fR as
a function to determine the type of a reference:
.PP
.Vb 2
\&  $yes = UNIVERSAL::isa($h, "HASH");
\&  $yes = UNIVERSAL::isa("Foo", "Bar");
.Ve
.PP
The problem is that this code would \fInever\fR call an overridden \f(CW\*(C`isa\*(C'\fR method in
any class.  Instead, use \f(CW\*(C`reftype\*(C'\fR from Scalar::Util for the first case:
.PP
.Vb 1
\&  use Scalar::Util \*(Aqreftype\*(Aq;
\&
\&  $yes = reftype( $h ) eq "HASH";
.Ve
.PP
and the method form of \f(CW\*(C`isa\*(C'\fR for the second:
.PP
.Vb 1
\&  $yes = Foo\->isa("Bar");
.Ve