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

Collaboration diagram for argList:

[legend]

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

stringList::subList	additionalArgs () const
	Return arguments that are additional to the executable. 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	noBanner ()
	Disable emitting the banner information. More...

static void	noParallel ()
	Remove the parallel options. 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...

Private Member Functions
void	getRootCase ()
	Get rootPath_ / globalCase_ from one of the following forms. More...

bool	regroupArgv (int &argc, char **&argv)
	Transcribe argv into internal args_. More...

Static Private Member Functions
static void	printOptionUsage (const label location, const string &str)
	Helper function for printUsage. More...

Private Attributes
ParRunControl	parRunControl_
	Switch on/off parallel mode. Has to be first to be constructed. More...

stringList	args_

HashTable< string >	options_

word	executable_

fileName	rootPath_

fileName	globalCase_

fileName	case_

string	argListStr_

Static Private Attributes
static bool	bannerEnabled = true

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

Parameters

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

References Foam::endl(), error::exit(), Foam::FatalError, and fileName::name().

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

◆ ~argList()

~argList ( )

virtual

Destructor.

Definition at line 913 of file argList.C.

References JobInfo::end(), and Foam::jobInfo.

Here is the call graph for this function:

Member Function Documentation

◆ printOptionUsage()

void printOptionUsage	(	const label	location,
		const string &	str
	)

staticprivate

Helper function for printUsage.

Definition at line 171 of file argList.C.

References Foam::Info, Foam::isspace(), Foam::nl, and Foam::pos().

Here is the call graph for this function:

◆ getRootCase()

void getRootCase ( )

private

Get rootPath_ / globalCase_ from one of the following forms.

* [-case dir] cwd

Also export FOAM_CASE and FOAM_CASENAME environment variables so they can be used immediately (eg, in decomposeParDict)

Definition at line 330 of file argList.C.

References fileName::clean(), Foam::cwd(), fileName::isAbsolute(), fileName::name(), fileName::path(), Foam::setEnv(), and Foam::toUnixPath().

Here is the call graph for this function:

◆ regroupArgv()

bool regroupArgv	(	int &	argc,
		char **&	argv
	)

private

Transcribe argv into internal args_.

return true if any "(" ... ")" sequences were captured

Definition at line 274 of file argList.C.

◆ parse()

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

Parse.

Definition at line 506 of file argList.C.

References dictionary::add(), dynamicCode::allowSystemOperations, clock::clockTime(), UPstream::commsTypeNames, Foam::cwd(), clock::date(), UPstream::defaultCommsType, Foam::endl(), Foam::exit(), error::exit(), Foam::FatalError, regIOobject::fileCheckTypesNames, regIOobject::fileModificationChecking, UPstream::firstSlave(), UPstream::floatTransfer, Foam::FOAMbuild, Foam::FOAMversion, forAll, found, IOstream::good(), Foam::hostName(), Foam::Info, Foam::isDir(), Foam::jobInfo, UPstream::lastSlave(), dictionary::lookup(), dictionary::lookupOrDefault(), UPstream::master(), UPstream::masterNo(), UPstream::myProcNo(), IFstream::name(), Foam::name(), Foam::nl, UPstream::nPollProcInterfaces, UPstream::nProcs(), UPstream::nProcsSimpleSum, Foam::pgid(), Foam::pid(), Foam::ppid(), Foam::readLabel(), UPstream::scheduled, sigQuit::set(), sigSegv::set(), sigInt::set(), sigFpe::set(), List::setSize(), List::size(), Foam::userName(), JobInfo::write(), IOobject::writeBanner(), and IOobject::writeDivider().

Here is the call graph for this function:

◆ executable()

const Foam::word & executable ( ) const

inline

Name of executable without the path.

Definition at line 30 of file argListI.H.

References argList::executable_.

Referenced by if(), and main().

Here is the caller graph for this function:

◆ rootPath()

const Foam::fileName & rootPath ( ) const

inline

Return root path.

Definition at line 36 of file argListI.H.

Referenced by main().

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

Referenced by main().

Here is the caller graph for this function:

◆ globalCaseName()

const Foam::fileName & globalCaseName ( ) const

inline

Return case name.

Definition at line 48 of file argListI.H.

Referenced by main().

Here is the caller graph for this function:

◆ parRunControl()

const Foam::ParRunControl & parRunControl ( ) const

inline

Return parRunControl.

Definition at line 54 of file argListI.H.

◆ path()

Foam::fileName path ( ) const

inline

Return the path to the caseName.

Definition at line 60 of file argListI.H.

Referenced by main().

Here is the caller graph for this function:

◆ args() [1/2]

Foam::stringList & args ( ) const

inline

Return arguments.

Definition at line 66 of file argListI.H.

Referenced by main().

Here is the caller graph for this function:

◆ args() [2/2]

stringList& args ( )

inline

Return non-const access to arguments.

◆ arg()

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

inline

Return the argument corresponding to index.

Definition at line 78 of file argListI.H.

◆ size()

Foam::label size ( ) const

inline

Return the number of arguments.

Definition at line 84 of file argListI.H.

Referenced by main(), and zoltanRenumber::renumber().

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

References Foam::T().

Referenced by randomise::calc(), and main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ additionalArgs()

stringList::subList additionalArgs ( ) const

inline

Return arguments that are additional to the executable.

Deprecated:: use operator[] directly (deprecated Feb 2010)

Definition at line 252 of file argList.H.

◆ options() [1/2]

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

inline

Return options.

Definition at line 90 of file argListI.H.

Referenced by main().

Here is the caller graph for this function:

◆ options() [2/2]

Foam::HashTable<string>& options ( )

inline

Return non-const access to options.

◆ option()

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

inline

Return the argument string associated with the named option.

Definition at line 102 of file argListI.H.

◆ optionFound()

bool optionFound ( const word & opt ) const

inline

Return true if the named option is found.

Definition at line 108 of file argListI.H.

Referenced by main(), timeSelector::select(), and timeSelector::selectIfPresent().

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

Referenced by main(), 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 187 of file argListI.H.

References Foam::T().

Referenced by if(), and main().

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

Referenced by getMergeDistance(), main(), and addSubtract::preCalc().

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 217 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 237 of file argListI.H.

Referenced by main().

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 304 of file argList.H.

References argList::optionLookup().

Referenced by main().

Here is the call graph for this function:

Here is the caller 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 255 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 261 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 98 of file argList.C.

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

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

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

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

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

References argList::notes.

Referenced by main().

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

Referenced by main().

Here is the caller graph for this function:

◆ noBanner()

void noBanner ( )

static

Disable emitting the banner information.

Definition at line 155 of file argList.C.

Referenced by main().

Here is the caller graph for this function:

◆ noParallel()

void noParallel ( )

static

Remove the parallel options.

Definition at line 161 of file argList.C.

Referenced by main().

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

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

Here is the call graph for this function:

◆ unsetOption()

bool unsetOption ( const word & opt )

Unset option directly (use with caution)

Not all valid options can also be unset: eg, -case, -roots ... Return true if the option existed before being unset.

Definition at line 996 of file argList.C.

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

Here is the call graph for this function:

◆ printNotes()

void printNotes ( ) const

Print notes (if any)

Definition at line 1031 of file argList.C.

References forAllConstIter(), Foam::Info, and Foam::nl.

Here is the call graph for this function:

◆ printUsage()

void printUsage ( ) const

Print usage.

Definition at line 1045 of file argList.C.

References Foam::endl(), Foam::FOAMbuild, Foam::FOAMversion, forAll, forAllConstIter(), Foam::Info, and Foam::nl.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ displayDoc()

void displayDoc ( bool source = false ) const

Display documentation in browser.

Optionally display the application source code

Definition at line 1124 of file argList.C.

References Foam::debug::controlDict(), Foam::endl(), string::expand(), forAll, found, Foam::getEnv(), Foam::Info, Foam::isFile(), dictionary::lookup(), Foam::nl, string::replaceAll(), dictionary::subDict(), and Foam::system().

Here is the call graph for this function:

◆ check()

bool check	(	bool	checkArgs = `true`,
		bool	checkOpts = `true`
	)		const

Check argument list.

Definition at line 1184 of file argList.C.

References Foam::endl(), Foam::FatalError, forAllConstIter(), and UPstream::master().

Here is the call graph for this function:

◆ checkRootCase()

bool checkRootCase ( ) const

Check root path and case path.

Definition at line 1225 of file argList.C.

References Foam::endl(), Foam::FatalError, Foam::isDir(), UPstream::master(), and path().

Here is the call graph for this function:

Field Documentation

◆ bannerEnabled

bool bannerEnabled = true

staticprivate

Definition at line 100 of file argList.H.

◆ parRunControl_

ParRunControl parRunControl_

private

Switch on/off parallel mode. Has to be first to be constructed.

so destructor is done last.

Definition at line 104 of file argList.H.

◆ args_

stringList args_

private

Definition at line 106 of file argList.H.

◆ options_

HashTable<string> options_

private

Definition at line 107 of file argList.H.

◆ executable_

word executable_

private

Definition at line 109 of file argList.H.

Referenced by argList::executable().

◆ rootPath_

fileName rootPath_

private

Definition at line 110 of file argList.H.

◆ globalCase_

fileName globalCase_

private

Definition at line 111 of file argList.H.

◆ case_

fileName case_

private

Definition at line 112 of file argList.H.

◆ argListStr_

string argListStr_

private

Definition at line 113 of file argList.H.

◆ validArgs

Foam::SLList< Foam::string > validArgs

static

A list of valid (mandatory) arguments.

Definition at line 143 of file argList.H.

Referenced by interpolate::init(), magSqr::init(), mag::init(), randomise::init(), components::init(), div::init(), magGrad::init(), addSubtract::init(), and main().

◆ validOptions

Foam::HashTable< Foam::string > validOptions

static

A list of valid options.

Definition at line 146 of file argList.H.

Referenced by addSubtract::init(), main(), and timeSelector::select().

◆ validParOptions

Foam::HashTable< Foam::string > validParOptions

static

A list of valid parallel options.

Definition at line 149 of file argList.H.

◆ optionUsage

Foam::HashTable< Foam::string > optionUsage

static

Short usage information for validOptions.

Definition at line 152 of file argList.H.

◆ notes

Foam::SLList< Foam::string > notes

static

Additional notes for usage.

Definition at line 155 of file argList.H.

Referenced by argList::addNote().

◆ usageMin

Foam::string::size_type usageMin = 20

static

Min offset for displaying usage (default: 20)

Definition at line 158 of file argList.H.

◆ usageMax

Foam::string::size_type usageMax = 80

static

Max screen width for displaying usage (default: 80)

Definition at line 161 of file argList.H.

The documentation for this class was generated from the following files:

src/OpenFOAM/global/argList/argList.H
src/OpenFOAM/global/argList/argList.C
src/OpenFOAM/global/argList/argListI.H
src/OpenFOAM/include/addDictOption.H
src/OpenFOAM/include/addOverwriteOption.H
src/OpenFOAM/include/addRegionOption.H
src/OpenFOAM/include/addTimeOptions.H
applications/utilities/preProcessing/createExternalCoupledPatchGeometry/addRegionsOption.H

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ argList() [1/2]

◆ argList() [2/2]

◆ ~argList()

Member Function Documentation

◆ printOptionUsage()

◆ getRootCase()

◆ regroupArgv()

◆ parse()

◆ executable()

◆ rootPath()

◆ caseName()

◆ globalCaseName()

◆ parRunControl()

◆ path()

◆ args() [1/2]

◆ args() [2/2]

◆ arg()

◆ size()

◆ argRead()

◆ additionalArgs()

◆ options() [1/2]

◆ options() [2/2]

◆ option()

◆ optionFound()

◆ optionLookup()

◆ optionRead()

◆ optionReadIfPresent() [1/2]

◆ optionReadIfPresent() [2/2]

◆ optionLookupOrDefault()

◆ optionReadList()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ addBoolOption()

◆ addOption()

◆ addUsage()

◆ addNote()

◆ removeOption()

◆ noBanner()

◆ noParallel()

◆ setOption()

◆ unsetOption()

◆ printNotes()

◆ printUsage()

◆ displayDoc()

◆ check()

◆ checkRootCase()

Field Documentation

◆ bannerEnabled

◆ parRunControl_

◆ args_

◆ options_

◆ executable_

◆ rootPath_

◆ globalCase_

◆ case_

◆ argListStr_

◆ validArgs

◆ validOptions

◆ validParOptions

◆ optionUsage

◆ notes

◆ usageMin

◆ usageMax