General API for file formats. More...

#include <avogadro/io/fileformat.h>

Inheritance diagram for FileFormat:

Public Types
enum	Operation { None = 0x0 , Read = 0x1 , Write = 0x2 , ReadWrite = Read \| Write , MultiMolecule = 0x4 , Stream = 0x10 , String = 0x20 , File = 0x40 , All = ReadWrite \| MultiMolecule \| Stream \| String \| File }
	Flags defining supported operations.
using	Operations = int

Public Member Functions
virtual Operations	supportedOperations () const =0
bool	open (const std::string &fileName, Operation mode)
	Open the specified file in Read or Write mode.
Operation	mode ()
	The mode the format is currently operating in.
bool	isMode (Operation isInMode)
	Check if the supplied mode(s) is being used.
void	close ()
	Close any opened file handles.
bool	readMolecule (Core::Molecule &molecule)
	Read in a molecule, if there are no molecules to read molecule will be empty. This can be used to read in one or more molecules from a given file using repeated calls for each molecule.
bool	writeMolecule (const Core::Molecule &molecule)
	Write out a molecule. This can be used to write one or more molecules to a given file using repeated calls for each molecule.
virtual bool	read (std::istream &in, Core::Molecule &molecule)=0
	Read the given `in` stream and load it into `molecule`.
virtual bool	write (std::ostream &out, const Core::Molecule &molecule)=0
	Write to the given `out` stream the contents of `molecule`.
virtual bool	readFile (const std::string &fileName, Core::Molecule &molecule)
	Read the given `fileName` and load it into `molecule`.
virtual bool	writeFile (const std::string &fileName, const Core::Molecule &molecule)
	Write to the given `fileName` the contents of `molecule`.
bool	readString (const std::string &string, Core::Molecule &molecule)
	Read the given `string` and load it into `molecule`.
bool	writeString (std::string &string, const Core::Molecule &molecule)
	Write to the given `string` the contents of `molecule`.
std::string	error () const
	Get the error string, contains errors/warnings encountered.
std::string	fileName () const
	Get the file name (if known).
void	setOptions (const std::string &options)
	Set options for the file reader.
std::string	options () const
	Get the file format options, can be used to change file IO.
virtual void	clear ()
virtual FileFormat *	newInstance () const =0
virtual std::string	identifier () const =0
	A unique identifier, used to retrieve formats programmatically. CML, XYZ, PDB etc. A runtime warning will be generated if the identifier is not unique.
virtual std::string	name () const =0
	The name of the format, should be short such as Chemical Markup Language, XYZ format, Protein Databank etc.
virtual std::string	description () const =0
virtual std::string	specificationUrl () const =0
virtual std::vector< std::string >	fileExtensions () const =0
	Get the file name extension(s) that the format supports reading.
virtual std::vector< std::string >	mimeTypes () const =0
	Get the MIME type(s) that the format supports reading.
virtual std::vector< std::string >	contentPatterns () const
	Get literal strings that identify files in this format by content.

Static Public Member Functions
static bool	validateFileName (const std::string &fileName)
	Validates the given file name.

Protected Member Functions
void	appendError (const std::string &errorString, bool newLine=true)
	Append an error to the error string for the format.
bool	boolOption (const std::string &name, bool &value)
	Look up a boolean value in the options() string.
bool	stringOption (const std::string &name, std::string &value)
	Look up a string value in the options() string.
bool	stringArrayOption (const std::string &name, std::vector< std::string > &values)
	Look up an array of strings in the options() string.
long long	maxDecompressedSizeOption ()
	The ceiling on decompressed data for this read, in bytes.
bool	integerOption (const std::string &name, long long &value)
	Look up an integer value in the options() string.

Detailed Description

Author: Marcus D. Hanwell

This serves as the common base class for chemical file formats. Classes deriving from this one override the read and write virtual methods and operate on the given streams. Several other signatures are available for convenience. If there is an error reading or writing a file the string returned by error() will give more details.

