Gromacs  2024.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
List of all members | Public Member Functions | Protected Member Functions
gmx::AbstractOptionStorage Class Referenceabstract

#include <gromacs/options/abstractoptionstorage.h>

+ Inheritance diagram for gmx::AbstractOptionStorage:

Description

Abstract base class for converting, validating, and storing option values.

This class should normally not be subclassed directly, but the OptionStorageTemplate should be used instead. The templated class provides basic functionality for most of the pure virtual methods, and also integrates well with option setting objects derived from OptionTemplate.

This class really consists of two parts: the public interface that is used by the internal implementation of the options module, and the interface that derived classes use to provide type-dependent functionality. The latter consists of a few pure virtual methods, of which a few simple query methods are also part of the module-internal interface, others are protected and called by the non-virtual methods when needed. The reason why these two roles are in one class is twofold:

  1. Both the derived classes and the internal module implementation may need access to the same information like the allowed number of values and the name of the option.
  2. Having only one class is consistent with the structure used for options settings objects: there is very direct correspondence between AbstractOption and AbstractOptionStorage and between OptionTemplate and OptionStorageTemplate.

Public Member Functions

bool isSet () const
 Returns true if the option has been set.
 
bool isBoolean () const
 Returns true if the option is a boolean option. More...
 
bool isHidden () const
 Returns true if the option is a hidden option.
 
bool isRequired () const
 Returns true if the option is required.
 
bool isVector () const
 Returns true if the option is vector-valued.
 
const std::string & name () const
 Returns the name of the option.
 
const std::string & description () const
 Returns the description of the option set by the calling code.
 
bool defaultValueIfSetExists () const
 Returns true if defaultValueIfSet() value is specified.
 
int minValueCount () const
 Returns the minimum number of values required in one set.
 
int maxValueCount () const
 Returns the maximum allowed number of values in one set (-1 = no limit).
 
virtual OptionInfooptionInfo ()=0
 Returns an option info object corresponding to this option.
 
virtual std::string typeString () const =0
 Returns a short string describing the type of the option.
 
virtual std::string formatExtraDescription () const
 Formats additional description for the option. More...
 
virtual int valueCount () const =0
 Returns the number of option values added so far.
 
virtual std::vector< AnydefaultValues () const =0
 Returns the default value(s) of the option. More...
 
virtual std::vector< std::string > defaultValuesAsStrings () const =0
 Returns the default value(s) of the option as strings. More...
 
virtual std::vector< AnynormalizeValues (const std::vector< Any > &values) const =0
 Converts given values to native representation for this option. More...
 
void startSource ()
 Starts adding values from a new source for the option. More...
 
void startSet ()
 Starts adding a new set of values for the option. More...
 
void appendValue (const Any &value)
 Adds a new value for the option. More...
 
void finishSet ()
 Performs validation and/or actions once a set of values has been added. More...
 
void finish ()
 Performs validation and/or actions once all values have been added. More...
 

Protected Member Functions

 AbstractOptionStorage (const AbstractOption &settings, OptionFlags staticFlags)
 Initializes the storage object from the settings object. More...
 
void markAsSet ()
 Marks the option as set.
 
bool hasFlag (OptionFlag flag) const
 Returns true if the given flag is set.
 
void setFlag (OptionFlag flag)
 Sets the given flag.
 
void clearFlag (OptionFlag flag)
 Clears the given flag.
 
void setMinValueCount (int count)
 Sets a new minimum number of values required in one set. More...
 
void setMaxValueCount (int count)
 Sets a new maximum number of values required in one set. More...
 
virtual void clearSet ()=0
 Removes all values from temporary storage for a set. More...
 
virtual void convertValue (const Any &value)=0
 Adds a new value. More...
 
virtual void processSet ()=0
 Performs validation and/or actions once a set of values has been added. More...
 
virtual void processAll ()=0
 Performs validation and/or actions once all values have been added. More...
 

Constructor & Destructor Documentation

gmx::AbstractOptionStorage::AbstractOptionStorage ( const AbstractOption settings,
OptionFlags  staticFlags 
)
protected

Initializes the storage object from the settings object.

Parameters
[in]settingsOption settings.
[in]staticFlagsOption flags that are always set and specify generic behavior of the option.
Exceptions
APIErrorif invalid settings have been provided.

