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 checking):
  58  * \code
  59 gmx::options::Options options("name", "Title");
  60 // Set up options
  61
  62 gmx::options::OptionsAssigner assigner(&options);
  63 assigner.startOption("opt1");
  64 assigner.appendValue("3");
  65 assigner.startSubSection("section");
  66 assigner.startOption("opt2"); // Now in the subsection
  67 assigner.appendValue("yes");
  68 assigner.finishSubSection()
  69 assigner.startOption("opt3"); // Again in the main options
  70 assigner.appendValue("2");
  71 assigner.finish(); // At minimum, the return value of finish() should be checked.
  72  * \endcode
  73  *
  74  * As shown in the example, calling finishOption() or finishSubSection() is
  75  * optional; they are automatically called when appropriate by startOption(),
  76  * startSubSection(), and finish().
  77  * However, you need to call them explicitly if you want to act on the return
  78  * value: these calls do not influence the return value of
  79  * startOption() / startSubSection().
  80  * They do influence the return value of finish(), however.
  81  * The finish() method should always be called.
  82  *
  83  * \inlibraryapi
  84  * \ingroup module_options
  85  */
  86 class OptionsAssigner
  87 {
  88     public:
  89         /*! \brief
  90          * Creates an object that assigns to the given object.
  91          */
  92         OptionsAssigner(Options *options);
  93         ~OptionsAssigner();
  94
  95         /*! \brief
  96          * Sets the assigner to recognize boolean options with a "no" prefix.
  97          *
  98          * With this option set, \c startOption("noname") is interpreted as
  99          * \c startOption("name") followed by \c appendValue("no"), if there is
 100          * no option by the name "noname", but there is a boolean option with
 101          * name "name".
 102          *
 103          * By default, the prefix is not recognized.
 104          *
 105          * Can be set or cleared at any time, and will have effect on all
 106          * subsequent calls of startOption().
 107          */
 108         void setAcceptBooleanNoPrefix(bool enabled);
 109         /*! \brief
 110          * Sets the assigner to find options in non-active sections.
 111          *
 112          * By default, options are only looked for in the currently active
 113          * subsection.  With this option set, if no matching option is found in
 114          * the current section, a breadth-first search is performed, first on
 115          * all subsections of the current section, and then going up one level
 116          * at a time.  The first matching option is used, and the current
 117          * section is changed to the section that contains the matching option.
 118          *
 119          * Can be set or cleared at any time, and will have effect on all
 120          * subsequent calls of startOption().
 121          */
 122         void setNoStrictSectioning(bool enabled);
 123
 124         /*! \brief
 125          * Start assigning values.
 126          */
 127         void start();
 128         /*! \brief
 129          * Start assigning values to options in a subsection.
 130          *
 131          * \param[in] name  Name of the subsection to start assigning to.
 132          */
 133         void startSubSection(const char *name);
 134         /*! \brief
 135          * Start assigning values for an option.
 136          *
 137          * \param[in] name  Name of the option to start assigning to.
 138          */
 139         void startOption(const char *name);
 140         /*! \brief
 141          * Appends a value to the value list of the current option.
 142          *
 143          * \param[in] value  String representation of the value to assign.
 144          */
 145         void appendValue(const std::string &value);
 146         /*! \brief
 147          * Finish assigning values for the current option.
 148          */
 149         void finishOption();
 150         /*! \brief
 151          * Finish assigning values to a subsection.
 152          */
 153         void finishSubSection();
 154         /*! \brief
 155          * Finish assigning options through the object.
 156          */
 157         void finish();
 158
 159     private:
 160         class Impl;
 161
 162         Impl                   *_impl;
 163
 164         // Disallow copy and assign.
 165         OptionsAssigner(const OptionsAssigner &);
 166         void operator =(const OptionsAssigner &);
 167 };
 168
 169 } // namespace gmx
 170
 171 #endif