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