Collaboration diagram for Command Line Program Management (commandline):

Description

Provides functionality for managing command line programs.

This module provides utility classes and functions for implementing command line programs. They are mainly used within GROMACS, but can also be used from external programs if they want to get a similar user experience to GROMACS tools.

The classes exposed from this module can be roughly divided into two groups:

Helper classes/functions for implementing the main() function. See Using GROMACS as a library for an overview of those available for user programs. These are declared in cmdlineinit.h (gmx::CommandLineModuleInterface is declared in cmdlinemodule.h and gmx::CommandLineOptionsInterface in cmdlineoptionsmodule.h).

Additionally, for internal GROMACS use, gmx::CommandLineModuleManager provides the functionality to implement the gmx wrapper binary, as well as command line options common to all GROMACS programs (such as -version). This is described in more detail at Wrapper binary implementation.
Helper classes for particular command line tasks:
- gmx::CommandLineParser implements command line parsing to assign values to gmx::Options (see Extensible Handling of Options (options)).
- gmx::CommandLineHelpWriter writes help text for a program that uses the parser.
- parse_common_args() is an old interface to GROMACS command line parsing. This is still used by many parts of GROMACS.

Author: Teemu Murtola teemu.nosp@m..mur.nosp@m.tola@.nosp@m.gmai.nosp@m.l.com

Classes
class	gmx::CommandLineHelpContext::Impl
	Private implementation class for CommandLineHelpContext. More...

class	gmx::CommandLineHelpContext
	Context information for writing out command-line help. More...

class	gmx::anonymous_namespace{cmdlinehelpmodule.cpp}::HelpExportInterface
	Callbacks for exporting help information for command-line modules. More...

class	gmx::anonymous_namespace{cmdlinehelpmodule.cpp}::RootHelpTopic
	Help topic that forms the root of the help tree for the help subcommand. More...

class	gmx::anonymous_namespace{cmdlinehelpmodule.cpp}::CommandsHelpTopic
	Help topic for listing the commands. More...

class	gmx::anonymous_namespace{cmdlinehelpmodule.cpp}::ModuleHelpTopic
	Help topic wrapper for a command-line module. More...

class	gmx::anonymous_namespace{cmdlinehelpmodule.cpp}::HelpExportReStructuredText
	Implements export for web pages as reStructuredText. More...

class	gmx::anonymous_namespace{cmdlinehelpmodule.cpp}::HelpExportCompletion
	Implements export for command-line completion. More...

class	gmx::CommandLineHelpModule
	Command-line module for producing help. More...

class	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::OptionsFormatterInterface
	Interface for output format specific formatting of options. More...

class	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::OptionsFilter
	Output format independent processing of options. More...

class	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::SynopsisFormatter
	Formatter implementation for synopsis. More...

class	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::OptionsListFormatter
	Formatter implementation for help export. More...

class	gmx::CommandLineHelpWriter
	Writes help information for Options in ascii format. More...

class	gmx::CommandLineModuleSettings
	Settings to pass information between a module and the general runner. More...

class	gmx::CommandLineModuleInterface
	Module that can be run from command line using CommandLineModuleManager. More...

class	gmx::CommandLineModuleGroupData
	Internal data for a CommandLineModuleManager module group. More...

class	gmx::CommandLineCommonOptionsHolder
	Encapsulates some handling of common options to the wrapper binary. More...

class	gmx::anonymous_namespace{cmdlinemodulemanager.cpp}::CMainCommandLineModule
	Implements a CommandLineModuleInterface, given a function with C/C++ main() signature. More...

class	gmx::CommandLineModuleManager
	Implements a wrapper command-line interface for multiple modules. More...

class	gmx::CommandLineModuleGroup
	Handle to add content to a group added with CommandLineModuleManager::addModuleGroup(). More...

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

class	gmx::CommandLineParser
	Implements command-line parsing for Options objects. More...

class	gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::DefaultExecutableEnvironment
	Default implementation for ExecutableEnvironmentInterface. More...

class	gmx::ExecutableEnvironmentInterface
	Allows customization of the way various directories are found by CommandLineProgramContext. More...

class	gmx::CommandLineProgramContext
	Program context implementation for command line programs. More...

