3 * This source code is part of
7 * GROningen MAchine for Chemical Simulations
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.
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.
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.
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.
29 * For more info, check our website at http://www.gromacs.org
31 /*! \libinternal \file
33 * Declares gmx::OptionsAssigner.
35 * This header is only needed when implementing option parsers.
37 * \author Teemu Murtola <teemu.murtola@cbr.su.se>
39 * \ingroup module_options
41 #ifndef GMX_OPTIONS_OPTIONSASSIGNER_H
42 #define GMX_OPTIONS_OPTIONSASSIGNER_H
46 #include "../utility/common.h"
53 /*! \libinternal \brief
54 * Decorator class for assigning values to Options.
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):
61 gmx::options::Options options("name", "Title");
64 gmx::options::OptionsAssigner assigner(&options);
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();
81 * \ingroup module_options
87 * Creates an object that assigns to the given object.
89 explicit OptionsAssigner(Options *options);
93 * Sets the assigner to recognize boolean options with a "no" prefix.
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
100 * By default, the prefix is not recognized.
102 * Can be set or cleared at any time, and will have effect on all
103 * subsequent calls of startOption().
107 void setAcceptBooleanNoPrefix(bool bEnabled);
109 * Sets the assigner to find options in non-active sections.
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.
118 * Can be set or cleared at any time, and will have effect on all
119 * subsequent calls of startOption().
123 void setNoStrictSectioning(bool bEnabled);
126 * Start assigning values.
132 * Start assigning values to options in a subsection.
134 * \param[in] name Name of the subsection to start assigning to.
135 * \throws InvalidInputError if such a subsection is not found.
137 * Strong exception safety guarantee.
139 void startSubSection(const char *name);
141 * Start assigning values for an option.
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.
147 * Strong exception safety guarantee.
149 void startOption(const char *name);
151 * Appends a value to the value list of the current option.
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.
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.
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.
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.
174 void appendValue(const std::string &value);
176 * Finish assigning values for the current option.
178 * \throws InvalidInputError if the set of values since startOption()
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.
185 * Independent of whether the method throws, the option opened with
186 * startOption() will be closed after the call.
190 * Finish assigning values to a subsection.
194 void finishSubSection();
196 * Finish assigning options through the object.
205 PrivateImplPointer<Impl> impl_;