Bio::MAGE::Base - generic base class

  use Bio::MAGE::Base;

  # create an empty instance
  my $obj = Bio::MAGE::Base->new();

  # create an instance and populate with data
  my $obj = Bio::MAGE::Base->new(attr1=>$val1, attr2=>$val2);

  # copy an existing instance
  my $obj_copy = $obj->new();

##############################
#
# Bio::MAGE::Base
#
##############################
# C O P Y R I G H T   N O T I C E
#  Copyright (c) 2001-2006 by:
#    * The MicroArray Gene Expression Database Society (MGED)
#
# Permission is hereby granted, free of charge, to any person
# obtaining a copy of this software and associated documentation files
# (the "Software"), to deal in the Software without restriction,
# including without limitation the rights to use, copy, modify, merge,
# publish, distribute, sublicense, and/or sell copies of the Software,
# and to permit persons to whom the Software is furnished to do so,
# subject to the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
# BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
# ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.



package Bio::MAGE::Base;

use strict;
use Carp;

sub new {
  my $class = shift;
  my $obj;
  if (ref($class)) {
    # copy an existing object
    $obj = $class;
    $class = ref($class);
  }
  my $self = bless {}, $class;
  if (defined $obj) {
    $self->set_slots([$obj->get_slot_names],
                     [$obj->get_slots($obj->get_slot_names)],
                    );
  } else {
    $self->set_slots(@_) if @_;
  }
  my $rc = $self->initialize;
  return undef if $rc == -1;
  return $self;
}

sub __get_superclass {
  my $class = shift;

  {
    no strict 'refs';
    my $var = $class . '::ISA';
    my @isa = @$var;
    if (scalar @isa) {
      return $isa[0];
    } else {
      return undef;
    }
  }
}

sub __get_slot_array {
  my $class = shift;
  my $slot_name = shift;

  # allow the $obj->method() syntax
  $class = ref($class) if ref($class);
  {
    no strict 'refs';
    my $var = $class . '::' . $slot_name;
    my $val = $$var;
    while (not defined $val) {
      $class = $class->__get_superclass($class);
      last unless defined $class;
      $var = $class . '::' . $slot_name;
      $val = $$var;
    }

    if (defined $val) {
      return @{$val};
    } else {
      return ();
    }
  }
}

sub __get_slot_val {
  my $class = shift;
  my $slot_name = shift;

  # allow the $obj->method() syntax
  $class = ref($class) if ref($class);
  {
    no strict 'refs';
    my $var = $class . '::' . $slot_name;
    my $val = $$var;
    while (not defined $val) {
      $class = $class->__get_superclass($class);
      last unless defined $class;
      $var = $class . '::' . $slot_name;
      $val = $$var;
    }

    return $val;
  }
}

sub get_slot_names {
  my $class = shift;
  return $class->__get_slot_array('__SLOT_NAMES');
}

sub get_attribute_names {
  my $class = shift;
  return $class->__get_slot_array('__ATTRIBUTE_NAMES');
}

sub get_association_names {
  my $class = shift;
  return $class->__get_slot_array('__ASSOCIATION_NAMES');
}

sub get_superclasses {
  my $class = shift;
  return $class->__get_slot_array('__SUPERCLASSES');
}

sub get_subclasses {
  my $class = shift;
  return $class->__get_slot_array('__SUBCLASSES');
}

sub class_name {
  my $class = shift;
  return $class->__get_slot_val('__CLASS_NAME');
}

sub package_name {
  my $class = shift;
  return $class->__get_slot_val('__PACKAGE_NAME');
}

sub associations {
  my $class = shift;

  # allow the $obj->method() syntax
  $class = ref($class) if ref($class);
  my @list = ();

  # superclasses first
  my @superclasses = $class->get_superclasses();
  foreach my $super (@superclasses) {
    push(@list, $super->associations());
  }

  # then associations from this class
  push(@list, $class->__get_slot_array('__ASSOCIATIONS'));

  return @list;
}

#
# see above in new()
#

sub set_slots {
  my $self = shift;
  my %slots;
  if (ref($_[0])) {
    my @slot_names = @{shift()};
    my @slot_values = @{shift()};
    @slots{@slot_names} = @slot_values;
  } else {
    %slots = @_;
  }
  while (my ($slot_name,$slot_val) = each %slots) {
    $self->set_slot($slot_name,$slot_val);
  }
}

sub get_slots {
  my ($self, @slot_names) = @_;
  my @return;
  foreach my $slot (@slot_names) {
    push(@return,$self->get_slot($slot));
  }
  return @return;
}

sub set_slot {
  my ($self, $slot_name, $slot_val) = @_;
  my $method = 'set' . ucfirst($slot_name);
  unless ($self->can($method)) {
    unless ($self->can($slot_name)) {
      croak(__PACKAGE__ . "::set_slot: slot $slot_name doesn't exist");
    }
    # this is a class slot, not an attribute or association. They still
    # use the confusing polymorphic setter/getter methods.
    $method = $slot_name;
  }
  {
    no strict 'refs';
    # invoke the setter directly to gain type checking
    return $self->$method($slot_val);
  }
}

sub get_slot {
  my ($self, $slot_name) = @_;
  my $method = 'get' . ucfirst($slot_name);
  unless ($self->can($method)) {
    unless ($self->can($slot_name)) {
      croak(__PACKAGE__ . "::get_slot: slot $slot_name doesn't exist");
    }
    # this is a class slot, not an attribute or association. They still
    # use the confusing polymorphic setter/getter methods.
    $method = $slot_name;
  }
  {
    no strict 'refs';
    # invoke the getter directly
    return $self->$method();
  }
}


sub initialize {
  return 1;
}

sub throw {
   my ($self, $msg) = @_;

   die(caller().': '.$msg);
}

sub throw_not_implemented {
   my ($self) = @_;

   die("Abstract method ".caller()." implementing class did not provide method");
}

# all perl modules must be true...
1;