/*
 * 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 values.dox
 *
 * Created on: Mar 16, 2012
 *    Author: heber
 */

/**
 * \page values Values from the user to the Action
 *
 * The way from a value to end up as a option value/parameter inside an
 * \link MoleCuilder::Action Action \endlink ist rather complex. Hence,
 * let us briefly sketch the complete path, ranging from the \link
 * userinterfaces User Interface \endlink to the Action.
 *
 * \section value-from-ui From the user interface ...
 *
 * The user may enter a value either in ...
 *  -# a command line option, e.g. ...--position "0,1,2" ...
 *  -# a text interface, e.g. "Which position:" "0,1,2"
 *  -# a GUI dialog: Placing "0,1,2" in some text box or alike.
 *
 * This is handled by a class derived from a \ref Dialog::Query and all queries
 * of a specific Action are placed into a \ref Dialog. A \ref Dialog::Query
 * may e.g. be \ref TextDialog::VectorTextQuery. This class is derived from
 * \ref Dialog::VectorQuery which is derived from Query.
 *
 * The \ref Dialog::Query instance has a member Query::tmp which eventually
 * contains the value of a specific type (here Vector) from the user.
 * TextDialog::VectorTextQuery::handle() asks the user in some way for the value,
 * Dialog::VectorQuery::setResult() places Dialog::VectorQuery::tmp into the
 * \ref ValueStorage. This is done under a specific token which the Query
 * knows via its cstor: Query::title.
 *
 * ValueStorage does not take any value but only those it knows and more
 * specifically whose type it knows. I.e. for each option it has to know
 * a token and a name. These are contained in instances of \ref OptionTrait.
 * The list of these instances is contained in \ref ActionTrait which each
 * specialized \link MoleCuilder::Action Action \endlink gets on construction.
 * In Action's cstor these Trait's are registered with the \ref ActionRegistry
 * and the \ref OptionRegistry.
 *
 * And the OptionRegistry is then the place where \ref ValueStorage checks
 * whether token and type (the value) given to it are correct. This is required
 * to ensure that only a specific type is associated with each token. If another
 * type is needed simply think of a new token.
 *
 * \section value-from-action ... into the Action
 *
 * Now the value rests inside the ValueStorage as a string with a known type.
 * Every \link MoleCuilder::Action Action \endlink in its Action::performCall()
 * call Action::getParametersFromValueStorage() which fills an internal
 * Action::params structure (that is constructed as most of the other stuff
 * in an action via boost::preprocessor magic). This is then used by the
 * Action to know that the token "position" with value "0,1,2" which the user
 * supplied are meant to place a new atom at (0,1,2) (\ref AddAtomAction). It
 * takes the value from AtomAddAction::params::position (all these information
 * is stored in \ref AddAction.def).
 *
 *
 * \date 2012-03-16
 *
 */