class	gmx::anonymous_namespace{pargs.cpp}::OptionsAdapter
	Conversion helper between t_pargs/t_filenm and Options. More...

struct	t_pargs
	Command-line argument definition for C code. More...

class	gmx::test::MockModule
	Mock implementation of gmx::CommandLineModuleInterface. More...

class	gmx::test::MockOptionsModule
	Mock implementation of gmx::CommandLineOptionsModuleInterface. More...

class	gmx::test::CommandLineModuleManagerTestBase
	Test fixture for tests using gmx::CommandLineModuleManager. More...

Macros
#define	PCA_CAN_VIEW (1<<5)
	Add option -w to view output files (must be implemented in program). More...

#define	PCA_CAN_BEGIN (1<<6)
	Add option to set begin time for trajectory reading. More...

#define	PCA_CAN_END (1<<7)
	Add option to set end time for trajectory reading. More...

#define	PCA_CAN_DT (1<<14)
	Add option to set time step for trajectory reading. More...

#define	PCA_CAN_TIME (PCA_CAN_BEGIN \| PCA_CAN_END \| PCA_CAN_DT)
	Add all options for trajectory time control. More...

#define	PCA_TIME_UNIT (1<<15)
	Add option -tu to set time unit for output. More...

#define	PCA_CAN_SET_DEFFNM (1<<10)
	Add option -deffnm to set default for all file options. More...

#define	PCA_NOEXIT_ON_ARGS (1<<11)
	Do not raise a fatal error when invalid options are encountered. More...

#define	PCA_NOT_READ_NODE (1<<16)
	Is this node not reading: for parallel all nodes but the master.

#define	PCA_DISABLE_INPUT_FILE_CHECKING (1<<17)
	Don't do any special processing for ffREAD files.

Typedefs
typedef std::map< std::string, CommandLineModulePointer >	gmx::CommandLineModuleMap
	Container type for mapping module names to module objects.

typedef gmx_unique_ptr < CommandLineModuleGroupData > ::type	gmx::CommandLineModuleGroupDataPointer
	Smart pointer type for managing a CommandLineModuleGroup.

typedef std::vector < CommandLineModuleGroupDataPointer >	gmx::CommandLineModuleGroupList
	Container type for keeping a list of module groups.

typedef gmx_unique_ptr < CommandLineModuleInterface > ::type	gmx::CommandLineModulePointer
	Smart pointer type for managing a CommandLineModuleInterface.

typedef boost::shared_ptr < ExecutableEnvironmentInterface >	gmx::ExecutableEnvironmentPointer
	Shorthand for a smart pointer to ExecutableEnvironmentInterface.

Enumerations
enum	{ etINT, etINT64, etREAL, etTIME, etSTR, etBOOL, etRVEC, etENUM, etNR }
	Command line argument type. More...

enum	gmx::ShellCompletionFormat { gmx::eShellCompletionFormat_Bash }
	Output format for ShellCompletionWriter. More...

Functions
void	gmx::anonymous_namespace{cmdlinehelpmodule.cpp}::initProgramLinks (HelpLinks *links, const CommandLineHelpModuleImpl &helpModule)
	Adds hyperlinks to modules within this binary. More...

void	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::formatOptionNameAndValue (const OptionInfo &option, std::string name, std::string value)
	Formats option name and value.

std::string	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::defaultOptionValue (const OptionInfo &option)
	Formats the default option value as a string.

std::string	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::fileOptionFlagsAsString (const FileNameOptionInfo &option, bool bAbbrev)
	Formats the flags for a file option as a string.

std::string	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::descriptionWithOptionDetails (const CommonFormatterData &common, const OptionInfo &option)
	Formats the description for an option as a string.

CommandLineProgramContext &	gmx::initForCommandLine (int argc, char **argv)
	Initializes the GROMACS library for command-line use. More...

void	gmx::finalizeForCommandLine ()
	Deinitializes the GROMACS library after initForCommandLine(). More...

void	gmx::writeCommandLineHelpCMain (const CommandLineHelpContext &context, const char name, int(mainFunction)(int argc, char *argv[]))
	Helper to implement CommandLineModuleInterface::writeHelp() with a C-like main() function that calls parse_common_args(). More...

