view release on metacpan or  search on metacpan

README  view on Meta::CPAN

$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.