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

#include <gromacs/options/options.h>

Description

Collection of options.

This class provides a standard interface for implementing input options. Standard usage is to write a method that creates an Options that is owned by the object, populates it with supported options, and then returns it:

// <as class attributes>
Options options("common", "Common Options");
std::string arg1;
int arg2;
// <populating>
options.addOption(StringOption("arg1").store(&arg1));
options.addOption(IntegerOption("arg2").store(&arg2));
return &options;

The caller of that method can then use a parser implementation such as CommandLineParser to provide values for the options.

Header basicoptions.h provides declarations of several standard option types for use with addOption(). Documentation of those classes also give more examples of how to define options.

In order to keep the public interface of this class simple and to reduce build dependencies on objects that simply provide options, 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.

Examples:
template.cpp.

Classes

class  Impl
 Private implementation class for Options. More...
 

Public Member Functions

 Options (const char *name, const char *title)
 Initializes the name and title of an option collection. More...
 
const std::string & name () const
 Returns the short name of the option collection.
 
const std::string & title () const
 Returns the title of the option collection.
 
const std::string & description () const
 Returns the full description of the option collection.
 
void setDescription (const std::string &desc)
 Sets the full description of the option collection. More...
 
void setDescription (const ConstArrayRef< const char * > &descArray)
 Sets the full description of the option collection from string array. More...
 
void addManager (OptionManagerInterface *manager)
 Adds an option manager. More...
 
void addSubSection (Options *section)
 Adds an option collection as a subsection of this collection. More...
 
OptionInfoaddOption (const AbstractOption &settings)
 Adds a recognized option to the collection. More...
 
template<class OptionType >
OptionType::InfoType * addOption (const OptionType &settings)
 Adds a recognized option to the collection. More...
 
bool isSet (const char *name) const
 Returns true if option name is set.
 
void finish ()
 Notifies the collection that all option values are assigned. More...
 

Friends

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

Constructor & Destructor Documentation

gmx::Options::Options ( const char *  name,
const char *  title 
)

Initializes the name and title of an option collection.

Parameters
[in]nameSingle-word name.
[in]titleDescriptive title.

Copies the input strings.

Member Function Documentation

void gmx::Options::addManager ( OptionManagerInterface 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 subsections.

OptionInfo * gmx::Options::addOption ( const AbstractOption settings)

Adds a recognized option to the collection.

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

This method provides the internal implementation, but in most cases the templated method is called from user code. See the templated method for more details.

Examples:
template.cpp.
template<class OptionType >
OptionType::InfoType* gmx::Options::addOption ( const OptionType &  settings)
inline

Adds a recognized option to the collection.

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.

void gmx::Options::addSubSection ( Options section)

Adds an option collection as a subsection of this collection.

Parameters
[in]sectionSubsection to add.

The name() field of section is used as the name of the subsection. If an attempt is made to add two different subsections with the same name, this function asserts.

section should not have any options added at the point this method is called.

Only a pointer to the provided object is stored. The caller is responsible that the object exists for the lifetime of the collection. It is not possible to add the same Options object as a subsection to several different Options. If an attempt is made, the function asserts.

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.

void gmx::Options::setDescription ( const std::string &  desc)

Sets the full description of the option collection.

Parameters
[in]descString to set as the description.

This overload is mainly useful if the description is very short. Currently this is mostly the case in unit testing.

Examples:
template.cpp.
void gmx::Options::setDescription ( const ConstArrayRef< const char * > &  descArray)

Sets the full description of the option collection from string array.

Parameters
[in]descArrayString array to set as the description.

All strings in descArray are concatenated to form the description. Spaces are inserted between strings if they are missing.

Example usage:

const char *const desc[] = {
"This is the description",
"for the options"
};
gmx::Options options(NULL, NULL);
options.setDescription(desc);

To use this overload, you must also include gromacs/utility/arrayref.h.


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