src/gromacs/options/optionsassigner.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2010,2011,2012,2013,2014 by the GROMACS development team.
   5  * Copyright (c) 2015,2016,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::OptionsAssigner.
  39  *
  40  * This header is only needed when implementing option parsers.
  41  *
  42  * \author Teemu Murtola <teemu.murtola@gmail.com>
  43  * \inlibraryapi
  44  * \ingroup module_options
  45  */
  46 #ifndef GMX_OPTIONS_OPTIONSASSIGNER_H
  47 #define GMX_OPTIONS_OPTIONSASSIGNER_H
  48
  49 #include <string>
  50
  51 #include "gromacs/utility/classhelpers.h"
  52
  53 namespace gmx
  54 {
  55
  56 class Options;
  57 class Any;
  58
  59 /*! \libinternal \brief
  60  * Decorator class for assigning values to Options.
  61  *
  62  * This class extends the interface of an Options object by providing methods
  63  * to set values for options.  It also keeps track of necessary state variables
  64  * to assign values to options in subsections within the Options object.
  65  * Typical use (without error handling):
  66  * \code
  67    gmx::Options options("name", "Title");
  68    // Set up options
  69
  70    gmx::OptionsAssigner assigner(&options);
  71    assigner.start();
  72    assigner.startOption("opt1");
  73    assigner.appendValue("3");
  74    assigner.finishOption();
  75    assigner.startSection("section");
  76    assigner.startOption("opt2"); // Now in the subsection
  77    assigner.appendValue("yes");
  78    assigner.finishOption();
  79    assigner.finishSection()
  80    assigner.startOption("opt3"); // Again in the main options
  81    assigner.appendValue("2");
  82    assigner.finishOption();
  83    assigner.finish();
  84  * \endcode
  85  *
  86  * \inlibraryapi
  87  * \ingroup module_options
  88  */
  89 class OptionsAssigner
  90 {
  91 public:
  92     /*! \brief
  93      * Creates an object that assigns to the given object.
  94      */
  95     explicit OptionsAssigner(Options* options);
  96     ~OptionsAssigner();
  97
  98     /*! \brief
  99      * Sets the assigner to recognize boolean options with a "no" prefix.
 100      *
 101      * With this option set, \c startOption("noname") is interpreted as
 102      * \c startOption("name") followed by \c appendValue("no"), if there is
 103      * no option by the name "noname", but there is a boolean option with
 104      * name "name".
 105      *
 106      * By default, the prefix is not recognized.
 107      *
 108      * Can be set or cleared at any time, and will have effect on all
 109      * subsequent calls of startOption().
 110      *
 111      * Does not throw.
 112      */
 113     void setAcceptBooleanNoPrefix(bool bEnabled);
 114
 115     /*! \brief
 116      * Starts assigning values.
 117      *
 118      * Does not throw.
 119      */
 120     void start();
 121     /*! \brief
 122      * Starts assigning values to options in a subsection.
 123      *
 124      * \param[in] name  Name of the subsection to start assigning to.
 125      * \throws InvalidInputError if such a subsection is not found.
 126      *
 127      * Strong exception safety guarantee.
 128      */
 129     void startSection(const char* name);
 130     /*! \brief
 131      * Starts assigning values for an option.
 132      *
 133      * \param[in] name  Name of the option to start assigning to.
 134      * \throws InvalidInputError if such an option is not found, or if the
 135      *      option is specified more than once but doesn't support it.
 136      */
 137     void startOption(const char* name);
 138     /*! \brief
 139      * Starts assigning values for an option.
 140      *
 141      * \param[in] name  Name of the option to start assigning to.
 142      * \returns   true if \p name is a valid option name.
 143      * \throws InvalidInputError if the option is specified more than once
 144      *      but doesn't support it.
 145      */
 146     bool tryStartOption(const char* name);
 147     /*! \brief
 148      * Appends a value to the value list of the current option.
 149      *
 150      * \param[in] value  Value to assign.
 151      * \throws InvalidInputError if the value cannot be converted or if
 152      *      there are too many values for an option.
 153      *
 154      * Basic exception safety guarantee:
 155      * If this method throws, erroneous values are ignored, but it is
 156      * possible to continue assigning values to the same option.  However,
 157      * if \p value would result in more than one value, and some of them
 158      * can be converted, but some result in errors, it is currently
 159      * possible that some values have been added to the option even if an
 160      * exception is thrown.
 161      *
 162      * Strong exception safety guarantee if the option provides value
 163      * conversion with the same guarantee.  All options where a single
 164      * input value always results in a single output value provide this.
 165      *
 166      * \internal
 167      * This method provides the same exception safety guarantee as the
 168      * OptionStorageTemplate::convertValue() method of the storage class
 169      * implementing the option where the value is assigned to.
 170      */
 171     void appendValue(const Any& value);
 172     /*! \brief
 173      * Appends a value to the value list of the current option.
 174      *
 175      * \param[in] value  Value to assign.
 176      *
 177      * See appendValue(const Any &) for more details.
 178      */
 179     void appendValue(const std::string& value);
 180     /*! \brief
 181      * Finish assigning values for the current option.
 182      *
 183      * \throws InvalidInputError if the set of values since startOption()
 184      *      is not valid.
 185      *
 186      * If this method throws, it returns to the state where the option was
 187      * before startOption(), i.e., all values added with appendValue()
 188      * since the last startOption() are discarded.
 189      *
 190      * Independent of whether the method throws, the option opened with
 191      * startOption() will be closed after the call.
 192      */
 193     void finishOption();
 194     /*! \brief
 195      * Finish assigning values to a subsection.
 196      *
 197      * Does not throw.
 198      */
 199     void finishSection();
 200     /*! \brief
 201      * Finish assigning options through the object.
 202      *
 203      * Does not throw.
 204      */
 205     void finish();
 206
 207 private:
 208     class Impl;
 209
 210     PrivateImplPointer<Impl> impl_;
 211 };
 212
 213 } // namespace gmx
 214
 215 #endif