/*
+ * This file is part of the GROMACS molecular simulation package.
*
- * This source code is part of
+ * Copyright (c) 2010,2011,2012,2014, by the GROMACS development team, led by
+ * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
+ * and including many others, as listed in the AUTHORS file in the
+ * top-level source directory and at http://www.gromacs.org.
*
- * G R O M A C S
+ * GROMACS is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * as published by the Free Software Foundation; either version 2.1
+ * of the License, or (at your option) any later version.
*
- * GROningen MAchine for Chemical Simulations
+ * GROMACS is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
*
- * Written by David van der Spoel, Erik Lindahl, Berk Hess, and others.
- * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
- * Copyright (c) 2001-2009, The GROMACS development team,
- * check out http://www.gromacs.org for more information.
-
- * This program is free software; you can redistribute it and/or
- * modify it under the terms of the GNU General Public License
- * as published by the Free Software Foundation; either version 2
- * of the License, or (at your option) any later version.
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with GROMACS; if not, see
+ * http://www.gnu.org/licenses, or write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*
- * If you want to redistribute modifications, please consider that
- * scientific software is very special. Version control is crucial -
- * bugs must be traceable. We will be happy to consider code for
- * inclusion in the official distribution, but derived work must not
- * be called official GROMACS. Details are found in the README & COPYING
- * files - if they are missing, get the official version at www.gromacs.org.
+ * If you want to redistribute modifications to GROMACS, please
+ * consider that scientific software is very special. Version
+ * control is crucial - bugs must be traceable. We will be happy to
+ * consider code for inclusion in the official distribution, but
+ * derived work must not be called official GROMACS. Details are found
+ * in the README & COPYING files - if they are missing, get the
+ * official version at http://www.gromacs.org.
*
* To help us fund GROMACS development, we humbly ask that you cite
- * the papers on the package - you can find them in the top README file.
- *
- * For more info, check our website at http://www.gromacs.org
+ * the research papers on the package. Check out http://www.gromacs.org.
*/
/*! \file
* \brief
* Together with basicoptions.h, this header forms the part of the public
* API that most classes will use to provide options.
*
- * \author Teemu Murtola <teemu.murtola@cbr.su.se>
+ * \author Teemu Murtola <teemu.murtola@gmail.com>
* \inpublicapi
* \ingroup module_options
*/
#include <string>
-#include "../utility/common.h"
+#include "gromacs/options/abstractoption.h"
+#include "gromacs/utility/common.h"
+#include "gromacs/utility/gmxassert.h"
namespace gmx
{
+template <typename T> class ConstArrayRef;
+
class AbstractOption;
class OptionsAssigner;
class OptionsIterator;
+/*! \brief
+ * Base class for option managers.
+ *
+ * This class is used as a marker for all classes that are used with
+ * Options::addManager(). It doesn't provide any methods, but only supports
+ * transporting these classes through the Options collection into the
+ * individual option implementation classes.
+ *
+ * The virtual destructor is present to make this class polymorphic, such that
+ * `dynamic_cast` can be used when retrieving a manager of a certain type for
+ * the individual options.
+ *
+ * \inlibraryapi
+ * \ingroup module_options
+ */
+class OptionManagerInterface
+{
+ protected:
+ virtual ~OptionManagerInterface();
+};
+
/*! \brief
* Collection of options.
*
* Standard usage is to write a method that creates an Options that is owned by
* the object, populates it with supported options, and then returns it:
* \code
-// <as class attributes>
-using gmx::Options;
-Options options("common", "Common Options");
-std::string arg1;
-int arg2;
-
-// <populating>
-using gmx::StringOption;
-using gmx::IntegerOption;
-options.addOption(StringOption("arg1").store(&arg1));
-options.addOption(IntegerOption("arg2").store(&arg2));
-return &options;
- * \endcode
+
// <as class attributes>
+ using gmx::Options;
+ Options options("common", "Common Options");
+ std::string arg1;
+ int arg2;
+
+ using gmx::StringOption;
+ using gmx::IntegerOption;
+ options.addOption(StringOption("arg1").store(&arg1));
+ options.addOption(IntegerOption("arg2").store(&arg2));
+ return &options;
+ \endcode
* The caller of that method can then use a parser implementation such as
* CommandLineParser to provide values for the options.
*
*
* \param[in] desc String to set as the description.
*
- * concatenateStrings() is useful for forming the input string.
+ * This overload is mainly useful if the description is very short.
+ * Currently this is mostly the case in unit testing.
*/
void setDescription(const std::string &desc);
- //int addBugs(int nbugs, const char *const *bugs);
+ /*! \brief
+ * Sets the full description of the option collection from string array.
+ *
+ * \param[in] descArray String array to set as the description.
+ *
+ * All strings in `descArray` are concatenated to form the description.
+ * Spaces are inserted between strings if they are missing.
+ *
+ * Example usage:
+ * \code
+ const char *const desc[] = {
+ "This is the description",
+ "for the options"
+ };
+
+ gmx::Options options(NULL, NULL);
+ options.setDescription(desc);
+ \endcode
+ *
+ * To use this overload, you must also include
+ * `gromacs/utility/arrayref.h`.
+ */
+ void setDescription(const ConstArrayRef<const char *> &descArray);
+
+ /*! \brief
+ * Adds an option manager.
+ *
+ * \param manager Manager to add.
+ * \throws std::bad_alloc if out of memory.
+ *
+ * Option managers are used by some types of options that require
+ * interaction between different option instances (e.g., selection
+ * options), or need to support globally set properties (e.g., a global
+ * default file prefix). Option objects can retrieve the pointer to
+ * their manager when they are created, and the caller can alter the
+ * behavior of the options through the manager.
+ * See the individual managers for details.
+ *
+ * Caller is responsible for memory management of \p manager.
+ * The Options object (and its contained options) only stores a
+ * reference to the object.
+ *
+ * This method cannot be called after adding options or subsections.
+ */
+ void addManager(OptionManagerInterface *manager);
/*! \brief
* Adds an option collection as a subsection of this collection.
* subsection. If an attempt is made to add two different subsections
* with the same name, this function asserts.
*
- * For certain functionality to work properly, no options should
- * be added to the subsection after it has been added to another
- * collection.
+ * \p section should not have any options added at the point this
+ * method is called.
*
* Only a pointer to the provided object is stored. The caller is
* responsible that the object exists for the lifetime of the
/*! \brief
* Adds a recognized option to the collection.
*
- * \throws APIError if invalid option settings are provided.
+ * \param[in] settings Option description.
+ * \returns OptionInfo object for the created option (never NULL).
+ * \throws APIError if invalid option settings are provided.
+ *
+ * This method provides the internal implementation, but in most cases
+ * the templated method is called from user code.
+ * See the templated method for more details.
+ */
+ OptionInfo *addOption(const AbstractOption &settings);
+ /*! \brief
+ * Adds a recognized option to the collection.
+ *
+ * \tparam OptionType Type of the options description object.
+ * \param[in] settings Option description.
+ * \returns OptionInfo object for the created option (never NULL).
+ * \throws APIError if invalid option settings are provided.
+ *
+ * The return value is a pointer for more convenient use in callers:
+ * often callers need to declare the variable that will hold the return
+ * value in wider scope than would be achieved by declaring it at the
+ * site where addOption() is called.
+ * The returned pointer must not be freed.
*
* See \link Options class documentation \endlink for example usage.
+ *
+ * \libinternal
+ * \p OptionType::InfoType must specify a type that derives from
+ * OptionInfo and matches the type that is returned by
+ * AbstractOptionStorage::optionInfo() for the storage object that
+ * corresponds to \p OptionType.
*/
- void addOption(const AbstractOption &settings);
+ template <class OptionType>
+ typename OptionType::InfoType *addOption(const OptionType &settings)
+ {
+ OptionInfo *info
+ = addOption(static_cast<const AbstractOption &>(settings));
+ GMX_ASSERT(info->isType<typename OptionType::InfoType>(),
+ "Mismatching option info type declaration and implementation");
+ return info->toType<typename OptionType::InfoType>();
+ }
//! Returns true if option \p name is set.
bool isSet(const char *name) const;
private:
class Impl;
- PrivateImplPointer<Impl> _impl;
+ PrivateImplPointer<Impl> impl_;
//! Needed to be able to extend the interface of this object.
friend class OptionsAssigner;
biod.pnpi.spb.ru / alexxy / gromacs.git / blobdiff