BALL::GenericMolFile Class Reference
[Molecular structure file formats]

#include <BALL/FORMAT/genericMolFile.h>

Inheritance diagram for BALL::GenericMolFile:

[legend]

List of all members.

Public Member Functions
Constructors and Destructors
	GenericMolFile ()
	GenericMolFile (const String &filename, File::OpenMode open_mode=std::ios::in)
virtual	~GenericMolFile ()
Assignment
const GenericMolFile &	operator= (const GenericMolFile &rhs)
Reading and Writing of Kernel Datastructures
virtual bool	write (const System &system)
virtual bool	write (const Molecule &molecule)
virtual bool	read (System &system)
virtual Molecule *	read ()
Operators
virtual GenericMolFile &	operator>> (System &system)
virtual GenericMolFile &	operator<< (const System &system)
virtual GenericMolFile &	operator>> (Molecule &molecule)
virtual GenericMolFile &	operator<< (const Molecule &molecule)
Protected Member Functions
virtual void	initRead_ ()
virtual void	initWrite_ ()

---

Detailed Description

Base class for all molecule file format classes. This class provides an interface for all molecular structure formats (except for PDB files, due to their complex and capricious structure and contents).

GenericMolFile supports two type of operations: reading/writing single molecules and reading/writing systems (i.e. collections of molecules).

When reading molecules, the structures are read one at a time from the file in the order they are stored. In contrast, reading systems retrieves all structures contained in the file. For file formats that do not support multiple structure in a file (e.g. the MDL MOLFile ), those two operations are basically equivalent. A fundamental difference however is the fact that reading a molecule create a new molecule, whereas reading a system adds the molecules read to an existing instance of System . This implies that the system has to be cleared prior to reading a system if that incremental behaviour is not desired.

The user interface of the class is mainly provided through the stream operator. A typical example for reading a structure from a HyperChem file might look as follows:

{verbatim} HINFile hinfile(filename); System S; hinfile >> S; {verbatim} This interface applies to all derived classes as well, so that file formats can be exchanged conveniently.

GenericMolFile is derived from LineBasedFile since most molecular structure formats are line-based tagged formats, often containing Fortran-style formatted sections. LineBasedFile provides a number of convenient methods to parse that kind of format.

Definition at line 56 of file genericMolFile.h.

---

Constructor & Destructor Documentation

BALL::GenericMolFile::GenericMolFile

(

)

Default constructor

BALL::GenericMolFile::GenericMolFile	(	const String &	filename,
		File::OpenMode	open_mode = std::ios::in
	)

Detailed constructor

Exceptions:

Exception::FileNotFound

if the file could not be opened

virtual BALL::GenericMolFile::~GenericMolFile

(

)

[virtual]

Destructor

---

Member Function Documentation

virtual void BALL::GenericMolFile::initRead_

(

)

[protected, virtual]

Initialize internals for read. This method is called by the default implementation of read(System& system) . Its purpose is the initialization of internal members holding, for example, header information from the file. The default implementation provided is empty.

Reimplemented in BALL::GAMESSDatFile, BALL::GAMESSLogFile, and BALL::HINFile.

virtual void BALL::GenericMolFile::initWrite_

(

)

[protected, virtual]

Initialize internals for write. Same functionality as initRead , but is called prior to writing a system.

virtual GenericMolFile& BALL::GenericMolFile::operator<<

(

const Molecule &

molecule

)

[virtual]

Stream operator for writing a system of molecules. Calls write()

Exceptions:

File::CannotWrite

if writing to the file failed

Reimplemented in BALL::PDBFile.

virtual GenericMolFile& BALL::GenericMolFile::operator<<

(

const System &

system

)

[virtual]

Stream operator for writing a system of molecules. Calls write(const System& system) const .

Exceptions:

File::CannotWrite

if writing to the file failed

Reimplemented in BALL::PDBFile.

const GenericMolFile& BALL::GenericMolFile::operator=

(

const GenericMolFile &

rhs

)

Assignment operator. Create a new object pointing to the same filename.

Exceptions:

Exception::FileNotFound

if the file could not be opened

virtual GenericMolFile& BALL::GenericMolFile::operator>>

(

Molecule &

molecule

)

[virtual]

Stream operator for reading a molecule. Calls read()

Exceptions:

Exception::ParseError

if a syntax error was encountered

Reimplemented in BALL::PDBFile.

virtual GenericMolFile& BALL::GenericMolFile::operator>>

(

System &

system

)

[virtual]

Stream operator for reading a system. Calls read(System&) .

Exceptions:

Exception::ParseError

if a syntax error was encountered

Reimplemented in BALL::PDBFile.

virtual Molecule* BALL::GenericMolFile::read

(

)

[virtual]

Read a molecule. This method will load the first (or the next, on subsequent invocation) molecule from the file. If the file format does not support multiple molecules, only the first call to read will be successful. This method will create an instance of molecule and its the user's responsibility to destroy that molecule.

Returns:

a pointer to a molecule, 0 if the file was not open, empty, or at its end

Exceptions:

Exception::ParseError

if the contents of the file could not be parsed

Reimplemented in BALL::AntechamberFile, BALL::GAMESSDatFile, BALL::GAMESSLogFile, BALL::HINFile, BALL::KCFFile, BALL::MOL2File, BALL::MOLFile, BALL::PDBFile, BALL::SDFile, and BALL::XYZFile.

virtual bool BALL::GenericMolFile::read

(

System &

system

)

[virtual]

Read a system. This method will read all molecules contained in the file and add them to the system.

The default implementation calls read() until false is returned and adds the molecules read to the system.

Returns:

true if anything could be read

Exceptions:

Exception::ParseError

if the file could not be parsed while reading a molecule

Reimplemented in BALL::AntechamberFile, BALL::GAMESSDatFile, BALL::GAMESSLogFile, BALL::HINFile, BALL::KCFFile, BALL::MOL2File, BALL::MOLFile, BALL::PDBFile, BALL::SDFile, and BALL::XYZFile.

virtual bool BALL::GenericMolFile::write

(

const Molecule &

molecule

)

[virtual]

Write a molecule. Repeated invocations of this method append molecules to the same file.

The default implementation does nothing.

Exceptions:

File::CannotWrite

if writing to the file failed

Reimplemented in BALL::AntechamberFile, BALL::GAMESSDatFile, BALL::GAMESSLogFile, BALL::HINFile, BALL::KCFFile, BALL::MOL2File, BALL::MOLFile, BALL::PDBFile, BALL::SDFile, and BALL::XYZFile.

virtual bool BALL::GenericMolFile::write

(

const System &

system

)

[virtual]

Write the molecules of a system. If the file format does not support multiple molecules in a single file, a warning should be printed and only the first molecule should be stored.

The default implementation iterates over the system and calls write(const Molecule& molecule) for each molecule.

Exceptions:

File::CannotWrite

if writing to the file failed

Reimplemented in BALL::AntechamberFile, BALL::GAMESSDatFile, BALL::GAMESSLogFile, BALL::HINFile, BALL::KCFFile, BALL::MOL2File, BALL::MOLFile, BALL::PDBFile, BALL::SDFile, and BALL::XYZFile.