src/gromacs/options/repeatingsection.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2016,2018, by the GROMACS development team, led by
   5  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   6  * and including many others, as listed in the AUTHORS file in the
   7  * top-level source directory and at http://www.gromacs.org.
   8  *
   9  * GROMACS is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public License
  11  * as published by the Free Software Foundation; either version 2.1
  12  * of the License, or (at your option) any later version.
  13  *
  14  * GROMACS is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with GROMACS; if not, see
  21  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  23  *
  24  * If you want to redistribute modifications to GROMACS, please
  25  * consider that scientific software is very special. Version
  26  * control is crucial - bugs must be traceable. We will be happy to
  27  * consider code for inclusion in the official distribution, but
  28  * derived work must not be called official GROMACS. Details are found
  29  * in the README & COPYING files - if they are missing, get the
  30  * official version at http://www.gromacs.org.
  31  *
  32  * To help us fund GROMACS development, we humbly ask that you cite
  33  * the research papers on the package. Check out http://www.gromacs.org.
  34  */
  35 /*! \file
  36  * \brief
  37  * Declares gmx::RepeatingOptionSection and related classes.
  38  *
  39  * \author Teemu Murtola <teemu.murtola@gmail.com>
  40  * \inpublicapi
  41  * \ingroup module_options
  42  */
  43 #ifndef GMX_OPTIONS_REPEATINGSECTION_H
  44 #define GMX_OPTIONS_REPEATINGSECTION_H
  45
  46 #include <memory>
  47 #include <vector>
  48
  49 #include "gromacs/compat/make_unique.h"
  50 #include "gromacs/options/abstractsection.h"
  51 #include "gromacs/options/ioptionscontainerwithsections.h"
  52 #include "gromacs/options/isectionstorage.h"
  53 #include "gromacs/options/valuestore.h"
  54
  55 namespace gmx
  56 {
  57
  58 template <class T> class RepeatingOptionSectionHandle;
  59 template <class T> class RepeatingOptionSectionStorage;
  60
  61 /*! \brief
  62  * Declares an option section that creates a structure for each instance.
  63  *
  64  * \tparam  T  Structure that stores the values for an instance of the section.
  65  *
  66  * This class declares a section that can be specified multiple times, and
  67  * creates an instance of `T` for each instance.  Options within the section
  68  * can store their values in the created structure.
  69  *
  70  * \inpublicapi
  71  * \ingroup module_options
  72  */
  73 template <class T>
  74 class RepeatingOptionSection : public AbstractOptionSection
  75 {
  76     public:
  77         //! AbstractOptionSectionHandle corresponding to this option type.
  78         typedef RepeatingOptionSectionHandle<T> HandleType;
  79
  80         //! Creates a section with the given name.
  81         explicit RepeatingOptionSection(const char *name)
  82             : AbstractOptionSection(name), values_(nullptr)
  83         {
  84         }
  85
  86         //! Specifies a vector to receive the section structures.
  87         RepeatingOptionSection &storeVector(std::vector<T> *values)
  88         {
  89             values_ = values;
  90             return *this;
  91         }
  92
  93     private:
  94         virtual std::unique_ptr<IOptionSectionStorage> createStorage() const;
  95
  96         std::vector<T> *values_;
  97
  98         //! Allows accessing the properties when initializing the storage.
  99         friend class RepeatingOptionSectionStorage<T>;
 100 };
 101
 102 /*! \internal
 103  * \brief
 104  * Implements handling of the structures that stores per-section values.
 105  *
 106  * \ingroup module_options
 107  */
 108 template <class T>
 109 class RepeatingOptionSectionStorage : public IOptionSectionStorage
 110 {
 111     public:
 112         //! Initializes the storage for given section properties.
 113         explicit RepeatingOptionSectionStorage(const RepeatingOptionSection<T> &section)
 114             : store_(new OptionValueStoreVector<T>(section.values_)), currentData_()
 115         {
 116         }
 117
 118         virtual void initStorage()
 119         {
 120             defaultValues_ = currentData_;
 121         }
 122         virtual void startSection()
 123         {
 124             resetSection();
 125         }
 126         virtual void finishSection()
 127         {
 128             store_->append(currentData_);
 129             resetSection();
 130         }
 131
 132     private:
 133         void resetSection()
 134         {
 135             currentData_ = defaultValues_;
 136         }
 137
 138         //! Final storage location for the section structures.
 139         const std::unique_ptr<IOptionValueStore<T> > store_;
 140         T                                            defaultValues_;
 141         /*! \brief
 142          * Stores the values for the current in-process section.
 143          *
 144          * Options within the section store their values to this structure, and
 145          * they are then copied to the final storage when the section finishes.
 146          */
 147         T                                            currentData_;
 148
 149         //! Allows binding option storage to the current section data structure.
 150         friend class RepeatingOptionSectionHandle<T>;
 151 };
 152
 153 template <class T>
 154 std::unique_ptr<IOptionSectionStorage> RepeatingOptionSection<T>::createStorage() const
 155 {
 156
 157     return compat::make_unique<RepeatingOptionSectionStorage<T> >(*this);
 158 }
 159
 160 /*! \brief
 161  * Allows adding options to an RepeatingOptionSection.
 162  *
 163  * An instance of this class is returned from
 164  * IOptionsContainerWithSections::addSection(), and supports adding options and
 165  * subsections to a section created with OptionSection.
 166  *
 167  * Example:
 168  * \code
 169    struct SectionData { int value; }
 170    // as class attribute
 171    std::vector<SectionData> values;
 172
 173    void MyClass::initOptions(gmx::IOptionsContainerWithSections *options)
 174    {
 175        auto sec = options->addSection(gmx::RepeatingOptionSection<SectionData>("sec").storeVector(&values));
 176        sec->addOption(gmx::IntegerOption("arg").store(&sec.bind().value));
 177    }
 178    \endcode
 179  *
 180  * \inpublicapi
 181  * \ingroup module_options
 182  */
 183 template <class T>
 184 class RepeatingOptionSectionHandle : public AbstractOptionSectionHandle
 185 {
 186     public:
 187         //! Wraps a given section storage object.
 188         explicit RepeatingOptionSectionHandle(internal::OptionSectionImpl *section)
 189             : AbstractOptionSectionHandle(section),
 190               storage_(getStorage<RepeatingOptionSectionStorage<T> >(section))
 191         {
 192         }
 193
 194         /*! \brief
 195          * Supports storing option values within the per-section data structure.
 196          *
 197          * See class documentation for an example.
 198          */
 199         T &bind()
 200         {
 201             return storage_->currentData_;
 202         }
 203
 204     private:
 205         RepeatingOptionSectionStorage<T> *storage_;
 206 };
 207
 208 } // namespace gmx
 209
 210 #endif