Extract command arguments and options from the supplied argc and argv parameters. More...

Collaboration diagram for argList:

Classes
class	initValidTables

Public Member Functions
	argList (int &argc, char **&argv, bool checkArgs=true, bool checkOpts=true, bool initialise=true)
	Construct from argc and argv. More...

	argList (const argList &args, const HashTable< string > &options, bool checkArgs=true, bool checkOpts=true, bool initialise=true)
	Construct copy with new options. More...

virtual	~argList ()
	Destructor. More...

void	parse (bool checkArgs, bool checkOpts, bool initialise)
	Parse. More...

const string &	commandLine () const
	Return the command line string. More...

const word &	executable () const
	Name of executable without the path. More...

const fileName &	rootPath () const
	Return root path. More...

const fileName &	caseName () const
	Return case name (parallel run) or global case (serial run) More...

const fileName &	globalCaseName () const
	Return case name. More...

const ParRunControl &	parRunControl () const
	Return parRunControl. More...

fileName	path () const
	Return the path to the caseName. More...

const stringList &	args () const
	Return arguments. More...

stringList &	args ()
	Return non-const access to arguments. More...

const string &	arg (const label index) const
	Return the argument corresponding to index. More...

label	size () const
	Return the number of arguments. More...

template<class T >
T	argRead (const label index) const
	Read a value from the argument at index. More...

const Foam::HashTable< string > &	options () const
	Return options. More...

Foam::HashTable< string > &	options ()
	Return non-const access to options. More...

const string &	option (const word &opt) const
	Return the argument string associated with the named option. More...

bool	optionFound (const word &opt) const
	Return true if the named option is found. More...

IStringStream	optionLookup (const word &opt) const
	Return an IStringStream from the named option. More...

template<class T >
T	optionRead (const word &opt) const
	Read a value from the named option. More...

template<class T >
bool	optionReadIfPresent (const word &opt, T &) const
	Read a value from the named option if present. More...

template<class T >
bool	optionReadIfPresent (const word &opt, T &, const T &deflt) const
	Read a value from the named option if present. More...

template<class T >
T	optionLookupOrDefault (const word &opt, const T &deflt) const
	Read a value from the named option if present. More...

template<class T >
List< T >	optionReadList (const word &opt) const
	Read a List of values from the named option. More...

const string &	operator[] (const label index) const
	Return the argument corresponding to index. More...

const string &	operator[] (const word &opt) const
	Return the argument string associated with the named option. More...

bool	setOption (const word &opt, const string &param="")
	Set option directly (use with caution) More...

bool	unsetOption (const word &opt)
	Unset option directly (use with caution) More...

void	printNotes () const
	Print notes (if any) More...

void	printUsage () const
	Print usage. More...

void	displayDoc (bool source=false) const
	Display documentation in browser. More...

bool	check (bool checkArgs=true, bool checkOpts=true) const
	Check argument list. More...

bool	checkRootCase () const
	Check root path and case path. More...

Static Public Member Functions
static void	addBoolOption (const word &opt, const string &usage="")
	Add to a bool option to validOptions with usage information. More...

static void	addOption (const word &opt, const string &param="", const string &usage="")
	Add to an option to validOptions with usage information. More...

static void	addUsage (const word &opt, const string &usage)
	Add option usage information to optionUsage. More...

static void	addNote (const string &)
	Add extra notes for the usage information. More...

static void	removeOption (const word &opt)
	Remove option from validOptions and from optionUsage. More...

static void	noParallel ()
	Remove the parallel options. More...

static bool	postProcess (int argc, char *argv[])
	Return true if the post-processing option is specified. More...

static bool	hasArgs (int argc, char *argv[])
	Return true if there are arguments. More...

Static Public Attributes
static SLList< string >	validArgs
	A list of valid (mandatory) arguments. More...

static HashTable< string >	validOptions
	A list of valid options. More...

static HashTable< string >	validParOptions
	A list of valid parallel options. More...

static HashTable< string >	optionUsage
	Short usage information for validOptions. More...

static SLList< string >	notes
	Additional notes for usage. More...

static string::size_type	usageMin = 20
	Min offset for displaying usage (default: 20) More...

static string::size_type	usageMax = 80
	Max screen width for displaying usage (default: 80) More...

static word	postProcessOptionName
	Standard name for the post-processing option. More...

Detailed Description

Extract command arguments and options from the supplied argc and argv parameters.

