src/gromacs/options/abstractoption.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 /*! \file
  32  * \brief
  33  * Defines gmx::AbstractOption and a related template.
  34  *
  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.
  38  *
  39  * These classes also take care of creating and setting up the actual option
  40  * objects.
  41  *
  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
  44  * its subclasses.
  45  *
  46  * \author Teemu Murtola <teemu.murtola@cbr.su.se>
  47  * \inlibraryapi
  48  * \ingroup module_options
  49  */
  50 #ifndef GMX_OPTIONS_ABSTRACTOPTION_H
  51 #define GMX_OPTIONS_ABSTRACTOPTION_H
  52
  53 #include <string>
  54 #include <vector>
  55
  56 #include "../utility/uniqueptr.h"
  57
  58 #include "optionflags.h"
  59
  60 namespace gmx
  61 {
  62
  63 class AbstractOptionStorage;
  64 template <typename T> class OptionStorageTemplate;
  65 class Options;
  66
  67 //! Smart pointer for managing an AbstractOptionStorage object.
  68 typedef gmx_unique_ptr<AbstractOptionStorage>::type
  69         AbstractOptionStoragePointer;
  70
  71 /*! \brief
  72  * Abstract base class for specifying option properties.
  73  *
  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.
  80  *
  81  * Subclasses should override createStorage() to create the correct type
  82  * of storage object.
  83  *
  84  * \ingroup module_options
  85  */
  86 class AbstractOption
  87 {
  88     public:
  89         // Virtual only for completeness, in normal use should not be needed.
  90         virtual ~AbstractOption() { }
  91
  92     protected:
  93         /*! \cond libapi */
  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)
  98         { }
  99
 100         /*! \brief
 101          * Creates a default storage object for the option.
 102          *
 103          * \returns The created storage object.
 104          * \throws  APIError if invalid option settings have been provided.
 105          *
 106          * This method is called by Options::addOption() when initializing an
 107          * option from the settings.
 108          *
 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.
 112          *
 113          * Should only be called by Options::addOption().
 114          */
 115         virtual AbstractOptionStoragePointer createStorage() const = 0;
 116
 117         /*! \brief
 118          * Creates the description string for the option.
 119          *
 120          * \returns Description string for the option.
 121          *
 122          * This function is virtual to allow derived classes to customize the
 123          * description programmatically, e.g., by adding the list of allowed
 124          * values.
 125          * The default implementation simply returns the user-provided
 126          * description.
 127          */
 128         virtual std::string createDescription() const
 129         { return descr_ ? descr_ : ""; }
 130
 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(efOption_Vector); }
 141         /*! \brief
 142          * Sets the option to be vector-valued.
 143          *
 144          * This method is provided for convenience to make management of value
 145          * counts easier.  In order to implement a vector-valued option, the
 146          * class derived from AbstractOption should expose a method that calls
 147          * this method, and the storage object derived from
 148          * AbstractOptionStorage should check isVector().
 149          * If only a single value is provided, the storage object should fill
 150          * the whole vector with that value.
 151          *
 152          * The length of the vector (the value of maxValueCount_) must be
 153          * fixed.  The default length is 3 elements.
 154          */
 155         void setVector()
 156         {
 157             setFlag(efOption_Vector);
 158             minValueCount_ = 1;
 159             if (maxValueCount_ == 1)
 160             {
 161                 maxValueCount_ = 3;
 162             }
 163         }
 164         //! Sets the required number of values for the option.
 165         void setValueCount(int count)
 166         {
 167             if (!hasFlag(efOption_Vector))
 168             {
 169                 minValueCount_ = count;
 170             }
 171             maxValueCount_ = count;
 172         }
 173
 174         //! Minimum number of values required for the option.
 175         int                     minValueCount_;
 176         //! Maximum number of values allowed for the option.
 177         int                     maxValueCount_;
 178         //! \endcond
 179
 180     private:
 181         //! Returns true if a flag has been set.
 182         bool hasFlag(OptionFlag flag) const { return flags_.test(flag); }
 183
 184         const char             *name_;
 185         //! Pointer to description of the option.
 186         const char             *descr_;
 187         OptionFlags             flags_;
 188
 189         /*! \brief
 190          * Needed to initialize an AbstractOptionStorage object from this class
 191          * without otherwise unnecessary accessors.
 192          */
 193         friend class AbstractOptionStorage;
 194         /*! \brief
 195          * Needed to be able to call createStorage().
 196          */
 197         friend class Options;
 198 };
 199
 200 /*! \brief
 201  * Templated base class for constructing concrete option settings classes.
 202  *
 203  * \tparam T Assignable type that stores a single option value.
 204  * \tparam U Type of the derived class.
 205  *
 206  * This template is used as a base class like this:
 207  * \code
 208 class ConcreteOption : public OptionTemplate<int, ConcreteOption>
 209 {
 210  * \endcode
 211  *
 212  * All public functions in this class return \c *this casted to a reference to
 213  * \p U.  They do not throw.
 214  *
 215  * For examples of how to use classes derived from this class, see the class
 216  * documentation for Options.
 217  *
 218  * \inlibraryapi
 219  * \ingroup module_options
 220  */
 221 template <typename T, class U>
 222 class OptionTemplate : public AbstractOption
 223 {
 224     public:
 225         //! Type that stores a single option value.
 226         typedef T ValueType;
 227         //! Alias for the derived class type.
 228         typedef U MyClass;
 229
 230         /*! \brief
 231          * Sets a description for the option.
 232          *
 233          * \param[in] descr Description to set.
 234          *
 235          * String in \p descr is copied when the option is created.
 236          */
 237         MyClass &description(const char *descr)
 238         { setDescription(descr); return me(); }
 239         //! Hides the option from normal help output.
 240         MyClass &hidden(bool bHidden = true)
 241         { setFlag(efOption_Hidden, bHidden); return me(); }
 242         //! Requires the option to be specified explicitly.
 243         MyClass &required(bool bRequired = true)
 244         { setFlag(efOption_Required, bRequired); return me(); }
 245         //! Allows the option to be specified multiple times.
 246         MyClass &allowMultiple(bool bMulti = true)
 247         { setFlag(efOption_MultipleTimes, bMulti); return me(); }
 248         //! Requires exactly \p count values for the option.
 249         MyClass &valueCount(int count) { setValueCount(count); return me(); }
 250         //! Allows any number of values for the option.
 251         MyClass &multiValue() { maxValueCount_ = -1; return me(); }
 252
 253         /*! \brief
 254          * Sets a default value for the option.
 255          *
 256          * \param[in] defaultValue Default value.
 257          *
 258          * If the option is never set, the default value is copied to the
 259          * assigned storage.  Note that if the option is not set and there
 260          * is no default value, the storage is not altered, which can also be
 261          * used to provide a default value.  The latter method has to be used
 262          * if the option can take multiple values.
 263          * If required() is specified, only affects the default value shown in
 264          * help output.
 265          *
 266          * \p defaultValue is copied when the option is created.
 267          */
 268         MyClass &defaultValue(const T &defaultValue)
 269         { defaultValue_ = &defaultValue; return me(); }
 270         /*! \brief
 271          * Sets a default value for the option when it is set.
 272          *
 273          * \param[in] defaultValue Default value.
 274          *
 275          * This value is used if the option is set, but no value is provided.
 276          * If the option is never set, the value set with defaultValue() is
 277          * used.  Can only be used for options that accept a single value.
 278          *
 279          * \p defaultValue is copied when the option is created.
 280          */
 281         MyClass &defaultValueIfSet(const T &defaultValue)
 282         { defaultValueIfSet_ = &defaultValue; return me(); }
 283         /*! \brief
 284          * Stores value(s) in memory pointed by \p store.
 285          *
 286          * \param[in] store  Storage for option value(s).
 287          *
 288          * The caller is responsible for allocating enough memory such that
 289          * the any allowed number of values fits into the array pointed by
 290          * \p store.  If there is no maximum allowed number or if the maximum
 291          * is inconveniently large, storeVector() should be used.
 292          *
 293          * For information on when values are available in the storage, see
 294          * storeVector().
 295          *
 296          * The pointer provided should remain valid as long as the associated
 297          * Options object exists.
 298          */
 299         MyClass &store(T *store)
 300         { store_ = store; return me(); }
 301         /*! \brief
 302          * Stores number of values in the value pointed by \p countptr.
 303          *
 304          * \param[in] countptr Storage for the number of values.
 305          *
 306          * For information on when values are available in the storage, see
 307          * storeVector().
 308          *
 309          * The pointers provided should remain valid as long as the associated
 310          * Options object exists.
 311          */
 312         MyClass &storeCount(int *countptr)
 313         { countptr_ = countptr; return me(); }
 314         /*! \brief
 315          * Stores option values in the provided vector.
 316          *
 317          * \param[in] store  Vector to store option values in.
 318          *
 319          * Values are added to the vector after each successful set of values
 320          * is parsed.  Note that for some options, the value may be changed
 321          * later, and is only guaranteed to be correct after Options::finish()
 322          * has been called.
 323          *
 324          * The pointer provided should remain valid as long as the associated
 325          * Options object exists.
 326          */
 327         MyClass &storeVector(std::vector<T> *store)
 328         { storeVector_ = store; return me(); }
 329
 330     protected:
 331         /*! \cond libapi */
 332         //! Alias for the template class for use in base classes.
 333         typedef OptionTemplate<T, U> MyBase;
 334
 335         //! Initializes the name and default values for an option.
 336         explicit OptionTemplate(const char *name)
 337             : AbstractOption(name),
 338               defaultValue_(NULL), defaultValueIfSet_(NULL), store_(NULL),
 339               countptr_(NULL), storeVector_(NULL)
 340         { }
 341
 342         /*! \brief
 343          * Returns a pointer to user-specified default value, or NULL if there
 344          * is none.
 345          */
 346         const T *defaultValue() const { return defaultValue_; }
 347         /*! \brief
 348          * Returns a pointer to user-specified default value, or NULL if there
 349          * is none.
 350          */
 351         const T *defaultValueIfSet() const { return defaultValueIfSet_; }
 352         //! Returns \p *this casted into MyClass to reduce typing.
 353         MyClass &me() { return static_cast<MyClass &>(*this); }
 354         //! \endcond
 355
 356     private:
 357         const T                *defaultValue_;
 358         const T                *defaultValueIfSet_;
 359         T                      *store_;
 360         int                    *countptr_;
 361         std::vector<T>         *storeVector_;
 362
 363         /*! \brief
 364          * Needed to initialize storage from this class without otherwise
 365          * unnecessary accessors.
 366          */
 367         friend class OptionStorageTemplate<T>;
 368 };
 369
 370 } // namespace gmx
 371
 372 #endif