Fix copyright notices for new C++ code.
[alexxy/gromacs.git] / src / gromacs / options / optionsassigner.h
1 /*
2  * This file is part of the GROMACS molecular simulation package.
3  *
4  * Copyright (c) 2010,2011,2012, by the GROMACS development team, led by
5  * David van der Spoel, Berk Hess, Erik Lindahl, and including many
6  * others, as listed in the AUTHORS file in the top-level source
7  * directory and at http://www.gromacs.org.
8  *
9  * GROMACS is free software; you can redistribute it and/or
10  * modify it under the terms of the GNU Lesser General Public License
11  * as published by the Free Software Foundation; either version 2.1
12  * of the License, or (at your option) any later version.
13  *
14  * GROMACS is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17  * Lesser General Public License for more details.
18  *
19  * You should have received a copy of the GNU Lesser General Public
20  * License along with GROMACS; if not, see
21  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
22  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
23  *
24  * If you want to redistribute modifications to GROMACS, please
25  * consider that scientific software is very special. Version
26  * control is crucial - bugs must be traceable. We will be happy to
27  * consider code for inclusion in the official distribution, but
28  * derived work must not be called official GROMACS. Details are found
29  * in the README & COPYING files - if they are missing, get the
30  * official version at http://www.gromacs.org.
31  *
32  * To help us fund GROMACS development, we humbly ask that you cite
33  * the research papers on the package. Check out http://www.gromacs.org.
34  */
35 /*! \libinternal \file
36  * \brief
37  * Declares gmx::OptionsAssigner.
38  *
39  * This header is only needed when implementing option parsers.
40  *
41  * \author Teemu Murtola <teemu.murtola@gmail.com>
42  * \inlibraryapi
43  * \ingroup module_options
44  */
45 #ifndef GMX_OPTIONS_OPTIONSASSIGNER_H
46 #define GMX_OPTIONS_OPTIONSASSIGNER_H
47
48 #include <string>
49
50 #include "../utility/common.h"
51
52 namespace gmx
53 {
54
55 class Options;
56
57 /*! \libinternal \brief
58  * Decorator class for assigning values to Options.
59  *
60  * This class extends the interface of an Options object by providing methods
61  * to set values for options.  It also keeps track of necessary state variables
62  * to assign values to options in subsections within the Options object.
63  * Typical use (without error handling):
64  * \code
65    gmx::options::Options options("name", "Title");
66    // Set up options
67
68    gmx::options::OptionsAssigner assigner(&options);
69    assigner.start();
70    assigner.startOption("opt1");
71    assigner.appendValue("3");
72    assigner.finishOption();
73    assigner.startSubSection("section");
74    assigner.startOption("opt2"); // Now in the subsection
75    assigner.appendValue("yes");
76    assigner.finishOption();
77    assigner.finishSubSection()
78    assigner.startOption("opt3"); // Again in the main options
79    assigner.appendValue("2");
80    assigner.finishOption();
81    assigner.finish();
82  * \endcode
83  *
84  * \inlibraryapi
85  * \ingroup module_options
86  */
87 class OptionsAssigner
88 {
89     public:
90         /*! \brief
91          * Creates an object that assigns to the given object.
92          */
93         explicit OptionsAssigner(Options *options);
94         ~OptionsAssigner();
95
96         /*! \brief
97          * Sets the assigner to recognize boolean options with a "no" prefix.
98          *
99          * With this option set, \c startOption("noname") is interpreted as
100          * \c startOption("name") followed by \c appendValue("no"), if there is
101          * no option by the name "noname", but there is a boolean option with
102          * name "name".
103          *
104          * By default, the prefix is not recognized.
105          *
106          * Can be set or cleared at any time, and will have effect on all
107          * subsequent calls of startOption().
108          *
109          * Does not throw.
110          */
111         void setAcceptBooleanNoPrefix(bool bEnabled);
112         /*! \brief
113          * Sets the assigner to find options in non-active sections.
114          *
115          * By default, options are only looked for in the currently active
116          * subsection.  With this option set, if no matching option is found in
117          * the current section, a breadth-first search is performed, first on
118          * all subsections of the current section, and then going up one level
119          * at a time.  The first matching option is used, and the current
120          * section is changed to the section that contains the matching option.
121          *
122          * Can be set or cleared at any time, and will have effect on all
123          * subsequent calls of startOption().
124          *
125          * Does not throw.
126          */
127         void setNoStrictSectioning(bool bEnabled);
128
129         /*! \brief
130          * Start assigning values.
131          *
132          * Does not throw.
133          */
134         void start();
135         /*! \brief
136          * Start assigning values to options in a subsection.
137          *
138          * \param[in] name  Name of the subsection to start assigning to.
139          * \throws InvalidInputError if such a subsection is not found.
140          *
141          * Strong exception safety guarantee.
142          */
143         void startSubSection(const char *name);
144         /*! \brief
145          * Start assigning values for an option.
146          *
147          * \param[in] name  Name of the option to start assigning to.
148          * \throws InvalidInputError if such an option is not found, or if the
149          *      option is specified more than once but doesn't support it.
150          *
151          * Strong exception safety guarantee.
152          */
153         void startOption(const char *name);
154         /*! \brief
155          * Appends a value to the value list of the current option.
156          *
157          * \param[in] value  String representation of the value to assign.
158          * \throws InvalidInputError if the value cannot be converted or if
159          *      there are too many values for an option.
160          *
161          * Basic exception safety guarantee:
162          * If this method throws, erroneous values are ignored, but it is
163          * possible to continue assigning values to the same option.  However,
164          * if \p value would result in more than one value, and some of them
165          * can be converted, but some result in errors, it is currently
166          * possible that some values have been added to the option even if an
167          * exception is thrown.
168          *
169          * Strong exception safety guarantee if the option provides value
170          * conversion with the same guarantee.  All options where a single
171          * input value always results in a single output value provide this.
172          *
173          * \internal
174          * This method provides the same exception safety guarantee as the
175          * OptionStorageTemplate::convertValue() method of the storage class
176          * implementing the option where the value is assigned to.
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 finishSubSection();
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         PrivateImplPointer<Impl> impl_;
210 };
211
212 } // namespace gmx
213
214 #endif