Sequences with "(" ... ")" are transformed into a stringList. For example,

    program -listFiles \( *.txt \)

would create a stringList:

    ( "file1.txt" "file2.txt" ... "fileN.txt" )

The backslash-escaping is required to avoid interpretation by the shell.

Default command-line options:

-case <dir>
Select a case directory instead of the current working directory
-parallel
Specify case as a parallel job
-doc
Display the documentation in browser
-srcDoc
Display the source documentation in browser
-help
Print the usage
The environment variable FOAM_CASE is set to the path of the global case (same for serial and parallel jobs). The environment variable FOAM_CASENAME is set to the name of the global case.

Note:

The document browser used is defined by the FOAM_DOC_BROWSER environment variable or the Documentation/docBrowser entry in the ~OpenFOAM/controlDict file. The %f token is used as a placeholder for the file name.
The valid (mandatory) arguments can be adjusted by directly manipulating the argList::validArgs static member.
The valid options can be adjusted via the addOption/removeOption static methods instead of directly manipulating the argList::validOptions static member.

Source files

Definition at line 102 of file argList.H.

Constructor & Destructor Documentation

◆ argList() [1/2]

argList	(	int &	argc,
		char **&	argv,
		bool	checkArgs = `true`,
		bool	checkOpts = `true`,
		bool	initialise = `true`
	)

Construct from argc and argv.

checking the arguments and options as requested

Definition at line 437 of file argList.C.

References fileOperation::defaultFileHandler, Foam::endl(), error::exit(), Foam::FatalError, Foam::getEnv(), Foam::libs, fileName::name(), fileOperationInitialise::New(), dlLibraryTable::open(), argList::parse(), argList::printUsage(), argList::validOptions, and argList::validParOptions.

Referenced by argList::hasArgs().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ argList() [2/2]

argList	(	const argList &	args,
		const HashTable< string > &	options,
		bool	checkArgs = `true`,
		bool	checkOpts = `true`,
		bool	initialise = `true`
	)

Construct copy with new options.

Definition at line 583 of file argList.C.

References argList::parse().

Here is the call graph for this function:

◆ ~argList()

~argList ( )

virtual

Destructor.

Definition at line 1100 of file argList.C.

References Foam::fileHandler(), and Foam::jobInfo_.

Here is the call graph for this function:

Member Function Documentation

◆ parse()

void parse	(	bool	checkArgs,
		bool	checkOpts,
		bool	initialise
	)

Parse.

Definition at line 605 of file argList.C.

References dictionary::add(), dynamicCode::allowSystemOperations, argList::check(), clock::clockTime(), UPstream::commsTypeNames, Foam::cwd(), clock::date(), UPstream::defaultCommsType, fileOperation::defaultFileHandler, argList::displayDoc(), Foam::endl(), argList::executable(), Foam::exit(), error::exit(), Foam::FatalError, FatalErrorIn, FatalErrorInFunction, IOobject::fileCheckTypesNames, Foam::fileHandler(), IOobject::fileModificationChecking, regIOobject::fileModificationSkew, Foam::findStrings(), Tuple2< Type1, Type2 >::first(), UPstream::firstSlave(), UPstream::floatTransfer, Foam::FOAMbuild, Foam::FOAMversion, forAll, found, Foam::getEnv(), IOstream::good(), Foam::hostName(), Foam::Info, Foam::isDir(), Foam::jobInfo_, UPstream::lastSlave(), dictionary::lookup(), dictionary::lookupOrDefault(), UPstream::master(), UPstream::masterNo(), UPstream::myProcNo(), Foam::name(), fileOperation::New(), Foam::nl, UPstream::nPollProcInterfaces, UPstream::nProcs(), UPstream::nProcsSimpleSum, Foam::pgid(), Foam::pid(), Foam::ppid(), argList::printUsage(), Foam::constant::atomic::re, UPstream::scheduled, Tuple2< Type1, Type2 >::second(), List< T >::setSize(), List< T >::size(), IOobject::timeStamp, IOobject::timeStampMaster, Foam::userName(), IOobject::writeBanner(), IOobject::writeDivider(), and Foam::writeInfoHeader.

Referenced by argList::argList().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ commandLine()

const Foam::string & commandLine ( ) const

inline

Return the command line string.

Definition at line 30 of file argListI.H.

Referenced by functionObjectList::New().

Here is the caller graph for this function:

◆ executable()

const Foam::word & executable ( ) const

inline

Name of executable without the path.

Definition at line 36 of file argListI.H.

Referenced by forAll(), if(), argList::parse(), and Time::Time().

Here is the caller graph for this function:

◆ rootPath()

const Foam::fileName & rootPath ( ) const

inline

Return root path.

Definition at line 42 of file argListI.H.

Referenced by argList::checkRootCase(), and argList::path().

Here is the caller graph for this function:

◆ caseName()

const Foam::fileName & caseName ( ) const

inline

Return case name (parallel run) or global case (serial run)

Definition at line 48 of file argListI.H.

Referenced by argList::path().

Here is the caller graph for this function:

◆ globalCaseName()

const Foam::fileName & globalCaseName ( ) const

inline

Return case name.

Definition at line 54 of file argListI.H.

◆ parRunControl()

const Foam::ParRunControl & parRunControl ( ) const

inline

Return parRunControl.

Definition at line 60 of file argListI.H.

◆ path()

Foam::fileName path ( ) const

inline

Return the path to the caseName.

Definition at line 66 of file argListI.H.

References argList::caseName(), and argList::rootPath().

Referenced by argList::checkRootCase(), and Time::Time().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ args() [1/2]

const Foam::stringList & args ( ) const

inline

Return arguments.

Definition at line 72 of file argListI.H.

◆ args() [2/2]

Foam::stringList & args ( )

inline

Return non-const access to arguments.

Definition at line 78 of file argListI.H.

◆ arg()

const Foam::string & arg ( const label index ) const

inline

Return the argument corresponding to index.

Definition at line 84 of file argListI.H.

Referenced by argList::hasArgs().

Here is the caller graph for this function:

◆ size()

Foam::label size ( ) const

inline

Return the number of arguments.

Definition at line 90 of file argListI.H.

References List< T >::size().

Referenced by argList::printUsage().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ argRead()

T argRead ( const label index ) const

inline

Read a value from the argument at index.

Index 0 corresponds to the name of the executable. Index 1 corresponds to the first argument.

Definition at line 183 of file argListI.H.

References Foam::T().

Here is the call graph for this function:

◆ options() [1/2]

const Foam::HashTable< Foam::string > & options ( ) const

inline

Return options.

Definition at line 96 of file argListI.H.

Referenced by Time::Time().

Here is the caller graph for this function:

◆ options() [2/2]

Foam::HashTable< Foam::string > & options ( )

inline

Return non-const access to options.

Definition at line 102 of file argListI.H.

◆ option()

const Foam::string & option ( const word & opt ) const

inline

Return the argument string associated with the named option.

Definition at line 108 of file argListI.H.

◆ optionFound()

bool optionFound ( const word & opt ) const

inline

Return true if the named option is found.

Definition at line 114 of file argListI.H.

Referenced by if(), functionObjectList::New(), argList::optionLookupOrDefault(), argList::optionReadIfPresent(), timeSelector::select(), timeSelector::selectIfPresent(), Foam::selectRegionNames(), and Foam::systemDictIO().

Here is the caller graph for this function:

◆ optionLookup()

Foam::IStringStream optionLookup ( const word & opt ) const

inline

Return an IStringStream from the named option.

Definition at line 120 of file argListI.H.

Referenced by functionObjectList::New(), argList::optionRead(), argList::optionReadList(), and timeSelector::select().

Here is the caller graph for this function:

◆ optionRead()

T optionRead ( const word & opt ) const

inline

Read a value from the named option.

Definition at line 193 of file argListI.H.

References argList::optionLookup(), argList::optionReadIfPresent(), and Foam::T().

Referenced by if().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ optionReadIfPresent() [1/2]

bool optionReadIfPresent	(	const word &	opt,
		T &	val
	)		const

inline

Read a value from the named option if present.

Return true if the named option was found.

Definition at line 204 of file argListI.H.

References argList::optionFound().

Referenced by argList::optionRead(), and Foam::selectRegionNames().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ optionReadIfPresent() [2/2]

bool optionReadIfPresent	(	const word &	opt,
		T &	val,
		const T &	deflt
	)		const

inline

Read a value from the named option if present.

Return true if the named option was found, otherwise use the supplied default and return false.

Definition at line 223 of file argListI.H.

References argList::optionLookupOrDefault(), and Foam::T().

Here is the call graph for this function:

◆ optionLookupOrDefault()

T optionLookupOrDefault	(	const word &	opt,
		const T &	deflt
	)		const

