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.

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.

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::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::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::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...

struct	gmx::anonymous_namespace{filenameoption.cpp}::FileTypeMapping
	Mapping from OptionFileType to a file type in filetypes.h. More...

class	gmx::anonymous_namespace{filenameoption.cpp}::FileTypeHandler
	Handles a single file type known to FileNameOptionStorage. 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::FileNameOptionManager::Impl
	Private implemention class for FileNameOptionManager. 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::IOptionSectionStorage
	Provides behavior specific to a certain option section type. More...

class	gmx::IOptionValueStore< T >
	Represents the final storage location of option values. 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::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::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...

class	gmx::OptionValueStoreNull< T >
	Value storage that does not store anywhere. 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
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...

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...

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...

	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	abstractoption.h
	Defines gmx::AbstractOption, gmx::OptionTemplate and gmx::OptionInfo.

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	basicoptions.h
	Declares option objects for basic option types.

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	filenameoption.h
	Declares gmx::FileNameOption and gmx::FileNameOptionInfo.

file	filenameoptionmanager.cpp
	Implements gmx::FileNameOptionManager.

file	filenameoptionmanager.h
	Declares gmx::FileNameOptionManager.

file	filenameoptionstorage.h
	Declares gmx::FileNameOptionStorage.

file	ioptionsbehavior.h
	Declares gmx::IOptionsBehavior.

file	ioptionscontainer.h
	Declares gmx::IOptionsContainer.

file	ioptionscontainerwithsections.h
	Declares gmx::IOptionsContainerWithSections.

file	isectionstorage.h
	Declares gmx::IOptionSectionStorage.

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	optionmanagercontainer.h
	Declares gmx::OptionManagerContainer.

file	options.cpp
	Implements gmx::Options.

file	options.h
	Declares 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	timeunitmanager.h
	Declares 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	options.h
	Public API convenience header for handling of options.

Typedef Documentation

gmx::RealOption

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.

gmx::RealOptionInfo

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

ValueType Type of values to process.

Parameters

[in]	length	Length of the resulting vector.
[in,out]	values	Values to process.

Exceptions

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.

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

explicit

Returns a handler for a single file type.

Parameters

[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.

Parameters

[in]	allowedValues	List of allowed values.
[in]	value	Value to search for.

Exceptions

gmx::InvalidInputError if 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.

Description

Basic Use

Advanced Use (in library API)

Classes

Typedefs

Enumerations

Functions

Variables

Directories

Files

Typedef Documentation

Function Documentation

Variable Documentation