Gromacs  2026.0-dev-20241121-c76fa1e
 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::CommandLineModuleManager Class Reference

#include <gromacs/commandline/cmdlinemodulemanager.h>

Description

Implements a wrapper command-line interface for multiple modules.

Typical usage:

int main(int argc, char *argv[])
{
try
{
gmx::CommandLineModuleManager manager("gmx", &programContext);
// <register all necessary modules>
int rc = manager.run(argc, argv);
return rc;
}
catch (const std::exception &ex)
{
}
}
*
See Also
page_wrapperbinary

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

Constructor & Destructor Documentation

gmx::CommandLineModuleManager::CommandLineModuleManager ( const char *  binaryName,
CommandLineProgramContext programContext 
)

Initializes a command-line module manager.

Parameters
[in]binaryNameName of the running binary (without Gromacs binary suffix or .exe on Windows).
programContextProgram information for the running binary.
Exceptions
std::bad_allocif 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.

Member Function Documentation

void gmx::CommandLineModuleManager::addHelpTopic ( HelpTopicPointer  topic)

Makes given help topic available through the manager's help module.

Parameters
[in]topicHelp topic to add.
Exceptions
std::bad_allocif out of memory.

The manager takes ownership of the help topic.

void gmx::CommandLineModuleManager::addModule ( CommandLineModulePointer  module)

Adds a given module to this manager.

Parameters
moduleModule to add.
Exceptions
std::bad_allocif 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.

See Also
registerModule()
void gmx::CommandLineModuleManager::addModuleCMain ( const char *  name,
const char *  shortDescription,
CMainFunction  mainFunction 
)

Adds a module that runs a given main()-like function.

Parameters
[in]nameName for the module.
[in]shortDescriptionOne-line description for the module.
[in]mainFunctionMain function to wrap.
Exceptions
std::bad_allocif 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.

Parameters
[in]titleShort title for the group.
Returns
Handle that can be used to add modules to the group.
Exceptions
std::bad_allocif 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.

template<class Module >
void gmx::CommandLineModuleManager::registerModule ( )
inline

Registers a module of a certain type to this manager.

Template Parameters
ModuleType of module to register.
Exceptions
std::bad_allocif 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.

Parameters
[in]argcNumber of elements in argv.
[in]argvCommand-line arguments.
Exceptions
unspecifiedThrows any exception that the selected module throws.
Returns
Exit code for the program.
Return values
0on successful termination.
2if no module is specified, or if the module is not found.

Runs the module whose name matches argv[1].

int gmx::CommandLineModuleManager::runAsMainCMain ( int  argc,
char *  argv[],
CMainFunction  mainFunction 
)
static

Implements a main() method that runs a given function.

Parameters
argcargc passed to main().
argvargv passed to main().
mainFunctionThe 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:

int my_main(int argc, char *argv[])
{
// <...>
}
int main(int argc, char *argv[])
{
return gmx::CommandLineModuleManager::runAsMainCMain(argc, argv, &my_main);
}
*

Does not throw. All exceptions are caught and handled internally.

int gmx::CommandLineModuleManager::runAsMainCMainWithSettings ( int  argc,
char *  argv[],
CMainFunction  mainFunction,
InitSettingsFunction  settingsFunction 
)
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.

int gmx::CommandLineModuleManager::runAsMainSingleModule ( int  argc,
char *  argv[],
ICommandLineModule module 
)
static

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

Parameters
argcargc passed to main().
argvargv passed to main().
moduleModule 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.).

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:

int main(int argc, char *argv[])
{
CustomCommandLineModule module;
}
*

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.

Parameters
[in]outputFile 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.

Parameters
[in]bQuietWhether 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.

Parameters
moduleModule 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.


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