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.

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

Files
file	abstractoption.h
	Defines gmx::AbstractOption, gmx::OptionTemplate and gmx::OptionInfo.
file	abstractoptionstorage.h
	Declares gmx::AbstractOptionStorage.
file	abstractsection.h
	Declares base classes for declaring option sections.
file	basicoptions.h
	Declares option objects for basic option types.
file	behaviorcollection.h
	Declares gmx::OptionsBehaviorCollection.
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	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.h
	Declares gmx::Options.
file	optionsassigner.h
	Declares gmx::OptionsAssigner.
file	optionsection.h
	Declares gmx::OptionSection and gmx::OptionSectionInfo.
file	optionstoragetemplate.h
	Defines gmx::OptionStorageTemplate template.
file	optionsvisitor.h
	Declares gmx::OptionsVisitor interface and supporting classes.
file	repeatingsection.h
	Declares gmx::RepeatingOptionSection and related classes.
file	timeunitmanager.h
	Declares gmx::TimeUnitManager.
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.