Gromacs  2024.3
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Classes | Typedefs | Enumerations | Functions | Variables | Directories | Files
Extensible Handling of Options (options)
+ Collaboration diagram for Extensible Handling of Options (options):

Description

Provides functionality for handling options.

Basic Use

Code that provides options does so using methods in gmx::IOptionsContainer and classes defined in basicoptions.h. Only these are needed if a class wants to provide a set of standard options (other modules can provide additional option types, such as gmx::SelectionOption). For each option, the caller provides an output variable that will receive the final value of the option once user input has been parsed. When adding options, it is possible to also provide descriptions for the options for use in generated help text.

Generic code that handles the user input does so by creating a gmx::Options instance and passing it (as gmx::IOptionsContainer) to the classes that add the actual options. It can then use a parser to set values to the options. Final values for the options can be inspected in the code that added the individual options, from the provided output variables.

The sequence charts below provides an overview of how the options work from usage perspective. They include two fictional modules, A and B, that provide options, and a main routine that manages these. The first chart shows a typical initialization sequence, where the main routine creates an options object, and calls an initOptions() method in each module that can provide options (the modules may also request their submodules to add their own options). Each module uses gmx::IOptionsContainer::addOption() to add the options they require, and specify output variables into which the options values are stored.

msc_inline_mscgraph_12

After all options have been specified, they can be parsed. A parser splits the input into option-value pairs (one option may have multiple values), and passes these into the gmx::Options object, which is responsible for converting them into the appropriate types and storing the values into the variables provided in the calls to gmx::IOptionsContainer::addOption().

msc_inline_mscgraph_13

After all options have been parsed (possibly using multiple different parsers), gmx::Options::finish() is called. This performs final validation of the options and may further adjust the values stored in the output variables (see documentation on individual option types on when this may happen).

msc_inline_mscgraph_14

Module Command Line Program Management (commandline) implements classes that assign option values from command line and produce help for programs that use the command line parser.

Advanced Use (in library API)

It is possible to extend the module with new option types and/or parsers for option values.

To implement new option types, it is necessary to subclass the templates OptionTemplate and OptionStorageTemplate with the type of the values that the option should provide as the template argument. After this is done, it is possible to add options of this new type using IOptionsContainer::addOption().

To implement new parsers, one can use OptionsAssigner, which provides an interface to set values in an Options object.

There is also an interface to iterate over all options in an Options object. One should implement the OptionsVisitor interface, and then use OptionsIterator to apply this visitor to the Options object.

Author
Teemu Murtola teemu.nosp@m..mur.nosp@m.tola@.nosp@m.gmai.nosp@m.l.com

Classes

class  gmx::AbstractOptionStorage
 Abstract base class for converting, validating, and storing option values. More...
 
class  gmx::AbstractOptionSection
 Base class for specifying option section properties. More...
 
class  gmx::AbstractOptionSectionHandle
 Base class for handles to option sections. More...
 
class  gmx::BooleanOptionStorage
 Converts, validates, and stores boolean values. More...
 
class  gmx::IntegerOptionStorage
 Converts, validates, and stores integer values. More...
 
class  gmx::Int64OptionStorage
 Converts, validates, and stores integer values. More...
 
class  gmx::DoubleOptionStorage
 Converts, validates, and stores floating-point (double) values. More...
 
class  gmx::FloatOptionStorage
 Converts, validates, and stores floating-point (float) values. More...
 
class  gmx::StringOptionStorage
 Converts, validates, and stores string values. More...
 
class  gmx::EnumOptionStorage
 Converts, validates, and stores enum values. More...
 
class  gmx::OptionsBehaviorCollection
 Container for IOptionsBehavior objects. More...
 
class  gmx::anonymous_namespace{filenameoption.cpp}::FileTypeHandler
 Handles a single file type known to FileNameOptionStorage. More...
 
class  gmx::FileNameOptionManager::Impl
 Private implemention class for FileNameOptionManager. More...
 
class  gmx::IOptionSectionStorage
 Provides behavior specific to a certain option section type. More...
 
