| 1 | /*
|
|---|
| 2 | * Project: MoleCuilder
|
|---|
| 3 | * Description: creates and alters molecular systems
|
|---|
| 4 | * Copyright (C) 2010 University of Bonn. All rights reserved.
|
|---|
| 5 | * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
|
|---|
| 6 | */
|
|---|
| 7 |
|
|---|
| 8 | /**
|
|---|
| 9 | * \file parsers.dox
|
|---|
| 10 | *
|
|---|
| 11 | * Created on: Oct 28, 2011
|
|---|
| 12 | * Author: heber
|
|---|
| 13 | */
|
|---|
| 14 |
|
|---|
| 15 | /** \page parsers Format Parsers
|
|---|
| 16 | *
|
|---|
| 17 | * Format Parsers load or save information about the World (i.e. all atoms,
|
|---|
| 18 | * contained bonds, ...) in a specific file format.
|
|---|
| 19 | *
|
|---|
| 20 | * All parsers derive from FormatParser and all available instances of
|
|---|
| 21 | * FormatParser's are stored in a FormatParserStorage such that they can be
|
|---|
| 22 | * retrieved with simply knowing the associated token.
|
|---|
| 23 | *
|
|---|
| 24 | * We have this storage as the FormatParser may also contain extra information
|
|---|
| 25 | * per atom (...AtomDataContainer or alikes) which should be copied when an
|
|---|
| 26 | * atom is copied. Hence, as soon as a FormatParser is accessed once it sits
|
|---|
| 27 | * in the Storage and accumulates all information. Therefore, every parser
|
|---|
| 28 | * instance is unique per type throughout the run of the program.
|
|---|
| 29 | *
|
|---|
| 30 | * A specific parser can be obtained from the FormatParserStorage just by
|
|---|
| 31 | * knowing the correct keyword such as this:
|
|---|
| 32 | * \code
|
|---|
| 33 | * ParserTypes type = FormatParserStorage::getInstance().getTypeFromName("xyz");
|
|---|
| 34 | * FormatParserInterface &parser = FormatParserStorage::getInstance().get(type);
|
|---|
| 35 | * \endcode
|
|---|
| 36 | *
|
|---|
| 37 | * Associated to the FormatParser's is also the ChangeTracker (\ref observers)
|
|---|
| 38 | * that observers the World and tells all parsers on program exit whether
|
|---|
| 39 | * to save or not (i.e. whether any changes occurred). FormatParser_common
|
|---|
| 40 | * makes sure that each FormatParser signUp()s to this ChangeTracker.
|
|---|
| 41 | *
|
|---|
| 42 | * Important is also the concept of a Parameter here. A Parameter is a value
|
|---|
| 43 | * of a certain type with a given valid range or set of valid values. There
|
|---|
| 44 | * ContinuousValue and DiscreteValue template classes that are subsequently
|
|---|
| 45 | * joined with a name to give a ContinuousParameter and DiscreteParameter to
|
|---|
| 46 | * be stored via a unifying ParameterInterface into a ParameterStorage. Such
|
|---|
| 47 | * an instance each of the FormatParser's contains. Therein extra information
|
|---|
| 48 | * such as a basis set, unit length, energy cutoff or other parser-specific
|
|---|
| 49 | * parameters are stored.
|
|---|
| 50 | *
|
|---|
| 51 | * Various actions (WorldInputAction, WorldOuputAction, AtomSaveSelectedAtomsAction,
|
|---|
| 52 | * MoleculeSaveSelectedAction) use the parser to load or store atoms or to
|
|---|
| 53 | * control the behavior of storage (ParserSetOutputFormatAction, ...)
|
|---|
| 54 | *
|
|---|
| 55 | * \section parsers-add To add a new parser ...
|
|---|
| 56 | *
|
|---|
| 57 | * The following tasks are necessary:
|
|---|
| 58 | * -# think of unique brief name for your parser, e.g. "xyz" and add to
|
|---|
| 59 | * \b ParserTypes.def. This will inform FormatParserStorage of your new parser.
|
|---|
| 60 | * (Again there is some preprocessor magic for instanting all ...)
|
|---|
| 61 | * -# Implement a FormatParserTraits specialization with some common stuff to
|
|---|
| 62 | * your parsers
|
|---|
| 63 | * \code
|
|---|
| 64 | * template<>
|
|---|
| 65 | * struct FormatParserTrait<name>
|
|---|
| 66 | * {
|
|---|
| 67 | * //!> Name of the parser
|
|---|
| 68 | * static const std::string name;
|
|---|
| 69 | * //!> suffix of the files the parser understands to read and write
|
|---|
| 70 | * static const std::string suffix;
|
|---|
| 71 | * //!> ParserTypes enumeration for the parser
|
|---|
| 72 | * static const enum ParserTypes type;
|
|---|
| 73 | * };
|
|---|
| 74 | * \endcode
|
|---|
| 75 | * where \a name is the name unique name of your parser, e.g. \a xyz.
|
|---|
| 76 | * -# Create all these static variables with matching contents.
|
|---|
| 77 | * -# Implement a FormatParser specialization
|
|---|
| 78 | * \code
|
|---|
| 79 | * template <>
|
|---|
| 80 | * class FormatParser< name > : virtual public FormatParserInterface, public FormatParser_common
|
|---|
| 81 | * {
|
|---|
| 82 | * ...
|
|---|
| 83 | * };
|
|---|
| 84 | * \endcode
|
|---|
| 85 | * where \a name is again the name of your parser. FormatParser_common
|
|---|
| 86 | * contains some functionality common to all Parsers where FormatParserInterface
|
|---|
| 87 | * is the interface where load() and save() are defined. This allows for storage
|
|---|
| 88 | * in FormatParserRegistry.
|
|---|
| 89 | * -# implement FormatParserInterface::load() and FormatParserInterface::save().
|
|---|
| 90 | * -# implement FormatParser_common::AtomInserted() and
|
|---|
| 91 | * FormatParser_common::AtomRemoved()
|
|---|
| 92 | *
|
|---|
| 93 | *
|
|---|
| 94 | * \date 2011-10-31
|
|---|
| 95 | */
|
|---|
