src/gromacs/options/repeatingsection.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2016, 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/options/abstractsection.h"
  50 #include "gromacs/options/ioptionscontainerwithsections.h"
  51 #include "gromacs/options/isectionstorage.h"
  52 #include "gromacs/options/valuestore.h"
  53
  54 namespace gmx
  55 {
  56
  57 template <class T> class RepeatingOptionSectionHandle;
  58 template <class T> class RepeatingOptionSectionStorage;
  59
  60 /*! \brief
  61  * Declares an option section that creates a structure for each instance.
  62  *
  63  * \tparam  T  Structure that stores the values for an instance of the section.
  64  *
  65  * This class declares a section that can be specified multiple times, and
  66  * creates an instance of `T` for each instance.  Options within the section
  67  * can store their values in the created structure.
  68  *
  69  * \inpublicapi
  70  * \ingroup module_options
  71  */
  72 template <class T>
  73 class RepeatingOptionSection : public AbstractOptionSection
  74 {
  75     public:
  76         //! AbstractOptionSectionHandle corresponding to this option type.
  77         typedef RepeatingOptionSectionHandle<T> HandleType;
  78
  79         //! Creates a section with the given name.
  80         explicit RepeatingOptionSection(const char *name)
  81             : AbstractOptionSection(name), values_(nullptr)
  82         {
  83         }
  84
  85         //! Specifies a vector to receive the section structures.
  86         RepeatingOptionSection &storeVector(std::vector<T> *values)
  87         {
  88             values_ = values;
  89             return *this;
  90         }
  91
  92     private:
  93         virtual IOptionSectionStorage *createStorage() const;
  94
  95         std::vector<T> *values_;
  96
  97         //! Allows accessing the properties when initializing the storage.
  98         friend class RepeatingOptionSectionStorage<T>;
  99 };
 100
 101 /*! \internal
 102  * \brief
 103  * Implements handling of the structures that stores per-section values.
 104  *
 105  * \ingroup module_options
 106  */
 107 template <class T>
 108 class RepeatingOptionSectionStorage : public IOptionSectionStorage
 109 {
 110     public:
 111         //! Initializes the storage for given section properties.
 112         explicit RepeatingOptionSectionStorage(const RepeatingOptionSection<T> &section)
 113             : store_(new OptionValueStoreVector<T>(section.values_)), currentData_()
 114         {
 115         }
 116
 117         virtual void initStorage()
 118         {
 119             defaultValues_ = currentData_;
 120         }
 121         virtual void startSection()
 122         {
 123             resetSection();
 124         }
 125         virtual void finishSection()
 126         {
 127             store_->append(currentData_);
 128             resetSection();
 129         }
 130
 131     private:
 132         void resetSection()
 133         {
 134             currentData_ = defaultValues_;
 135         }
 136
 137         //! Final storage location for the section structures.
 138         const std::unique_ptr<IOptionValueStore<T> > store_;
 139         T                                            defaultValues_;
 140         /*! \brief
 141          * Stores the values for the current in-process section.
 142          *
 143          * Options within the section store their values to this structure, and
 144          * they are then copied to the final storage when the section finishes.
 145          */
 146         T                                            currentData_;
 147
 148         //! Allows binding option storage to the current section data structure.
 149         friend class RepeatingOptionSectionHandle<T>;
 150 };
 151
 152 template <class T>
 153 IOptionSectionStorage *RepeatingOptionSection<T>::createStorage() const
 154 {
 155     return new RepeatingOptionSectionStorage<T>(*this);
 156 }
 157
 158 /*! \brief
 159  * Allows adding options to an RepeatingOptionSection.
 160  *
 161  * An instance of this class is returned from
 162  * IOptionsContainerWithSections::addSection(), and supports adding options and
 163  * subsections to a section created with OptionSection.
 164  *
 165  * Example:
 166  * \code
 167    struct SectionData { int value; }
 168    // as class attribute
 169    std::vector<SectionData> values;
 170
 171    void MyClass::initOptions(gmx::IOptionsContainerWithSections *options)
 172    {
 173        auto sec = options->addSection(gmx::RepeatingOptionSection<SectionData>("sec").storeVector(&values));
 174        sec->addOption(gmx::IntegerOption("arg").store(&sec.bind().value));
 175    }
 176    \endcode
 177  *
 178  * \inpublicapi
 179  * \ingroup module_options
 180  */
 181 template <class T>
 182 class RepeatingOptionSectionHandle : public AbstractOptionSectionHandle
 183 {
 184     public:
 185         //! Wraps a given section storage object.
 186         explicit RepeatingOptionSectionHandle(internal::OptionSectionImpl *section)
 187             : AbstractOptionSectionHandle(section),
 188               storage_(getStorage<RepeatingOptionSectionStorage<T> >(section))
 189         {
 190         }
 191
 192         /*! \brief
 193          * Supports storing option values within the per-section data structure.
 194          *
 195          * See class documentation for an example.
 196          */
 197         T &bind()
 198         {
 199             return storage_->currentData_;
 200         }
 201
 202     private:
 203         RepeatingOptionSectionStorage<T> *storage_;
 204 };
 205
 206 } // namespace gmx
 207
 208 #endif