class  gmx::OptionManagerContainer
 Container to keep managers added with Options::addManager() and pass them to options. More...
 
class  gmx::internal::OptionSectionImpl
 Internal implementation class for storing an option section. More...
 
class  gmx::internal::OptionSectionImpl::Group
 Describes a group of options (see Options::addGroup()). More...
 
class  gmx::internal::OptionsImpl
 Private implementation class for Options. More...
 
class  gmx::OptionsAssigner
 Decorator class for assigning values to Options. More...
 
class  gmx::OptionSection
 Declares a simple option section. More...
 
class  gmx::OptionSectionHandle
 Allows adding options to an OptionSection. More...
 
class  gmx::OptionStorageTemplate< T >
 Templated base class for constructing option value storage classes. More...
 
class  gmx::OptionStorageTemplateSimple< T >
 Simplified option storage template for options that have one-to-one value conversion. More...
 
class  gmx::OptionsVisitor
 Pure interface for visiting options in a Options object. More...
 
class  gmx::OptionsTypeVisitor< InfoType >
 Abstract base class for visiting options of a particular type. More...
 
class  gmx::OptionsIterator
 Decorator class for visiting options in a Options object. More...
 
class  gmx::OptionsModifyingVisitor
 Pure interface for visiting options in a Options object, allowing modifications. More...
 
class  gmx::OptionsModifyingTypeVisitor< InfoType >
 Abstract base class for visiting options of a particular type, allowing modifications. More...
 
class  gmx::OptionsModifyingIterator
 Decorator class for visiting options in a Options object, allowing changes. More...
 
class  gmx::RepeatingOptionSection< T >
 Declares an option section that creates a structure for each instance. More...
 
class  gmx::RepeatingOptionSectionStorage< T >
 Implements handling of the structures that stores per-section values. More...
 
class  gmx::RepeatingOptionSectionHandle< T >
 Allows adding options to an RepeatingOptionSection. More...
 
class  anonymous_namespace{abstractoptionstorage.cpp}::MockOptionStorage
 Mock implementation of an option storage class for unit testing. More...
 
class  anonymous_namespace{abstractoptionstorage.cpp}::MockOption
 Specifies an option that has a mock storage object for unit testing. More...
 
class  gmx::anonymous_namespace{timeunitmanager.cpp}::TimeOptionScaler< FloatingPointOptionInfo >
 Option visitor that scales time options. More...
 
class  gmx::OptionValueConverterSimple< OutType >
 Helper for converting from Any to a given type. More...
 
class  gmx::OptionValueStoreNull< T >
 Value storage that does not store anywhere. More...
 
class  gmx::AbstractOption
 Abstract base class for specifying option properties. More...
 
class  gmx::OptionTemplate< T, U >
 Templated base class for constructing concrete option settings classes. More...
 
class  gmx::OptionInfo
 Gives information and allows modifications to an option after creation. More...
 
class  gmx::BooleanOption
 Specifies an option that provides boolean values. More...
 
class  gmx::IntegerOption
 Specifies an option that provides integer values. More...
 
class  gmx::Int64Option
 Specifies an option that provides 64-bit integer values. More...
 
class  gmx::DoubleOption
 Specifies an option that provides floating-point (double) values. More...
 
class  gmx::FloatOption
 Specifies an option that provides floating-point (float) values. More...
 
class  gmx::StringOption
 Specifies an option that provides string values. More...
 
class  gmx::internal::EnumIndexStore< EnumType >
 Type-specific implementation for IOptionValueStore for an enum option. More...
 
class  gmx::EnumOption< EnumType >
 Specifies an option that accepts an EnumerationArray of string values and writes the selected index into an enum variable. More...
 
class  gmx::LegacyEnumOption< EnumType >
 Specifies an option that accepts enumerated string values and writes the selected index into an enum variable. More...
 
class  gmx::BooleanOptionInfo
 Wrapper class for accessing boolean option information. More...
 
class  gmx::IntegerOptionInfo
 Wrapper class for accessing integer option information. More...
 
