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
33 * Defines gmx::AbstractOption and a related template.
35 * This header defines base classes for option settings that are used with
36 * Options::addOption(). These classes implement the "named parameter"
37 * idiom for specifying option properties.
39 * These classes also take care of creating and setting up the actual option
42 * This header is needed directly only when implementing new option types,
43 * but methods of OptionTemplate are visible even to the normal user through
46 * \author Teemu Murtola <teemu.murtola@cbr.su.se>
48 * \ingroup module_options
50 #ifndef GMX_OPTIONS_ABSTRACTOPTION_H
51 #define GMX_OPTIONS_ABSTRACTOPTION_H
56 #include "../utility/uniqueptr.h"
58 #include "optionflags.h"
63 class AbstractOptionStorage;
64 template <typename T> class OptionStorageTemplate;
67 //! Smart pointer for managing an AbstractOptionStorage object.
68 typedef gmx_unique_ptr<AbstractOptionStorage>::type
69 AbstractOptionStoragePointer;
72 * Abstract base class for specifying option properties.
74 * Concrete classes should normally not derive directly from this class,
75 * but from OptionTemplate instead. Classes derived from this class
76 * are mainly designed to implement the "named parameter" idiom. For
77 * efficiency and clarity, these classes should only store values provided to
78 * them. All error checking and memory management should be postponed to the
79 * point when the actual option is created.
81 * Subclasses should override createStorage() to create the correct type
84 * \ingroup module_options
89 // Virtual only for completeness, in normal use should not be needed.
90 virtual ~AbstractOption() { }
94 //! Initializes the name and default values for an option.
95 explicit AbstractOption(const char *name)
96 : _minValueCount(1), _maxValueCount(1),
97 _name(name), _descr(NULL)
101 * Creates a default storage object for the option.
103 * \returns The created storage object.
104 * \throws APIError if invalid option settings have been provided.
106 * This method is called by Options::addOption() when initializing an
107 * option from the settings.
109 * Derived classes should implement the method to create an actual
110 * storage object and populate it with correct values.
111 * They should also throw APIError if they detect problems.
113 * Should only be called by Options::addOption().
115 virtual AbstractOptionStoragePointer createStorage() const = 0;
118 * Creates the description string for the option.
120 * \returns Description string for the option.
122 * This function is virtual to allow derived classes to customize the
123 * description programmatically, e.g., by adding the list of allowed
125 * The default implementation simply returns the user-provided
128 virtual std::string createDescription() const
129 { return _descr ? _descr : ""; }
131 //! Sets the description for the option.
132 void setDescription(const char *descr) { _descr = descr; }
133 //! Sets a flag for the option.
134 void setFlag(OptionFlag flag) { _flags.set(flag); }
135 //! Clears a flag for the option.
136 void clearFlag(OptionFlag flag) { _flags.clear(flag); }
137 //! Sets or clears a flag for the option.
138 void setFlag(OptionFlag flag, bool bSet) { _flags.set(flag, bSet); }
139 //! Returns true if the option is vector-valued.
140 bool isVector() const { return hasFlag(efVector); }
141 //! Sets the option to be vector-valued.
146 if (_maxValueCount == 1)
151 //! Sets the required number of values for the option.
152 void setValueCount(int count)
154 if (!hasFlag(efVector))
156 _minValueCount = count;
158 _maxValueCount = count;
161 //! Minimum number of values required for the option.
163 //! Maximum number of values allowed for the option.
168 //! Returns true if a flag has been set.
169 bool hasFlag(OptionFlag flag) const { return _flags.test(flag); }
172 //! Pointer to description of the option.
177 * Needed to initialize an AbstractOptionStorage object from this class
178 * without otherwise unnecessary accessors.
180 friend class AbstractOptionStorage;
182 * Needed to be able to call createStorage().
184 friend class Options;
188 * Templated base class for constructing concrete option settings classes.
190 * \tparam T Assignable type that stores a single option value.
191 * \tparam U Type of the derived class.
193 * This template is used as a base class like this:
195 class ConcreteOption : public OptionTemplate<int, ConcreteOption>
199 * All public functions in this class return \c *this casted to a reference to
200 * \p U. They do not throw.
202 * For examples of how to use classes derived from this class, see the class
203 * documentation for Options.
206 * \ingroup module_options
208 template <typename T, class U>
209 class OptionTemplate : public AbstractOption
212 //! Type that stores a single option value.
214 //! Alias for the derived class type.
218 * Sets a description for the option.
220 * \param[in] descr Description to set.
222 * String in \p descr is copied when the option is created.
224 MyClass &description(const char *descr)
225 { setDescription(descr); return me(); }
226 //! Hides the option from normal help output.
227 MyClass &hidden(bool bHidden = true)
228 { setFlag(efHidden, bHidden); return me(); }
229 //! Requires the option to be specified explicitly.
230 MyClass &required(bool bRequired = true)
231 { setFlag(efRequired, bRequired); return me(); }
232 //! Allows the option to be specified multiple times.
233 MyClass &allowMultiple(bool bMulti = true)
234 { setFlag(efMulti, bMulti); return me(); }
235 //! Requires exactly \p count values for the option.
236 MyClass &valueCount(int count) { setValueCount(count); return me(); }
237 //! Allows any number of values for the option.
238 MyClass &multiValue() { _maxValueCount = -1; return me(); }
241 * Sets a default value for the option.
243 * \param[in] defaultValue Default value.
245 * If the option is never set, the default value is copied to the
246 * assigned storage. Note that if the option is not set and there
247 * is no default value, the storage is not altered, which can also be
248 * used to provide a default value. The latter method has to be used
249 * if the option can take multiple values.
250 * If required() is specified, only affects the default value shown in
253 * \p defaultValue is copied when the option is created.
255 MyClass &defaultValue(const T &defaultValue)
256 { _defaultValue = &defaultValue; return me(); }
258 * Sets a default value for the option when it is set.
260 * \param[in] defaultValue Default value.
262 * This value is used if the option is set, but no value is provided.
263 * If the option is never set, the value set with defaultValue() is
264 * used. Can only be used for options that accept a single value.
266 * \p defaultValue is copied when the option is created.
268 MyClass &defaultValueIfSet(const T &defaultValue)
269 { _defaultValueIfSet = &defaultValue; return me(); }
271 * Stores value(s) in memory pointed by \p store.
273 * \param[in] store Storage for option value(s).
275 * The caller is responsible for allocating enough memory such that
276 * the any allowed number of values fits into the array pointed by
277 * \p store. If there is no maximum allowed number or if the maximum
278 * is inconveniently large, storeVector() should be used.
280 * For information on when values are available in the storage, see
283 * The pointer provided should remain valid as long as the associated
284 * Options object exists.
286 MyClass &store(T *store)
287 { setFlag(efExternalStore); _store = store; return me(); }
289 * Stores number of values in the value pointed by \p countptr.
291 * \param[in] countptr Storage for the number of values.
293 * For information on when values are available in the storage, see
296 * The pointers provided should remain valid as long as the associated
297 * Options object exists.
299 MyClass &storeCount(int *countptr)
300 { _countptr = countptr; return me(); }
302 * Stores option values in the provided vector.
304 * \param[in] store Vector to store option values in.
306 * Values are added to the vector after each successful set of values
307 * is parsed. Note that for some options, the value may be changed
308 * later, and is only guaranteed to be correct after Options::finish()
311 * The pointer provided should remain valid as long as the associated
312 * Options object exists.
314 MyClass &storeVector(std::vector<T> *store)
315 { setFlag(efExternalValueVector); _storeVector = store; return me(); }
319 //! Alias for the template class for use in base classes.
320 typedef OptionTemplate<T, U> MyBase;
322 //! Initializes the name and default values for an option.
323 explicit OptionTemplate(const char *name)
324 : AbstractOption(name),
325 _defaultValue(NULL), _defaultValueIfSet(NULL), _store(NULL),
326 _countptr(NULL), _storeVector(NULL)
330 * Returns a pointer to user-specified default value, or NULL if there
333 const T *defaultValue() const { return _defaultValue; }
335 * Returns a pointer to user-specified default value, or NULL if there
338 const T *defaultValueIfSet() const { return _defaultValueIfSet; }
339 //! Returns \p *this casted into MyClass to reduce typing.
340 MyClass &me() { return static_cast<MyClass &>(*this); }
344 const T *_defaultValue;
345 const T *_defaultValueIfSet;
348 std::vector<T> *_storeVector;
351 * Needed to initialize storage from this class without otherwise
352 * unnecessary accessors.
354 friend class OptionStorageTemplate<T>;