Gromacs
2026.0-dev-20241121-c76fa1e
|
#include <gromacs/commandline/cmdlinemodulemanager.h>
Implements a wrapper command-line interface for multiple modules.
Typical usage:
Public Types | |
typedef int(* | CMainFunction )(int argc, char *argv[]) |
Function pointer type for a C main function. | |
typedef void(* | InitSettingsFunction )(CommandLineModuleSettings *settings) |
Function pointer to a settings provider. | |
Public Member Functions | |
CommandLineModuleManager (const char *binaryName, CommandLineProgramContext *programContext) | |
Initializes a command-line module manager. More... | |
void | setQuiet (bool bQuiet) |
Sets the module manager to quiet mode: don't print anything. More... | |
void | setOutputRedirector (IFileOutputRedirector *output) |
Redirects the output of the module manager to a file. More... | |
void | setSingleModule (ICommandLineModule *module) |
Makes the manager always run a single module. More... | |
void | addModule (CommandLineModulePointer module) |
Adds a given module to this manager. More... | |
void | addModuleCMain (const char *name, const char *shortDescription, CMainFunction mainFunction) |
Adds a module that runs a given main()-like function. More... | |
void | addModuleCMainWithSettings (const char *name, const char *shortDescription, CMainFunction mainFunction, InitSettingsFunction settingsFunction) |
Adds a module that runs a given main()-like function with custom settings. More... | |
template<class Module > | |
void | registerModule () |
Registers a module of a certain type to this manager. More... | |
CommandLineModuleGroup | addModuleGroup (const char *title) |
Adds a group for modules to use in help output. More... | |
void | addHelpTopic (HelpTopicPointer topic) |
Makes given help topic available through the manager's help module. More... | |
int | run (int argc, char *argv[]) |
Runs a module based on given command line. More... | |
Static Public Member Functions | |
static int | runAsMainSingleModule (int argc, char *argv[], ICommandLineModule *module) |
Implements a main() method that runs a single module. More... | |
static int | runAsMainCMain (int argc, char *argv[], CMainFunction mainFunction) |
Implements a main() method that runs a given function. More... | |
static int | runAsMainCMainWithSettings (int argc, char *argv[], CMainFunction mainFunction, InitSettingsFunction settingsFunction) |
Implements a main() method that runs a given function with custom settings. More... | |
gmx::CommandLineModuleManager::CommandLineModuleManager | ( | const char * | binaryName, |
CommandLineProgramContext * | programContext | ||
) |
Initializes a command-line module manager.
[in] | binaryName | Name of the running binary (without Gromacs binary suffix or .exe on Windows). |
programContext | Program information for the running binary. |
std::bad_alloc | if out of memory. |
binaryName
is used to detect when the binary is run through a symlink, and automatically invoke a matching module in such a case.
programInfo
is non-const to allow the manager to amend it based on the actual module that is getting executed.
void gmx::CommandLineModuleManager::addHelpTopic | ( | HelpTopicPointer | topic | ) |
Makes given help topic available through the manager's help module.
[in] | topic | Help topic to add. |
std::bad_alloc | if out of memory. |
The manager takes ownership of the help topic.
void gmx::CommandLineModuleManager::addModule | ( | CommandLineModulePointer | module | ) |
Adds a given module to this manager.
module | Module to add. |
std::bad_alloc | if out of memory. |
The manager takes ownership of the object.
This method is public mostly for testing purposes; for typical uses, registerModule() is a more convenient way of adding modules.
void gmx::CommandLineModuleManager::addModuleCMain | ( | const char * | name, |
const char * | shortDescription, | ||
CMainFunction | mainFunction | ||
) |
Adds a module that runs a given main()-like function.
[in] | name | Name for the module. |
[in] | shortDescription | One-line description for the module. |
[in] | mainFunction | Main function to wrap. |
std::bad_alloc | if out of memory. |
There is normally no need to call this method outside the Gromacs library. User code usually wants to use runAsMainCMain().
name
and shortDescription
should be string constants, or the caller should otherwise ensure that they stay in scope for the duration the CommandLineModuleManager object exists. mainFunction
should call parse_common_args() to process its command-line arguments.
void gmx::CommandLineModuleManager::addModuleCMainWithSettings | ( | const char * | name, |
const char * | shortDescription, | ||
CMainFunction | mainFunction, | ||
InitSettingsFunction | settingsFunction | ||
) |
Adds a module that runs a given main()-like function with custom settings.
This method does the same as runAsMainCMain(), but additionally calls settingsFunction
to initialize CommandLineModuleSettings. This allows specifying, e.g., a different default nice level.
CommandLineModuleGroup gmx::CommandLineModuleManager::addModuleGroup | ( | const char * | title | ) |
Adds a group for modules to use in help output.
[in] | title | Short title for the group. |
std::bad_alloc | if out of memory. |
Creates a group that is used to structure the list of all modules in help output. Modules are added to the group using the returned object.
|
inline |
Registers a module of a certain type to this manager.
Module | Type of module to register. |
std::bad_alloc | if out of memory. |
Module
must be default-constructible and implement ICommandLineModule.
This method is provided as a convenient alternative to addModule() for cases where each module is implemented by a different type (which should be the case for typical situations outside unit tests).
int gmx::CommandLineModuleManager::run | ( | int | argc, |
char * | argv[] | ||
) |
Runs a module based on given command line.
[in] | argc | Number of elements in argv . |
[in] | argv | Command-line arguments. |
unspecified | Throws any exception that the selected module throws. |
0 | on successful termination. |
2 | if no module is specified, or if the module is not found. |
Runs the module whose name matches argv
[1].
|
static |
Implements a main() method that runs a given function.
argc | argc passed to main(). |
argv | argv passed to main(). |
mainFunction | The main()-like method to wrap. |
This method creates a dummy command-line module that does its processing by calling mainFunction
; see addModuleCMain() for details. It then runs this module with runAsMainSingleModule(). This allows the resulting executable to handle common options and do other common actions (e.g., startup headers) without duplicate code in the main methods.
Usage:
Does not throw. All exceptions are caught and handled internally.
|
static |
Implements a main() method that runs a given function with custom settings.
This method does the same as runAsMainCMain(), but additionally calls settingsFunction
to initialize CommandLineModuleSettings. This allows specifying, e.g., a different default nice level.
|
static |
Implements a main() method that runs a single module.
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.).
The signature assumes that module
construction does not throw (because otherwise the caller would need to duplicate all the exception handling code). It is possible to move the construction inside the try/catch in this method using an indirection similar to TrajectoryAnalysisCommandLineRunner::runAsMain(), but until that is necessary, the current approach leads to simpler code.
Usage:
Does not throw. All exceptions are caught and handled internally.
void gmx::CommandLineModuleManager::setOutputRedirector | ( | IFileOutputRedirector * | output | ) |
Redirects the output of the module manager to a file.
[in] | output | File redirector to use for output. |
Normally, the module manager prints explicitly requested text such as help output to stdout
, but this method can be used to redirect that output to a file. For exporting help from the module manager, several files are written, and can be redirected with this method as well.
This is used for unit tests, either to keep them quiet or to verify that output. To keep implementation options open, behavior with output == NULL
is undefined and should not be relied on. For tests, there should only be need to call this a single time, right after creating the manager.
void gmx::CommandLineModuleManager::setQuiet | ( | bool | bQuiet | ) |
Sets the module manager to quiet mode: don't print anything.
[in] | bQuiet | Whether the module manager should remain silent. |
Normally, the module manager prints out some information to stderr
before it starts the module and after it finishes. This removes that output, which is useful in particular for unit tests so that they don't spam stderr
.
void gmx::CommandLineModuleManager::setSingleModule | ( | ICommandLineModule * | module | ) |
Makes the manager always run a single module.
module | Module to run. |
This method disables all mechanisms for selecting a module, and directly passes all command-line arguments to module
. Help arguments are an exception: these are still recognized by the manager and translated into a call to ICommandLineModule::writeHelp().
This is public mainly for unit testing purposes; for other code, runAsMainSingleModule() typically provides the desired functionality.
Does not throw.