class  gmx::Int64OptionInfo
 Wrapper class for accessing 64-bit integer option information. More...
 
class  gmx::DoubleOptionInfo
 Wrapper class for accessing floating-point option information. More...
 
class  gmx::FloatOptionInfo
 Wrapper class for accessing floating-point option information. More...
 
class  gmx::StringOptionInfo
 Wrapper class for accessing string option information. More...
 
class  gmx::EnumOptionInfo
 Wrapper class for accessing enum option information. More...
 
class  gmx::FileNameOption
 Specifies an option that provides file names. More...
 
class  gmx::FileNameOptionInfo
 Wrapper class for accessing file name option information. More...
 
class  gmx::IOptionsBehavior
 Interface to provide extension points for options parsing. More...
 
class  gmx::IOptionsContainer
 Interface for adding input options. More...
 
class  gmx::IOptionsContainerWithSections
 Interface for adding input options with sections. More...
 
class  gmx::IOptionValueStore< T >
 Represents the final storage location of option values. More...
 
class  gmx::IOptionManager
 Base class for option managers. More...
 
class  gmx::Options
 Collection of options. More...
 
class  gmx::TimeUnitManager
 Provides common functionality for time unit conversions. More...
 
class  gmx::TimeUnitBehavior
 Options behavior to add a time unit option. More...
 

Typedefs

typedef FloatOption gmx::RealOption
 Typedef for either DoubleOption or FloatOption, depending on precision. More...
 
typedef FloatOptionInfo gmx::RealOptionInfo
 Typedef for either DoubleOptionInfo or FloatOptionInfo, depending on precision. More...
 

Enumerations

enum  gmx::OptionFileType : int {
  Topology, RunInput, Trajectory, Energy,
  PDB, AtomIndex, Plot, GenericData,
  Csv, QMInput, Count
}
 Purpose of file(s) provided through an option.
 

Functions

template<typename ValueType >
void anonymous_namespace{basicoptions.cpp}::expandVector (size_t length, std::vector< ValueType > *values)
 Expands a single value to a vector by copying the value. More...
 
std::vector< std::string >
::const_iterator 
anonymous_namespace{basicoptions.cpp}::findEnumValue (const std::vector< std::string > &allowedValues, const std::string &value)
 Finds an enumerated value from the list of allowed values. More...
 
void gmx::assignOptionsFromKeyValueTree (Options *options, const KeyValueTreeObject &tree, IKeyValueTreeErrorHandler *errorHandler)
 Assigns option values from a given KeyValueTreeObject. More...
 
void gmx::checkForUnknownOptionsInKeyValueTree (const KeyValueTreeObject &tree, const Options &options)
 Checks that a given KeyValueTreeObject can be assigned to given Options. More...
 
KeyValueTreeObject gmx::adjustKeyValueTreeFromOptions (const KeyValueTreeObject &tree, const Options &options)
 Adjusts a KeyValueTreeObject to the structure of given Options. More...
 
AbstractOptionStorage * gmx::internal::createEnumOptionStorage (const AbstractOption &option, const char *const *enumValues, int count, int defaultValue, int defaultValueIfSet, std::unique_ptr< IOptionValueStore< int >> store)
 Helper to create EnumOptionStorage instances. More...
 
 gmx::anonymous_namespace{filenameoption.cpp}::FileTypeHandler::FileTypeHandler (int fileType)
 Returns a handler for a single file type. More...
 
int gmx::anonymous_namespace{filenameoption.cpp}::FileTypeHandler::extensionCount () const
 Returns the number of acceptable extensions for this file type.
 
const char * gmx::anonymous_namespace{filenameoption.cpp}::FileTypeHandler::extension (int i) const
 Returns the extension with the given index.
 
bool gmx::anonymous_namespace{filenameoption.cpp}::FileTypeHandler::isValidType (int fileType) const
 Returns whether fileType (from filetypes.h) is accepted for this type.
 

Variables

constexpr EnumerationArray
< OptionFileType, int > 
gmx::anonymous_namespace{filenameoption.cpp}::sc_fileTypeMapping
 Mappings from OptionFileType to file types in filetypes.h. More...
 

