Gromacs
2022.2
|
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::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::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::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::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::OptionsBehaviorCollection |
Container for IOptionsBehavior objects. 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::OptionManagerContainer |
Container to keep managers added with Options::addManager() and pass them to options. More... | |
class | gmx::IOptionManager |
Base class for option managers. More... | |
class | gmx::Options |
Collection of 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::RepeatingOptionSectionHandle< T > |
Allows adding options to an RepeatingOptionSection. More... | |
class | gmx::TimeUnitManager |
Provides common functionality for time unit conversions. More... | |
class | gmx::TimeUnitBehavior |
Options behavior to add a time unit option. More... | |
class | gmx::OptionValueConverterSimple< OutType > |
Helper for converting from Any to a given type. 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, Index, Plot, GenericData, Csv, QMInput, Count } |
Purpose of file(s) provided through an option. | |
Functions | |
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... | |
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.