std::string	gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::quoteIfNecessary (const char *str)
	Quotes a string if it contains spaces.

std::string	gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::findFullBinaryPath (const std::string &invokedName, const ExecutableEnvironmentInterface &env)
	Finds the absolute path of the binary from `argv`[0]. More...

bool	gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::isAcceptableLibraryPath (const std::string &path)
	Returns whether given path contains files from `share/top/`. More...

bool	gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::isAcceptableLibraryPathPrefix (const std::string &path)
	Returns whether given path prefix contains files from `share/top/`. More...

std::string	gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::findFallbackInstallationPrefixPath ()
	Returns a fallback installation prefix path. More...

std::string	gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::findInstallationPrefixPath (const std::string &binaryPath, bool *bSourceLayout)
	Generic function to find data files based on path of the binary. More...

virtual std::string	gmx::ExecutableEnvironmentInterface::getWorkingDirectory () const =0
	Returns the working directory when the program was launched.

virtual std::vector< std::string >	gmx::ExecutableEnvironmentInterface::getExecutablePaths () const =0
	Returns list of paths where executables are searched for. More...

	gmx::CommandLineProgramContext::CommandLineProgramContext ()
	Constructs an empty context object. More...

	gmx::CommandLineProgramContext::CommandLineProgramContext (const char *binaryName)
	Initializes a program context object with binary name only. More...

	gmx::CommandLineProgramContext::CommandLineProgramContext (int argc, const char *const argv[])
	Initializes a program context object based on command line. More...

	gmx::CommandLineProgramContext::CommandLineProgramContext (int argc, const char *const argv[], ExecutableEnvironmentPointer env)
	Initializes a program context object based on command line. More...

void	gmx::CommandLineProgramContext::setDisplayName (const std::string &name)
	Sets a display name for the binary. More...

virtual const char *	gmx::CommandLineProgramContext::programName () const
	Returns the name of the binary as it was invoked without any path. More...

virtual const char *	gmx::CommandLineProgramContext::displayName () const
	Returns a display name of the current module. More...

virtual const char *	gmx::CommandLineProgramContext::fullBinaryPath () const
	Returns the full path of the running binary. More...

virtual InstallationPrefixInfo	gmx::CommandLineProgramContext::installationPrefix () const
	Returns the installation prefix (for finding GROMACS data files). More...

virtual const char *	gmx::CommandLineProgramContext::commandLine () const
	Returns the full command line used to invoke the binary. More...

int	gmx::anonymous_namespace{pargs.cpp}::getDefaultXvgFormat (gmx::ConstArrayRef< const char * > xvgFormats)
	Returns the index of the default xvg format.

int	nenum (const char *const enumc[])
	Returns ordinal number for an etENUM argument. More...

int	opt2parg_int (const char *option, int nparg, t_pargs pa[])
	Returns value of an etINT option. More...

gmx_bool	opt2parg_bool (const char *option, int nparg, t_pargs pa[])
	Returns value of an etBOOL option. More...

real	opt2parg_real (const char *option, int nparg, t_pargs pa[])
	Returns value of an etREAL/etTIME option. More...

const char *	opt2parg_str (const char *option, int nparg, t_pargs pa[])
	Returns value of an etSTR option. More...

const char *	opt2parg_enum (const char *option, int nparg, t_pargs pa[])
	Returns value of an etENUM option. More...

gmx_bool	opt2parg_bSet (const char *option, int nparg, t_pargs pa[])
	Returns whether an argument has been set. More...

gmx_bool	parse_common_args (int argc, char argv[], unsigned long Flags, int nfile, t_filenm fnm[], int npargs, t_pargs pa, int ndesc, const char desc, int nbugs, const char bugs, output_env_t oenv)
	Parse command-line arguments. More...

void	anonymous_namespace{cmdlinehelpmodule.cpp}::initOptionsBasic (gmx::Options *options)
	Initializes Options for help export tests.

void	gmx::test::anonymous_namespace{cmdlinemodulemanagertest.cpp}::disableNice (gmx::CommandLineModuleSettings *settings)
	Helper method to disable nice() calls from CommandLineModuleManager.

virtual void	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::DescriptionsFormatter::visitSubSection (const Options &section)
	Formats the description for a single subsection and handles recursion.

void	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::OptionsFilter::formatSelected (FilterType type, OptionsFormatterInterface *formatter, const Options &options)
	Formats selected options using the formatter.

virtual void	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::OptionsFilter::visitSubSection (const Options &section)
	Called for each subsection in Options.

virtual void	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::OptionsFilter::visitOption (const OptionInfo &option)
	Called for each option in Options.

void	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::SynopsisFormatter::start (const char *name)
	Starts formatting the synopsis.

void	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::SynopsisFormatter::finish ()
	Finishes formatting the synopsis.

virtual void	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::SynopsisFormatter::formatOption (const OptionInfo &option)
	Formats a single option option.

	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::OptionsListFormatter::OptionsListFormatter (const HelpWriterContext &context, const CommonFormatterData &common, const char *title)
	Creates a helper object for formatting options.

virtual void	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::OptionsListFormatter::formatOption (const OptionInfo &option)
	Formats a single option option.

Variables
const CommandLineHelpContext *	gmx::anonymous_namespace{cmdlinehelpcontext.cpp}::g_globalContext = NULL
	Stores the global context set with GlobalCommandLineHelpContext. More...

boost::scoped_ptr < CommandLineProgramContext >	gmx::anonymous_namespace{cmdlineinit.cpp}::g_commandLineContext
	Global context instance initialized in initForCommandLine().

boost::scoped_ptr< DataFileFinder >	gmx::anonymous_namespace{cmdlineinit.cpp}::g_libFileFinder
	Global library data file finder that respects GMXLIB.

Directories
directory	commandline
	Command Line Program Management (commandline)

directory	tests
	Unit tests for Command Line Program Management (commandline).

Files
file	cmdlinehelpcontext.cpp
	Implements gmx::CommandLineHelpContext.

file	cmdlinehelpcontext.h
	Declares gmx::CommandLineHelpContext.

file	cmdlinehelpmodule.cpp
	Implements gmx::CommandLineHelpModule.

file	cmdlinehelpmodule.h
	Declares gmx::CommandLineHelpModule.

file	cmdlinehelpwriter.cpp
	Implements gmx::CommandLineHelpWriter.

file	cmdlinehelpwriter.h
	Declares gmx::CommandLineHelpWriter.

file	cmdlineinit.cpp
	Implements functions from cmdlineinit.h.

file	cmdlineinit.h
	Declares functions for initializing the GROMACS library for command line use.

file	cmdlinemodule.cpp
	Implements classes from cmdlinemodule.h.

file	cmdlinemodule.h
	Declares gmx::CommandLineModuleInterface and supporting classes.

file	cmdlinemodulemanager-impl.h
	Declares implementation types for gmx::CommandLineModuleManager.

file	cmdlinemodulemanager.cpp
	Implements gmx::CommandLineModuleManager.

file	cmdlinemodulemanager.h
	Declares gmx::CommandLineModuleManager.

file	cmdlineoptionsmodule.cpp
	Implements supporting routines for gmx::CommandLineOptionsModuleInterface.

file	cmdlineoptionsmodule.h
	Declares gmx::CommandLineOptionsModuleInterface and supporting routines.

file	cmdlineparser.cpp
	Implements gmx::CommandLineParser.

file	cmdlineparser.h
	Declares gmx::CommandLineParser.

file	cmdlineprogramcontext.cpp
	Implements gmx::CommandLineProgramContext.

file	cmdlineprogramcontext.h
	Declares gmx::CommandLineProgramContext.

file	pargs.h
	Declares `t_pargs`, parse_common_args() and related methods.

file	shellcompletions.cpp
	Implements gmx::ShellCompletionWriter.

file	shellcompletions.h
	Declares gmx::ShellCompletionWriter.

file	cmdlinehelpmodule.cpp
	Tests gmx::CommandLineHelpModule through gmx::CommandLineModuleManager.

file	cmdlinehelpwriter.cpp
	Tests gmx::CommandLineHelpWriter.

file	cmdlinemodulemanager.cpp
	Tests gmx::CommandLineModuleManager.

file	cmdlinemodulemanagertest.cpp
	Implements classes from cmdlinemodulemanagertest.h.

