view release on metacpan or  search on metacpan

lib/Anansi/Class.pm  view on Meta::CPAN

    use Anansi::Example;

    my $object = Anansi::Example->new();

    1;

=head1 DESCRIPTION

This is a base module definition that manages the creation and destruction of
module object instances including embedded objects and ensures that destruction
can only occur when an object is no longer used.  Makes use of
L<Anansi::ObjectManager>.

=cut


our $VERSION = '0.10';

use Anansi::ObjectManager;


=head1 METHODS

=cut


=head2 DESTROY

=over 4

=item self I<(Blessed Hash, Required)>

An object of this namespace.

=back

Performs module object instance clean-up actions.  Calls the
L<finalise|Anansi::Class/"finalise"> method prior to dereferencing the object.
Indirectly called by the perl interpreter.

=cut


sub DESTROY {
    my ($self) = @_;
    my $objectManager = Anansi::ObjectManager->new();
    if(1 == $objectManager->registrations($self)) {
        $self->finalise();
        $objectManager->obsolete(
            USER => $self,
        );
        $objectManager->unregister($self);
    }
}


=head2 finalise

    $OBJECT->finalise();

    $OBJECT->SUPER::finalise();

=over 4

=item self I<(Blessed Hash, Required)>

An object of this namespace.

=back

A virtual method.  Called just prior to module instance object destruction.

=cut


sub finalise {
    my ($self) = @_;
}


=head2 identification

=over 4

=item self I<(Blessed Hash, Required)>

An object of this namespace.

=back

Returns this object's unique identification or B<undef> on error.

=cut


sub identification {
    my ($self) = @_;
    return if(ref($self) =~ /^(|ARRAY|CODE|FORMAT|GLOB|HASH|IO|LVALUE|REF|Regexp|SCALAR|VSTRING)$/i);
    my $result;
    eval {
        $result = $self->isa('Anansi::Class');
    };
    return if($@);
    return if(!$result);
    return if(!defined($self->{Anansi}));
    return if(ref($self->{Anansi}) !~ /^HASH$/i);
    return if(!defined(${$self->{Anansi}}{ObjectManager}));
    return if(ref(${$self->{Anansi}}{ObjectManager}) !~ /^HASH$/i);
    return if(!defined(${${$self->{Anansi}}{ObjectManager}}{IDENTIFICATION}));
    return if(ref(${${$self->{Anansi}}{ObjectManager}}{IDENTIFICATION}) !~ /^$/);
    return if(${${$self->{Anansi}}{ObjectManager}}{IDENTIFICATION} =~ /^\s*$/);
    return ${${$self->{Anansi}}{ObjectManager}}{IDENTIFICATION};
}


=head2 implicate

    sub implicate {
        my ($self, $caller, $parameter) = @_;
        if('EXAMPLE_VARIABLE' eq $parameter) {
            return \EXAMPLE_VARIABLE;
        }
        try {
            return $self->SUPER::implicate($caller, $parameter);
        }
        return if($@);
    }

=over 4

=item self I<(Blessed Hash, Required)>

An object of this namespace.

=item caller I<(Array, Required)>

An array containing the I<package>, I<file name> and I<line number> of the caller.

=item parameter I<(String, Required)>

A string containing the name to import.

=back

A virtual method.  Performs one module instance name import.  Called for each
name to import.

=cut


sub implicate {
    my ($self, $caller, $parameter) = @_;
    try {
        return $self->SUPER::implicate($caller, $parameter);
    }
    return if($@);
}


=head2 import

    use Anansi::Example qw(EXAMPLE_VARIABLE);

=over 4

=item self I<(Blessed Hash, Required)>

An object of this namespace.

=item parameters I<(Array, Optional)>

An array containing all of the names to import.

=back

Performs all required module name imports.  Indirectly called via an extending
module.

=cut


sub import {
    my ($self, @parameters) = @_;
    my $caller = caller();
    foreach my $parameter (@parameters) {
        my $value = $self->implicate($caller, $parameter);
        *{$caller.'::'.$parameter} = $value if(defined($value));
    }
}


=head2 initialise

    $OBJECT->initialise();

    $OBJECT->SUPER::initialise();

=over 4

=item self I<(Blessed Hash, Required)>

An object of this namespace.

=item parameters I<(Hash, Optional)>

Named parameters that were supplied to the I<new> method.

=back

A virtual method.  Called just after module instance object creation.

=cut


sub initialise {
    my ($self, %parameters) = @_;
}


=head2 namespace

=over 4

=item self I<(Blessed Hash, Required)>

An object of this namespace.

=back

Returns this object's namespace or B<undef> on error.

=cut


sub namespace {
    my ($self) = @_;
    return if(ref($self) =~ /^(|ARRAY|CODE|FORMAT|GLOB|HASH|IO|LVALUE|REF|Regexp|SCALAR|VSTRING)$/i);
    return ref($self);
}


=head2 new

    my $object = Anansi::Example->new();

    my $object = Anansi::Example->new(
       SETTING => 'example',
    );

=over 4

=item class I<(Blessed Hash B<or> String, Required)>

Either an object or a string of this namespace.

=item parameters I<(Hash, Optional)>