src/gromacs/options/options_impl.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2010-2018, The GROMACS development team.
   5  * Copyright (c) 2019,2021, by the GROMACS development team, led by
   6  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   7  * and including many others, as listed in the AUTHORS file in the
   8  * top-level source directory and at http://www.gromacs.org.
   9  *
  10  * GROMACS is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU Lesser General Public License
  12  * as published by the Free Software Foundation; either version 2.1
  13  * of the License, or (at your option) any later version.
  14  *
  15  * GROMACS is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  * Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public
  21  * License along with GROMACS; if not, see
  22  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  23  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  24  *
  25  * If you want to redistribute modifications to GROMACS, please
  26  * consider that scientific software is very special. Version
  27  * control is crucial - bugs must be traceable. We will be happy to
  28  * consider code for inclusion in the official distribution, but
  29  * derived work must not be called official GROMACS. Details are found
  30  * in the README & COPYING files - if they are missing, get the
  31  * official version at http://www.gromacs.org.
  32  *
  33  * To help us fund GROMACS development, we humbly ask that you cite
  34  * the research papers on the package. Check out http://www.gromacs.org.
  35  */
  36 /*! \internal \file
  37  * \brief
  38  * Declares private implementation class for gmx::Options.
  39  *
  40  * \author Teemu Murtola <teemu.murtola@gmail.com>
  41  * \ingroup module_options
  42  */
  43 #ifndef GMX_OPTIONS_OPTIONS_IMPL_H
  44 #define GMX_OPTIONS_OPTIONS_IMPL_H
  45
  46 #include <list>
  47 #include <map>
  48 #include <memory>
  49 #include <string>
  50 #include <vector>
  51
  52 #include "gromacs/options/abstractoption.h"
  53 #include "gromacs/options/abstractoptionstorage.h"
  54 #include "gromacs/options/ioptionscontainer.h"
  55 #include "gromacs/options/ioptionscontainerwithsections.h"
  56 #include "gromacs/options/optionmanagercontainer.h"
  57 #include "gromacs/options/options.h"
  58 #include "gromacs/options/optionsection.h"
  59 #include "gromacs/utility/classhelpers.h"
  60
  61 #include "isectionstorage.h"
  62
  63 namespace gmx
  64 {
  65
  66 namespace internal
  67 {
  68
  69 /*! \internal
  70  * \brief
  71  * Internal implementation class for storing an option section.
  72  *
  73  * All options are stored within a section: the top-level contents of an
  74  * Options object are handled within an unnamed, "root" section.
  75  * This class handles the common functionality for all sections, related to
  76  * storing the options and subsections.  Functionality specific to a section
  77  * type is provided by IOptionSectionStorage.
  78  *
  79  * \ingroup module_options
  80  */
  81 class OptionSectionImpl : public IOptionsContainerWithSections
  82 {
  83 public:
  84     /*! \internal \brief
  85      * Describes a group of options (see Options::addGroup()).
  86      *
  87      * \ingroup module_options
  88      */
  89     class Group : public IOptionsContainer
  90     {
  91     public:
  92         //! Convenience typedef for list of options.
  93         typedef std::vector<AbstractOptionStorage*> OptionList;
  94         //! Convenience typedef for list of subgroups.
  95         typedef std::list<Group> SubgroupList;
  96
  97         //! Creates a group within the given Options.
  98         explicit Group(OptionSectionImpl* parent) : parent_(parent) {}
  99
 100         // From IOptionsContainer
 101         IOptionsContainer& addGroup() override;
 102         OptionInfo*        addOptionImpl(const AbstractOption& settings) override;
 103
 104         //! Containing options object.
 105         OptionSectionImpl* parent_;
 106         /*! \brief
 107          * List of options, in insertion order.
 108          *
 109          * Pointers in this container point to the objects managed by
 110          * Impl::optionsMap_.
 111          */
 112         OptionList options_;
 113         //! List of groups, in insertion order.
 114         SubgroupList subgroups_;
 115     };
 116
 117     //! Smart pointer for managing an AbstractOptionStorage object.
 118     typedef std::unique_ptr<AbstractOptionStorage> AbstractOptionStoragePointer;
 119     //! Convenience typedef for a map that contains all the options.
 120     typedef std::map<std::string, AbstractOptionStoragePointer> OptionMap;
 121     //! Smart pointer for managing subsections.
 122     typedef std::unique_ptr<OptionSectionImpl> SectionPointer;
 123     //! Convenience typedef for a container for subsections.
 124     typedef std::vector<SectionPointer> SectionList;
 125
 126     //! Creates storage for a new section.
 127     OptionSectionImpl(const OptionManagerContainer&          managers,
 128                       std::unique_ptr<IOptionSectionStorage> storage,
 129                       const char*                            name) :
 130         managers_(managers),
 131         storage_(std::move(storage)),
 132         info_(this),
 133         name_(name),
 134         rootGroup_(this),
 135         storageInitialized_(false)
 136     {
 137     }
 138
 139     // From IOptionsContainerWithSections
 140     OptionSectionImpl* addSectionImpl(const AbstractOptionSection& section) override;
 141
 142     // From IOptionsContainer
 143     IOptionsContainer& addGroup() override;
 144     OptionInfo*        addOptionImpl(const AbstractOption& settings) override;
 145
 146     //! Returns section info object for this section.
 147     OptionSectionInfo& info() { return info_; }
 148     //! Returns section info object for this section.
 149     const OptionSectionInfo& info() const { return info_; }
 150
 151     /*! \brief
 152      * Finds a subsection by name.
 153      *
 154      * \param[in] name  Name to search for.
 155      * \returns Pointer to the found subsection, or NULL if not found.
 156      *
 157      * Does not throw.
 158      */
 159     OptionSectionImpl* findSection(const char* name) const;
 160     /*! \brief
 161      * Finds an option by name.
 162      *
 163      * \param[in] name  Name to search for.
 164      * \returns Pointer to the found option, or NULL if not found.
 165      *
 166      * Does not throw.
 167      */
 168     AbstractOptionStorage* findOption(const char* name) const;
 169
 170     /*! \brief
 171      * Called when entering the section.
 172      *
 173      * Calls AbstractOptionStorage::startSource() for all options.
 174      */
 175     void start();
 176     /*! \brief
 177      * Calls AbstractOptionStorage::finish() for all options.
 178      */
 179     void finish();
 180
 181     //! Reference to the option managers in the parent Options object.
 182     const OptionManagerContainer& managers_;
 183     //! Type-specific storage object for this section.
 184     std::unique_ptr<IOptionSectionStorage> storage_;
 185     //! Info object for this section.
 186     OptionSectionInfo info_;
 187     //! Name of this section (empty and unused for the root section).
 188     std::string name_;
 189     /*! \brief
 190      * Group that contains all options (and subgroups).
 191      *
 192      * This is used to store the insertion order of options.
 193      */
 194     Group rootGroup_;
 195     //! Map from option names to options; owns the option storage objects.
 196     OptionMap optionMap_;
 197     //! List of subsections, in insertion order.
 198     SectionList subsections_;
 199     //! Whether initStorage() has been called for `storage_`.
 200     bool storageInitialized_;
 201
 202     GMX_DISALLOW_COPY_AND_ASSIGN(OptionSectionImpl);
 203 };
 204
 205 /*! \internal
 206  * \brief
 207  * Private implementation class for Options.
 208  *
 209  * Note that in addition to Options, the OptionsAssigner class also directly
 210  * accesses this class.
 211  *
 212  * \ingroup module_options
 213  */
 214 class OptionsImpl
 215 {
 216 public:
 217     OptionsImpl();
 218
 219     //! Option managers set for this collection.
 220     OptionManagerContainer managers_;
 221     //! Root section for this collection.
 222     OptionSectionImpl rootSection_;
 223 };
 224
 225 } // namespace internal
 226
 227 } // namespace gmx
 228
 229 #endif