##---------------------------------------------------------------------------##
##  File:
##      @(#) CfgFile.pm 1.1 97/12/12 14:05:45 @(#)
##  Author:
##      Earl Hood       ehood@medusa.acs.uci.edu
##  Description:
##	Class for supporting the loading of a configuration file.
##	More explanation at end of source file.
##---------------------------------------------------------------------------##
##  Copyright (C) 1997   	Earl Hood, ehood@medusa.acs.uci.edu
##
##  This program is free software; you can redistribute it and/or modify
##  it under the terms of either:
##
##	a) the GNU General Public License as published by the Free
##	   Software Foundation; either version 2, or (at your option)
##	   later version, or
##
##	b) the "Artistic License" which comes with Perl.
##---------------------------------------------------------------------------##

package CfgFile;

use Exporter ();
@ISA = qw ( Exporter );
@EXPORT = ();
@EXPORT_OK = ();
$VERSION = "0.0.1.1";

##---------------------------------------------------------------------------##

use Carp;
use FileHandle;

###############################################################################
##	Public Class Methods
###############################################################################

##---------------------------------------------------------------------------##
##	Constructor
##
##	Usage:
##	    $conf = new CfgFile $filename;
##	Return:
##	    If no errors, and object reference.  Else undef.
##
sub new {
    my $this	= { };
    my $mod	= shift;	# Name of module
    my $file	= shift;	# Filename of template
    return undef   unless defined $file;

    my $type	= shift;	# Config file type
    my $class	= ref($mod) || $mod;

    bless $this, $class;
    return undef  unless $this->_read_file($file, $type);
    $this;
}

###############################################################################
##	Public Object Methods
###############################################################################

##---------------------------------------------------------------------------##
##	get_resource retrieves a value of a resource.
##
sub get_resource {
    my $this	=    shift;
    my $name	= lc shift;	# Name of resource

    $this->{resource}{$name};
}

##---------------------------------------------------------------------------##
##	get_resource_name_list returns a sorted list all resource
##	names.
##
sub get_resource_name_list {
    my $this	= shift;

    sort keys %{$this->{resource}};
}

###############################################################################
##	Private Object Methods
###############################################################################

##---------------------------------------------------------------------------##
sub _read_file {
    my $this	= shift;
    my $file	= shift;	# Filename
    my $type	= shift;	# Config file type

    my $fh = new FileHandle $file;
    if (not defined $fh) {
	carp qq(Unable to open "$file");
	return undef;
    }

    $this->{file} = $file;
    $this->{type} = $type;

    TYPESW: {
	# Default: name=value pairs
	$this->_read_nv($fh);
    }
    close $fh;
    1;
}

##---------------------------------------------------------------------------##
sub _read_nv {
    my $this	= shift;
    my $fh	= shift;

    while (<$fh>) {
	next  if /^\s*#/;
	next  unless /\S/;
	chomp;
	($name, $value) = split(/=/, $_, 2);
	$this->{resource}{lc $name} = $value;
    }
    1;
}

##---------------------------------------------------------------------------##
1;

__END__

Synopsis:
    
    use CfgFile;

    # Create a new object
    $conf = new CfgFile "file.cfg"

    # Get a resource value defined in configuration file
    $value = $conf->get_resource($resource);


Configuration File Syntax

    Currently, the only syntax is name=value pair format.  Example:

	PATH=/some/path/here
	name=John Doe
	E-Mail=jdoe@foo.org
	# This is a comment
	Foo=bar

    Blank lines are ignored.  Any line starting with the '#' character
    is also ignored.

    Resource names are case insensitive.  Hence, "FOO", "Foo", and
    "FoO" are all the same resource.  If the same resource occurs
    more than once in a file, then last one defined is used.

    Alternate configuration file syntax maybe added in the future.

End