file	cmdlinemodulemanagertest.h
	Test fixture and helper classes for tests using gmx::CommandLineModuleManager.

file	cmdlineparser.cpp
	Tests gmx::CommandLineParser.

file	cmdlineprogramcontext.cpp
	Tests for gmx::CommandLineProgramContext.

file	pargs.cpp
	Tests parse_common_args().

file	commandline.h
	Public API convenience header for managing command line programs.

Macro Definition Documentation

#define PCA_CAN_BEGIN (1<<6)

Add option to set begin time for trajectory reading.

#define PCA_CAN_DT (1<<14)

Add option to set time step for trajectory reading.

#define PCA_CAN_END (1<<7)

Add option to set end time for trajectory reading.

#define PCA_CAN_SET_DEFFNM (1<<10)

Add option -deffnm to set default for all file options.

#define PCA_CAN_TIME (PCA_CAN_BEGIN | PCA_CAN_END | PCA_CAN_DT)

Add all options for trajectory time control.

#define PCA_CAN_VIEW (1<<5)

Add option -w to view output files (must be implemented in program).

#define PCA_NOEXIT_ON_ARGS (1<<11)

Do not raise a fatal error when invalid options are encountered.

#define PCA_TIME_UNIT (1<<15)

Add option -tu to set time unit for output.

Enumeration Type Documentation

anonymous enum

Command line argument type.

enum gmx::ShellCompletionFormat

Output format for ShellCompletionWriter.

Enumerator
eShellCompletionFormat_Bash	Shell completions for bash.

Function Documentation

const char * gmx::CommandLineProgramContext::commandLine ( ) const

virtual

Returns the full command line used to invoke the binary.

Does not throw.

Implements gmx::ProgramContextInterface.

gmx::CommandLineProgramContext::CommandLineProgramContext ( )

Constructs an empty context object.

All methods in the constructed object return dummy values.

gmx::CommandLineProgramContext::CommandLineProgramContext ( const char * binaryName )

explicit

Initializes a program context object with binary name only.

Parameters

[in] binaryName Name of the binary.

This is needed for unit testing purposes. The constructed object works as if the command line consisted of only of the binary name.

gmx::CommandLineProgramContext::CommandLineProgramContext	(	int	argc,
		const char *const	argv[]
	)

Initializes a program context object based on command line.

Parameters

[in]	argc	argc value passed to main().
[in]	argv	argv array passed to main().

gmx::CommandLineProgramContext::CommandLineProgramContext	(	int	argc,
		const char *const	argv[],
		ExecutableEnvironmentPointer	env
	)

Initializes a program context object based on command line.

Parameters

[in]	argc	argc value passed to main().
[in]	argv	argv array passed to main().
[in]	env	Customizes the way the binary name is handled.

This overload allows one to customize the way the binary is located by providing a custom ExecutableEnvironmentInterface implementation. This is mainly useful for testing purposes to make it possible to test different paths without setting environment variables, changing the working directory or doing other process-wide operations. It may also be useful for making Gromacs behave better when linked into a non-Gromacs executable (with possible extensions in ExecutableEnvironmentInterface).

const char * gmx::CommandLineProgramContext::displayName ( ) const

virtual

Returns a display name of the current module.

The returned value equals programName(), unless a separate display name has been set with setDisplayName().

Does not throw.

Implements gmx::ProgramContextInterface.

void gmx::finalizeForCommandLine ( )

Deinitializes the GROMACS library after initForCommandLine().

Calls gmx::finalize() and additionally undoes the work done by initForCommandLine().

See Also: gmx::finalize()

std::string gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::findFallbackInstallationPrefixPath ( )

Returns a fallback installation prefix path.

Checks a few standard locations for the data files before returning a configure-time hard-coded path. The hard-coded path is preferred if it actually contains the data files, though.

std::string gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::findFullBinaryPath	(	const std::string &	invokedName,
		const ExecutableEnvironmentInterface &	env
	)

Finds the absolute path of the binary from argv[0].

Parameters

[in]	invokedName	`argv`[0] the binary was invoked with.
[in]	env	Executable environment.

Returns: The full path of the binary.

If a binary with the given name cannot be located, invokedName is returned.

std::string gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::findInstallationPrefixPath	(	const std::string &	binaryPath,
		bool *	bSourceLayout
	)

Generic function to find data files based on path of the binary.

Parameters

[in]	binaryPath	Absolute path to the binary.
[out]	bSourceLayout	Set to `true` if the binary is run from the build tree and the original source directory can be found.

Returns: Path to the share/top/ data files.

The search based on the path only works if the binary is in the same relative path as the installed GROMACS binaries. If the binary is somewhere else, a hard-coded fallback is used. This doesn't work if the binaries are somewhere else than the path given during configure time...

Extra logic is present to allow running binaries from the build tree such that they use up-to-date data files from the source tree.

const char * gmx::CommandLineProgramContext::fullBinaryPath ( ) const

virtual

Returns the full path of the running binary.

Exceptions

std::bad_alloc	if out of memory.
tMPI::system_error	on thread synchronization errors.

Returns argv[0] if there was an error in finding the absolute path.

Implements gmx::ProgramContextInterface.

virtual std::vector<std::string> gmx::ExecutableEnvironmentInterface::getExecutablePaths ( ) const

pure virtual

Returns list of paths where executables are searched for.

The returned list should be in priority order. An empty string in the returned list corresponds to getWorkindDirectory().

Implemented in gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::DefaultExecutableEnvironment.

CommandLineProgramContext & gmx::initForCommandLine	(	int *	argc,
		char ***	argv
	)

Initializes the GROMACS library for command-line use.

Parameters

[in]	argc	argc value passed to main().
[in]	argv	argv array passed to main().

Returns: Reference to initialized program context object.

This function is tailored for use in command line applications. For other usage, combination of gmx::init() and gmx::setProgramContext() provides more flexible initialization alternatives. Unlike gmx::init(), calls to this method cannot be nested.

The command line arguments are communicated so that they can be parsed on each processor. argc and argv are passed to gmx::init(); see there for additional discussion. This method does not place any additional limitations, but generally there should be no need to pass NULL values.

Does not throw. Terminates the program on out-of-memory error.

This method is not thread-safe, since it is intended to be the first method called. See setProgramContext() for additional discussion.

See Also: gmx::init(); setProgramContext()

void gmx::anonymous_namespace{cmdlinehelpmodule.cpp}::initProgramLinks	(	HelpLinks *	links,
		const CommandLineHelpModuleImpl &	helpModule
	)

Adds hyperlinks to modules within this binary.

Parameters

[in,out]	links	Links are added here.
[in]	helpModule	Help module to get module information from.

Exceptions

std::bad_alloc if out of memory.

Initializes a HelpLinks object with links to modules defined in helpModule.

InstallationPrefixInfo gmx::CommandLineProgramContext::installationPrefix ( ) const

virtual

Returns the installation prefix (for finding GROMACS data files).

Exceptions

std::bad_alloc	if out of memory.
tMPI::system_error	on thread synchronization errors.

Returns a hardcoded path set during configuration time if there is an error in finding the library data files.

Implements gmx::ProgramContextInterface.

bool gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::isAcceptableLibraryPath ( const std::string & path )

Returns whether given path contains files from share/top/.

Only checks for a single file that has an uncommon enough name.

bool gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::isAcceptableLibraryPathPrefix ( const std::string & path )

Returns whether given path prefix contains files from share/top/.

Parameters

[in] path Path prefix to check.

Returns: true if path contains the data files.

Checks whether path could be the installation prefix where share/top/ files have been installed: appends the relative installation path of the data files and calls isAcceptableLibraryPath().

int nenum ( const char *const enumc[] )

Returns ordinal number for an etENUM argument.

Parameters

[in] enumc Array passed to t_pargs for an etENUM argument.

Returns: Index of selected enum value in the array.

See t_pargs::u::c for the expected format of the array, including how the first element should be initialized. Note that the return value starts at one instead of zero: if the first enum value is selected, this returns 1.

gmx_bool opt2parg_bool	(	const char *	option,
		int	nparg,
		t_pargs	pa[]
	)

Returns value of an etBOOL option.

Parameters

[in]	option	Name of etBOOL argument to query.
[in]	nparg	Number of elements in `pa`.
[in]	pa	Array of arguments.

Returns: Value of option.

option must specify a valid argument in pa of the correct type.