Member Function Documentation

void gmx::AbstractOptionStorage::appendValue ( const Any value)

Adds a new value for the option.

Parameters
[in]valueValue to convert.
Exceptions
InvalidInputErrorif value cannot be converted, or if there are too many values.

This method should only be called between startSet() and finishSet().

virtual void gmx::AbstractOptionStorage::clearSet ( )
protectedpure virtual

Removes all values from temporary storage for a set.

This function is always called before starting to add values to a set, allowing the storage to clear its internal buffers.

Should not throw.

Implemented in gmx::OptionStorageTemplate< T >, gmx::OptionStorageTemplate< int64_t >, gmx::OptionStorageTemplate< double >, gmx::OptionStorageTemplate< std::string >, gmx::OptionStorageTemplate< float >, gmx::OptionStorageTemplate< int >, gmx::OptionStorageTemplate< Selection >, and gmx::OptionStorageTemplate< bool >.

virtual void gmx::AbstractOptionStorage::convertValue ( const Any value)
protectedpure virtual

Adds a new value.

Parameters
[in]valueValue to convert.
Exceptions
InvalidInputErrorif value is not valid for this option or if there have been too many values in the set.

This method may be called multiple times if the underlying option is defined to accept multiple values.

See Also
OptionStorageTemplate::convertValue()

Implemented in gmx::OptionStorageTemplate< T >, gmx::OptionStorageTemplate< int64_t >, gmx::OptionStorageTemplate< double >, gmx::OptionStorageTemplate< std::string >, gmx::OptionStorageTemplate< float >, gmx::OptionStorageTemplate< int >, gmx::OptionStorageTemplate< Selection >, gmx::OptionStorageTemplate< bool >, and anonymous_namespace{abstractoptionstorage.cpp}::MockOptionStorage.

virtual std::vector<Any> gmx::AbstractOptionStorage::defaultValues ( ) const
pure virtual

Returns the default value(s) of the option.

The returned values should all be of the same type, but returning each as a separate any is currently simpler.

Currently, this can only be called before option values have been assigned.

Implemented in gmx::OptionStorageTemplate< T >, gmx::OptionStorageTemplate< int64_t >, gmx::OptionStorageTemplate< double >, gmx::OptionStorageTemplate< std::string >, gmx::OptionStorageTemplate< float >, gmx::OptionStorageTemplate< int >, gmx::OptionStorageTemplate< Selection >, gmx::OptionStorageTemplate< bool >, and gmx::SelectionFileOptionStorage.

virtual std::vector<std::string> gmx::AbstractOptionStorage::defaultValuesAsStrings ( ) const
pure virtual

Returns the default value(s) of the option as strings.

If there is no default value, but defaultValueIfSet() is set, that is returned instead.

Currently, this can only be called before option values have been assigned.

Implemented in gmx::OptionStorageTemplate< T >, gmx::OptionStorageTemplate< int64_t >, gmx::OptionStorageTemplate< double >, gmx::OptionStorageTemplate< std::string >, gmx::OptionStorageTemplate< float >, gmx::OptionStorageTemplate< int >, gmx::OptionStorageTemplate< Selection >, gmx::OptionStorageTemplate< bool >, and gmx::SelectionFileOptionStorage.

void gmx::AbstractOptionStorage::finish ( )

Performs validation and/or actions once all values have been added.

Exceptions
InvalidInputErrorif the option is required but not set, or if all valid values together are invalid as a set.

This method should be called after all values have been provided with appendValue().

void gmx::AbstractOptionStorage::finishSet ( )

Performs validation and/or actions once a set of values has been added.

Exceptions
InvalidInputErrorif too few values have been provided, or if the valid values since previous startSet() are invalid as a set.

If the parameter is specified multiple times, finishSet() should be called after the values for each instance.

virtual std::string gmx::AbstractOptionStorage::formatExtraDescription ( ) const
inlinevirtual

Formats additional description for the option.

If this method returns a non-empty string, it is appended to the plain description when printing help texts. The default implementation returns an empty string.

Reimplemented in gmx::EnumOptionStorage, gmx::StringOptionStorage, and gmx::FileNameOptionStorage.