Member Function Documentation

◆ supportedOperations()

virtual Operations supportedOperations ( ) const

pure virtual

Returns: Operation flags defining the capabilities of this format.

Implemented in CjsonFormat, CmlFormat, DcdFormat, GromacsFormat, LammpsDataFormat, LammpsTrajectoryFormat, MdlFormat, MMTFFormat, OutcarFormat, PdbFormat, PoscarFormat, SdfFormat, SmilesFormat, TrrFormat, TurbomoleFormat, XyzFormat, GAMESSUSOutput, GaussianCube, GaussianFchk, GenericJson, GenericOutput, MoldenFile, MopacAux, NWChemJson, NWChemLog, ORCAOutput, and QCSchema.

◆ validateFileName()

bool validateFileName ( const std::string & fileName )

static

Checks if the filename contains any invalid characters (e.g. ..) Also checks if the filename contains a restricted name on Windows. e.g., CON, PRN, AUX, NUL, COM1, COM2, COM3, COM4, COM5, etc.

Parameters

fileName The name of the file to be validated.

Returns: true if the file name is valid, false otherwise.

◆ open()

bool open	(	const std::string &	fileName,
		Operation	mode )

Returns: True on success, false on failure.

◆ mode()

Operation mode ( )

Returns: The mode the format is in.

◆ isMode()

bool isMode ( Operation isInMode )

Parameters

isInMode The mode(s) to test against

Returns: True if the format is currently in the supplied mode(s).

◆ readMolecule()

bool readMolecule ( Core::Molecule & molecule )

Parameters

molecule The molecule the data will be read into.

Returns: True on success, false on failure.

◆ writeMolecule()

bool writeMolecule ( const Core::Molecule & molecule )

Parameters

molecule The molecule the data will be written from.

Returns: True on success, false on failure.

◆ read()

virtual bool read	(	std::istream &	in,
		Core::Molecule &	molecule )

nodiscardpure virtual

Parameters

in	The input file stream.
molecule	The molecule the data will be read into.

Returns: True on success, false on failure.

Implemented in CjsonFormat, CmlFormat, DcdFormat, GromacsFormat, LammpsDataFormat, LammpsTrajectoryFormat, MdlFormat, MMTFFormat, OutcarFormat, PdbFormat, PoscarFormat, SdfFormat, SmilesFormat, TrrFormat, TurbomoleFormat, XyzFormat, GAMESSUSOutput, GaussianCube, GaussianFchk, GenericJson, GenericOutput, MoldenFile, MopacAux, NWChemJson, NWChemLog, ORCAOutput, and QCSchema.

◆ write()

virtual bool write	(	std::ostream &	out,
		const Core::Molecule &	molecule )

nodiscardpure virtual

Parameters

out	The output stream to write the data to.
molecule	The contents of this molecule will be written to output.

Returns: True on success, false on failure.

Implemented in CjsonFormat, CmlFormat, DcdFormat, GromacsFormat, LammpsDataFormat, LammpsTrajectoryFormat, MdlFormat, MMTFFormat, OutcarFormat, PdbFormat, PoscarFormat, SdfFormat, SmilesFormat, TrrFormat, TurbomoleFormat, XyzFormat, GAMESSUSOutput, GaussianCube, GaussianFchk, GenericJson, GenericOutput, MoldenFile, MopacAux, NWChemJson, NWChemLog, ORCAOutput, and QCSchema.

◆ readFile()

virtual bool readFile	(	const std::string &	fileName,
		Core::Molecule &	molecule )

virtual

Parameters

fileName	The full path to the file to be read in.
molecule	The molecule the data will be read into.

Returns: True on success, false on failure.

◆ writeFile()

virtual bool writeFile	(	const std::string &	fileName,
		const Core::Molecule &	molecule )

virtual

Parameters

fileName	The full path to the file to be written.
molecule	The contents of this molecule will be written to the file.

