view release on metacpan or  search on metacpan

lib/Alter.pm  view on Meta::CPAN

objects.  To clone an C<Alter>-based object,
C<Storable::thaw(Storable::freeze($obj)> must be called explicitly.

Per default, both C<Alter::Dumper> and C<Alter::Storable> are made
base classes of the current class (if necessary) by C<use Alter>.
If the function C<Dumper> is imported, or if C<-dumper> is specified,
C<Alter::Dumper> is not made a base class.  If any of the functions
C<STORABLE_freeze>, C<STORABLE_thaw> or C<STORABLE_attach> is imported,
or if C<-storable> is specified, C<Alter::Storable> is not made a base class.

=head3 Fallback Perl Implementation

C<Alter> is properly an XS module and a suitable C compiler is
required to build it.  If compilation isn't possible, the XS part 
is replaced with a I<pure Perl> implementation C<Alter::AlterXS_in_perl>.
That happens automatically at load time when loading the XS part
fails.  The boolean function C<Alter::is_xs> tells (in the obvious
way) which implementation is active.  If, for some reason, you want
to run the Perl fallback when the XS version is available, set
the environment variable C<PERL_ALTER_NO_XS> to a true value before
C<Alter> is loaded.

This fallback is not a full replacement for the XS implementation.
Besides being markedly slower, it lacks key features in that it is
I<not> automatically garbage-collected and I<not> thread-safe.
Instead, C<Alter::AlterXS_in_perl> provides a C<CLONE> method
for thread safety and a universal destructor C<Alter::Destructor::DESTROY>
for garbage collection.  A class that uses the pure Perl implementation
of C<Alter> will obtain this destructor through inheritance (unless
C<-destroy> is specified with the C<use> statement).  So at the surface
thread-safety and garbage-collection are retained.  However, if
you want to add your own destructor to a class, you must make sure
that both (all) destructors are called as needed.  Perl only calls the
first one it meets on the C<@ISA> tree and that's it.

Otherwise the fallback implementation works like the original.  If
compilation has problems, it should allow you to run test cases to
help decide if it's worth trying.  To make sure that production code
doesn't inadvertently run with the Perl implementation

  Alter::is_xs or die "XS implementation of Alter required";

can be used.

=head2 Exports

None by default, C<alter()> and C<ego()> upon request.
Further available are C<STORABLE_freeze>, C<STORABLE_thaw> and
C<STORABLE_attach> as well as C<Dumper>.  C<:all> imports all these
functions.

=head2 Environment

The environment variable C<PERL_ALTER_NO_XS> is inspected once at
load time to decide whether to load the XS version of C<Alter> or
the pure Perl fallback.  At run time it has no effect.

=head2 Description

The C<Alter> module is meant to facilitate the creation of classes
that support I<black-box inheritance>, which is to say that an
C<Alter> based class can be a parent class for I<any other> class,
whether itself C<Alter> based or not.  Inside-out classes also have
that property.  C<Alter> is thus an alternative to the I<inside-out>
technique of class construction.  In some respects, C<Alter> objects
are easier to handle.

Alter objects support the same data model as traditional Perl
objects.  To each class, an Alter object presents an arbitrary
reference, the object's I<alter ego>. The type of reference and
how it is used are the entirely the class's business.  In particular,
the common practice of using a hash whose keys represent object
fields still applies, only each class sees its individual hash.

C<Alter> based objects are garbage-collected and thread-safe without
additional measures.

C<Alter> also supports C<Data::Dumper> and C<Storable> in
a generic way, so that C<Alter> based objects can be easily be viewed
and made persistent (within the limitations of the respective modules).

C<Alter> works by giving every object a class-specific I<alter ego>,
which can be any scalar, for its (the classe's) specific needs for
data storage.  The alter ego is set by the C<alter()> function (or
by autovivification), usually once per class and object at initialization
time.  It is retrieved by the C<ego()> function in terms of which 
a class will define its accessors.

That works by magically (in the technical sense of C<PERL_MAGIC_ext>)
assigning a hash keyed by classname, the I<corona>, to every object
that takes part in the game.  The corona holds the individual alter
ego's for each class.  It is created when needed and stays with
an object for its lifetime.  It is subject to garbage collection
when the object goes out of scope.  Normally the corona is invisible
to the user, but the C<Alter::corona()> function (not exported)
allows direct access if needed.

=head2 Example

The example first shows how a class C<Name> is built from two
classes C<First> and C<Last> which implement the first and last
names separately.  C<First> treats its objects as hashes whereas
C<Last> uses them as arrays.  Nevertheless, the code in C<Name> that
joins the two classes via subclassing is straightforward.

The second part of the example shows that C<Alter> classes actually
support black-box inheritance.  Here, we use an object of class
C<IO::File> as the "carrier" object.  This must be a globref to work.
This object can be initialized to the class C<Name>, which in part
sees it as a hash, in another part as an array.  Methods of both
classes now work on the object.

    #!/usr/local/bin/perl
    use strict; use warnings; $| = 1;

    # Show that class Name works
    my $prof = Name->new( qw( Albert Einstein));
    print $prof->fname, "\n";
    print $prof->lname, "\n";
    print $prof->name, "\n";