Chemistry::ESPT::ESSfile - Generic Electronic Structure Suite (ESS) file object.

    package Chemistry::ESPT::MyFile;
    use base qw(Chemistry::ESPT::ESSfile);

    package Main;
    my $object = Chemistry::ESPT::MyFile->new();
    $object->prepare(filename);

package	Chemistry::ESPT::ESSfile;

use strict;
use warnings;

our $VERSION = '0.03';

## the object constructor **
        
sub new {
        my $invocant = shift;
        my $class = ref($invocant) || $invocant;
        my $ESSfile = {};

	# Generating ESS
	$ESSfile->{PROGRAM} = undef;

	# File type (log, out, fchk, etc.)
	$ESSfile->{TYPE} = undef;

	# Analysis info
	$ESSfile->{DEBUG} = 0;
        $ESSfile->{FILENAME} = undef;
        $ESSfile->{SPIN} = undef;

        # Calculation info
	$ESSfile->{BASIS} = undef;
	$ESSfile->{CHARGE} = undef;		# total molecular charge
	$ESSfile->{COMPLETE} = 0;		# flag indicating job completion
	$ESSfile->{EINFO} = undef;		# string description of ENERGY
	$ESSfile->{ENERGY} = undef;		# total energy
	$ESSfile->{JOBTYPE} = undef;		# type of calculation performed
	$ESSfile->{MULTIPLICITY} = undef;	# 2S+1
	$ESSfile->{NBASIS} = undef;
	$ESSfile->{THEORY} = undef;
	$ESSfile->{TIME} = [ 0, 0, 0, 0 ]; 	# Total computation time in days [0], hours [1], minutes [2], seconds [3]
	$ESSfile->{TITLE} = undef;	

	# Molecular info
	$ESSfile->{ALPHA} = undef;
	$ESSfile->{ATOMS} = undef;
	$ESSfile->{BETA} = undef;
	$ESSfile->{NATOMS} = undef;
	
	
	bless($ESSfile, $class);
	return $ESSfile;
}


### Methods ###

# set filename, spin, & debug options 
sub prepare : method {
        my $ESSfile = shift;
        $ESSfile->{FILENAME} = shift;
        $ESSfile->{SPIN} = shift;
        $ESSfile->{SPIN} ||= "Alpha";
        return;
}

# Convert atomic numbers to atomic symbols
sub atomconvert : method {
	shift; # remove object reference
	my (@num2sym, %sym2num);
	
	#populate atomic symbols
	@num2sym = ("H", "He", "Li", "Be", "B", "C", "N", "O", "F", "Ne");
	push @num2sym, ("Na", "Mg", "Al", "Si", "P", "S", "Cl", "Ar");
	push @num2sym, ("K", "Ca", "Sc", "Ti", "V", "Cr", "Mn", "Fe", "Co", "Ni", "Cu", "Zn", "Ga", "Ge", "As", "Se", "Br", "Kr");
	push @num2sym, ("Rb", "Sr", "Y", "Zr", "Nb", "Mo", "Tc", "Ru", "Rh", "Pd", "Ag", "Cd", "In", "Sn", "Sb", "Te", "I", "Xe");
	push @num2sym, ("Cs", "Ba", "La", "Ce", "Pr", "Nd", "Pm", "Sm", "Eu", "Gd", "Tb", "Dy", "Ho", "Er", "Tm", "Yb", "Lu");
	push @num2sym, ("Hf", "Ta", "W", "Re", "Os", "Ir", "Pt", "Au", "Hg", "Tl", "Pb", "Bi", "Po", "At", "Rn");
	push @num2sym, ("Fr", "Ra", "Ac", "Th", "Pa", "U", "Np", "Pu", "Am", "Cm", "Bk", "Cf", "Es", "Fm", "Md", "No", "Lr");
	push @num2sym, ("Rf", "Db", "Sg", "Bh", "Hs", "Mt", "Ds", "Rg", "Uub", "Uut", "Uuq", "Uup");
	
	for (my $i=0; $i<scalar(@num2sym); $i++){
		$sym2num{$num2sym[$i]} = $i+1;
	}
	$sym2num{D} = $sym2num{T} = 1;

	my $value = shift;
	
	# determine what was passed and return the opposite
	if ( $value =~ /^[a-zA-Z]+\Z/ ){
		return $sym2num{$value};
	} else {
		if ( $value <= $#num2sym ) {
			return $num2sym[$value - 1];
		} else {
			return $value;
		}
	}
}

sub debug : method {
	my $ESSfile = shift;

	my $debug = shift;

	if (defined $debug && $debug =~ /\d+/ ) {
		$ESSfile->{DEBUG} = $debug;
		return;
	} else {
		return $ESSfile->{DEBUG};
	}
}

# retrieve values. for array data the last element is returned
# unless otherwise requested
sub get : method {
        my $ESSfile = shift;

        # required parameters : value
        my $value = shift;
	print "Get method called for ", $value, "\n" if $ESSfile->{DEBUG} >= 4;

        # optional parameters : index values
	my @index = @_;

        # warn if requested property is not coded & return empty string
        my $valid = 0;
        foreach my $p ( keys %$ESSfile ) {
                if ( $value eq $p ) {
			$valid = 1;
	        	last;
		} elsif ( $value eq "DEBUG" ) {
			$valid = 2;
			last;
		}
			
        }
        if ( $valid == 0 ) {
                warn "Requested property, $value, is not currently coded.\n$!\n" if $ESSfile->{DEBUG} == 1;
                return "";
        } elsif ( $valid ==2 ) {
		warn "Please use the debug() method to access the DEBUG attribute.\n$!\n";
		return "";
	}

	# build hard reference 
	my $reference = \$ESSfile->{$value};

        # undef if no scalar value is present
        return "undef" unless ( defined $ESSfile->{$value} );

        # check for  multidimensional array in a nested
        # manner to avoid autovivification problems.
        my $i =0;
	while ( ref $$reference eq "ARRAY" ) {
	  # get array length
          $index [$i] ||= scalar(@{$$reference}) - 1 unless ( defined $index[$i] );
       	  return "undef" unless ( defined @{$$reference} [$index[$i]] );

	  # update reference 
	  $reference = \@{$$reference} [$index[$i]];       
	  return $$reference unless ( ref $$reference eq "ARRAY" );
	  $i++;
      	}

	# scalar values	
	return $$reference;

}

# decode homo, shomo & lumo 
# correct for arrays starting with 0 
sub MOdecoder : method  {
        my $ESSfile = shift;
        my $MO = lc(shift);

        if ($MO eq "homo") {
                return $ESSfile->{HOMO} - 1;
        } elsif ($MO eq "lumo") {
                return $ESSfile->{HOMO};
        } elsif ($MO eq "shomo") {
                return $ESSfile->{HOMO} - 2;
        } else {
                return $MO - 1;
        }
}

### Utilities ###

sub printattributes : method {
	# print out object attributes
	my $ESSfile = shift;
        foreach my $p ( sort keys %$ESSfile ) {
		print "$p\n";
        }

}


1;
__END__