Loading...
Searching...
No Matches
FileFormat Class Referenceabstract

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.

## 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.

## 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, CMsgPackFormat, DcdFormat, GromacsFormat, LammpsDataFormat, LammpsTrajectoryFormat, MdlFormat, MMTFFormat, OutcarFormat, PdbFormat, PoscarFormat, SdfFormat, 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 )

nodiscard pure 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, CMsgPackFormat, DcdFormat, GromacsFormat, LammpsDataFormat, LammpsTrajectoryFormat, MdlFormat, MMTFFormat, OutcarFormat, PdbFormat, PoscarFormat, SdfFormat, 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 )

nodiscard pure 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, CMsgPackFormat, DcdFormat, GromacsFormat, LammpsDataFormat, LammpsTrajectoryFormat, MdlFormat, MMTFFormat, OutcarFormat, PdbFormat, PoscarFormat, SdfFormat, 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, CMsgPackFormat, DcdFormat, GromacsFormat, LammpsDataFormat, LammpsTrajectoryFormat, MdlFormat, MMTFFormat, OutcarFormat, PdbFormat, PoscarFormat, SdfFormat, TrrFormat, TurbomoleFormat, XyzFormat, GAMESSUSOutput, GaussianCube, GaussianFchk, GenericJson, GenericOutput, MoldenFile, MopacAux, NWChemJson, NWChemLog, ORCAOutput, and QCSchema.

## identifier()

virtual std::string identifier | ( |  | ) | const

pure virtual

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

## name()

virtual std::string name | ( |  | ) | const

pure virtual

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

## 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, CMsgPackFormat, DcdFormat, GromacsFormat, LammpsDataFormat, LammpsTrajectoryFormat, MdlFormat, MMTFFormat, OutcarFormat, PdbFormat, PoscarFormat, SdfFormat, 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, CMsgPackFormat, DcdFormat, GromacsFormat, LammpsDataFormat, LammpsTrajectoryFormat, MdlFormat, MMTFFormat, OutcarFormat, PdbFormat, PoscarFormat, SdfFormat, 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, CMsgPackFormat, DcdFormat, GromacsFormat, LammpsDataFormat, LammpsTrajectoryFormat, MdlFormat, MMTFFormat, OutcarFormat, PdbFormat, PoscarFormat, SdfFormat, 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, CMsgPackFormat, DcdFormat, GromacsFormat, LammpsDataFormat, LammpsTrajectoryFormat, MdlFormat, MMTFFormat, OutcarFormat, PdbFormat, PoscarFormat, SdfFormat, TrrFormat, TurbomoleFormat, XyzFormat, GAMESSUSOutput, GaussianCube, GaussianFchk, GenericJson, GenericOutput, MoldenFile, MopacAux, NWChemJson, NWChemLog, ORCAOutput, and QCSchema.

## 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?

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

- fileformat.h