Returns: True on success, false on failure.

◆ readString()

bool readString	(	const std::string &	string,
		Core::Molecule &	molecule )

Parameters

string	The string containing the molecule file contents.
molecule	The molecule the data will be read into.

Returns: True on success, false on failure.

◆ writeString()

bool writeString	(	std::string &	string,
		const Core::Molecule &	molecule )

Parameters

string	The string to write the contents of the molecule into.
molecule	The contents of this molecule will be written to the string.

Returns: True on success, false on failure.

◆ error()

std::string error ( ) const

Returns: String containing any errors or warnings encountered.

◆ fileName()

std::string fileName ( ) const

Returns: The full path to the file name as supplied, can be empty.

◆ setOptions()

void setOptions ( const std::string & options )

Parameters

options The options, each reader chooses how to use/interpret them.

◆ options()

std::string options ( ) const

Returns: The options set for the reader (defaults to empty).

◆ clear()

virtual void clear ( )

virtual

Clear the format and reset all state.

◆ newInstance()

virtual FileFormat * newInstance ( ) const

pure virtual

Create a new instance of the file format class. Ownership passes to the caller.

Implemented in CjsonFormat, CmlFormat, DcdFormat, GromacsFormat, LammpsDataFormat, LammpsTrajectoryFormat, MdlFormat, MMTFFormat, OutcarFormat, PdbFormat, PoscarFormat, SdfFormat, SmilesFormat, TrrFormat, TurbomoleFormat, XyzFormat, GAMESSUSOutput, GaussianCube, GaussianFchk, GenericJson, GenericOutput, MoldenFile, MopacAux, NWChemJson, NWChemLog, ORCAOutput, and QCSchema.

◆ identifier()

virtual std::string identifier ( ) const

pure virtual

◆ name()

virtual std::string name ( ) const

pure virtual

◆ description()

virtual std::string description ( ) const

pure virtual

A description of the format, along with any relevant help text for users.

Implemented in CjsonFormat, CmlFormat, DcdFormat, GromacsFormat, LammpsDataFormat, LammpsTrajectoryFormat, MdlFormat, MMTFFormat, OutcarFormat, PdbFormat, PoscarFormat, SdfFormat, SmilesFormat, TrrFormat, TurbomoleFormat, XyzFormat, GAMESSUSOutput, GaussianCube, GaussianFchk, GenericJson, GenericOutput, MoldenFile, MopacAux, NWChemJson, NWChemLog, ORCAOutput, and QCSchema.

◆ specificationUrl()

virtual std::string specificationUrl ( ) const

pure virtual

The URL of the format specification if available (relevant web page/wiki otherwise).

Implemented in CjsonFormat, CmlFormat, DcdFormat, GromacsFormat, LammpsDataFormat, LammpsTrajectoryFormat, MdlFormat, MMTFFormat, OutcarFormat, PdbFormat, PoscarFormat, SdfFormat, SmilesFormat, TrrFormat, TurbomoleFormat, XyzFormat, GAMESSUSOutput, GaussianCube, GaussianFchk, GenericJson, GenericOutput, MoldenFile, MopacAux, NWChemJson, NWChemLog, ORCAOutput, and QCSchema.

◆ fileExtensions()

virtual std::vector< std::string > fileExtensions ( ) const

pure virtual

Returns: A vector containing a list of extensions (in lower case).

Implemented in CjsonFormat, CmlFormat, DcdFormat, GromacsFormat, LammpsDataFormat, LammpsTrajectoryFormat, MdlFormat, MMTFFormat, OutcarFormat, PdbFormat, PoscarFormat, SdfFormat, SmilesFormat, TrrFormat, TurbomoleFormat, XyzFormat, GAMESSUSOutput, GaussianCube, GaussianFchk, GenericJson, GenericOutput, MoldenFile, MopacAux, NWChemJson, NWChemLog, ORCAOutput, and QCSchema.

◆ mimeTypes()

