The FileFormatScript class interfaces with external scripts that implement chemical file reader/writers. More...

#include <fileformatscript.h>

Inheritance diagram for FileFormatScript:

Public Types
enum	Format { NotUsed , Cjson , Cml , Xyz }

Public Types inherited from FileFormat
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.

typedef int	Operations

Public Member Functions
	FileFormatScript (const QString &scriptFileName)

QString	scriptFilePath () const

Format	inputFormat () const

Format	outputFormat () const

bool	isValid () const

FileFormat *	newInstance () const override

bool	read (std::istream &in, Core::Molecule &molecule) override
	Read the given `in` stream and load it into `molecule`. More...

bool	write (std::ostream &out, const Core::Molecule &molecule) override
	Write to the given `out` stream the contents of `molecule`. More...

Operations	supportedOperations () const override

std::string	identifier () const override
	A unique identifier, used to retrieve formats programatically. CML, XYZ, PDB etc. A runtime warning will be generated if the identifier is not unique.

std::string	name () const override
	The name of the format, should be short such as Chemical Markup Language, XYZ format, Protein Databank etc.

std::string	description () const override

std::string	specificationUrl () const override

std::vector< std::string >	fileExtensions () const override
	Get the file name extension(s) that the format supports reading. More...

std::vector< std::string >	mimeTypes () const override
	Get the MIME type(s) that the format supports reading. More...

Public Member Functions inherited from FileFormat
bool	open (const std::string &fileName, Operation mode)
	Open the specified file in Read or Write mode. More...

Operation	mode ()
	The mode the format is currently operating in. More...

bool	isMode (Operation isInMode)
	Check if the supplied mode(s) is being used. More...

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

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

bool	readFile (const std::string &fileName, Core::Molecule &molecule)
	Read the given `fileName` and load it into `molecule`. More...

bool	writeFile (const std::string &fileName, const Core::Molecule &molecule)
	Write to the given `fileName` the contents of `molecule`. More...

bool	readString (const std::string &string, Core::Molecule &molecule)
	Read the given `string` and load it into `molecule`. More...

bool	writeString (std::string &string, const Core::Molecule &molecule)
	Write to the given `string` the contents of `molecule`. More...

std::string	error () const
	Get the error string, contains errors/warnings encountered. More...

std::string	fileName () const
	Get the file name (if known). More...

void	setOptions (const std::string &options)
	Set options for the file reader. More...

std::string	options () const
	Get the file format options, can be used to change file IO. More...

virtual void	clear ()

Additional Inherited Members
Protected Member Functions inherited from FileFormat
void	appendError (const std::string &errorString, bool newLine=true)
	Append an error to the error string for the format. More...

Detailed Description

Script Entry Points

The script must handle the following command line arguments:

--metadata Print metadata describing the format and the script's abilities and exit.
--read Read data from standard input and produce a standard representation on standard output.
--write Read a standard representation from standard input and write the formatted result to standard output.

Identify the Format with <tt>--metadata</tt>

Running the script with the --metadata option should print a JSON object of the following form:

{
  "inputFormat": "cml",
  "outputFormat": "cml",
  "operations": ["read", "write"],
  "identifier": "Unique Name",
  "name": "User-friendly Name",
  "description": "Description of format.",
  "specificationUrl": "http://url.specifying.format/if/any/exist",
  "fileExtensions": ["ext"],
  "mimeTypes": ["chemical/x-ext"]
}

Details:

inputFormat indicates the format that the script can convert to the implemented format by the --write command. Allowed values are "cml", "cjson", or "xyz". See the --write documentation for more detail.
outputFormat indicates the format that the script can convert to from the implemented format by the --read command. Allowed values are "cml", "cjson", or "xyz". See the --read documentation for more detail.
operations specifies the scripts capabilies. The array should contain "read" if the script implements the --read option, and/or "write" if --write is available.
identifier is a unique identifier. The value must only be unique amongst script formats, as it will be prefixed with "User Script: " internally by Avogadro.
name is a user-friendly name for the format.
description is a description of the format, along with any relevant help text for users.
specificationUrl is the URL of the format specification if available (or relevant web page/wiki otherwise).
fileExtensions is an array specifying the file extensions that this format supports.
mimeTypes is an array specifying the mime types that this format supports.

Required members are

operations
inputFormat (if "write" is specified in operations)
outputFormat (if "read" is specified in operations)
identifier
name

Optional members are

description
specificationUrl
fileExtensions
mimeTypes

Reading a format with <tt>--read</tt>

If "read" is specified in the operations --metadata output along with a valid outputFormat, Avogadro will call the script with --read and write the implemented format to the script's standard input. The script shall convert the input to outputFormat and print it to standard output.

Writing a format with <tt>--write</tt>

If "write" is specified in the operations --metadata output along with a valid inputFormat, Avogadro will call the script with --write and write the inputFormat to the script's standard input. The script shall convert the input to the implemented format and print it to standard output.

Member Enumeration Documentation

◆ Format

enum Format

Formats that may be written to the script's input/output formats.

Member Function Documentation

◆ newInstance()

FileFormat* newInstance ( ) const

overridevirtual

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

Implements FileFormat.

◆ read()

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

overridevirtual

Parameters

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

Returns: True on success, false on failure.

Implements FileFormat.

◆ write()

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

overridevirtual

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.

Implements FileFormat.

◆ supportedOperations()

Operations supportedOperations ( ) const

overridevirtual

Returns: Operation flags defining the capabilities of this format.

Implements FileFormat.

◆ description()

std::string description ( ) const

overridevirtual

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

Implements FileFormat.

◆ specificationUrl()

std::string specificationUrl ( ) const

overridevirtual

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

Implements FileFormat.

◆ fileExtensions()

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

overridevirtual

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

Implements FileFormat.

◆ mimeTypes()

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

overridevirtual

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

Implements FileFormat.

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

fileformatscript.h

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Script Entry Points

Identify the Format with <tt>--metadata</tt>

Reading a format with <tt>--read</tt>

Writing a format with <tt>--write</tt>

Member Enumeration Documentation

◆ Format

Member Function Documentation

◆ newInstance()

◆ read()

◆ write()

◆ supportedOperations()

◆ description()

◆ specificationUrl()

◆ fileExtensions()

◆ mimeTypes()