Gromacs  2016.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Classes | Macros | Typedefs | Enumerations | Functions | Directories | Files
Command Line Program Management (commandline)
+ 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:

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

Classes

class  gmx::CommandLineHelpContext
 Context information for writing out command-line help. More...
 
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::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::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...
 
class  gmx::IExecutableEnvironment
 Allows customization of the way various directories are found by CommandLineProgramContext. More...
 
class  gmx::CommandLineProgramContext
 Program context implementation for command line programs. 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_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 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
< ICommandLineModule > 
gmx::CommandLineModulePointer
 Smart pointer type for managing a ICommandLineModule.
 
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...
 
void gmx::writeCommandLineHelpCMain (const CommandLineHelpContext &context, const char *name, int(*mainFunction)(int argc, char *argv[]))
 Helper to implement ICommandLineModule::writeHelp() with a C-like main() function that calls parse_common_args(). More...
 
virtual std::string gmx::IExecutableEnvironment::getWorkingDirectory () const =0
 Returns the working directory when the program was launched.
 
virtual std::vector< std::string > 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...
 
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...
 
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.
 
int opt2fns (char **fns[], const char *opt, int nfile, const t_filenm fnm[])
 Returns the filenames belonging to cmd-line option opt, or NULL when no such option.
 
const t_filenmgetFilenm (const char *opt, int nfile, const t_filenm fnm[])
 Return a pointer to the t_filenm data structure of filenames belonging to command-line option opt, or NULL when no such option was used.
 
const char * ftp2fn (int ftp, int nfile, const t_filenm fnm[])
 Returns the first file name with type ftp, or NULL when none found.
 
int ftp2fns (char **fns[], int ftp, int nfile, const t_filenm fnm[])
 Returns the number of files for the first option with type ftp and the files in **fns[] (will be allocated), or NULL when none found.
 
gmx_bool ftp2bSet (int ftp, int nfile, const t_filenm fnm[])
 Returns TRUE when this file type has been found on the cmd-line.
 
gmx_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...
 
gmx_bool is_optional (const t_filenm *fnm)
 Returns whether or not this filenm is optional.
 
gmx_bool is_output (const t_filenm *fnm)
 Returns whether or not this filenm is output.
 
gmx_bool is_set (const t_filenm *fnm)
 Returns whether or not this filenm is set.
 
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.
 
t_filenmdup_tfn (int nf, const t_filenm tfn[])
 Duplicates the filename list (to make a private copy for each thread, for example).
 
void done_filenms (int nf, t_filenm fnm[])
 Frees memory allocated for file names by parse_common_args().
 
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, gmx_output_env_t **oenv)
 Parse command-line arguments. More...
 

Directories

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

Files

file  cmdlinehelpcontext.h
 Declares gmx::CommandLineHelpContext.
 
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  cmdlinemodulemanager.h
 Declares gmx::CommandLineModuleManager.
 
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).
 
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.

Implements gmx::IProgramContext.

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]binaryNameName 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]argcargc value passed to main().
[in]argvargv 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]argcargc value passed to main().
[in]argvargv array passed to main().
[in]envCustomizes 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
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::IProgramContext.

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.

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

Returns the full path of the running binary.

Exceptions
std::bad_allocif out of memory.
tMPI::system_erroron thread synchronization errors.

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

Implements gmx::IProgramContext.

virtual std::vector<std::string> 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().

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

Initializes the GROMACS library for command-line use.

Parameters
[in]argcargc value passed to main().
[in]argvargv 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_allocif out of memory.
tMPI::system_erroron thread synchronization errors.

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

Implements gmx::IProgramContext.

int nenum ( const char *const  enumc[])

Returns ordinal number for an etENUM argument.

Parameters
[in]enumcArray 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_bool opt2parg_bool ( const char *  option,
int  nparg,
t_pargs  pa[] 
)

Returns value of an etBOOL option.

Parameters
[in]optionName of etBOOL argument to query.
[in]npargNumber of elements in pa.
[in]paArray 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]optionName of argument to check.
[in]npargNumber of elements in pa.
[in]paArray 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]optionName of etENUM argument to query.
[in]npargNumber of elements in pa.
[in]paArray 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]optionName of etINT argument to query.
[in]npargNumber of elements in pa.
[in]paArray 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]optionName of etREAL/etTIME argument to query.
[in]npargNumber of elements in pa.
[in]paArray 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]optionName of etSTR argument to query.
[in]npargNumber of elements in pa.
[in]paArray 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,
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 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::IProgramContext.

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

Sets a display name for the binary.

Exceptions
std::bad_allocif 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 ICommandLineModule::writeHelp() with a C-like main() function that calls parse_common_args().

Parameters
[in]contextContext object for writing the help.
[in]nameName of the module.
[in]mainFunctionC-like main() function that calls parse_common_args().