argList Class Reference

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 stringcommandLine () const
 Return the command line string. More...
 
const wordexecutable () const
 Name of executable without the path. More...
 
const fileNamerootPath () const
 Return root path. More...
 
const fileNamecaseName () const
 Return case name (parallel run) or global case (serial run) More...
 
const fileNameglobalCaseName () const
 Return case name. More...
 
const ParRunControlparRunControl () const
 Return parRunControl. More...
 
fileName path () const
 Return the path to the caseName. More...
 
const stringListargs () const
 Return arguments. More...
 
stringListargs ()
 Return non-const access to arguments. More...
 
const stringarg (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 stringoption (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< ToptionReadList (const word &opt) const
 Read a List of values from the named option. More...
 
const stringoperator[] (const label index) const
 Return the argument corresponding to index. More...
 
const stringoperator[] (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< stringvalidArgs
 A list of valid (mandatory) arguments. More...
 
static HashTable< stringvalidOptions
 A list of valid options. More...
 
static HashTable< stringvalidParOptions
 A list of valid parallel options. More...
 
static HashTable< stringoptionUsage
 Short usage information for validOptions. More...
 
static SLList< stringnotes
 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()

◆ 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:
Here is the caller 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 1188 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:
Here is the caller graph for this function:

◆ printNotes()

void printNotes ( ) const

Print notes (if any)

Definition at line 1224 of file argList.C.

References forAllConstIter, Foam::Info, Foam::nl, and argList::notes.

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

Here is the caller graph for this function:

◆ printUsage()

void printUsage ( ) const

Print usage.

Definition at line 1238 of file argList.C.

References Foam::endl(), Foam::FOAMbuild, Foam::FOAMversion, forAll, forAllConstIter, Foam::Info, Foam::nl, argList::optionUsage, argList::printNotes(), argList::size(), argList::validArgs, and argList::validOptions.

Referenced by argList::argList(), argList::check(), forAll(), argList::optionReadList(), and argList::parse().

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

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

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

Here is the call graph for this function:
Here is the caller graph for this function:

◆ check()

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

Check argument list.

Definition at line 1400 of file argList.C.

References Foam::endl(), Foam::FatalError, forAllConstIter, UPstream::master(), argList::printUsage(), argList::validArgs, argList::validOptions, and argList::validParOptions.

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

Here is the call graph for this function:
Here is the caller graph for this function:

◆ checkRootCase()

bool checkRootCase ( ) const

Check root path and case path.

Definition at line 1441 of file argList.C.

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

Referenced by argList::optionReadList().

Here is the call graph for this function:
Here is the caller graph for this function:

Member Data Documentation

◆ validArgs

Foam::SLList< Foam::string > validArgs
static

A list of valid (mandatory) arguments.

Definition at line 153 of file argList.H.

Referenced by argList::check(), and argList::printUsage().

◆ validOptions

◆ validParOptions

Foam::HashTable< Foam::string > validParOptions
static

A list of valid parallel options.

Definition at line 159 of file argList.H.

Referenced by argList::argList(), argList::check(), argList::initValidTables::initValidTables(), and argList::noParallel().

◆ optionUsage

Foam::HashTable< Foam::string > optionUsage
static

Short usage information for validOptions.

Definition at line 162 of file argList.H.

Referenced by argList::addOption(), argList::addUsage(), argList::printUsage(), and argList::removeOption().

◆ notes

Foam::SLList< Foam::string > notes
static

Additional notes for usage.

Definition at line 165 of file argList.H.

Referenced by argList::addNote(), and argList::printNotes().

◆ usageMin

Foam::string::size_type usageMin = 20
static

Min offset for displaying usage (default: 20)

Definition at line 168 of file argList.H.

Referenced by argList::noParallel().

◆ usageMax

Foam::string::size_type usageMax = 80
static

Max screen width for displaying usage (default: 80)

Definition at line 171 of file argList.H.

Referenced by argList::noParallel().

◆ postProcessOptionName

Foam::word postProcessOptionName
static

Standard name for the post-processing option.

Definition at line 174 of file argList.H.

Referenced by argList::postProcess().


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