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


package PSGConf::Data::String;

use strict;

use PSGConf::Data;

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


###############################################################################
###  equals() method (for conditional expressions)
###############################################################################

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

#	print "==> equals(" . ref($self) . "='$self->{value}', '$value')\n";

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

	return ($self->get() eq $value);
}


###############################################################################
###  match() method (for conditional expressions)
###############################################################################

sub match
{
	my ($self, $regex) = @_;

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

	return ($self->get() =~ m/$regex/i);
}


###############################################################################
###  set() method
###############################################################################

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

#	print "==> String::set($value)\n";

	if (defined($value))
	{
		die "non-scalar value specified for string variable\n"
			if (ref($value));

		die "value must be absolute path\n"
			if ($self->{value_abspath}
			    && $value !~ m|^/|);
	}

	return $self->SUPER::set($value);
}


###############################################################################
###  append() method - append new string to existing value
###############################################################################

sub append
{
	my ($self, $value) = @_;

	die "non-scalar value specified for string variable\n"
		if (defined($value) && ref($value));

	$self->set( $self->get() . $value );

	return 1;
}


###############################################################################
###  prepend() method - prepend new string to existing value
###############################################################################

sub prepend
{
	my ($self, $value) = @_;

	die "non-scalar value specified for string variable\n"
		if (defined($value) && ref($value));

	$self->set( $value . $self->get() );

	return 1;
}


###############################################################################
###  gsub() method - substring replacement
###############################################################################

sub gsub
{
	my ($self, $old, $new) = @_;
	my ($value);

	$value = $self->get();
	$value =~ s/$old/$new/g;
	$self->set($value);

	return 1;
}


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

1;

__END__

=head1 NAME

PSGConf::Data::String - string data type class for PSGConf

=head1 SYNOPSIS

  use PSGConf::Data::String;

  $psgconf->register_data(
		'stringobj'	=> PSGConf::Data::String->new()
	);

=head1 DESCRIPTION

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

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

=over 4

=item set()

Sets the object's value to its argument.  The value must be a scalar.

If the object was created with the I<value_abspath> attribute enabled,
the value must be an absolute path string.

If the object was created with the I<value_optional> attribute enabled,
the argument is optional; if missing, an empty string will be used
instead.

=item append()

Appends its argument to the object's value using string concatenation.

=item prepend()

Prepends its argument to the object's value using string concatenation.

=item gsub()

For each substring matching the first argument in the object's value,
substitutes the second argument.

=item equals()

Returns true if the argument equals the object's value.  The comparison
is done using the perl "eq" operator.

=item match()

Returns true if the object's value matches the argument.  The comparison
is done using the argument as a case-insensitive regular expression.

=back

=head1 SEE ALSO

L<perl>

L<PSGConf>

L<PSGConf::Data>

=cut