/*
* This file is part of the GROMACS molecular simulation package.
*
- * Copyright (c) 2010,2011,2012,2014, by the GROMACS development team, led by
+ * Copyright (c) 2010,2011,2012,2014,2015, 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.
#include <string>
-#include "../utility/common.h"
-#include "../utility/gmxassert.h"
-
-#include "abstractoption.h"
+#include "gromacs/options/ioptionscontainer.h"
+#include "gromacs/utility/classhelpers.h"
namespace gmx
{
-template <typename T> class ConstArrayRef;
-
class AbstractOption;
class OptionsAssigner;
class OptionsIterator;
/*! \brief
- * Collection of options.
+ * 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.
*
- * This class provides a standard interface for implementing input 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
- * The caller of that method can then use a parser implementation such as
- * CommandLineParser to provide values for the options.
+ * 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 IOptionManager
+{
+ protected:
+ virtual ~IOptionManager();
+};
+
+/*! \brief
+ * Collection of options.
*
- * Header basicoptions.h provides declarations of several standard
- * option types for use with addOption(). Documentation of those classes
- * also give more examples of how to define options.
+ * See \ref module_options for an overview of how the options work.
+ * The IOptionsContainer interface documents how to add options.
*
- * In order to keep the public interface of this class simple and to reduce
- * build dependencies on objects that simply provide options, functionality
+ * In order to keep the public interface of this class simple, functionality
* to assign values to options is provided by a separate OptionsAssigner class.
* Similarly, functionality for looping over all options (e.g., for writing out
* help) is provided by OptionsIterator.
* \inpublicapi
* \ingroup module_options
*/
-class Options
+class Options : public IOptionsContainer
{
public:
/*! \brief
//! Returns the short name of the option collection.
const std::string &name() const;
- //! Returns the title of the option collection.
- const std::string &title() const;
- //! Returns the full description of the option collection.
- const std::string &description() const;
/*! \brief
- * Sets the full description of the option collection.
- *
- * \param[in] desc String to set as the description.
- *
- * 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);
- /*! \brief
- * Sets the full description of the option collection from string array.
+ * Adds an option manager.
*
- * \param[in] descArray String array to set as the description.
+ * \param manager Manager to add.
+ * \throws std::bad_alloc if out of memory.
*
- * All strings in `descArray` are concatenated to form the description.
- * Spaces are inserted between strings if they are missing.
+ * 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.
*
- * Example usage:
- * \code
- const char *const desc[] = {
- "This is the description",
- "for the options"
- };
-
- gmx::Options options(NULL, NULL);
- options.setDescription(desc);
- \endcode
+ * Caller is responsible for memory management of \p manager.
+ * The Options object (and its contained options) only stores a
+ * reference to the object.
*
- * To use this overload, you must also include
- * `gromacs/utility/arrayref.h`.
+ * This method cannot be called after adding options or subsections.
*/
- void setDescription(const ConstArrayRef<const char *> &descArray);
+ void addManager(IOptionManager *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
* If an attempt is made, the function asserts.
*/
void addSubSection(Options *section);
- /*! \brief
- * Adds a recognized option to the collection.
- *
- * \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.
- */
- 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>();
- }
+
+ // From IOptionsContainer
+ virtual OptionInfo *addOption(const AbstractOption &settings);
+ using IOptionsContainer::addOption;
//! Returns true if option \p name is set.
bool isSet(const char *name) const;