Acme-Holy
view release on metacpan or search on metacpan
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()>
=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
MODULE = Acme::Holy PACKAGE = Acme::Holy
SV *
holy( rv )
SV * rv;
PROTOTYPE: $
ALIAS:
blessed = 1
consecrated = 2
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 ) );
/* return the name of the package */
RETVAL = newSVpv( name , 0 );
OUTPUT:
$Id: README,v 1.4 2003/06/16 02:12:38 ian Exp $
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'
INSTALLATION
To install this module type the following:
perl Makefile.PL
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:
* 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
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.
use strict;
use Test::More tests => 17;
use Test::Exception;
# load Acme::Holy
use Acme::Holy;
#
# make sure holy returns the package name when given a blessed reference
#
# define blessed references for testing
my $number = 1; $number = bless \$number;
my $string = '2'; $string = bless \$string;
my @array = (); my $array = bless \@array;
my %hash = (); my $hash = bless \%hash;
my $code = sub {}; $code = bless $code;
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" );
t/3aliases.t view on Meta::CPAN
#
# Ensure the holy aliases work.
use strict;
use Test::More tests => 12;
use Test::Exception;
# load Acme::Damn and the aliases
my @aliases;
BEGIN {
@aliases = qw( blessed consecrated divine hallowed sacred sacrosanct );
}
# load Acme::Holy
use Acme::Holy @aliases;
foreach my $alias ( @aliases ) {
no strict 'refs';
# create a reference, and strify it
my $ref = [];
my $string = "$ref";
# bless the reference and the "unbless" it
bless $ref;
lives_ok { $alias->( $ref ) } "$alias executes successfully";
# make sure the stringification is correct
ok( $alias->( $ref ) eq __PACKAGE__ , "$alias executes correctly" );
}
( run in 2.391 seconds using v1.01-cache-2.11-cpan-de7293f3b23 )