NAME

Object::Generic - A generic base class that allows storage of key/value pairs.

SYNOPSIS

  use Object::Generic;
  $thing = new Object::Generic  color => 'red';

  $color = $thing->get('color');
  $color = $thing->get_color;
  $color = $thing->color;

  $thing->set( color => 'blue' );
  $thing->set_color('blue');
  $thing->color('blue');

  $thing->remove('color');

  @key_list  = $thing->keys;
  $has_color = $thing->exists('color');

  package myClass;
  use base 'Object:Generic';
  myClass->set_allowed_keys('color', 'width', 'height', 'border');
  sub myMethod {
    my $self=shift;
    $self->args(@_);    # processes @args=(key=>value, key=>value, ...)
    print $self->width;
  }

  package otherClass;
  use base 'Object::Generic';
  otherClass->define_accessors(qw( name age weight ));
  my $guy = new OtherClass;
  $guy->name('Jim');  
  print "his name is " . $guy->name . "\n";

  package main;
  use myClass;
  $obj = new myClass color => 'green', width => 5;
  $usa = new Object::Generic language=>'english', hemisphere=>'north';
  $obj->set_country($usa);             # fails; 'country' not an allowed key.
  if ($obj->country->language){ ... }  # false, but isn't an error.
  $obj->myMethod( width => 10 );
  $obj->border(10) if $obj->allows_key('border');
  print $obj->border;

DESCRIPTION

This package defines an object that lets key/value pairs be stored and fetched with either the typical $obj->set_key('value') and $obj->get_key() syntax, or with a Class::DBI-ish $obj->key('value') and $obj->key syntax.

The keys may be but do not need to be declared ahead of time. Any previously undefined method invoked on an instance of Object::Generic defines a possible key.

The methods 'exists' and keys' serve the same purpose as the perl functions exists(%hash{key}) and keys(%hash).

Class methods, methods that try to fetch a value that has never been defined, and keys that aren't allowed all return an Object::Generic::False which is false in a boolean context but which allows error chaining without a fatal error. In other words, even though $obj->foo is not defined, $obj->foo->bar->baz returns false (well, an Object::Generic::False) rather than crashing.

A number of key/value pairs may be defined all at once with the built-in $obj->args( key1=>'value1', key2=>'value2') method.

The Object::Generic class may be used as a base class; by default any methods in the inherited class that aren't defined will be treated as keys.

As an alternative to having the accessor subroutines (e.g. $object->name, $object->set_name, $object->get_name for key='name') defined by AUTOLOAD the first time they're invoked, they may be created explicitly with a call to $class->define_accessors(@keys). This also calls $class->set_allowed_keys(@keys), which means that trying to access keys that aren't explicitly allowed will give an error. One advantage to defining the accessors explicitly is that multiple inheritence is easier, since the Object::Generic::AUTOLOAD isn't needed.

BUGS

This should be in the Class:: namespace somewhere. Oops.

SEE ALSO

Object::Generic::False, Object::Generic::Session, Class::DBI

AUTHOR

Jim Mahoney, <mahoney@marlboro.edu<gt>

COPYRIGHT AND LICENSE

Copyright (C) 2005 by Jim Mahoney

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.