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.

Author

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

Classes
class	gmx::AbstractOptionSection
	Base class for specifying option section properties. More...
class	gmx::AbstractOptionSectionHandle
	Base class for handles to option sections. More...
class	gmx::OptionSection
	Declares a simple option section. More...
class	gmx::OptionSectionHandle
	Allows adding options to an OptionSection. 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::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::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::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.

Directories
directory	options
	Extensible Handling of Options (options)

Files
file	abstractsection.h
	Declares base classes for declaring option sections.
file	isectionstorage.h
	Declares gmx::IOptionSectionStorage.
file	optionsection.h
	Declares gmx::OptionSection and gmx::OptionSectionInfo.
file	repeatingsection.h
	Declares gmx::RepeatingOptionSection and related classes.
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

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.