source: src/documentation/constructs/parsers.dox@ 2528d8

/*
 * Project: MoleCuilder
 * Description: creates and alters molecular systems
 * Copyright (C)  2010 University of Bonn. All rights reserved.
 * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
 */

/**
 * \file parsers.dox
 *
 * Created on: Oct 28, 2011
 *    Author: heber
 */

/** \page parsers Format Parsers
 *
 *  Format Parsers load or save information about the World (i.e. all atoms,
 *  contained bonds, ...) in a specific file format.
 *
 *  All parsers derive from FormatParser and all available instances of
 *  FormatParser's are stored in a FormatParserStorage such that they can be
 *  retrieved with simply knowing the associated token.
 *
 *  We have this storage as the FormatParser may also contain extra information
 *  per atom (...AtomDataContainer or alikes) which should be copied when an
 *  atom is copied. Hence, as soon as a FormatParser is accessed once it sits
 *  in the Storage and accumulates all information. Therefore, every parser
 *  instance is unique per type throughout the run of the program.
 *
 *  A specific parser can be obtained from the FormatParserStorage just by
 *  knowing the correct keyword such as this:
 *  \code
 *  ParserTypes type = FormatParserStorage::getInstance().getTypeFromName("xyz");
 *  FormatParserInterface &parser = FormatParserStorage::getInstance().get(type);
 *  \endcode
 *
 *  Associated to the FormatParser's is also the ChangeTracker (\ref observers)
 *  that observers the World and tells all parsers on program exit whether
 *  to save or not (i.e. whether any changes occurred). FormatParser_common
 *  makes sure that each FormatParser signUp()s to this ChangeTracker.
 *
 *  Important is also the concept of a Parameter here. A Parameter is a value
 *  of a certain type with a given valid range or set of valid values. There
 *  ContinuousValue and DiscreteValue template classes that are subsequently
 *  joined with a name to give a ContinuousParameter and DiscreteParameter to
 *  be stored via a unifying ParameterInterface into a ParameterStorage. Such
 *  an instance each of the FormatParser's contains. Therein extra information
 *  such as a basis set, unit length, energy cutoff or other parser-specific
 *  parameters are stored.
 *
 *  Various actions (WorldInputAction, WorldOuputAction, AtomSaveSelectedAtomsAction,
 *  MoleculeSaveSelectedAction) use the parser to load or store atoms or to
 *  control the behavior of storage (ParserSetOutputFormatAction, ...)
 *
 * \section parsers-add To add a new parser ...
 *
 *  The following tasks are necessary:
 *  -# think of unique brief name for your parser, e.g. "xyz" and add to
 *  \b ParserTypes.def. This will inform FormatParserStorage of your new parser.
 *  (Again there is some preprocessor magic for instanting all ...)
 *  -# Implement a FormatParserTraits specialization with some common stuff to
 *    your parsers
 *  \code
 *  template<>
 *  struct FormatParserTrait<name>
 *  {
 *    //!> Name of the parser
 *    static const std::string name;
 *    //!> suffix of the files the parser understands to read and write
 *    static const std::string suffix;
 *    //!> ParserTypes enumeration for the parser
 *    static const enum ParserTypes type;
 *  };
 *  \endcode
 *  where \a name is the name unique name of your parser, e.g. \a xyz.
 *  -# Create all these static variables with matching contents.
 *  -# Implement a FormatParser specialization
 *  \code
 *  template <>
 *  class FormatParser< name >  : virtual public FormatParserInterface, public FormatParser_common
 *  {
 *  ...
 *  };
 *  \endcode
 *  where \a name is again the name of your parser. FormatParser_common
 *  contains some functionality common to all Parsers where FormatParserInterface
 *  is the interface where load() and save() are defined. This allows for storage
 *  in FormatParserRegistry.
 *  -# implement FormatParserInterface::load() and FormatParserInterface::save().
 *  -# implement FormatParser_common::AtomInserted() and
 *    FormatParser_common::AtomRemoved()
 *
 *
 * \date 2011-10-31
 */