bool gmx::AbstractOptionStorage::isBoolean ( ) const

Returns true if the option is a boolean option.

This is used to optionally support an alternative syntax where an option provided with no value sets the value to true and an option prefixed with "no" clears the value.

virtual std::vector<Any> gmx::AbstractOptionStorage::normalizeValues ( const std::vector< Any > &  values) const
pure virtual

Converts given values to native representation for this option.

For example, strings are parsed to the type that is actually used to store the options.

The return value only depends on the option type, not on the current value of the option, and the current value in the option is not changed.

Implemented in gmx::OptionStorageTemplateSimple< T >, gmx::OptionStorageTemplateSimple< int64_t >, gmx::OptionStorageTemplateSimple< double >, gmx::OptionStorageTemplateSimple< std::string >, gmx::OptionStorageTemplateSimple< float >, gmx::OptionStorageTemplateSimple< int >, gmx::OptionStorageTemplateSimple< bool >, anonymous_namespace{abstractoptionstorage.cpp}::MockOptionStorage, gmx::SelectionOptionStorage, and gmx::SelectionFileOptionStorage.

virtual void gmx::AbstractOptionStorage::processAll ( )
protectedpure virtual

Performs validation and/or actions once all values have been added.

Exceptions
InvalidInputErrorif all provided values are not valid as a set.

This method is always called once.

If the method throws, implementation should take care to leave the option in a consistent, meaningful state. However, currently none of the implementations actually throw in any situation where the option may be left in an inconsistent state.

Implemented in gmx::OptionStorageTemplate< T >, gmx::OptionStorageTemplate< int64_t >, gmx::OptionStorageTemplate< double >, gmx::OptionStorageTemplate< std::string >, gmx::OptionStorageTemplate< float >, gmx::OptionStorageTemplate< int >, gmx::OptionStorageTemplate< Selection >, and gmx::OptionStorageTemplate< bool >.

virtual void gmx::AbstractOptionStorage::processSet ( )
protectedpure virtual

Performs validation and/or actions once a set of values has been added.

Exceptions
InvalidInputErrorif the values in the set are not valid as a whole.

This method may be called multiple times if the underlying option can be specified multiple times. This method is not currently called if one of the convertValue() calls throwed.

Todo:
Improve the call semantics.
See Also
OptionStorageTemplate::processSetValues()

Implemented in gmx::OptionStorageTemplate< T >, gmx::OptionStorageTemplate< int64_t >, gmx::OptionStorageTemplate< double >, gmx::OptionStorageTemplate< std::string >, gmx::OptionStorageTemplate< float >, gmx::OptionStorageTemplate< int >, gmx::OptionStorageTemplate< Selection >, and gmx::OptionStorageTemplate< bool >.

void gmx::AbstractOptionStorage::setMaxValueCount ( int  count)
protected

Sets a new maximum number of values required in one set.

Parameters
[in]countNew maximum number of values (must be > 0, or -1 for no limit).
Exceptions
InvalidInputErrorif already provided values violate the limit.

If values have already been provided, it is checked that there are not too many.

Cannot be called for options with efOption_MultipleTimes set, because it is impossible to check the requirement after the values have been set. If attempted, will assert.

void gmx::AbstractOptionStorage::setMinValueCount ( int  count)
protected

Sets a new minimum number of values required in one set.

Parameters
[in]countNew minimum number of values (must be > 0).
Exceptions
InvalidInputErrorif already provided values violate the limit.

If values have already been provided, it is checked that there are enough.

Cannot be called for options with efOption_MultipleTimes set, because it is impossible to check the requirement after the values have been set. If attempted, will assert.

void gmx::AbstractOptionStorage::startSet ( )

Starts adding a new set of values for the option.

Exceptions
InvalidInputErrorif option is specified multiple times, but is not specified to accept it.

If the parameter is specified multiple times, startSet() should be called before the values for each instance.

Strong exception safety guarantee.

void gmx::AbstractOptionStorage::startSource ( )

Starts adding values from a new source for the option.

This marks the vurrent value of the option as a default value, causing next call to startSet() to clear it. This allows values from the new source to overwrite old values.

This method does not throw.


The documentation for this class was generated from the following files: