Gromacs  2016.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Classes | Typedefs | Enumerations | Directories | Files
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.

msc_inline_mscgraph_1

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

msc_inline_mscgraph_2

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

msc_inline_mscgraph_3

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::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 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::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::OptionStorageTemplate< T >
 Templated base class for constructing option value storage classes. 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::TimeUnitManager
 Provides common functionality for time unit conversions. More...
 
class  gmx::TimeUnitBehavior
 Options behavior to add a time unit option. More...
 

Typedefs

typedef EnumOption< int > gmx::EnumIntOption
 Shorthand for an enumerated option that stores into an int variable.
 
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 {
  eftUnknown, eftTopology, eftTrajectory, eftEnergy,
  eftPDB, eftIndex, eftPlot, eftGenericData,
  eftOptionFileType_NR
}
 Purpose of file(s) provided through an option.
 

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  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  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  optionstoragetemplate.h
 Defines gmx::OptionStorageTemplate template.
 
file  optionsvisitor.h
 Declares gmx::OptionsVisitor interface and supporting classes.
 
file  timeunitmanager.h
 Declares gmx::TimeUnitManager.
 
file  options.h
 Public API convenience header for handling of options.
 

Typedef Documentation

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.