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

struct	t_pargs
	Command-line argument definition for C code. 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...

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

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::CommandLineModuleInterface and supporting classes.

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

file	cmdlineparser.h
	Declares gmx::CommandLineParser.

file	cmdlineprogramcontext.h
	Declares gmx::CommandLineProgramContext.

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

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.

Function Documentation

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

virtual

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

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

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

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

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.

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.

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

Classes

Macros

Typedefs

Enumerations

Functions

Directories

Files

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation