cifo/src/CifParser.cpp

/*
 * CifParser.cpp
 *
 * Copyright Notice: see copyright.txt
 *
 * Date: 3/8/2012 (D/M/Y)
 * Author: Dmitrij Lioubartsev
 * Email: dmitrijl42@gmail.com
 *
 * For class info, see CifParser.h
 */

#include "CifParser.h"
#include <cstdlib>
#include <cstring>
#include <fstream>
#include <vector>

CifParser::CifParser(CifCrystal* structure) {
	crystal = structure;
	line = 1;
}

CifParser::~CifParser() {
	// do nothing
}

/*
 * Tries to open the file with the specified filename.
 * If file doesn't exist, returns false.
 */
bool CifParser::opencif(const char * fileName) {
	cifFile.open(fileName);
	if(cifFile)
		return true;
	else
		return false;
}

/*
 * Reads the file opened by opencif, and puts all
 * information into the CifCrystal pointed by the
 * specified variable crystal.
 */
void CifParser::readcif() {

	bool saveFrame = false; //to indicate if in a save frame
	//only used for some warning messages, since this program doesn't
	// change the contains of the file.

	bool dataBlock = false; //to indicate if inside a data block
	//if data found outside of data block, it is still read, but
	//a warning message is printed.

	bool fulhax = false; //this is to fix a weird bug with not
						//recognizing eof for some reason.

	while(!cifFile.eof()) { //main parsing loop

		if(fulhax)
			break;

		//skip all whitespaces
		//Whitespace characters are ' ', '\t', '\n' and comments (#)
		if(skipWhiteSpace())
			break; //found eof, stop

		string token("");

		if(getWord(token)) //get next token (word)
			break;

		/*
		 * Now, token can be one of these things:
		 * 1. data block header, in that case it starts with data_
		 * 			-> set dataBlock = true
		 * 2. Save Frame header, begins with "save_"
		 * 			-> do nothing (except warning messages)
		 * 3. Save frame end, is "save_"
		 * 			-> do nothing (except warning messages)
		 * 4. Data tag, begins with '_'
		 * 			-> fetch value
		 * 5. Loop, begins with "loop_"
		 * 			-> fetch loop data values
		 * 6. Something else, in which case there is an error
		 */

		if(beginsWith(token.c_str(), "data_")) { //case 1, datablock
			dataBlock = true;
		} else if(beginsWith(token.c_str(),"save_")) { //cases 2-3, save frame

			if(!dataBlock) {
				cout << "(line " << line << ") WARNING: A Save Frame "
						<< "token is found outside a datablock. It is "
						<< "still read, but its advised that the file "
						<< "gets repaired." << endl;
			}

			//For the program, the following code isn't important, but
			//it will give the user a notification if incorrect usage
			//of save frames is found. It does not have any impact on
			//the functioning of this program.

			if(!saveFrame && token.length() > 5) { //save frame header
				saveFrame = true;
			} else if(!saveFrame && token.length() == 5) { //save frame end without it being initialized
				cout << "(line " << line << ") WARNING: Save Frame header has no name."
						" Ignoring." << endl;
				saveFrame = true;
			} else if(saveFrame && token.length() > 5) { //found save frame inside a save frame
				cout << "(line " << line << ") WARNING: Save Frames inside Save Frames"
						" are not allowed. Ignoring." << endl;
			} else if(saveFrame && token.length() == 5 ) { //save frame end.
				saveFrame = false;
			}

		} else if((token[0] == '_') && token.length() > 1) { // case 4, data item

			if(!dataBlock) {
				cout << "(line " << line << ") WARNING: A Data Item "
						<< "token is found outside a datablock. It is "
						<< "still read, but its advised that the file "
						<< "gets repaired." << endl;
			}


			if(skipWhiteSpace()) { //skip the whitespace after the tag
				cout << "(line " << line << ") WARNING: Data item { "
						<< token << " } does not have an assigned data "
						<< "value. Ignoring item." << endl;
				break;
			}

			char ch;
			ch = cifFile.peek();
			if(ch == '_' || ch == '$' || ch == '|') {
				cout << "(line " << line << ") WARNING: Data item { "
						<< token << " } does not have an assigned data "
						<< "value, or the value starts with a forbidden "
						<< "starting character ('_','$','|'). Ignoring "
						<< "data tag." << endl;

			} else {
				string value("");
				getValue(value); //get value
				ifReservedReset(value); //check if its a reserved word
				setDataItem(token, value); //set data item
			}

		} else if(beginsWith(token.c_str(),"loop_")) { //case 5, loop
			if(!dataBlock) {
				cout << "(line " << line << ") WARNING: A Loop "
						<< "token is found outside a datablock. It is "
						<< "still read, but its advised that the file "
						<< "gets repaired." << endl;
			}

			if(skipWhiteSpace()) {
				cout << "(line " << line << ") WARNING: A Loop "
					<< "token is found but nothing after it."<< endl;
				break;
			}

			if(!(cifFile.peek() == '_')) {
				cout << "(line " << line << ") WARNING: A Loop "
					<< "token is found but no data tags found "<< endl;
				continue;
			}

			//parse loop data tags

			vector<string> tokens(0); //vector that holds data tags.
			while(cifFile.peek() == '_') { //while there are tags
				string token = "";

				if(getWord(token)) //get tag
					break;

				tokens.push_back(token); //add to tag vector

				if(skipWhiteSpace()) //skip whitespaces.
					break;
			}
			if(cifFile.eof()) {
				cout << "(line " << line << ") WARNING: A loop is "
					"initialized but end of file is reached before "
					"any values were found. Ignoring everything in "
					"the loop body." << endl;
				break;
			}

			//Loop header parsed, all data tags are in vector "tokens"
			unsigned long int vals = 0; //to keep track of which tag to add the value to
			string value("");

			while(!cifFile.eof()) {
				char c = cifFile.peek();
				if((c == '_') || (c == '$') || c == '|') {
					break; //loop over
				}

				getValue(value);
				if(ifReservedReset(value)) { //if value is a reserved word
					break;
				} else {
					setDataItem(tokens[vals % tokens.size()], value); //set data item
					vals++; //increment vals
					if(skipWhiteSpace()) {//and skip whitespaces to next value
						fulhax = true;
						break;
					}
				}

			}

			if((vals % tokens.size()) != 0 ) {
				cout << "(line " << line << ") WARNING: a loop was "
						"terminated but amount of values does not "
						"go even, and thus not enough values was "
						"read, which may or may not cause problems." << endl;
			}

		} else if(beginsWith(token.c_str(),"global_")){ // part of case 6, since global_ is forbidden
			cout << "(line " << line << ") WARNING: usage of the \"global_\" keyword "
					<< "is forbidden by .cif standards. Ignoring." << endl;
		} else { //case 6, file syntax error
			cout << "(line " << line << ") WARNING: found unknown token { "
					<< token << " }. Ignoring." << endl;
		}
	}
	return;
}

/*
 * Checks if c is a whitespace char ('\t', ' '),
 * but not end of line.
 */
bool CifParser::isWhiteSpace(char c) {
	return (c == ' ') || (c == '\t'); //11 is ASCII for tab '\t', 12 is new line '\n'
}

/*
 * Checks if c is a whitespace char ('\t', ' ', \n).
 */
bool CifParser::isWhiteSpaceNL(char c) {
	return (c == ' ') || (c == '\t') || (c == '\n') || (c == '\r'); //11 is ASCII for tab '\t', 12 is new line '\n'
}

/*
 * Skips through all whitespace characters and comments, and leaves
 * the file stream at the next token. White space characters are
 * ' ', '\t', '\n' and comments start with '#' and continue until
 * a '\n' character is found.
 * The integer "line" is incremented each time a '\n' is found.
 * If eof found, returns true.
 */
bool CifParser::skipWhiteSpace() {
	char c = ' ';

	bool eof = false;
	while((isWhiteSpaceNL(c) || c == '#') && !cifFile.eof()) {
		cifFile.get(c); //get next char
		if(cifFile.eof()) {
			eof = true;
			break; //reached end of file, stop
		}
		//some special cases
		if(c == '\n') { //new line
			line++;
		} else if(c == '#') { //comment
			cifFile.ignore(CIF_MAX_LINE_LENGTH, '\n'); // ignore rest of line.
			line++; //increment line
			if(cifFile.eof())
				eof = true;
		}

	}

	cifFile.unget(); //put the char from get() back.

	return eof;
}

/*
 * Similar to the skipWhiteSpace, it extracts all characters found
 * and puts them in word. It stops when a whitespace character is found.
 * If eof found, returns true.
 */
bool CifParser::getWord(string& word) {
	bool eof = false;
	char c;
	word = "";
	do {
		cifFile.get(c);
		if(cifFile.eof()) {
			//reached end of file, stop
			eof = true;
			break;
		}
		word.append(1, c);
	}
	while(!isWhiteSpaceNL(c));

	if(!eof) { //reset last char
		cifFile.unget();
		word.erase(word.length()-1,1);
	}

	return eof;
}

/*
 * beginsWith() checks if "what" begins with "with".
 * "with" should be lowercase, because the test
 * is case-insensitive (uses toUpper() ).
 * Example use: beginsWith(myString, "data_")
 */
bool CifParser::beginsWith(const char * what, const char* with) {

	if(strlen(with) > strlen(what))
		return false;

	bool correct = true; //the return variable
	int i = 0; //byte counter

	while(correct && with[i]) { // only continue tests while still equal, and
								// end of comparing string isn't reached
		if(!((what[i] == with[i]) || (what[i] == toupper(with[i]))))
			correct = false;

		i++;
	}

	return correct;
}

/*
 * Extracts a value, as defined by cif standards,
 * and puts it into "value".
 * If eof found, returns true.
 */
bool CifParser::getValue(string& value) {
	bool eof = false;
	value = "";

	//try to identify the type of the value
	char c = (char) cifFile.peek();

	if(c == '\'') { //single-quote string
		if(getQuoteValue(value, '\''))
			eof = true;

	} else if(c == '\"') { //double-quote string
		if(getQuoteValue(value, '\"'))
			eof = true;
	} else if(c == ';') { //text field OR unquoted string
		//check last char, if its '\n' then its a text field
		cifFile.unget();
		cifFile.get(c);
		if(c == '\n') { //we have ourselves a text field
			cifFile.ignore(2); //ignore the '\n'
								//and ignore the ;
			if(cifFile.eof()) { //if eof is after the ;
				cout << "(line " << line << ") WARNING: End of file reached, "
						"immediatly after a text field was initialized. Value "
						"of last token is therefore set to \"?\" (unknown)." << endl;
				value = "?";
				eof = true;
				return eof;
			}

			bool finished = false;
			while(!finished) { //main loop of parsing text field data
				cifFile.get(c);

				if(cifFile.eof()) { //if suddenly eof
					cout << "(line " << line << ") WARNING: End of file reached "
							"before the text field data value was properly terminated."
							" Value is still read until that point, but "
							"it is advised to repair the file." << endl;
					eof = true;
					break;
				}

				if(c == '\n') { //if read char is end of line
					line++;     //increment line
					char ch = (char) cifFile.peek();
					if(ch == ';') { //and terminate if a ';' is found at start of line
						finished = true;
						cifFile.ignore(); //ignores the ';'
					} else {
						value.append(1,c); //otherwise appends the '\n'
					}
				} else {
					value.append(1,c); //if not a '\n', just append
				}
			}

		} else { //a single unquoted string
			// this assumes that ; is included in the value
			if(getWord(value))
				eof = true;
		}

	} else { //unquoted string, a word continues until whitespace
		if(getWord(value))
			eof = true;

	}

	return eof;
}

/*
 * This is solely a helper method used by getValue, to avoid duplicating
 * very similar code. It extracts a single quote value or a double quote value,
 * depending on what is specified.
 * If eof found, returns true.
 */
bool CifParser::getQuoteValue(string& value, const char quote) {
	cifFile.ignore(); //ignore first quote.
	bool finished = false;
	bool eof = false;
	char c;

	//main loop
	while(!finished) {
		cifFile.get(c); //get char
		if(cifFile.eof()) { //in case eof was reached
			if(!(c == quote)) {
				if(!(c == '\n'))
					value.append(1, c);
				cout << "(line " << line << ") WARNING: Quote data value did not "
						"terminate before end of file was reached. Ignoring." << endl;
			}
			eof = true;
			break;
		}

		if(c == '\n') { //if line break is found.
			//print an error message and increment line.

			cout << "(line " << line << ") WARNING: Single and double quote "
					"data values are not permitted to extend over "
					"multiple lines. Value is read until the end of this "
					"line, which might lead to bad results. "
					"Suggesting usage of a text field instead." << endl;
			line++;
			break;
		}

		//normal procedure, all above is basically error handling
		if(c == quote && isWhiteSpaceNL(cifFile.peek())) {
			finished = true; //end of value found
		} else {
			value.append(1, c); //else append
		}
	}

	return eof;

}

/*
 * Assigns the data item with the given header and
 * value. If the value is "unknown" ('.','?'), nothing happens.
 */
void CifParser::setDataItem(string& token, string& value) {

	if(value != "." && value != "?") {

	if(token == "_cell_length_a") {
		if(!((*crystal).seta(atof(value.c_str())))) {
			printErrorAS("_cell_length_a");
		}
		/*
		 * To explain this above which looks very complicated:
		 * 1. Follow the CifCrystalPointer, to set its 'a' field.
		 * 2. The value to set it to is calculated by std::atof().
		 * 3. atof() does only take a c string, so need to convert.
		 * 4. seta() returns false if the value has already been
		 * 		assigned, meaning that the tag "_cell_length_a" is
		 * 		appearing multiple times in the file. If so, print
		 * 		a warning message.
		 */

	} else if(token == "_cell_length_b") {
		if(!((*crystal).setb(atof(value.c_str())))) {
			printErrorAS("_cell_length_b");
		}
	} else if(token == "_cell_length_c") {
		if(!((*crystal).setc(atof(value.c_str())))) {
			printErrorAS("_cell_length_c");
		}
	} else if(token == "_cell_angle_alpha") {
		if(!((*crystal).setalpha(atof(value.c_str())))) {
			printErrorAS("_cell_angle_alpha");
		}
	} else if(token == "_cell_angle_beta") {
		if(!((*crystal).setbeta(atof(value.c_str())))) {
			printErrorAS("_cell_angle_beta");
		}
	} else if(token == "_cell_angle_gamma") {
		if(!((*crystal).setgamma(atof(value.c_str())))) {
			printErrorAS("_cell_angle_gamma");
		}
	} else if(token == "_symmetry_equiv_pos_as_xyz"
			|| token == "_space_group_symop_operation_xyz") {
		(*crystal).addSymmetry(value); //simply add the symmetry

	} else if(token == "_atom_site_type_symbol") {
		(*crystal).setAElement(value);
	} else if(token == "_atom_site_fract_x") {
		(*crystal).setAx(atof(value.c_str()));
	} else if(token == "_atom_site_fract_y") {
		(*crystal).setAy(atof(value.c_str()));
	} else if(token == "_atom_site_fract_z") {
		(*crystal).setAz(atof(value.c_str()));
	} else {
		//do nothing
	}

	}

	return;
}

/*
 * This takes the string value, and checks if it
 * is a reserved word (data_,loop_ etc.). If it is, it
 * sets back the cifFile pointer to the beginning of
 * the word, and sets the value to "?" (unknown).
 */
bool CifParser::ifReservedReset(string& value) {
	if(beginsWith(value.c_str(), "data_") ||	//not allowed to be a value.
		beginsWith(value.c_str(), "save_") ||
		beginsWith(value.c_str(), "loop_") ||
		beginsWith(value.c_str(), "global_")) {

		for(unsigned int i = 0; i < value.length(); i++) {
			cifFile.unget(); //unget the amount of characters got.
		}
		/*
		 * This below is another way of fixig the above.
		while(!isWhiteSpaceNL(cifFile.peek())) {
			cifFile.unget();
		}
		cifFile.ignore();*/

		value = "?"; //set value to unknown
		return true;
	} else {
		return false;
	}
}

/*
 * This is a small helper method to indicate that the
 * data value has already been assigned (multiple
 * instances of a data tag found). "value" should be
 * something like "_cell_length_a"
 */
void CifParser::printErrorAS(const char * value) {
	cout << "(line " << line << ") WARNING: data item "
			" {" << value << " } has been found "
			"multiple times in the file. Using the "
			"first encountered value. " << endl;
}