Acme-Holy

 view release on metacpan or  search on metacpan

Holy.pm  view on Meta::CPAN

should use the official "holy" implementation now found in the Perl core:
L<Scalar::Util>. There you will find the C<blessed> function which behaves
identically to C<holy()>.

... Oh well, on with the show ...


=head1 DESCRIPTION

B<Acme::Holy> provides a single routine, B<holy()>, which returns the name
of the package an object has been C<bless>ed into, or C<undef>, if its first
argument is not a blessed reference.

Isn't this what C<ref()> does already? Yes, and no. If given a blessed
reference, C<ref()> will return the name of the package the reference has
been blessed into. However, if C<ref()> is passed an unblessed reference,
then it will return the type of reference (e.g. C<SCALAR>, C<HASH>, C<CODEREF>,
etc). This means that a call to C<ref()> by itself cannot determine if a
given reference is an object. B<holy()> differs from C<ref()> by returning
C<undef> if its first argument is not a blessed reference (even if it is
a reference).

Can't we use C<UNIVERSAL::isa()>? Yes, and no. If you already have an object,
then C<isa()> will let you know if it inherits from a given class. But what do
we do if we know nothing of the inheritance tree of the object's class? Also,
if we don't have an object, just a normal reference, then attempting to call
C<isa()> through it will result in a run-time error.

B<holy()> is a quick, single test to determine if a given scalar represents
an object (i.e. a blessed reference).

Holy.pm  view on Meta::CPAN

namespace. Aliases for B<holy()> (see below) may be imported upon request.

=head2 Methods

=over 4

=item B<holy> I<scalar>

B<holy()> accepts a single scalar as its argument, and, if that scalar is
a blessed reference, returns the name of the package the reference has been
blessed into. Otherwise, B<holy()> returns C<undef>.

=back


=head2 Method Aliases

To reflect that there are many terms for referring to something that is
blessed, B<Acme::Holy> offers a list of aliases for B<holy()> that may be
imported upon request:

Holy.xs  view on Meta::CPAN

		divine      = 3
		hallowed    = 4
		sacred      = 5
		sacrosanct  = 6

	PREINIT:
		SV		*sv;
		char	*name;

	CODE:
		/* if we don't have a blessed reference then return undef */
		if ( ! sv_isobject( rv ) )
			XSRETURN_UNDEF;

		/*
		** OK, so we have a blessed reference - an object - so
		** we should extract the name of the stash.
		*/

		sv		= SvRV( rv );
		name	= HvNAME( SvSTASH( sv ) );

README  view on Meta::CPAN

      make
      make test
      make install

    Acme::Holy uses XS to access the internals of Perl for it's magic, and
    therefore must be compiled to be installed. Also, for testing,
    Acme::Holy relies on Test::More and Test::Exception.

DESCRIPTION
    Acme::Holy provides a single routine, holy(), which returns the name of
    the package an object has been "bless"ed into, or "undef", if its first
    argument is not a blessed reference.

    Isn't this what "ref()" does already? Yes, and no. If given a blessed
    reference, "ref()" will return the name of the package the reference has
    been blessed into. However, if "ref()" is passed an unblessed reference,
    then it will return the type of reference (e.g. "SCALAR", "HASH",
    "CODEREF", etc). This means that a call to "ref()" by itself cannot
    determine if a given reference is an object. holy() differs from "ref()"
    by returning "undef" if its first argument is not a blessed reference
    (even if it is a reference).

    Can't we use "UNIVERSAL::isa()"? Yes, and no. If you already have an
    object, then "isa()" will let you know if it inherits from a given
    class. But what do we do if we know nothing of the inheritance tree of
    the object's class? Also, if we don't have an object, just a normal
    reference, then attempting to call "isa()" through it will result in a
    run-time error.

    holy() is a quick, single test to determine if a given scalar represents
    an object (i.e. a blessed reference).

  EXPORT
    By default, Acme::Holy exports the method holy() into the current
    namespace. Aliases for holy() (see below) may be imported upon request.

  Methods
    holy *scalar*
        holy() accepts a single scalar as its argument, and, if that scalar
        is a blessed reference, returns the name of the package the
        reference has been blessed into. Otherwise, holy() returns "undef".

  Method Aliases
    To reflect that there are many terms for referring to something that is
    blessed, Acme::Holy offers a list of aliases for holy() that may be
    imported upon request:

      use Acme::Holy qw( blessed );

    The following aliases are supported:

t/2holy.t  view on Meta::CPAN

my	$glob	= \*STDOUT;		$glob	= bless $glob;

ok( holy $number eq __PACKAGE__ , "holy() ok with numerical object" );
ok( holy $string eq __PACKAGE__ , "holy() ok with string object"    );
ok( holy $array  eq __PACKAGE__ , "holy() ok with array object"     );
ok( holy $hash   eq __PACKAGE__ , "holy() ok with hash object"      );
ok( holy $code   eq __PACKAGE__ , "holy() ok with code object"      );
ok( holy $glob   eq __PACKAGE__ , "holy() ok with glob object"      );

#
# make sure holy returns undef for all unblessed references
#

	$number	= \1;
	$string	= \'2';
	$array	= [];
	$hash	= {};
	$code	= sub {};
	$glob	= \*STDIN;

ok( ! defined holy $number , "holy() not defined with numerical reference" );
ok( ! defined holy $string , "holy() not defined with string reference"    );
ok( ! defined holy $array  , "holy() not defined with array reference"     );
ok( ! defined holy $hash   , "holy() not defined with hash reference"      );
ok( ! defined holy $code   , "holy() not defined with code reference"      );
ok( ! defined holy $glob   , "holy() not defined with glob reference"      );

#
# make sure holy returns undef for all non-references
#

	$number	= 1;
	$string	= '2';
	@array	= ();
	%hash	= ();

ok( ! defined holy undef   , "holy() not defined with undefined argument" );
ok( ! defined holy $number , "holy() not defined with numerical argument" );
ok( ! defined holy $string , "holy() not defined with string argument"    );
ok( ! defined holy @array  , "holy() not defined with array argument"     );
ok( ! defined holy %hash   , "holy() not defined with hash argument"      );