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

FreeBSD Manual Pages

  
 
  

home | help
Safe::Isa(3)	      User Contributed Perl Documentation	  Safe::Isa(3)

NAME
       Safe::Isa - Call	isa, can, does and DOES	safely on things that may not
       be objects

SYNOPSIS
	 use strict;
	 use warnings;

	 { package Foo;	sub new	{ bless({}, $_[0]) } }
	 { package Bar;	our @ISA = qw(Foo); sub	bar { 1	} }

	 my $foo = Foo->new;
	 my $bar = Bar->new;
	 my $blam = [ 42 ];

	 # basic isa usage -

	 $foo->isa('Foo');  # true
	 $bar->isa('Foo');  # true
	 $blam->isa('Foo'); # BOOM

	 $foo->can('bar');  # false
	 $bar->can('bar');  # true
	 $blam->can('bar'); # BOOM

	 # Safe::Isa usage -

	 use Safe::Isa;

	 $foo->$_isa('Foo');  #	true
	 $bar->$_isa('Foo');  #	true
	 $blam->$_isa('Foo'); #	false, no boom today

	 $foo->$_can('bar');  #	false
	 $bar->$_can('bar');  #	true
	 $blam->$_can('bar'); #	false, no boom today

       Similarly:

	 $maybe_an_object->$_does('RoleName'); # true or false,	no boom	today
	 $maybe_an_object->$_DOES('RoleName'); # true or false,	no boom	today

       And just	in case	we missed a method or two:

	 $maybe_an_object->$_call_if_object(name => @args);
	 $maybe_an_object->$_call_if_can(name => @args);

       Or to re-use a previous example for purposes of explication:

	 $foo->$_call_if_object(isa => 'Foo');	# true
	 $bar->$_call_if_object(isa => 'Foo');	# true
	 $blam->$_call_if_object(isa =>	'Foo');	# false, no boom today

DESCRIPTION
       How many	times have you found yourself writing:

	 if ($obj->isa('Something')) {

       and then	shortly	afterwards cursing and changing	it to:

	 if (Scalar::Util::blessed($obj) and $obj->isa('Something')) {

       Right. That's why this module exists.

       Since perl allows us to provide a subroutine reference or a method name
       to the -> operator when used as a method	call, and a subroutine doesn't
       require the invocant to actually	be an object, we can create safe
       versions	of isa,	can and	friends	by using a subroutine reference	that
       only tries to call the method if	it's used on an	object.	So:

	 my $isa_Foo = $maybe_an_object->$_call_if_object(isa => 'Foo');

       is equivalent to

	 my $isa_Foo = do {
	   if (Scalar::Util::blessed($maybe_an_object))	{
	     $maybe_an_object->isa('Foo');
	   } else {
	     undef;
	   }
	 };

       Note that we don't handle trying	class names, because many things are
       valid class names that you might	not want to treat as one (like say
       "Matt") - the "is_module_name" function from Module::Runtime is a good
       way to check for	something you might be able to call methods on if you
       want to do that.

       We are careful to make sure that	scalar/list context is preserved for
       the method that is eventually called.

EXPORTS
   $_isa
	 $maybe_an_object->$_isa('Foo');

       If called on an object, calls "isa" on it and returns the result,
       otherwise returns nothing.

   $_can
	 $maybe_an_object->$_can('Foo');

       If called on an object, calls "can" on it and returns the result,
       otherwise returns nothing.

   $_does
	 $maybe_an_object->$_does('Foo');

       If called on an object, calls "does" on it and returns the result,
       otherwise returns nothing. If the "does"	method does not	exist, returns
       nothing rather than failing.

   $_DOES
	 $maybe_an_object->$_DOES('Foo');

       If called on an object, calls "DOES" on it and returns the result,
       otherwise returns nothing. On perl versions prior to 5.10.0, the	built
       in core "DOES" method doesn't exist. If the method doesn't exist, this
       will fall back to calling "isa" just like the core "DOES" method.

   $_call_if_object
	 $maybe_an_object->$_call_if_object(method_name	=> @args);

       If called on an object, calls "method_name" on it and returns the
       result, otherwise returns nothing.

   $_call_if_can
	 $maybe_an_object->$_call_if_can(name => @args);

       If called on an object, calls "can" on it; if that returns true,	then
       calls "method_name" on it and returns the result; if any	condition is
       false returns nothing.

SEE ALSO
       I gave a	lightning talk on this module (and curry and Import::Into) at
       YAPC::NA	2013 <https://www.youtube.com/watch?v=wFXWV2yY7gE&t=46m05s>.

AUTHOR
       mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>

CONTRIBUTORS
       None yet. Well volunteered? :)

COPYRIGHT
       Copyright (c) 2012 the Safe::Isa	"AUTHOR" and "CONTRIBUTORS" as listed
       above.

LICENSE
       This library is free software and may be	distributed under the same
       terms as	perl itself.

perl v5.32.1			  2018-04-21			  Safe::Isa(3)

NAME | SYNOPSIS | DESCRIPTION | EXPORTS | SEE ALSO | AUTHOR | CONTRIBUTORS | COPYRIGHT | LICENSE

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

home | help