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::ICommandLineModule is declared in cmdlinemodule.h and gmx::ICommandLineOptions in cmdlineoptionsmodule.h).
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

Namespaces
	gmx
	Generic GROMACS namespace.

Classes
class	gmx::CommandLineHelpWriter
	Writes help information for Options. More...

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

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

class	gmx::ICommandLineOptionsModuleSettings
	Settings to pass information between a CommandLineOptionsModule and generic code that runs it. More...

class	gmx::ICommandLineOptionsModule
	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...

struct	t_filenm
	File name option definition for C code. More...

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

Macros
#define	ffSET 1 << 0
	Whether a file name option is set.

#define	ffREAD 1 << 1
	Whether a file name option specifies an input file.

#define	ffWRITE 1 << 2
	Whether a file name option specifies an output file.

#define	ffOPT 1 << 3
	Whether a file name option specifies an optional file.

#define	ffLIB 1 << 4
	Whether a file name option specifies a library file.

#define	ffMULT 1 << 5
	Whether a file name option accepts multiple file names.

#define	ffALLOW_MISSING 1 << 6
	Whether an input file name option accepts non-existent files.

#define	ffRW (ffREAD \| ffWRITE)
	Convenience flag for an input/output file.

#define	ffOPTRD (ffREAD \| ffOPT)
	Convenience flag for an optional input file.

#define	ffOPTWR (ffWRITE \| ffOPT)
	Convenience flag for an optional output file.

#define	ffOPTRW (ffRW \| ffOPT)
	Convenience flag for an optional input/output file.

#define	ffLIBRD (ffREAD \| ffLIB)
	Convenience flag for a library input file.

#define	ffLIBOPTRD (ffOPTRD \| ffLIB)
	Convenience flag for an optional library input file.

#define	ffRDMULT (ffREAD \| ffMULT)
	Convenience flag for an input file that accepts multiple files.

#define	ffOPTRDMULT (ffRDMULT \| ffOPT)
	Convenience flag for an optional input file that accepts multiple files.

#define	ffWRMULT (ffWRITE \| ffMULT)
	Convenience flag for an output file that accepts multiple files.

#define	ffOPTWRMULT (ffWRMULT \| ffOPT)
	Convenience flag for an optional output file that accepts multiple files.

#define	opt2FILE(opt, nfile, fnm, mode) gmx_ffopen(opt2fn(opt, nfile, fnm), mode)
	Returns a file pointer from the filename.

#define	ftp2FILE(ftp, nfile, fnm, mode) gmx_ffopen(ftp2fn(ftp, nfile, fnm), mode)
	Returns a file pointer from the file type.

#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_DISABLE_INPUT_FILE_CHECKING (1 << 17)
	Don't do any special processing for ffREAD files.

Typedefs
typedef std::unique_ptr < ICommandLineModule >	gmx::CommandLineModulePointer
	Smart pointer type for managing a ICommandLineModule.

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

typedef std::unique_ptr < CommandLineModuleGroupData >	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 std::unique_ptr < IExecutableEnvironment >	gmx::ExecutableEnvironmentPointer
	Shorthand for a smart pointer to IExecutableEnvironment.

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

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

virtual std::filesystem::path	gmx::IExecutableEnvironment::getWorkingDirectory () const =0
	Returns the working directory when the program was launched.

virtual std::vector < std::filesystem::path >	gmx::IExecutableEnvironment::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...

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

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

std::filesystem::path	gmx::CommandLineProgramContext::fullBinaryPath () const override
	Returns the full path of the running binary. More...

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

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

const char *	opt2fn (const char *opt, int nfile, const t_filenm fnm[])
	Returns the filename belonging to cmd-line option opt, or NULL when no such option.

gmx::ArrayRef< const std::string >	opt2fns (const char *opt, int nfile, const t_filenm fnm[])
	Returns the filenames belonging to cmd-line option opt. More...

gmx::ArrayRef< const std::string >	opt2fnsIfOptionSet (const char *opt, int nfile, const t_filenm fnm[])
	Returns the filenames belonging to cmd-line option opt when set, returns an empty vector when the option is not set. More...

const char *	ftp2fn (int ftp, int nfile, const t_filenm fnm[])
	Returns the first file name with type ftp, or NULL when none found.

gmx::ArrayRef< const std::string >	ftp2fns (int ftp, int nfile, const t_filenm fnm[])
	Returns the filenames for the first option with type ftp. More...

bool	ftp2bSet (int ftp, int nfile, const t_filenm fnm[])
	Returns TRUE when this file type has been found on the cmd-line.

bool	opt2bSet (const char *opt, int nfile, const t_filenm fnm[])
	Returns TRUE when this option has been found on the cmd-line.

const char *	opt2fn_null (const char *opt, int nfile, const t_filenm fnm[])
	Returns the file name belonging top cmd-line option opt, or NULL when no such option. More...

const char *	ftp2fn_null (int ftp, int nfile, const t_filenm fnm[])
	Returns the first file name with type ftp, or NULL when none found. More...

bool	is_optional (const t_filenm *fnm)
	Returns whether or not this filenm is optional.

bool	is_output (const t_filenm *fnm)
	Returns whether or not this filenm is output.

bool	is_set (const t_filenm *fnm)
	Returns whether or not this filenm is set.

bool	hasSuffixFromNoAppend (std::string_view filename)
	Return whether `filename` might have been produced by mdrun -noappend. More...

int	add_suffix_to_output_names (t_filenm fnm, int nfile, const char suffix)
	When we do checkpointing, this routine is called to check for previous output files and append a '.partNNNN' suffix before the (output) file extensions. If there was already a '.partNNNN' suffix before the file extension, that is removed before the new suffix is added.

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

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

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

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, gmx_output_env_t *oenv)
	Parse command-line arguments. More...

Directories
directory	commandline
	Command Line Program Management (commandline)

Files
file	cmdlinehelpwriter.h
	Declares gmx::CommandLineHelpWriter.

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

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

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

file	cmdlineparser.h
	Declares gmx::CommandLineParser.

file	cmdlineprogramcontext.h
	Declares gmx::CommandLineProgramContext.

file	filenm.h
	Declares t_filenm for old-style command-line parsing of file name options.

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

file	viewit.h
	Provides function to open output files automatically (with some X11 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.

Function Documentation

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

override

Returns the full command line used to invoke the binary.

Does not throw.

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

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

override

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.

void gmx::finalizeForCommandLine ( )

Deinitializes the GROMACS library after initForCommandLine().

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

See Also: gmx::finalize()

const char* ftp2fn_null	(	int	ftp,
		int	nfile,
		const t_filenm	fnm[]
	)

Returns the first file name with type ftp, or NULL when none found.

Also return NULL when ftp is optional and option is not set.

gmx::ArrayRef<const std::string> ftp2fns	(	int	ftp,
		int	nfile,
		const t_filenm	fnm[]
	)

Returns the filenames for the first option with type ftp.

An assertion will fail when when none found.

std::filesystem::path gmx::CommandLineProgramContext::fullBinaryPath ( ) const

override

Returns the full path of the running binary.

Exceptions

std::bad_alloc if out of memory.

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

virtual std::vector<std::filesystem::path> gmx::IExecutableEnvironment::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().

bool hasSuffixFromNoAppend ( std::string_view filename )

Return whether filename might have been produced by mdrun -noappend.

If so, it must match "prefix.partNNNN.extension", for four decimal digits N and non-empty prefix and extension.

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()

InstallationPrefixInfo gmx::CommandLineProgramContext::installationPrefix ( ) const

override

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

Exceptions

std::bad_alloc if out of memory.

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

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.

const char* opt2fn_null	(	const char *	opt,
		int	nfile,
		const t_filenm	fnm[]
	)

Returns the file name belonging top cmd-line option opt, or NULL when no such option.

Also return NULL when opt is optional and option is not set.

gmx::ArrayRef<const std::string> opt2fns	(	const char *	opt,
		int	nfile,
		const t_filenm	fnm[]
	)

Returns the filenames belonging to cmd-line option opt.

An assertion will fail when the option does not exist.

gmx::ArrayRef<const std::string> opt2fnsIfOptionSet	(	const char *	opt,
		int	nfile,
		const t_filenm	fnm[]
	)

Returns the filenames belonging to cmd-line option opt when set, returns an empty vector when the option is not set.

An assertion will fail when the option does not exist.

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.

bool opt2parg_bSet	(	const char *	option,
		int	nparg,
		const 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.

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,
		gmx_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 main 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

override

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

Does not throw.

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.

Description

Namespaces

Classes

Macros

Typedefs

Enumerations

Functions

Directories

Files

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation