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

Collaboration diagram for argList:

[legend]

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 436 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(), ParRunControl::runPar(), List< T >::setSize(), List< T >::size(), argList::validOptions, and argList::validParOptions.

Here is the call 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 582 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 604 of file argList.C.

References dictionary::add(), dynamicCode::allowSystemOperations, clock::clockTime(), UPstream::commsTypeNames, Foam::cwd(), clock::date(), UPstream::defaultCommsType, fileOperation::defaultFileHandler, Foam::endl(), error::exit(), Foam::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(), 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(), main(), 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.

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

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

Referenced by Time::Time().

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.

Referenced by Foam::readConfigFile().

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(), main(), functionObjectList::New(), timeSelector::select(), timeSelector::selectIfPresent(), 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::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 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 203 of file argListI.H.

◆ 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 222 of file argListI.H.

◆ 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 242 of file argListI.H.

◆ 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::optionLookup().

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.

◆ 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 117 of file argList.C.

References argList::addOption().

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

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 127 of file argList.C.

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

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

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 142 of file argList.C.

References argList::optionUsage.

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

◆ removeOption()

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(), and argList::noParallel().

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 argList::removeOption(), and argList::validParOptions.

Here is the call 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.

◆ 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(), and argList::validOptions.

Here is the call 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, and Foam::nl.

Here is the call graph for this function: