#include <gromacs/commandline/cmdlinemodulemanager.h>

Description

Implements a wrapper command-line interface for multiple modules.

Typical usage:

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

See Also: page_wrapperbinary

Classes
class	Impl
	Private implementation class for CommandLineModuleManager. More...

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]	binaryName	Name of the running binary (without Gromacs binary suffix or .exe on Windows).
	programContext	Program information for the running binary.

Exceptions

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.

Member Function Documentation

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

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

Parameters

[in] topic Help topic to add.

Exceptions

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.

Parameters

module Module to add.

Exceptions

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.

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]	name	Name for the module.
[in]	shortDescription	One-line description for the module.
[in]	mainFunction	Main function to wrap.

Exceptions

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.

Parameters

[in] title Short title for the group.

Returns: Handle that can be used to add modules to the group.

Exceptions

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.

template<class Module >

void gmx::CommandLineModuleManager::registerModule ( )

inline

Registers a module of a certain type to this manager.

Template Parameters

Module Type of module to register.

Exceptions

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.

Parameters

[in]	argc	Number of elements in `argv`.
[in]	argv	Command-line arguments.

Exceptions

unspecified Throws any exception that the selected module throws.

Returns: Exit code for the program.

Return values

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

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

static

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

Parameters

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:

  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

argc	`argc` passed to main().
argv	`argv` passed to main().
module	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.).

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;
      return gmx::CommandLineModuleManager::runAsMainSingleModule(argc, argv, &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] 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.

Parameters

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

Parameters

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.

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

src/gromacs/commandline/cmdlinemodulemanager.h
src/gromacs/commandline/cmdlinemodulemanager.cpp

Description

Classes

Public Types

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation