Chemfiles internals

Sources organization

You will find the following directory in chemfiles source code:

  • cmake: CMake modules used for build configuration;

  • doc: the source for this documentation;

  • examples: usage examples for C and C++ interfaces;

  • external: external libraries used by chemfiles;

  • include: the headers of chemfiles;

  • scripts: some python and bash scripts used in development.

  • src: the sources of the library;

  • tests: the sources of the unit tests;

Classes organization

Chemfiles is written in C++11, in an object-oriented fashion. A Trajectory is built on the top of two other private classes: a File and a Format. These are pure abstract class defining the interface for reading and writing data.

Adding new formats and tweaking behavior of existing formats should be done either in the File implementation for everything related to interactions with the actual file, or in the Format implementation for everything related with parsing data from the file.

Every Format class can be associated to an extension and a format name, the associations are managed by the FormatFactory class. New file and formats should be registered with this class, by specializing the chemfiles::format_metadata() template and calling chemfiles::FormatFactory::add_format().

class chemfiles::FormatFactory

This class allow to register Format with names and file extensions.

Public Functions

format_creator_t name(const std::string &name)

Get a format_creator_t from a format name.

Parameters

  • name: the format name

Exceptions

memory_stream_t memory_stream(const std::string &name)

Get a memory_stream_t from a format name.

Parameters

  • name: the format name

Exceptions

  • FormatError: if the format can not be found or does not support reading / writing from memory

format_creator_t extension(const std::string &extension)

Get a format_creator_t from a format extention.

Parameters

  • extension: the format extention

Exceptions

template<class Format, enable_if_t<SupportsMemoryIO<Format>::value, int> = 0>
void add_format()

Register a given Format in the factory if it supports memory IO

The format informations are taken from the specialization of the template function chemfiles::format_metadata for this format. The second template argument is used to determine if the Format supports memory IO.

template<class Format, enable_if_t<!SupportsMemoryIO<Format>::value, int> = 0>
void add_format()

Register a given Format in the factory if it does not support memory IO

The format informations are taken from the specialization of the template function chemfiles::format_metadata for this format. The second template argument is used to determine if the Format supports memory IO.

std::vector<std::reference_wrapper<const FormatMetadata>> formats()

Get the metadata for all registered formats.

Public Static Functions

FormatFactory &get()

Get the instance of the FormatFactory

template<class Format>
const FormatMetadata &chemfiles::format_metadata()

Get the metadata associated with Format.

The metadata should be a reference to static memory.

In order to implement a new format, one should specialise this function with the corresponding format:

class MyFormat: public Format {
    // ...
};

namespace chemfiles {
    template<> const FormatMetadata& format_metadata<MyFormat>() {
        static FormatMetadata metadata;
        metadata.name = "MyFormat";
        metadata.extension = ".mtf";
        return metadata;
    }
}