Gromacs
2026.0-dev-20241204-d69d709
|
Provides functionality for handling options.
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.
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().
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).
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.
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.
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 | gmx::test::anonymous_namespace{abstractoptionstorage.cpp}::MockOptionStorage |
Mock implementation of an option storage class for unit testing. More... | |
class | gmx::test::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). | |
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.
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.
void anonymous_namespace{basicoptions.cpp}::expandVector | ( | size_t | length, |
std::vector< ValueType > * | values | ||
) |
Expands a single value to a vector by copying the value.
ValueType | Type of values to process. |
[in] | length | Length of the resulting vector. |
[in,out] | values | Values to process. |
std::bad_alloc | if out of memory. |
InvalidInputError | if 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.
|
explicit |
Returns a handler for a single file type.
[in] | fileType | File 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.
[in] | allowedValues | List of allowed values. |
[in] | value | Value to search for. |
gmx::InvalidInputError | if value does not match anything in allowedValues . |
constexpr EnumerationArray<OptionFileType, int> gmx::anonymous_namespace{filenameoption.cpp}::sc_fileTypeMapping |
Mappings from OptionFileType to file types in filetypes.h.