Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
UNIVERSAL(3)	       Perl Programmers	Reference Guide		  UNIVERSAL(3)

NAME
       UNIVERSAL - base	class for ALL classes (blessed references)

SYNOPSIS
	   $is_io    = $fd->isa("IO::Handle");
	   $is_io    = Class->isa("IO::Handle");

	   $does_log = $obj->DOES("Logger");
	   $does_log = Class->DOES("Logger");

	   $sub	     = $obj->can("print");
	   $sub	     = Class->can("print");

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

	   # but never do this!
	   $is_io    = UNIVERSAL::isa($fd, "IO::Handle");
	   $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.

	   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.34.0			  2020-06-14			  UNIVERSAL(3)

NAME | SYNOPSIS | DESCRIPTION | WARNINGS | EXPORTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=UNIVERSAL&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help