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