Public Member Functions | Static Public Member Functions | Static Public Attributes | List of all members
argList Class Reference

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

Collaboration diagram for argList:
Collaboration graph
[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 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...
 
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 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 noBanner ()
 Disable emitting the banner information. More...
 
static void noParallel ()
 Remove the parallel options. 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...
 

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

Constructor & Destructor Documentation

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

References Foam::endl(), error::exit(), Foam::FatalError, fileName::name(), argList::parse(), argList::printUsage(), ParRunControl::runPar(), List< T >::setSize(), List< T >::size(), argList::validOptions, and argList::validParOptions.

Referenced by argList::noParallel().

Here is the call graph for this function:

Here is the caller graph for this function:

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

References argList::parse().

Here is the call graph for this function:

~argList ( )
virtual

Destructor.

Definition at line 875 of file argList.C.

References Foam::jobInfo.

Member Function Documentation

void parse ( bool  checkArgs,
bool  checkOpts,
bool  initialise 
)
const Foam::word & executable ( ) const
inline

Name of executable without the path.

Definition at line 30 of file argListI.H.

Referenced by forAll(), if(), and timeSelector::select0().

Here is the caller graph for this function:

const Foam::fileName & rootPath ( ) const
inline

Return root path.

Definition at line 36 of file argListI.H.

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

Here is the caller graph for this function:

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 argList::path().

Here is the caller graph for this function:

const Foam::fileName & globalCaseName ( ) const
inline

Return case name.

Definition at line 48 of file argListI.H.

const Foam::ParRunControl & parRunControl ( ) const
inline

Return parRunControl.

Definition at line 54 of file argListI.H.

Foam::fileName path ( ) const
inline

Return the path to the caseName.

Definition at line 60 of file argListI.H.

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

Referenced by argList::checkRootCase().

Here is the call graph for this function:

Here is the caller graph for this function:

const Foam::stringList & args ( ) const
inline

Return arguments.

Definition at line 66 of file argListI.H.

Foam::stringList & args ( )
inline

Return non-const access to arguments.

Definition at line 72 of file argListI.H.

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

Return the argument corresponding to index.

Definition at line 78 of file argListI.H.

Foam::label size ( ) const
inline

Return the number of arguments.

Definition at line 84 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:

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

Here is the call graph for this function:

Here is the caller graph for this function:

stringList::subList additionalArgs ( ) const
inline

Return arguments that are additional to the executable.

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

Definition at line 263 of file argList.H.

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

Return options.

Definition at line 90 of file argListI.H.

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

Return non-const access to options.

Definition at line 96 of file argListI.H.

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.

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 argList::optionLookupOrDefault(), argList::optionReadIfPresent(), timeSelector::select(), and timeSelector::selectIfPresent().

Here is the caller graph for this function:

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 argList::optionRead(), argList::optionReadList(), and timeSelector::select().

Here is the caller graph for this function:

T optionRead ( const word opt) const
inline

Read a value from the named option.

Definition at line 187 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:

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.

References argList::optionFound().

Referenced by argList::optionRead(), and addSubtract::preCalc().

Here is the call graph for this function:

Here is the caller graph for this function:

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.

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

Here is the call graph for this function:

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.

References argList::optionFound().

Referenced by argList::optionReadIfPresent().

Here is the call graph for this function:

Here is the caller graph for this function:

List<T> optionReadList ( const word opt) const
inline
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.

Referenced by argList::optionReadList().

Here is the caller graph for this function:

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 ( const word opt,
const string usage = "" 
)
static

Add to a bool option to validOptions with usage information.

Definition at line 83 of file argList.C.

References argList::addOption().

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

Here is the call graph for this function:

Here is the caller graph for this function:

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

References argList::addUsage().

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

Here is the call graph for this function:

Here is the caller graph for this function:

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

Add option usage information to optionUsage.

Definition at line 108 of file argList.C.

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

Here is the caller graph for this function:

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

References argList::notes.

Referenced by argList::optionReadList().

Here is the caller graph for this function:

void removeOption ( const word opt)
static

Remove option from validOptions and from optionUsage.

Definition at line 133 of file argList.C.

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

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

Here is the caller graph for this function:

void noBanner ( )
static

Disable emitting the banner information.

Definition at line 140 of file argList.C.

Referenced by argList::optionReadList().

Here is the caller graph for this function:

void noParallel ( )
static

Remove the parallel options.

Definition at line 146 of file argList.C.

References argList::argList(), fileName::clean(), Foam::cwd(), Foam::Info, fileName::isAbsolute(), Foam::isspace(), fileName::name(), Foam::nl, fileName::path(), Foam::pos(), argList::removeOption(), Foam::setEnv(), List< T >::setSize(), 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:

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 883 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:

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 958 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:

void printNotes ( ) const

Print notes (if any)

Definition at line 993 of file argList.C.

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

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

Here is the call graph for this function:

Here is the caller graph for this function:

void printUsage ( ) const

Print usage.

Definition at line 1007 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(), argList::optionReadList(), and argList::parse().

Here is the call graph for this function:

Here is the caller graph for this function:

void displayDoc ( bool  source = false) const

Display documentation in browser.

Optionally display the application source code

Definition at line 1086 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().

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

Here is the call graph for this function:

Here is the caller graph for this function:

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

Check argument list.

Definition at line 1146 of file argList.C.

References Foam::endl(), Foam::FatalError, forAllConstIter(), UPstream::master(), argList::printUsage(), List< T >::size(), 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:

bool checkRootCase ( ) const

Check root path and case path.

Definition at line 1187 of file argList.C.

References Foam::endl(), Foam::FatalError, 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

Foam::SLList< Foam::string > validArgs
static
Foam::HashTable< Foam::string > validOptions
static
Foam::HashTable< Foam::string > validParOptions
static

A list of valid parallel options.

Definition at line 160 of file argList.H.

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

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

Short usage information for validOptions.

Definition at line 163 of file argList.H.

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

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

Additional notes for usage.

Definition at line 166 of file argList.H.

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

Foam::string::size_type usageMin = 20
static

Min offset for displaying usage (default: 20)

Definition at line 169 of file argList.H.

Referenced by argList::noParallel().

Foam::string::size_type usageMax = 80
static

Max screen width for displaying usage (default: 80)

Definition at line 172 of file argList.H.

Referenced by argList::noParallel().


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