Directories

directory options
 Extensible Handling of Options (options)
 
directory tests
 Unit tests for Extensible Handling of Options (options).
 

Files

file  abstractoption.cpp
 Implements classes in abstractoption.h and abstractoptionstorage.h.
 
file  abstractoptionstorage.h
 Declares gmx::AbstractOptionStorage.
 
file  abstractsection.cpp
 Implements classes from abstractsection.h.
 
file  abstractsection.h
 Declares base classes for declaring option sections.
 
file  basicoptions.cpp
 Implements classes in basicoptions.h and basicoptionstorage.h.
 
file  basicoptionstorage.h
 Declares storage classes for basic option types.
 
file  behaviorcollection.cpp
 Implements gmx::OptionsBehaviorCollection.
 
file  behaviorcollection.h
 Declares gmx::OptionsBehaviorCollection.
 
file  filenameoption.cpp
 Implements classes in filenameoption.h and filenameoptionstorage.h.
 
file  filenameoptionmanager.cpp
 Implements gmx::FileNameOptionManager.
 
file  filenameoptionstorage.h
 Declares gmx::FileNameOptionStorage.
 
file  isectionstorage.h
 Declares gmx::IOptionSectionStorage.
 
file  optionmanagercontainer.h
 Declares gmx::OptionManagerContainer.
 
file  options.cpp
 Implements gmx::Options.
 
file  options_impl.h
 Declares private implementation class for gmx::Options.
 
file  optionsassigner.cpp
 Implements gmx::OptionsAssigner.
 
file  optionsassigner.h
 Declares gmx::OptionsAssigner.
 
file  optionsection.h
 Declares gmx::OptionSection and gmx::OptionSectionInfo.
 
file  optionstoragetemplate.h
 Defines gmx::OptionStorageTemplate template.
 
file  optionsvisitor.cpp
 Implements classes in optionsvisitor.h.
 
file  optionsvisitor.h
 Declares gmx::OptionsVisitor interface and supporting classes.
 
file  repeatingsection.h
 Declares gmx::RepeatingOptionSection and related classes.
 
file  abstractoptionstorage.cpp
 Tests proper handling of option storage.
 
file  filenameoption.cpp
 Tests basic file name option implementation.
 
file  filenameoptionmanager.cpp
 Tests file name option implementation dependent on gmx::FileNameOptionManager.
 
file  option.cpp
 Tests creation of basic option types.
 
file  optionsassigner.cpp
 Tests option assignment.
 
file  repeatingsection.cpp
 Tests functionality related to repeating sections.
 
file  timeunitmanager.cpp
 Tests handling of time units with gmx::TimeUnitManager and gmx::TimeUnitBehavior.
 
file  treesupport.cpp
 Tests option support for operations on KeyValueTree.
 
file  timeunitmanager.cpp
 Implements gmx::TimeUnitManager.
 
file  treesupport.cpp
 Implements functions from treesupport.h.
 
file  treesupport.h
 Declares functions for using keyvaluetree.h with Options.
 
file  valueconverter.h
 Provides gmx::OptionValueConverterSimple.
 
file  valuestore.h
 Declares implementations for IOptionValueStore.
 
file  abstractoption.h
 Defines gmx::AbstractOption, gmx::OptionTemplate and gmx::OptionInfo.
 
file  basicoptions.h
 Declares option objects for basic option types.
 
file  filenameoption.h
 Declares gmx::FileNameOption and gmx::FileNameOptionInfo.
 
file  filenameoptionmanager.h
 Declares gmx::FileNameOptionManager.
 
file  ioptionsbehavior.h
 Declares gmx::IOptionsBehavior.
 
file  ioptionscontainer.h
 Declares gmx::IOptionsContainer.
 
file  ioptionscontainerwithsections.h
 Declares gmx::IOptionsContainerWithSections.
 
file  ivaluestore.h
 Declares gmx::IOptionValueStore.
 
file  optionfiletype.h
 Defines an enumeration type for specifying file types for options.
 