virtual std::vector< std::string > mimeTypes ( ) const

pure virtual

Returns: A vector containing a list of MIME type(s) (in lower case).

Implemented in CjsonFormat, CmlFormat, DcdFormat, GromacsFormat, LammpsDataFormat, LammpsTrajectoryFormat, MdlFormat, MMTFFormat, OutcarFormat, PdbFormat, PoscarFormat, SdfFormat, SmilesFormat, TrrFormat, TurbomoleFormat, XyzFormat, GAMESSUSOutput, GaussianCube, GaussianFchk, GenericJson, GenericOutput, MoldenFile, MopacAux, NWChemJson, NWChemLog, ORCAOutput, and QCSchema.

◆ contentPatterns()

virtual std::vector< std::string > contentPatterns ( ) const

virtual

Each entry is a plain substring (not a regular expression). If any one of them occurs in a line of a file, the file is taken to be in this format. Generic extensions such as ".out" and ".log" are written by many programs, so the extension alone cannot choose a reader; QuantumIO::GenericOutput consults these patterns to pick one. Empty entries are meaningless (they would match every line) and should not be returned.

The default implementation returns an empty list: the format is never chosen by content.

Returns: A vector of substrings, possibly empty.

◆ appendError()

void appendError	(	const std::string &	errorString,
		bool	newLine = true )

protected

Parameters

errorString	The error to be added.
newLine	Add a new line after the error string?

◆ boolOption()

bool boolOption	(	const std::string &	name,
		bool &	value )

protected

The options string is read as a JSON object; anything else (empty, malformed, or a bare JSON value) is treated as no options at all.

Parameters

name	The name of the option to look up.
value	Set to the stored value when the option is present and is a boolean, otherwise left untouched, so seed it with the format default.

Returns: False when the option is present but holds the wrong type, in which case an error is appended. Formats that treat a bad option as fatal should return early, the rest can ignore the result and use the default.

◆ stringOption()

bool stringOption	(	const std::string &	name,
		std::string &	value )

protected

Parameters

name	The name of the option to look up.
value	Set to the stored value when the option is present and is a string, otherwise left untouched, so seed it with the format default.

Returns: False when the option is present but holds the wrong type, see boolOption() for how this is intended to be used.

◆ stringArrayOption()

bool stringArrayOption	(	const std::string &	name,
		std::vector< std::string > &	values )

protected

Parameters

name	The name of the option to look up.
values	Set to the stored values when the option is present and is an array of strings, otherwise left untouched.

Returns: False when the option is present but is not an array of strings, see boolOption() for how this is intended to be used.

◆ maxDecompressedSizeOption()

long long maxDecompressedSizeOption ( )

protected

Reads the "maxDecompressedSize" option, falling back to the default when absent, and appending an error and using the default when negative. Zero means no ceiling.

◆ integerOption()

bool integerOption	(	const std::string &	name,
		long long &	value )

protected

Parameters

name	The name of the option to look up.
value	Set to the stored value when the option is present and is an integer, otherwise left untouched, so seed it with the format default.

Returns: False when the option is present but holds the wrong type, see boolOption() for how this is intended to be used.

The documentation for this class was generated from the following file:

fileformat.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Member Function Documentation

◆ supportedOperations()

◆ validateFileName()

◆ open()

◆ mode()

◆ isMode()

◆ readMolecule()

◆ writeMolecule()

◆ read()

◆ write()

◆ readFile()

◆ writeFile()

◆ readString()

◆ writeString()

◆ error()

◆ fileName()

◆ setOptions()

◆ options()

◆ clear()

◆ newInstance()

◆ identifier()

◆ name()

◆ description()

◆ specificationUrl()

◆ fileExtensions()

◆ mimeTypes()

◆ contentPatterns()

◆ appendError()

◆ boolOption()

◆ stringOption()

◆ stringArrayOption()

◆ maxDecompressedSizeOption()

◆ integerOption()