inline

Read a value from the named option if present.

Return supplied default otherwise.

Definition at line 243 of file argListI.H.

References argList::optionFound().

Referenced by argList::optionReadIfPresent().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ optionReadList()

List<T> optionReadList ( const word & opt ) const

inline

Read a List of values from the named option.

Definition at line 316 of file argList.H.

References argList::addBoolOption(), argList::addNote(), argList::addOption(), argList::addUsage(), argList::check(), argList::checkRootCase(), argList::displayDoc(), argList::hasArgs(), argList::noParallel(), argList::operator[](), argList::optionLookup(), argList::postProcess(), argList::printNotes(), argList::printUsage(), argList::removeOption(), argList::setOption(), and argList::unsetOption().

Here is the call graph for this function:

◆ operator[]() [1/2]

const Foam::string & operator[] ( const label index ) const

inline

Return the argument corresponding to index.

Index 0 corresponds to the name of the executable. Index 1 corresponds to the first argument.

Definition at line 261 of file argListI.H.

Referenced by argList::optionReadList().

Here is the caller graph for this function:

◆ operator[]() [2/2]

const Foam::string & operator[] ( const word & opt ) const

inline

Return the argument string associated with the named option.

See also: option()

Definition at line 267 of file argListI.H.

◆ addBoolOption()

addBoolOption	(	const word &	opt,
		const string &	usage = `""`
	)

static

Add to a bool option to validOptions with usage information.

Definition at line 118 of file argList.C.

References argList::addOption().

Referenced by timeSelector::addOptions(), argList::initValidTables::initValidTables(), and argList::optionReadList().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ addOption()

addOption	(	const word &	opt,
		const string &	param = `""`,
		const string &	usage = `""`
	)

static

Add to an option to validOptions with usage information.

An option with an empty param is a bool option

Definition at line 128 of file argList.C.

References argList::addUsage(), argList::optionUsage, and argList::validOptions.

Referenced by argList::addBoolOption(), timeSelector::addOptions(), argList::initValidTables::initValidTables(), and argList::optionReadList().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ addUsage()

void addUsage	(	const word &	opt,
		const string &	usage
	)

static

Add option usage information to optionUsage.

Definition at line 143 of file argList.C.

References argList::optionUsage.

Referenced by argList::addOption(), and argList::optionReadList().

Here is the caller graph for this function:

◆ addNote()

void addNote ( const string & note )

static

Add extra notes for the usage information.

This string is used "as-is" without additional formatting

Definition at line 159 of file argList.C.

References argList::notes.

Referenced by argList::optionReadList().

Here is the caller graph for this function:

◆ removeOption()

void removeOption ( const word & opt )

static

Remove option from validOptions and from optionUsage.

Definition at line 168 of file argList.C.

References argList::optionUsage, and argList::validOptions.

Referenced by argList::initValidTables::clear(), argList::noParallel(), and argList::optionReadList().

Here is the caller graph for this function:

◆ noParallel()

void noParallel ( )

static

Remove the parallel options.

Definition at line 175 of file argList.C.

References Foam::Info, Foam::isspace(), Foam::nl, Foam::pos(), argList::removeOption(), argList::usageMax, argList::usageMin, and argList::validParOptions.

Referenced by argList::optionReadList().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ postProcess()

bool postProcess	(	int	argc,
		char *	argv[]
	)

static

Return true if the post-processing option is specified.

Definition at line 284 of file argList.C.

References argList::postProcessOptionName.

Referenced by argList::optionReadList().

Here is the caller graph for this function:

◆ hasArgs()

bool hasArgs	(	int	argc,
		char *	argv[]
	)

static

Return true if there are arguments.

Definition at line 298 of file argList.C.

References argList::arg(), argList::argList(), fileName::clean(), Foam::cwd(), fileName::isAbsolute(), fileName::name(), fileName::path(), Foam::setEnv(), and argList::validOptions.

Referenced by argList::optionReadList().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setOption()

bool setOption	(	const word &	opt,
		const string &	param = `""`
	)

Set option directly (use with caution)

An option with an empty param is a bool option. Not all valid options can also be set: eg, -case, -roots, ... Return true if the existing option value needed changing, or if the option did not previously exist.

Definition at line 1112 of file argList.C.

References Foam::endl(), error::exit(), Foam::FatalError, Foam::nl, and argList::validOptions.

Referenced by argList::optionReadList().

Here is the call graph for this function: