src/gromacs/options/optionsassigner.h

   1 /*
   2  *
   3  *                This source code is part of
   4  *
   5  *                 G   R   O   M   A   C   S
   6  *
   7  *          GROningen MAchine for Chemical Simulations
   8  *
   9  * Written by David van der Spoel, Erik Lindahl, Berk Hess, and others.
  10  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
  11  * Copyright (c) 2001-2009, The GROMACS development team,
  12  * check out http://www.gromacs.org for more information.
  13
  14  * This program is free software; you can redistribute it and/or
  15  * modify it under the terms of the GNU General Public License
  16  * as published by the Free Software Foundation; either version 2
  17  * of the License, or (at your option) any later version.
  18  *
  19  * If you want to redistribute modifications, please consider that
  20  * scientific software is very special. Version control is crucial -
  21  * bugs must be traceable. We will be happy to consider code for
  22  * inclusion in the official distribution, but derived work must not
  23  * be called official GROMACS. Details are found in the README & COPYING
  24  * files - if they are missing, get the official version at www.gromacs.org.
  25  *
  26  * To help us fund GROMACS development, we humbly ask that you cite
  27  * the papers on the package - you can find them in the top README file.
  28  *
  29  * For more info, check our website at http://www.gromacs.org
  30  */
  31 /*! \libinternal \file
  32  * \brief
  33  * Declares gmx::OptionsAssigner.
  34  *
  35  * This header is only needed when implementing option parsers.
  36  *
  37  * \author Teemu Murtola <teemu.murtola@cbr.su.se>
  38  * \inlibraryapi
  39  * \ingroup module_options
  40  */
  41 #ifndef GMX_OPTIONS_OPTIONSASSIGNER_H
  42 #define GMX_OPTIONS_OPTIONSASSIGNER_H
  43
  44 #include <string>
  45
  46 namespace gmx
  47 {
  48
  49 class Options;
  50
  51 /*! \libinternal \brief
  52  * Decorator class for assigning values to Options.
  53  *
  54  * This class extends the interface of an Options object by providing methods
  55  * to set values for options.  It also keeps track of necessary state variables
  56  * to assign values to options in subsections within the Options object.
  57  * Typical use (without error handling):
  58  * \code
  59 gmx::options::Options options("name", "Title");
  60 // Set up options
  61
  62 gmx::options::OptionsAssigner assigner(&options);
  63 assigner.start();
  64 assigner.startOption("opt1");
  65 assigner.appendValue("3");
  66 assigner.finishOption();
  67 assigner.startSubSection("section");
  68 assigner.startOption("opt2"); // Now in the subsection
  69 assigner.appendValue("yes");
  70 assigner.finishOption();
  71 assigner.finishSubSection()
  72 assigner.startOption("opt3"); // Again in the main options
  73 assigner.appendValue("2");
  74 assigner.finishOption();
  75 assigner.finish();
  76  * \endcode
  77  *
  78  * \inlibraryapi
  79  * \ingroup module_options
  80  */
  81 class OptionsAssigner
  82 {
  83     public:
  84         /*! \brief
  85          * Creates an object that assigns to the given object.
  86          */
  87         OptionsAssigner(Options *options);
  88         ~OptionsAssigner();
  89
  90         /*! \brief
  91          * Sets the assigner to recognize boolean options with a "no" prefix.
  92          *
  93          * With this option set, \c startOption("noname") is interpreted as
  94          * \c startOption("name") followed by \c appendValue("no"), if there is
  95          * no option by the name "noname", but there is a boolean option with
  96          * name "name".
  97          *
  98          * By default, the prefix is not recognized.
  99          *
 100          * Can be set or cleared at any time, and will have effect on all
 101          * subsequent calls of startOption().
 102          *
 103          * Does not throw.
 104          */
 105         void setAcceptBooleanNoPrefix(bool enabled);
 106         /*! \brief
 107          * Sets the assigner to find options in non-active sections.
 108          *
 109          * By default, options are only looked for in the currently active
 110          * subsection.  With this option set, if no matching option is found in
 111          * the current section, a breadth-first search is performed, first on
 112          * all subsections of the current section, and then going up one level
 113          * at a time.  The first matching option is used, and the current
 114          * section is changed to the section that contains the matching option.
 115          *
 116          * Can be set or cleared at any time, and will have effect on all
 117          * subsequent calls of startOption().
 118          *
 119          * Does not throw.
 120          */
 121         void setNoStrictSectioning(bool enabled);
 122
 123         /*! \brief
 124          * Start assigning values.
 125          *
 126          * Does not throw.
 127          */
 128         void start();
 129         /*! \brief
 130          * Start assigning values to options in a subsection.
 131          *
 132          * \param[in] name  Name of the subsection to start assigning to.
 133          * \throws InvalidInputError if such a subsection is not found.
 134          *
 135          * Strong exception safety guarantee.
 136          */
 137         void startSubSection(const char *name);
 138         /*! \brief
 139          * Start assigning values for an option.
 140          *
 141          * \param[in] name  Name of the option to start assigning to.
 142          * \throws InvalidInputError if such an option is not found, or if the
 143          *      option is specified more than once but doesn't support it.
 144          *
 145          * Strong exception safety guarantee.
 146          */
 147         void startOption(const char *name);
 148         /*! \brief
 149          * Appends a value to the value list of the current option.
 150          *
 151          * \param[in] value  String representation of the value to assign.
 152          * \throws InvalidInputError if the value cannot be converted or if
 153          *      there are too many values for an option.
 154          *
 155          * Basic exception safety guarantee:
 156          * If this method throws, erroneous values are ignored, but it is
 157          * possible to continue assigning values to the same option.  However,
 158          * if \p value would result in more than one value, and some of them
 159          * can be converted, but some result in errors, it is currently
 160          * possible that some values have been added to the option even if an
 161          * exception is thrown.
 162          *
 163          * Strong exception safety guarantee if the option provides value
 164          * conversion with the same guarantee.  All options where a single
 165          * input value always results in a single output value provide this.
 166          *
 167          * \internal
 168          * This method provides the same exception safety guarantee as the
 169          * OptionStorageTemplate::convertValue() method of the storage class
 170          * implementing the option where the value is assigned to.
 171          */
 172         void appendValue(const std::string &value);
 173         /*! \brief
 174          * Finish assigning values for the current option.
 175          *
 176          * \throws InvalidInputError if the set of values since startOption()
 177          *      is not valid.
 178          *
 179          * If this method throws, it returns to the state where the option was
 180          * before startOption(), i.e., all values added with appendValue()
 181          * since the last startOption() are discarded.
 182          *
 183          * Independent of whether the method throws, the option opened with
 184          * startOption() will be closed after the call.
 185          */
 186         void finishOption();
 187         /*! \brief
 188          * Finish assigning values to a subsection.
 189          *
 190          * Does not throw.
 191          */
 192         void finishSubSection();
 193         /*! \brief
 194          * Finish assigning options through the object.
 195          *
 196          * Does not throw.
 197          */
 198         void finish();
 199
 200     private:
 201         class Impl;
 202
 203         Impl                   *_impl;
 204
 205         // Disallow copy and assign.
 206         OptionsAssigner(const OptionsAssigner &);
 207         void operator =(const OptionsAssigner &);
 208 };
 209
 210 } // namespace gmx
 211
 212 #endif