file  optionflags.h
 Defines flags used in option implementation.
 
file  options.h
 Declares gmx::Options.
 
file  timeunitmanager.h
 Declares gmx::TimeUnitManager.
 

Typedef Documentation

Typedef for either DoubleOption or FloatOption, depending on precision.

Generally, new would be better using DoubleOption, but this is provided for cases where the output value needs to be of type real for some reason.

Typedef for either DoubleOptionInfo or FloatOptionInfo, depending on precision.

Generally, new would be better using DoubleOption, but this is provided for cases where the output value needs to be of type real for some reason.

Function Documentation

KeyValueTreeObject gmx::adjustKeyValueTreeFromOptions ( const KeyValueTreeObject &  tree,
const Options &  options 
)

Adjusts a KeyValueTreeObject to the structure of given Options.

Assumes that all values in the input KeyValueTreeObject are valid values for the options. The output has all the values in the input, but in the order they are in the options. Values are also converted to the native type for the underlying option (e.g., strings are parsed to integers if the option accepts those). For any option that does not have a corresponding value in the input, the output has it with a default value (if one exists for the option).

Any values in tree that do not have matching options are not present in the output. If this is not desirable, call checkForUnknownOptionsInKeyValueTree() before calling this function to ensure that no such values are present.

Does not currently work for option sections in an array.

void gmx::assignOptionsFromKeyValueTree ( Options *  options,
const KeyValueTreeObject &  tree,
IKeyValueTreeErrorHandler *  errorHandler 
)

Assigns option values from a given KeyValueTreeObject.

Each property with a simple value (or an array of simple values) is assigned to an option with the same name. Objects and arrays of objects are assigned to sections with the same name.

void gmx::checkForUnknownOptionsInKeyValueTree ( const KeyValueTreeObject &  tree,
const Options &  options 
)

Checks that a given KeyValueTreeObject can be assigned to given Options.

Throws an exception if tree contains any values that are not recognized by options. Does not verify the type of the values, only that an option with the correct names exists.

AbstractOptionStorage * gmx::internal::createEnumOptionStorage ( const AbstractOption &  option,
const char *const *  enumValues,
int  count,
int  defaultValue,
int  defaultValueIfSet,
std::unique_ptr< IOptionValueStore< int >>  store 
)

Helper to create EnumOptionStorage instances.

This function works as a proxy between EnumOption::createStorage() and the EnumOptionStorage constructor, such that the latter does not need to be exposed in the header.

template<typename ValueType >
void anonymous_namespace{basicoptions.cpp}::expandVector ( size_t  length,
std::vector< ValueType > *  values 
)

Expands a single value to a vector by copying the value.

Template Parameters
ValueTypeType of values to process.
Parameters
[in]lengthLength of the resulting vector.
[in,out]valuesValues to process.
Exceptions
std::bad_allocif out of memory.
InvalidInputErrorif values has an invalid number of values.

values should have 0, 1, or length values. If values has 1 value, it is expanded such that it has length identical values. In other valid cases, nothing is done.

gmx::anonymous_namespace{filenameoption.cpp}::FileTypeHandler::FileTypeHandler ( int  fileType)
explicit

Returns a handler for a single file type.

Parameters
[in]fileTypeFile type (from filetypes.h) to use.
std::vector<std::string>::const_iterator anonymous_namespace{basicoptions.cpp}::findEnumValue ( const std::vector< std::string > &  allowedValues,
const std::string &  value 
)

Finds an enumerated value from the list of allowed values.

Parameters
[in]allowedValuesList of allowed values.
[in]valueValue to search for.
Exceptions
gmx::InvalidInputErrorif value does not match anything in allowedValues.
Returns
Iterator to the found value.

Variable Documentation

constexpr EnumerationArray<OptionFileType, int> gmx::anonymous_namespace{filenameoption.cpp}::sc_fileTypeMapping
Initial value:
= { efTPS, efTPR, efTRX, efEDR,
efPDB, efNDX, efXVG, efDAT,
efCSV, efQMI }

Mappings from OptionFileType to file types in filetypes.h.