Gromacs  2024.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
List of all members | Public Types | Public Member Functions | Static Public Member Functions
gmx::ICommandLineOptionsModule Class Referenceabstract

#include <gromacs/commandline/cmdlineoptionsmodule.h>

Inherited by gmx::test::MockOptionsModule.

Description

Module that can be run from a command line and uses gmx::Options for argument processing.

This class provides a higher-level interface on top of gmx::ICommandLineModule for cases where gmx::Options will be used for declaring the command-line arguments. The module only needs to declare the options it uses, and the framework takes care of command-line parsing and help output. The module typically consists of the following parts:

registerModule(), runAsMain(), or createModule() can be used to use modules of this type in all contexts where a gmx::ICommandLineModule is expected. These methods create a gmx::ICommandLineModule implementation that contains the common code needed to parse command-line options and write help, based on the information provided from the methods in this class.

Public Types

typedef std::function
< ICommandLineOptionsModulePointer()> 
FactoryMethod
 Function pointer to a factory method that returns an interface of this type. More...
 

Public Member Functions

virtual void init (CommandLineModuleSettings *settings)=0
 Initializes the module and provides settings for the runner. More...
 
virtual void initOptions (IOptionsContainer *options, ICommandLineOptionsModuleSettings *settings)=0
 Initializes command-line arguments understood by the module. More...
 
virtual void optionsFinished ()=0
 Called after all option values have been set. More...
 
virtual int run ()=0
 Runs the module. More...
 

Static Public Member Functions

static std::unique_ptr
< ICommandLineModule
createModule (const char *name, const char *description, ICommandLineOptionsModulePointer module)
 Creates a ICommandLineModule to run the specified module. More...
 
static int runAsMain (int argc, char *argv[], const char *name, const char *description, FactoryMethod factory)
 Implements a main() method that runs a single module. More...
 
static void registerModuleFactory (CommandLineModuleManager *manager, const char *name, const char *description, FactoryMethod factory)
 Registers a module of a certain type to this manager. More...
 
static void registerModuleDirect (CommandLineModuleManager *manager, const char *name, const char *description, ICommandLineOptionsModulePointer module)
 Registers a module to this manager. More...
 

Member Typedef Documentation

Function pointer to a factory method that returns an interface of this type.

Returns
Module to run.
Exceptions
std::bad_allocif out of memory.

Member Function Documentation

std::unique_ptr< ICommandLineModule > gmx::ICommandLineOptionsModule::createModule ( const char *  name,
const char *  description,
ICommandLineOptionsModulePointer  module 
)
static

Creates a ICommandLineModule to run the specified module.

Parameters
[in]nameName for the module.
[in]descriptionShort description for the module.
[in]moduleModule to run.
Returns
ICommandLineModule object that runs module module.
Exceptions
std::bad_allocif out of memory.
virtual void gmx::ICommandLineOptionsModule::init ( CommandLineModuleSettings settings)
pure virtual

Initializes the module and provides settings for the runner.

This will be called before run(), and can be used to adjust initialization that the runner does.

This method is currently not called when writing the help.

virtual void gmx::ICommandLineOptionsModule::initOptions ( IOptionsContainer options,
ICommandLineOptionsModuleSettings settings 
)
pure virtual

Initializes command-line arguments understood by the module.

Parameters
[in,out]optionsOptions object to add the options to.
[in,out]settingsSettings to communicate information to/from generic code running the module.

When running the module, this method is called after init(). When printing help, there is no call to init(), and this is the only method called. In both cases, the implementation should add options understood by the module to options. Output values from options should be stored in member variables.

virtual void gmx::ICommandLineOptionsModule::optionsFinished ( )
pure virtual

Called after all option values have been set.

When running the module, this method is called after all command-line arguments have been parsed.

void gmx::ICommandLineOptionsModule::registerModuleDirect ( CommandLineModuleManager manager,
const char *  name,
const char *  description,
ICommandLineOptionsModulePointer  module 
)
static

Registers a module to this manager.

Parameters
managerManager to register to.
[in]nameName for the module.
[in]descriptionShort description for the module.
[in]moduleModule to register.
Exceptions
std::bad_allocif out of memory.

This method internally creates a ICommandLineModule module with the given name and description, and adds that to manager.

This method is mainly used by tests that need to have a reference to the ICommandLineOptionsModule instance (e.g., for mocking).

void gmx::ICommandLineOptionsModule::registerModuleFactory ( CommandLineModuleManager manager,
const char *  name,
const char *  description,
FactoryMethod  factory 
)
static

Registers a module of a certain type to this manager.

Parameters
managerManager to register to.
[in]nameName for the module.
[in]descriptionShort description for the module.
[in]factoryFactory that returns the module to register.
Exceptions
std::bad_allocif out of memory.

This method internally creates a ICommandLineModule module with the given name and description, and adds that to manager. When run or asked to write the help, the module calls factory to get the actual module, and forwards the necessary calls.

virtual int gmx::ICommandLineOptionsModule::run ( )
pure virtual

Runs the module.

Exceptions
unspecifiedMay throw exceptions to indicate errors.
Returns
Exit code for the program.
Return values
0on successful termination.

This method is called after optionsFinished() when running the module, and should do all the processing for the module.

int gmx::ICommandLineOptionsModule::runAsMain ( int  argc,
char *  argv[],
const char *  name,
const char *  description,
FactoryMethod  factory 
)
static

Implements a main() method that runs a single module.

Parameters
argcargc passed to main().
argvargv passed to main().
[in]nameName for the module.
[in]descriptionShort description for the module.
[in]factoryFactory that returns the module to run.

This method allows for uniform behavior for binaries that only contain a single module without duplicating any of the implementation from CommandLineModuleManager (startup headers, common options etc.).

See Also
runCommandLineModule()

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