gmx_bool opt2parg_bSet	(	const char *	option,
		int	nparg,
		t_pargs	pa[]
	)

Returns whether an argument has been set.

Parameters

[in]	option	Name of argument to check.
[in]	nparg	Number of elements in `pa`.
[in]	pa	Array of arguments.

Returns: true if option has been set.

option must specify a valid argument in pa.

const char* opt2parg_enum	(	const char *	option,
		int	nparg,
		t_pargs	pa[]
	)

Returns value of an etENUM option.

Parameters

[in]	option	Name of etENUM argument to query.
[in]	nparg	Number of elements in `pa`.
[in]	pa	Array of arguments.

Returns: Value of option.

option must specify a valid argument in pa of the correct type.

int opt2parg_int	(	const char *	option,
		int	nparg,
		t_pargs	pa[]
	)

Returns value of an etINT option.

Parameters

[in]	option	Name of etINT argument to query.
[in]	nparg	Number of elements in `pa`.
[in]	pa	Array of arguments.

Returns: Value of option.

option must specify a valid argument in pa of the correct type.

real opt2parg_real	(	const char *	option,
		int	nparg,
		t_pargs	pa[]
	)

Returns value of an etREAL/etTIME option.

Parameters

[in]	option	Name of etREAL/etTIME argument to query.
[in]	nparg	Number of elements in `pa`.
[in]	pa	Array of arguments.

Returns: Value of option.

option must specify a valid argument in pa of the correct type.

const char* opt2parg_str	(	const char *	option,
		int	nparg,
		t_pargs	pa[]
	)

Returns value of an etSTR option.

Parameters

[in]	option	Name of etSTR argument to query.
[in]	nparg	Number of elements in `pa`.
[in]	pa	Array of arguments.

Returns: Value of option.

option must specify a valid argument in pa of the correct type.

gmx_bool parse_common_args	(	int *	argc,
		char *	argv[],
		unsigned long	Flags,
		int	nfile,
		t_filenm	fnm[],
		int	npargs,
		t_pargs *	pa,
		int	ndesc,
		const char **	desc,
		int	nbugs,
		const char **	bugs,
		output_env_t *	oenv
	)

Parse command-line arguments.

Some common default arguments are also recognized in addition to those provided through pa. The set of recognized default arguments is affected by Flags.

Recognized arguments are removed from the list.

For full functionality, this function needs to be used within a function that is passed to gmx_run_cmain(). It should be called as the first thing in that function. Initialization code can be executed before it, but you need to be aware that if the program is executed with -h and MPI, the code before parse_common_args() only executes on the master node.

If the return value is FALSE, the program should return immediately (this is necessary for -h and a few other cases).

See Also: gmx_run_cmain().

const char * gmx::CommandLineProgramContext::programName ( ) const

virtual

Returns the name of the binary as it was invoked without any path.

Does not throw.

Implements gmx::ProgramContextInterface.

void gmx::CommandLineProgramContext::setDisplayName ( const std::string & name )

Sets a display name for the binary.

Exceptions

std::bad_alloc if out of memory.

This is used with the wrapper binary to add the name of the invoked module to the name of the binary shown.

It is not threadsafe if there are concurrent calls to displayName() before this method has returned. Thread safety is not required for the normal initialization sequence of command line programs; it is called in the wrapper binary before the control passes to the actual module which may create threads.

void gmx::writeCommandLineHelpCMain	(	const CommandLineHelpContext &	context,
		const char *	name,
		int()(int argc, char argv[])	mainFunction
	)

Helper to implement CommandLineModuleInterface::writeHelp() with a C-like main() function that calls parse_common_args().

Parameters

[in]	context	Context object for writing the help.
[in]	name	Name of the module.
[in]	mainFunction	C-like main() function that calls parse_common_args().

Variable Documentation

const CommandLineHelpContext* gmx::anonymous_namespace{cmdlinehelpcontext.cpp}::g_globalContext = NULL

Stores the global context set with GlobalCommandLineHelpContext.

This is not protected by a mutex, since it is only used in command-line start-up (i.e., single-threaded context), and is inherently not thread-safe.

Description

Classes

Macros

Typedefs

Enumerations

Functions

Variables

Directories

Files

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation