2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2010,2011,2012,2013,2014,2015, by the GROMACS development team, led by
5 * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
6 * and including many others, as listed in the AUTHORS file in the
7 * top-level source directory and at http://www.gromacs.org.
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.
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.
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.
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.
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.
37 * Defines gmx::AbstractOption, gmx::OptionTemplate and gmx::OptionInfo.
39 * This header defines base classes for option settings that are used with
40 * Options::addOption(). These classes implement the "named parameter"
41 * idiom for specifying option properties.
43 * These classes also take care of creating and setting up the actual option
46 * This header is needed directly only when implementing new option types,
47 * but methods of OptionTemplate are visible even to the normal user through
50 * \author Teemu Murtola <teemu.murtola@gmail.com>
52 * \ingroup module_options
54 #ifndef GMX_OPTIONS_ABSTRACTOPTION_H
55 #define GMX_OPTIONS_ABSTRACTOPTION_H
60 #include "gromacs/options/optionflags.h"
61 #include "gromacs/utility/classhelpers.h"
66 class AbstractOptionStorage;
67 template <typename T> class OptionStorageTemplate;
68 class OptionManagerContainer;
76 * Abstract base class for specifying option properties.
78 * Concrete classes should normally not derive directly from this class,
79 * but from OptionTemplate instead. Classes derived from this class
80 * are mainly designed to implement the "named parameter" idiom. For
81 * efficiency and clarity, these classes should only store values provided to
82 * them. All error checking and memory management should be postponed to the
83 * point when the actual option is created.
85 * Subclasses should override createStorage() to create the correct type
86 * of storage object. If they use their own info type derived from OptionInfo,
87 * they should also have a public typedef \c InfoType that specifies that
88 * info type. This is required for Options::addOption() to return the correct
91 * \ingroup module_options
96 // Virtual only for completeness, in normal use should not be needed.
97 virtual ~AbstractOption() { }
101 //! Initializes the name and default values for an option.
102 explicit AbstractOption(const char *name)
103 : minValueCount_(1), maxValueCount_(1),
104 name_(name), descr_(NULL), storeIsSet_(NULL)
108 * Creates a default storage object for the option.
110 * \param[in] managers Manager container (unused if the option does
111 * not use a manager).
112 * \returns The created storage object.
113 * \throws APIError if invalid option settings have been provided.
115 * This method is called by Options::addOption() when initializing an
116 * option from the settings.
118 * Derived classes should implement the method to create an actual
119 * storage object and populate it with correct values.
120 * They should also throw APIError if they detect problems.
122 * Should only be called by Options::addOption().
124 * The ownership of the return value is passed, but is not using a
125 * smart pointer to avoid introducing such a dependency in an installed
126 * header. The implementation will always consist of a single `new`
127 * call and returning that value, and the caller always immediately
128 * wraps the pointer in a smart pointer, so there is not exception
131 virtual AbstractOptionStorage *createStorage(
132 const OptionManagerContainer &managers) const = 0;
134 //! Sets the description for the option.
135 void setDescription(const char *descr) { descr_ = descr; }
136 //! Sets the storage location for whether the option is set.
137 void setStoreIsSet(bool *store) { storeIsSet_ = store; }
138 //! Sets a flag for the option.
139 void setFlag(OptionFlag flag) { flags_.set(flag); }
140 //! Clears a flag for the option.
141 void clearFlag(OptionFlag flag) { flags_.clear(flag); }
142 //! Sets or clears a flag for the option.
143 void setFlag(OptionFlag flag, bool bSet) { flags_.set(flag, bSet); }
144 //! Returns true if the option is vector-valued.
145 bool isVector() const { return hasFlag(efOption_Vector); }
147 * Sets the option to be vector-valued.
149 * This method is provided for convenience to make management of value
150 * counts easier. In order to implement a vector-valued option, the
151 * class derived from AbstractOption should expose a method that calls
152 * this method, and the storage object derived from
153 * AbstractOptionStorage should check isVector().
154 * If only a single value is provided, the storage object should fill
155 * the whole vector with that value.
157 * The length of the vector (the value of maxValueCount_) must be
158 * fixed. The default length is 3 elements.
162 setFlag(efOption_Vector);
164 if (maxValueCount_ == 1)
169 //! Sets the required number of values for the option.
170 void setValueCount(int count)
172 if (!hasFlag(efOption_Vector))
174 minValueCount_ = count;
176 maxValueCount_ = count;
179 //! Minimum number of values required for the option.
181 //! Maximum number of values allowed for the option.
186 //! Returns true if a flag has been set.
187 bool hasFlag(OptionFlag flag) const { return flags_.test(flag); }
190 //! Pointer to description of the option.
196 * Needed to initialize an AbstractOptionStorage object from this class
197 * without otherwise unnecessary accessors.
199 friend class AbstractOptionStorage;
200 //! Needed to be able to call createStorage().
201 friend class internal::OptionsImpl;
205 * Templated base class for constructing concrete option settings classes.
207 * \tparam T Assignable type that stores a single option value.
208 * \tparam U Type of the derived class.
210 * This template is used as a base class like this:
212 class ConcreteOption : public OptionTemplate<int, ConcreteOption>
216 * All public functions in this class return \c *this casted to a reference to
217 * \p U. They do not throw.
219 * For examples of how to use classes derived from this class, see the class
220 * documentation for Options.
223 * \ingroup module_options
225 template <typename T, class U>
226 class OptionTemplate : public AbstractOption
229 //! Type that stores a single option value.
231 //! Alias for the derived class type.
235 * Sets a description for the option.
237 * \param[in] descr Description to set.
239 * String in \p descr is copied when the option is created.
241 MyClass &description(const char *descr)
242 { setDescription(descr); return me(); }
243 //! Hides the option from normal help output.
244 MyClass &hidden(bool bHidden = true)
245 { setFlag(efOption_Hidden, bHidden); return me(); }
247 * Requires the option to be specified explicitly.
249 * Note that if you specify defaultValue() together with required(),
250 * the user is not required to explicitly provide the option.
251 * In this case, required() only affects possible help output.
253 MyClass &required(bool bRequired = true)
254 { setFlag(efOption_Required, bRequired); return me(); }
255 //! Allows the option to be specified multiple times.
256 MyClass &allowMultiple(bool bMulti = true)
257 { setFlag(efOption_MultipleTimes, bMulti); return me(); }
258 //! Requires exactly \p count values for the option.
259 MyClass &valueCount(int count) { setValueCount(count); return me(); }
260 //! Allows any number of values for the option.
261 MyClass &multiValue(bool bMulti = true)
262 { if (bMulti) { maxValueCount_ = -1; } return me(); }
265 * Sets a default value for the option.
267 * \param[in] defaultValue Default value.
269 * If the option is never set, the default value is copied to the
270 * assigned storage. Note that if the option is not set and there
271 * is no default value, the storage is not altered, which can also be
272 * used to provide a default value. The latter method has to be used
273 * if the option can take multiple values.
275 * \p defaultValue is copied when the option is created.
277 MyClass &defaultValue(const T &defaultValue)
278 { defaultValue_ = &defaultValue; return me(); }
280 * Sets a default value for the option when it is set.
282 * \param[in] defaultValue Default value.
284 * This value is used if the option is set, but no value is provided.
285 * If the option is never set, the value set with defaultValue() is
286 * used. Can only be used for options that accept a single value.
288 * \p defaultValue is copied when the option is created.
290 MyClass &defaultValueIfSet(const T &defaultValue)
291 { defaultValueIfSet_ = &defaultValue; return me(); }
293 * Stores value(s) in memory pointed by \p store.
295 * \param[in] store Storage for option value(s).
297 * The caller is responsible for allocating enough memory such that
298 * the any allowed number of values fits into the array pointed by
299 * \p store. If there is no maximum allowed number or if the maximum
300 * is inconveniently large, storeVector() should be used.
302 * For information on when values are available in the storage, see
305 * The pointer provided should remain valid as long as the associated
306 * Options object exists.
308 MyClass &store(T *store)
309 { store_ = store; return me(); }
311 * Stores number of values in the value pointed by \p countptr.
313 * \param[in] countptr Storage for the number of values.
315 * For information on when values are available in the storage, see
318 * The pointers provided should remain valid as long as the associated
319 * Options object exists.
321 MyClass &storeCount(int *countptr)
322 { countptr_ = countptr; return me(); }
324 * Stores option values in the provided vector.
326 * \param[in] store Vector to store option values in.
328 * Values are added to the vector after each successful set of values
329 * is parsed. Note that for some options, the value may be changed
330 * later, and is only guaranteed to be correct after Options::finish()
333 * The pointer provided should remain valid as long as the associated
334 * Options object exists.
336 MyClass &storeVector(std::vector<T> *store)
337 { storeVector_ = store; return me(); }
339 * Stores whether the option was explicitly set.
341 * \param[in] store Variable to store the flag in.
343 * The value is set to `false` on creation of the option, and to `true`
344 * as soon as a value is assigned to the option. A default value does
345 * not set the flag to `true`, but assignment that uses
346 * defaultValueIfSet() does.
348 * The pointer provided should remain valid as long as the associated
349 * Options object exists.
351 MyClass &storeIsSet(bool *store)
352 { setStoreIsSet(store); return me(); }
356 //! Alias for the template class for use in base classes.
357 typedef OptionTemplate<T, U> MyBase;
359 //! Initializes the name and default values for an option.
360 explicit OptionTemplate(const char *name)
361 : AbstractOption(name),
362 defaultValue_(NULL), defaultValueIfSet_(NULL), store_(NULL),
363 countptr_(NULL), storeVector_(NULL)
367 * Returns a pointer to user-specified default value, or NULL if there
370 const T *defaultValue() const { return defaultValue_; }
372 * Returns a pointer to user-specified default value, or NULL if there
375 const T *defaultValueIfSet() const { return defaultValueIfSet_; }
376 //! Returns \p *this casted into MyClass to reduce typing.
377 MyClass &me() { return static_cast<MyClass &>(*this); }
381 const T *defaultValue_;
382 const T *defaultValueIfSet_;
385 std::vector<T> *storeVector_;
388 * Needed to initialize storage from this class without otherwise
389 * unnecessary accessors.
391 friend class OptionStorageTemplate<T>;
395 * Gives information and allows modifications to an option after creation.
397 * When an option is added with Options::addOption(), an object of a subclass
398 * of OptionInfo is returned. This object can be later used to access
399 * information about the option. Non-const methods also allow later changing
400 * (some of) the option settings provided at initialization time.
401 * The properties accessible/modifiable through this interface are implemented
402 * based on need, and may not be implemented for all cases.
405 * This class is also used by OptionsVisitor and OptionsModifyingVisitor as
406 * the interface that allows querying/modifying each visited option.
409 * This class isolates the details of the internal option implementation from
410 * callers. Although this class is a simple reference to the underlying
411 * implementation, it is implemented as non-copyable to allow const/non-const
412 * status of a reference to this class to indicate whether modifications are
413 * allowed. Otherwise, separate classes would be needed for access and
414 * modification, complicating the implementation. In the implementation,
415 * there is always a single OptionInfo instance referring to one option.
416 * The underlying implementation object always owns this instance, and only
417 * references are passed to callers.
419 * \see Options::addOption()
421 * \see OptionsVisitor
422 * \see OptionsModifyingVisitor
426 * \ingroup module_options
431 virtual ~OptionInfo();
434 * Test whether the option is of a particular type.
436 * \tparam InfoType Option type to test for. Should be a class derived
439 template <class InfoType>
442 return toType<InfoType>() != NULL;
445 * Convert the info object to a particular type if the type is correct.
447 * \tparam InfoType Option type to convert to. Should be a class
448 * derived from OptionInfo.
449 * \retval this converted to a pointer to \p InfoType, or NULL if the
450 * conversion is not possible.
452 template <class InfoType>
455 return dynamic_cast<InfoType *>(this);
457 //! \copydoc toType()
458 template <class InfoType>
459 const InfoType *toType() const
461 return dynamic_cast<const InfoType *>(this);
464 //! Returns true if the option has been set.
466 //! Returns true if the option is a hidden option.
467 bool isHidden() const;
468 //! Returns true if the option is required.
469 bool isRequired() const;
470 //! Returns the minimum number of values that this option accepts.
471 int minValueCount() const;
472 //! Returns the maximum number of values that this option accepts.
473 int maxValueCount() const;
474 //! Returns the name of the option.
475 const std::string &name() const;
476 //! Returns the type of the option as a string.
477 std::string type() const;
478 //! Returns the description of the option.
479 std::string formatDescription() const;
481 * Returns the default value if set for the option as a string.
483 * \see OptionTemplate::defaultValueIfSet()
485 std::string formatDefaultValueIfSet() const;
487 //! Returns the number of values given for the option.
488 int valueCount() const;
489 //! Returns the i'th value of the option as a string.
490 std::string formatValue(int i) const;
495 * Wraps a given option object.
499 explicit OptionInfo(AbstractOptionStorage *option);
501 //! Returns the wrapped option storage object.
502 AbstractOptionStorage &option() { return option_; }
503 //! Returns the wrapped option storage object.
504 const AbstractOptionStorage &option() const { return option_; }
508 //! The wrapped option.
509 AbstractOptionStorage &option_;
511 GMX_DISALLOW_COPY_AND_ASSIGN(OptionInfo);