Gromacs
5.1.5
|
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.
Classes | |
class | gmx::CommandLineHelpContext |
Context information for writing out command-line help. 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::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::ExecutableEnvironmentInterface |
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_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... | |
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... | |
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) | |
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::CommandLineModuleInterface and supporting classes. | |
file | cmdlinemodulemanager.h |
Declares gmx::CommandLineModuleManager. | |
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. | |
#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.
anonymous enum |
Command line argument type.
|
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.
|
explicit |
Initializes a program context object with binary name only.
[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[] | ||
) |
gmx::CommandLineProgramContext::CommandLineProgramContext | ( | int | argc, |
const char *const | argv[], | ||
ExecutableEnvironmentPointer | env | ||
) |
Initializes a program context object based on command line.
[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).
|
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().
|
virtual |
Returns the full path of the running binary.
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.
|
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.
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.
|
virtual |
Returns the installation prefix (for finding GROMACS data files).
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.
int nenum | ( | const char *const | enumc[] | ) |
Returns ordinal number for an etENUM argument.
[in] | enumc | Array passed to t_pargs for an etENUM argument. |
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.
Returns value of an etBOOL option.
[in] | option | Name of etBOOL argument to query. |
[in] | nparg | Number of elements in pa . |
[in] | pa | Array of arguments. |
option
.option
must specify a valid argument in pa
of the correct type.
Returns whether an argument has been set.
[in] | option | Name of argument to check. |
[in] | nparg | Number of elements in pa . |
[in] | pa | Array of arguments. |
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.
[in] | option | Name of etENUM argument to query. |
[in] | nparg | Number of elements in pa . |
[in] | pa | Array of arguments. |
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.
[in] | option | Name of etINT argument to query. |
[in] | nparg | Number of elements in pa . |
[in] | pa | Array of arguments. |
option
.option
must specify a valid argument in pa
of the correct type.
Returns value of an etREAL/etTIME option.
[in] | option | Name of etREAL/etTIME argument to query. |
[in] | nparg | Number of elements in pa . |
[in] | pa | Array of arguments. |
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.
[in] | option | Name of etSTR argument to query. |
[in] | nparg | Number of elements in pa . |
[in] | pa | Array of arguments. |
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).
|
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.
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().
[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(). |