###
###  Copyright 2000-2007 University of Illinois Board of Trustees
###  All rights reserved. 
###
###  PSGConf::Data::Enum - Enumerated data type for PSGConf
###
###  Campus Information Technologies and Educational Services
###  University of Illinois at Urbana-Champaign
###


package PSGConf::Data::Enum;

use strict;

use PSGConf::Data;

our @ISA = qw(PSGConf::Data);


###############################################################################
###  utility function to interpret the defined enumerated values
###############################################################################

sub _enum
{
	my ($self, $key) = @_;

	# Lower case the value so we are case independent.
	$key = lc ($key);

	if ( exists $self->{values}->{$key} )
	{
		return $self->{values}->{$key};
	}

	if ( $key eq '' && exists $self->{'default'} )
	{
		return $self->{'default'};
	}

	die "non-enum value '$key' specified for enumerated variable\n";
}


###############################################################################
###  set method
###############################################################################

sub set
{
	my ($self, $key) = @_;

	$self->SUPER::set($self->_enum($key));

}


###############################################################################
###  equals method
###############################################################################

sub equals
{
	my ($self, $key) = @_;

	warn "comparing to \"$key\" when object is undefined\n"
		if ( ! defined $self->get() );

	return ($self->get() == $self->_enum($key));
}

###############################################################################
###  constructor
###############################################################################
     
sub new
{
     my ($class, %opts) = @_;
     my ($self);

     $self = {};
     bless($self, $class);

	for (my ($row) = 0; $row < scalar @{$opts{values}}; $row++) {
		map {
			$self->{values}->{lc($_)} = $row;
		} @{$opts{values}->[$row]};
	}

	$self->{'default'} = $self->_enum($opts{'default'})
		if ( defined $opts{'default'} );

	$self->set($opts{'value'})
		if ( defined $opts{'value'} );

     return $self;
}

###############################################################################
###  documentation
###############################################################################

1;

__END__

=head1 NAME

PSGConf::Data::Enum - enumerated data type class for PSGConf

=head1 SYNOPSIS

  use PSGConf::Data::Enum;

  $psgconf->register_data(
		'object'	=> PSGConf::Data::Enum->new(
					default =>	'yes',
					values =>		[ [ 'enable', 'yes' ]
					  			  [ 'disable', 'no' ]
					  			  [ 'Unmanaged', 'ignore' ] ]
				)
	);

=head1 DESCRIPTION

The B<PSGConf::Data::Enum> module provides a class that
represents a enumerated value in an object so that it can be 
used with B<PSGConf>.  Its methods can be used to manipulate the
encapsulated enumerated value from the B<PSGConf> data store(s).

The B<PSGConf::Data::Enum> class is derived from the
B<<PSGConf::Data> class, but it defines/overrides the
following methods:

=over 4

=item new()

Defines the valid values the enumerated type can hold.  It will
take a list of equal values.  The enumerated names are stored 
in lower case, so the enum type is case insensitive.

=item set()

Sets the object's value to the supplied value.  The value must be one
of the values defined when the constructor was called.  In the example
above, that is "Enable", "Disable", or Unmanaaged".  The "default" is
a special case.

=item equals()

Returns true if the argument equals the object's value.  If the argument
is not defined, it is treated to what ever C<default> is defined as.

=back

=head1 SEE ALSO

L<perl>

L<PSGConf>

L<PSGConf::Data>

=cut