Chemfiles internals

Sources organisation

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 developpement.
  • src: the sources of the library;
  • tests: the sources of the unit tests;

Classes organisation

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 behaviour 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_information() template and calling chemfiles::FormatFactory::add_format().

class 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

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>
void add_format()

Register a given Format in the factory.

The format informations are taken from the specialization of the template function chemfiles::format_information for this format.

std::vector<FormatInfo> formats()

Get the metadata for all registered formats.

Public Static Functions

static FormatFactory &get()

Get the instance of the FormatFactory

class FormatInfo

Metadata associated with a format.

This class uses the builder patern, chaining functions calls to set the class attributes:

auto meta = FormatInfo("MyFormat").with_extension(".mft").description(
    "some description"
);

Public Functions

FormatInfo(std::string name)

Create a FormatInfo with the given name.

Exceptions
  • Error: if the format name is the empty string

const std::string &name() const

Get the format name.

FormatInfo &with_extension(std::string extension)

Set the format extension, use this to allow users to use this format automatically with files having this extension. The extension should start by a dot (".xxx").

const std::string &extension() const

Get the format extension.

If the extension was not set, this returns an empty string

FormatInfo &description(std::string description)

Add a format description to this format.

const std::string &description() const

Get the format description.

template <class Format>
FormatInfo chemfiles::format_information()

Get the metadata associated with Format.

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

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

namespace chemfiles {
    template<> FormatInfo format_information<MyFormat>() {
        return FormatInfo("MyFormat").with_extension(".mft");
    }
}