File Coverage

blib/lib/Anansi/Singleton.pm

Criterion	Covered	Total	%
statement	6	29	20.6
branch	0	10	0.0
condition			n/a
subroutine	2	6	33.3
pod	3	3	100.0
total	11	48	22.9

package Anansi::Singleton;


=head1 NAME

Anansi::Singleton - A base module definition where only a single object instance
is allowed.

=head1 SYNOPSIS

    package Anansi::Example;

    use base qw(Anansi::Singleton);

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

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

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

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

    1;

    package main;

    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 that are not repeatable including embedded objects and
ensures that destruction can only occur when all duplicate object instances are
no longer used.  Uses L, L and L.

=cut


our $VERSION = '0.09';

use base qw(Anansi::Class);

use Anansi::ObjectManager;


my $NAMESPACE = {};


=head1 METHODS

=cut


=head2 Anansi::Class

See L for details.  A parent module of
L.

=cut


=head3 DESTROY

See L for details.  Overridden
by L.

=cut


=head3 finalise

See L for details.  A virtual
method.

=cut


=head3 implicate

See L for details.  A
virtual method.

=cut


=head3 import

See L for details.

=cut


=head3 initialise

See L for details.  A
virtual method.

=cut


=head3 new

See L for details.  Overridden by
L.

=cut


=head3 old

See L for details.

=cut


=head3 used

See L for details.

=cut


=head3 uses

See L for details.

=cut


=head3 using

See L for details.

=cut


=head2 DESTROY

=over 4

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

An object of this namespace.

=back

Overrides L.  Performs module
object instance clean-up actions.  Either calls the
L method prior to dereferencing an instance
of the object where more than one instance exists or the
L method prior to dereferencing the last
instance.  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);
    } elsif(1 < $objectManager->registrations($self)) {
        $self->fixate();
        $objectManager->unregister($self);
    }
}


=head2 fixate

    $OBJECT->fixate();

    $OBJECT->SUPER::fixate();

=over 4

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

An object of this namespace.

=item parameters I<(Hash, Optional)>

Named parameters.

=back

A virtual method.  Called just prior to module instance object destruction where
there are multiple instances of the object remaining.

=cut


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


=head2 new

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

=over 4

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

Either an object or a string of this namespace.

=item parameters I<(Hash, Optional)>

Named parameters.

=back

Overrides L.  Instantiates or
reinstantiates an object instance of a module.  Either calls the
L method with the supplied I
after the object is first instantiated or the
L method after subsequent
instantiations.

=cut


sub new {
    my ($class, %parameters) = @_;
    return if(ref($class) =~ /^(ARRAY|CODE|FORMAT|GLOB|HASH|IO|LVALUE|REF|Regexp|SCALAR|VSTRING)$/i);
    $class = ref($class) if(ref($class) !~ /^$/);
    if(!defined($NAMESPACE->{$class})) {
        my $self = {
            NAMESPACE => $class,
            PACKAGE => __PACKAGE__,
        };
        $NAMESPACE->{$class} = bless($self, $class);
        my $objectManager = Anansi::ObjectManager->new();
        $objectManager->register($NAMESPACE->{$class});
        $NAMESPACE->{$class}->initialise(%parameters);
    } else {
        my $objectManager = Anansi::ObjectManager->new();
        $objectManager->register($NAMESPACE->{$class});
        $NAMESPACE->{$class}->reinitialise(%parameters);
    }
    return $NAMESPACE->{$class};
}


=head2 reinitialise

    $OBJECT->reinitialise();

    $OBJECT->SUPER::reinitialise();

=over 4

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

An object of this namespace.

=item parameters I<(Hash, Optional)>

Named parameters.

=back

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

=cut


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


=head1 NOTES

This module is designed to make it simple, easy and quite fast to code your
design in perl.  If for any reason you feel that it doesn't achieve these goals
then please let me know.  I am here to help.  All constructive criticisms are
also welcomed.

=cut


=head1 AUTHOR

Kevin Treleaven  treleaven I net>

=cut


1;