Gromacs  2024.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
List of all members | Public Member Functions | Protected Member Functions | Friends

#include <gromacs/options/options.h>

+ Inheritance diagram for gmx::Options:
+ Collaboration diagram for gmx::Options:

Description

Collection of options.

See Extensible Handling of Options (options) for an overview of how the options work. The IOptionsContainerWithSections interface documents how to add options.

In order to keep the public interface of this class simple, functionality to assign values to options is provided by a separate OptionsAssigner class. Similarly, functionality for looping over all options (e.g., for writing out help) is provided by OptionsIterator.

Public Member Functions

 Options ()
 Initializes an empty options root container.
 
void addManager (IOptionManager *manager)
 Adds an option manager. More...
 
IOptionsContaineraddGroup () override
 Creates a subgroup of options within the current options. More...
 
OptionSectionInfo & rootSection ()
 Returns a handle to the root section.
 
const OptionSectionInfo & rootSection () const
 Returns a handle to the root section.
 
void finish ()
 Notifies the collection that all option values are assigned. More...
 
template<class SectionType >
SectionType::HandleType addSection (const SectionType &section)
 Adds a section to this collection. More...
 
template<class OptionType >
OptionType::InfoType * addOption (const OptionType &settings)
 Adds a recognized option. More...
 

Protected Member Functions

 GMX_DEFAULT_CONSTRUCTORS (IOptionsContainerWithSections)
 
 GMX_DEFAULT_CONSTRUCTORS (IOptionsContainer)
 

Friends

class OptionsAssigner
 Needed to be able to extend the interface of this object.
 

Member Function Documentation

IOptionsContainer & gmx::Options::addGroup ( )
overridevirtual

Creates a subgroup of options within the current options.

To add options to the group, use the returned interface.

Currently, this is only used to influence the order of options: all options in a group appear before options in a group added after it, no matter in which order the options are added to the groups. In the future, the groups could also be used to influence the help output.

Implements gmx::IOptionsContainer.

void gmx::Options::addManager ( IOptionManager manager)

Adds an option manager.

Parameters
managerManager to add.
Exceptions
std::bad_allocif out of memory.

Option managers are used by some types of options that require interaction between different option instances (e.g., selection options), or need to support globally set properties (e.g., a global default file prefix). Option objects can retrieve the pointer to their manager when they are created, and the caller can alter the behavior of the options through the manager. See the individual managers for details.

Caller is responsible for memory management of manager. The Options object (and its contained options) only stores a reference to the object.

This method cannot be called after adding options or sections.

template<class OptionType >
OptionType::InfoType* gmx::IOptionsContainer::addOption ( const OptionType &  settings)
inlineinherited

Adds a recognized option.

Template Parameters
OptionTypeType of the options description object.
Parameters
[in]settingsOption description.
Returns
OptionInfo object for the created option (never NULL).
Exceptions
APIErrorif invalid option settings are provided.

The return value is a pointer for more convenient use in callers: often callers need to declare the variable that will hold the return value in wider scope than would be achieved by declaring it at the site where addOption() is called. The returned pointer must not be freed.

See class documentation for example usage.

OptionType::InfoType must specify a type that derives from OptionInfo and matches the type that is returned by AbstractOptionStorage::optionInfo() for the storage object that corresponds to OptionType.

Examples:
template.cpp.
template<class SectionType >
SectionType::HandleType gmx::IOptionsContainerWithSections::addSection ( const SectionType &  section)
inlineinherited

Adds a section to this collection.

Template Parameters
SectionTypeType of the section description object.
Parameters
[in]sectionSection description.
Returns
AbstractOptionSectionHandle object for the created option.
Exceptions
APIErrorif invalid option settings are provided.

Options can be added to the section through the returned handle.

void gmx::Options::finish ( )

Notifies the collection that all option values are assigned.

Exceptions
InvalidInputErrorif invalid user input is detected.

This function should be called after no more option values are to be assigned. Values in storage variables are guaranteed to be available only after this call, although in most cases, they are available already during assignment.

If invalid option values, e.g., missing required option, is detected at this point, this function throws. The thrown exception contains information on all errors detected during the call.


The documentation for this class was generated from the following files: