src/gromacs/options/optionsvisitor.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2010,2011,2012,2014,2016 by the GROMACS development team.
   5  * Copyright (c) 2017,2018,2019,2020, 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 /*! \libinternal \file
  37  * \brief
  38  * Declares gmx::OptionsVisitor interface and supporting classes.
  39  *
  40  * \author Teemu Murtola <teemu.murtola@gmail.com>
  41  * \inlibraryapi
  42  * \ingroup module_options
  43  */
  44 #ifndef GMX_OPTIONS_OPTIONSVISITOR_H
  45 #define GMX_OPTIONS_OPTIONSVISITOR_H
  46
  47 #include <cstddef>
  48
  49 #include <string>
  50
  51 #include "gromacs/options/abstractoption.h"
  52 #include "gromacs/utility/classhelpers.h"
  53
  54 namespace gmx
  55 {
  56
  57 class Options;
  58 class OptionSectionInfo;
  59
  60 namespace internal
  61 {
  62 class OptionSectionImpl;
  63 }
  64
  65 /*! \libinternal \brief
  66  * Pure interface for visiting options in a Options object.
  67  *
  68  * \see OptionsIterator
  69  *
  70  * \inlibraryapi
  71  * \ingroup module_options
  72  */
  73 class OptionsVisitor
  74 {
  75 public:
  76     virtual ~OptionsVisitor() {}
  77
  78     //! Called for each section.
  79     virtual void visitSection(const OptionSectionInfo& section) = 0;
  80     //! Called for each option.
  81     virtual void visitOption(const OptionInfo& option) = 0;
  82 };
  83
  84 /*! \libinternal \brief
  85  * Abstract base class for visiting options of a particular type.
  86  *
  87  * \see OptionsIterator
  88  * \see OptionsVisitor
  89  *
  90  * \inlibraryapi
  91  * \ingroup module_options
  92  */
  93 template<class InfoType>
  94 class OptionsTypeVisitor : public OptionsVisitor
  95 {
  96 public:
  97     ~OptionsTypeVisitor() override {}
  98
  99     void visitSection(const OptionSectionInfo& section) override = 0;
 100     /*! \brief
 101      * Called for each option of type \p InfoType.
 102      */
 103     virtual void visitOptionType(const InfoType& option) = 0;
 104
 105 private:
 106     void visitOption(const OptionInfo& option) override
 107     {
 108         const InfoType* subtype = option.toType<InfoType>();
 109         if (subtype != NULL)
 110         {
 111             visitOptionType(*subtype);
 112         }
 113     }
 114 };
 115
 116 /*! \libinternal \brief
 117  * Decorator class for visiting options in a Options object.
 118  *
 119  * This class provides an interface for looping through sections and
 120  * options in a Options object.
 121  *
 122  * Typical use (loop over all options, iteratively descending into
 123  * subsections):
 124  * \code
 125    class Visitor : public gmx::OptionsVisitor
 126    {
 127        public:
 128            virtual void visitSection(const OptionSectionInfo &section)
 129            {
 130                OptionsIterator iterator(section);
 131                iterator.acceptSections(this);
 132                iterator.acceptOptions(this);
 133            }
 134
 135            virtual void visitOption(const OptionInfo &option)
 136            {
 137                // Do something.
 138            }
 139    }
 140
 141    Visitor().visitSection(options.rootSection());
 142  * \endcode
 143  *
 144  * \inlibraryapi
 145  * \ingroup module_options
 146  */
 147 class OptionsIterator
 148 {
 149 public:
 150     /*! \brief
 151      * Creates an object for visiting options in a Options object.
 152      *
 153      * The created iterator iterates over the "root" section in the Options
 154      * object.
 155      */
 156     explicit OptionsIterator(const Options& options);
 157     //! Creates an object for visiting options in an options section.
 158     explicit OptionsIterator(const OptionSectionInfo& section);
 159
 160     //! Visits each section in the wrapped section.
 161     void acceptSections(OptionsVisitor* visitor) const;
 162     //! Visits each option in the wrapped section.
 163     void acceptOptions(OptionsVisitor* visitor) const;
 164
 165 private:
 166     //! The wrapped section object.
 167     const internal::OptionSectionImpl& section_;
 168
 169     GMX_DISALLOW_COPY_AND_ASSIGN(OptionsIterator);
 170 };
 171
 172 /*! \libinternal \brief
 173  * Pure interface for visiting options in a Options object, allowing
 174  * modifications.
 175  *
 176  * \see OptionsModifyingIterator
 177  *
 178  * \inlibraryapi
 179  * \ingroup module_options
 180  */
 181 class OptionsModifyingVisitor
 182 {
 183 public:
 184     virtual ~OptionsModifyingVisitor() {}
 185
 186     //! Called for each section.
 187     virtual void visitSection(OptionSectionInfo* section) = 0;
 188     //! Called for each option.
 189     virtual void visitOption(OptionInfo* option) = 0;
 190 };
 191
 192 /*! \libinternal \brief
 193  * Abstract base class for visiting options of a particular type, allowing
 194  * modifications.
 195  *
 196  * \see OptionsModifyingIterator
 197  * \see OptionsModifyingVisitor
 198  *
 199  * \inlibraryapi
 200  * \ingroup module_options
 201  */
 202 template<class InfoType>
 203 class OptionsModifyingTypeVisitor : public OptionsModifyingVisitor
 204 {
 205 public:
 206     ~OptionsModifyingTypeVisitor() override {}
 207
 208     void visitSection(OptionSectionInfo* section) override = 0;
 209     /*! \brief
 210      * Called for each option of type \p InfoType.
 211      */
 212     virtual void visitOptionType(InfoType* option) = 0;
 213
 214 private:
 215     void visitOption(OptionInfo* option) override
 216     {
 217         InfoType* subtype = option->toType<InfoType>();
 218         if (subtype != nullptr)
 219         {
 220             visitOptionType(subtype);
 221         }
 222     }
 223 };
 224
 225 /*! \libinternal \brief
 226  * Decorator class for visiting options in a Options object, allowing changes.
 227  *
 228  * This class works exactly like OptionsIterator, except that it uses
 229  * OptionsModifyingVisitor interface, which allows modifying the options.
 230  *
 231  * \see OptionsIterator
 232  *
 233  * \inlibraryapi
 234  * \ingroup module_options
 235  */
 236 class OptionsModifyingIterator
 237 {
 238 public:
 239     /*! \brief
 240      * Creates an object for visiting options in a Options object.
 241      *
 242      * The created iterator iterates over the "root" section in the Options
 243      * object.
 244      */
 245     explicit OptionsModifyingIterator(Options* options);
 246     //! Creates an object for visiting options in an options section.
 247     explicit OptionsModifyingIterator(OptionSectionInfo* section);
 248
 249     //! Visits each section in the wrapped section.
 250     void acceptSections(OptionsModifyingVisitor* visitor) const;
 251     //! Visits each option in the wrapped section.
 252     void acceptOptions(OptionsModifyingVisitor* visitor) const;
 253
 254 private:
 255     //! The wrapped section object.
 256     internal::OptionSectionImpl& section_;
 257
 258     GMX_DISALLOW_COPY_AND_ASSIGN(OptionsModifyingIterator);
 259 };
 260
 261 } // namespace gmx
 262
 263 #endif