/ 
Acme-Holy-0.03
River stage zero No dependents
/ Acme::Holy

NAME

Acme::Holy - Test whether references are blessed.

SYNOPSIS

use Acme::Holy;

my $ref = ... some reference ...
my $obj = bless $ref , 'Some::Class';

print holy( $obj );                           # prints 'Some::Class'
print ( holy [] ? 'object' : 'not object' );  # prints 'not object'

WARNING

This module is a classic case of reinventing the wheel and not enough RTFM. Unless you really like having terms such as holy in your code, you should use the official "holy" implementation now found in the Perl core: Scalar::Util. There you will find the blessed function which behaves identically to holy().

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

DESCRIPTION

Acme::Holy provides a single routine, holy(), which returns the name of the package an object has been blessed 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:

  • blessed()

  • consecrated()

  • divine()

  • hallowed()

  • sacred()

  • sacrosanct()

ACKNOWLEDGEMENTS

The idea for this module came from a conversation I had with David Cantrell <david@cantrell.org.uk>. However, the lack of RTFM is a clear failing on my part. It was obviously a good idea, otherwise someone wouldn't have already written it.

SEE ALSO

Scalar::Util (oops!), bless, perlboot, perltoot, perltooc, perlbot, perlobj.

AUTHOR

Ian Brayshaw, <ian@onemore.org>

COPYRIGHT AND LICENSE

Copyright 2003 by Ian Brayshaw

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.