# $Id: Holy.pm,v 1.5 2003/06/16 02:49:03 ian Exp $
package Acme::Holy;
use 5.000;
use strict;
require Exporter;
require DynaLoader;
use vars qw( $VERSION @ISA @EXPORT @EXPORT_OK );
$VERSION = '0.03';
@ISA = qw( Exporter DynaLoader );
@EXPORT = qw( holy );
@EXPORT_OK = qw( blessed divine hallowed consecrated sacred sacrosanct );
bootstrap Acme::Holy $VERSION;
1;
__END__
=pod
=head1 NAME
Acme::Holy - Test whether references are blessed.
=head1 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'
=head1 WARNING
This module is a classic case of reinventing the wheel and not enough
RTFM. Unless you really like having terms such as C<holy> in your code, you
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).
=head2 EXPORT
By default, B<Acme::Holy> exports the method B<holy()> into the current
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:
use Acme::Holy qw( blessed );
The following aliases are supported:
=over 4
=item * B<blessed()>
=item * B<consecrated()>
=item * B<divine()>
=item * B<hallowed()>
=item * B<sacred()>
=item * B<sacrosanct()>
=back
=head1 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.
=head1 SEE ALSO
L<Scalar::Util> (oops!), L<bless|perlfunc/bless>, L<perlboot>, L<perltoot>,
L<perltooc>, L<perlbot>, L<perlobj>.
=head1 AUTHOR
Ian Brayshaw, E<lt>ian@onemore.orgE<gt>
=head1 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.
=cut