argList.H
Go to the documentation of this file.
1 /*---------------------------------------------------------------------------*\
2  ========= |
3  \\ / F ield | OpenFOAM: The Open Source CFD Toolbox
4  \\ / O peration | Website: https://openfoam.org
5  \\ / A nd | Copyright (C) 2011-2021 OpenFOAM Foundation
6  \\/ M anipulation |
7 -------------------------------------------------------------------------------
8 License
9  This file is part of OpenFOAM.
10 
11  OpenFOAM is free software: you can redistribute it and/or modify it
12  under the terms of the GNU General Public License as published by
13  the Free Software Foundation, either version 3 of the License, or
14  (at your option) any later version.
15 
16  OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
17  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
18  FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
19  for more details.
20 
21  You should have received a copy of the GNU General Public License
22  along with OpenFOAM. If not, see <http://www.gnu.org/licenses/>.
23 
24 Class
25  Foam::argList
26 
27 Description
28  Extract command arguments and options from the supplied
29  \a argc and \a argv parameters.
30 
31  Sequences with "(" ... ")" are transformed into a stringList.
32  For example,
33  \verbatim
34  program -listFiles \( *.txt \)
35  \endverbatim
36  would create a stringList:
37  \verbatim
38  ( "file1.txt" "file2.txt" ... "fileN.txt" )
39  \endverbatim
40  The backslash-escaping is required to avoid interpretation by the shell.
41 
42  Default command-line options:
43  - \par -case <dir>
44  Select a case directory instead of the current working directory
45  - \par -parallel
46  Specify case as a parallel job
47  - \par -doc
48  Display the documentation in browser
49  - \par -srcDoc
50  Display the source documentation in browser
51  - \par -help
52  Print the usage
53 
54  The environment variable \b FOAM_CASE is set to the path of the
55  global case (same for serial and parallel jobs).
56  The environment variable \b FOAM_CASENAME is set to the name of the
57  global case.
58 
59 Note
60  - The document browser used is defined by the \b FOAM_DOC_BROWSER
61  environment variable or the <tt>Documentation/docBrowser</tt> entry
62  in the <tt>~OpenFOAM/controlDict</tt> file.
63  The \%f token is used as a placeholder for the file name.
64  - The valid (mandatory) arguments can be adjusted
65  by directly manipulating the argList::validArgs static member.
66  - The valid options can be adjusted
67  via the addOption/removeOption static methods instead of directly
68  manipulating the argList::validOptions static member.
69 
70 SourceFiles
71  argList.C
72  argListI.H
73 
74 \*---------------------------------------------------------------------------*/
75 
76 #ifndef argList_H
77 #define argList_H
78 
79 #include "stringList.H"
80 #include "SubList.H"
81 #include "SLList.H"
82 #include "HashTable.H"
83 #include "word.H"
84 #include "fileName.H"
85 #include "parRun.H"
86 #include "IStringStream.H"
87 #include "OSspecific.H"
88 
89 #include "sigFpe.H"
90 #include "sigInt.H"
91 #include "sigQuit.H"
92 #include "sigSegv.H"
93 
94 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
95 
96 namespace Foam
97 {
98 
99 /*---------------------------------------------------------------------------*\
100  Class argList Declaration
101 \*---------------------------------------------------------------------------*/
103 class argList
104 {
105  // Private Data
106 
107  //- Switch on/off parallel mode. Has to be first to be constructed
108  // so destructor is done last.
109  ParRunControl parRunControl_;
110 
111  stringList args_;
112  HashTable<string> options_;
113 
114  word executable_;
115  fileName rootPath_;
116  fileName globalCase_;
117  fileName case_;
118  string argListStr_;
119 
120  // Signal handlers
121  sigFpe sigFpe_;
122  sigInt sigInt_;
123  sigQuit sigQuit_;
124  sigSegv sigSegv_;
125 
126 
127  // Private Member Functions
128 
129  //- Helper function for printUsage
130  static void printOptionUsage
131  (
132  const label location,
133  const string& str
134  );
135 
136  //- Get rootPath_ / globalCase_ from one of the following forms
137  // * [-case dir]
138  // * cwd
139  //
140  // Also export FOAM_CASE and FOAM_CASENAME environment variables
141  // so they can be used immediately (eg, in decomposeParDict)
142  void getRootCase();
143 
144  //- Transcribe argv into internal args_
145  // return true if any "(" ... ")" sequences were captured
146  bool regroupArgv(int& argc, char**& argv);
147 
148 
149 public:
150 
151  // Static Data Members
152 
153  //- A list of valid (mandatory) arguments
154  static SLList<string> validArgs;
155 
156  //- A list of valid options
158 
159  //- A list of valid parallel options
161 
162  //- Short usage information for validOptions
164 
165  //- Additional notes for usage
166  static SLList<string> notes;
167 
168  //- Min offset for displaying usage (default: 20)
170 
171  //- Max screen width for displaying usage (default: 80)
173 
174  //- Standard name for the post-processing option
176 
177  // Class to initialise options table
178  // with the standard case related options
179  class initValidTables
180  {
181  public:
182 
183  initValidTables();
184 
185  //- Clear the options table
186  // for utilities which do not operate on files rather than cases
187  static void clear();
188  };
189 
190 
191  // Constructors
192 
193  //- Construct from argc and argv
194  // checking the arguments and options as requested
195  argList
196  (
197  int& argc,
198  char**& argv,
199  bool checkArgs = true,
200  bool checkOpts = true,
201  bool initialise = true
202  );
203 
204  //- Construct copy with new options
205  argList
206  (
207  const argList& args,
208  const HashTable<string>& options,
209  bool checkArgs = true,
210  bool checkOpts = true,
211  bool initialise = true
212  );
213 
214 
215  //- Destructor
216  virtual ~argList();
217 
218 
219  // Member Functions
220 
221  //- Parse
222  void parse
223  (
224  bool checkArgs,
225  bool checkOpts,
226  bool initialise
227  );
228 
229 
230  // Access
231 
232  //- Return the command line string
233  inline const string& commandLine() const;
234 
235  //- Name of executable without the path
236  inline const word& executable() const;
237 
238  //- Return root path
239  inline const fileName& rootPath() const;
240 
241  //- Return case name (parallel run) or global case (serial run)
242  inline const fileName& caseName() const;
243 
244  //- Return case name
245  inline const fileName& globalCaseName() const;
246 
247  //- Return parRunControl
248  inline const ParRunControl& parRunControl() const;
249 
250  //- Return the path to the caseName
251  inline fileName path() const;
252 
253  //- Return arguments
254  inline const stringList& args() const;
255 
256  //- Return non-const access to arguments
257  inline stringList& args();
258 
259  //- Return the argument corresponding to index.
260  inline const string& arg(const label index) const;
261 
262  //- Return the number of arguments
263  inline label size() const;
264 
265  //- Read a value from the argument at index.
266  // Index 0 corresponds to the name of the executable.
267  // Index 1 corresponds to the first argument.
268  template<class T>
269  inline T argRead(const label index) const;
270 
271  //- Return options
272  inline const Foam::HashTable<string>& options() const;
273 
274  //- Return non-const access to options
276 
277  //- Return the argument string associated with the named option
278  inline const string& option(const word& opt) const;
279 
280  //- Return true if the named option is found
281  inline bool optionFound(const word& opt) const;
282 
283  //- Return an IStringStream from the named option
284  inline IStringStream optionLookup(const word& opt) const;
285 
286  //- Read a value from the named option
287  template<class T>
288  inline T optionRead(const word& opt) const;
289 
290  //- Read a value from the named option if present.
291  // Return true if the named option was found.
292  template<class T>
293  inline bool optionReadIfPresent(const word& opt, T&) const;
294 
295  //- Read a value from the named option if present.
296  // Return true if the named option was found, otherwise
297  // use the supplied default and return false.
298  template<class T>
299  inline bool optionReadIfPresent
300  (
301  const word& opt,
302  T&,
303  const T& deflt
304  ) const;
305 
306  //- Read a value from the named option if present.
307  // Return supplied default otherwise.
308  template<class T>
309  inline T optionLookupOrDefault
310  (
311  const word& opt,
312  const T& deflt
313  ) const;
314 
315  //- Read a List of values from the named option
316  template<class T>
317  List<T> optionReadList(const word& opt) const
318  {
319  return readList<T>(optionLookup(opt)());
320  }
321 
322 
323  //- Return the argument corresponding to index.
324  // Index 0 corresponds to the name of the executable.
325  // Index 1 corresponds to the first argument.
326  inline const string& operator[](const label index) const;
327 
328  //- Return the argument string associated with the named option
329  // \sa option()
330  inline const string& operator[](const word& opt) const;
331 
332 
333  // Edit
334 
335  //- Add to a bool option to validOptions with usage information
336  static void addBoolOption
337  (
338  const word& opt,
339  const string& usage = ""
340  );
341 
342  //- Add to an option to validOptions with usage information
343  // An option with an empty param is a bool option
344  static void addOption
345  (
346  const word& opt,
347  const string& param = "",
348  const string& usage = ""
349  );
350 
351  //- Add option usage information to optionUsage
352  static void addUsage
353  (
354  const word& opt,
355  const string& usage
356  );
357 
358  //- Add extra notes for the usage information
359  // This string is used "as-is" without additional formatting
360  static void addNote(const string&);
361 
362  //- Remove option from validOptions and from optionUsage
363  static void removeOption(const word& opt);
364 
365  //- Remove the parallel options
366  static void noParallel();
367 
368  //- Return true if the post-processing option is specified
369  static bool postProcess(int argc, char *argv[]);
370 
371  //- Set option directly (use with caution)
372  // An option with an empty param is a bool option.
373  // Not all valid options can also be set: eg, -case, -roots, ...
374  // Return true if the existing option value needed changing,
375  // or if the option did not previously exist.
376  bool setOption(const word& opt, const string& param = "");
377 
378  //- Unset option directly (use with caution)
379  // Not all valid options can also be unset: eg, -case, -roots ...
380  // Return true if the option existed before being unset.
381  bool unsetOption(const word& opt);
382 
383 
384  // Print
385 
386  //- Print notes (if any)
387  void printNotes() const;
388 
389  //- Print usage
390  void printUsage() const;
391 
392  //- Display documentation in browser
393  // Optionally display the application source code
394  void displayDoc(bool source=false) const;
395 
396 
397  // Check
398 
399  //- Check argument list
400  bool check(bool checkArgs=true, bool checkOpts=true) const;
401 
402  //- Check root path and case path
403  bool checkRootCase() const;
404 };
405 
406 
407 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
408 
409 } // End namespace Foam
410 
411 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
412 
413 #include "argListI.H"
414 
415 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
416 
417 #endif
418 
419 // ************************************************************************* //
bool checkRootCase() const
Check root path and case path.
Definition: argList.C:1412
const word & executable() const
Name of executable without the path.
Definition: argListI.H:36
bool setOption(const word &opt, const string &param="")
Set option directly (use with caution)
Definition: argList.C:1091
static void removeOption(const word &opt)
Remove option from validOptions and from optionUsage.
Definition: argList.C:168
intWM_LABEL_SIZE_t label
A label is an int32_t or int64_t as specified by the pre-processor macro WM_LABEL_SIZE.
Definition: label.H:59
A class for handling file names.
Definition: fileName.H:79
Helper class for initialising parallel jobs from the command arguments.
Definition: parRun.H:46
static word postProcessOptionName
Standard name for the post-processing option.
Definition: argList.H:174
bool unsetOption(const word &opt)
Unset option directly (use with caution)
Definition: argList.C:1167
const fileName & globalCaseName() const
Return case name.
Definition: argListI.H:54
static void addUsage(const word &opt, const string &usage)
Add option usage information to optionUsage.
Definition: argList.C:143
const string & operator[](const label index) const
Return the argument corresponding to index.
Definition: argListI.H:261
argList(int &argc, char **&argv, bool checkArgs=true, bool checkOpts=true, bool initialise=true)
Construct from argc and argv.
Definition: argList.C:416
const fileName & rootPath() const
Return root path.
Definition: argListI.H:42
Template class for non-intrusive linked lists.
Definition: LList.H:51
static SLList< string > notes
Additional notes for usage.
Definition: argList.H:165
bool optionFound(const word &opt) const
Return true if the named option is found.
Definition: argListI.H:114
static void noParallel()
Remove the parallel options.
Definition: argList.C:175
static SLList< string > validArgs
A list of valid (mandatory) arguments.
Definition: argList.H:153
static bool postProcess(int argc, char *argv[])
Return true if the post-processing option is specified.
Definition: argList.C:284
virtual ~argList()
Destructor.
Definition: argList.C:1079
bool optionReadIfPresent(const word &opt, T &) const
Read a value from the named option if present.
Definition: argListI.H:204
const ParRunControl & parRunControl() const
Return parRunControl.
Definition: argListI.H:60
void parse(bool checkArgs, bool checkOpts, bool initialise)
Parse.
Definition: argList.C:584
T optionLookupOrDefault(const word &opt, const T &deflt) const
Read a value from the named option if present.
Definition: argListI.H:243
Functions used by OpenFOAM that are specific to POSIX compliant operating systems and need to be repl...
Signal handler for QUIT interrupt.
Definition: sigQuit.H:54
void displayDoc(bool source=false) const
Display documentation in browser.
Definition: argList.C:1294
const Foam::HashTable< string > & options() const
Return options.
Definition: argListI.H:96
T optionRead(const word &opt) const
Read a value from the named option.
Definition: argListI.H:193
static HashTable< string > validParOptions
A list of valid parallel options.
Definition: argList.H:159
void printNotes() const
Print notes (if any)
Definition: argList.C:1203
Set up trapping for floating point exceptions (signal FPE).
Definition: sigFpe.H:67
A class for handling words, derived from string.
Definition: word.H:59
Extract command arguments and options from the supplied argc and argv parameters. ...
Definition: argList.H:102
static void addOption(const word &opt, const string &param="", const string &usage="")
Add to an option to validOptions with usage information.
Definition: argList.C:128
label size() const
Return the number of arguments.
Definition: argListI.H:90
static HashTable< string > optionUsage
Short usage information for validOptions.
Definition: argList.H:162
An STL-conforming hash table.
Definition: HashTable.H:61
graph_traits< Graph >::vertices_size_type size_type
Definition: SloanRenumber.C:73
const fileName & caseName() const
Return case name (parallel run) or global case (serial run)
Definition: argListI.H:48
Signal handler for INT interrupt.
Definition: sigInt.H:54
const string & arg(const label index) const
Return the argument corresponding to index.
Definition: argListI.H:84
void T(FieldField< Field, Type > &f1, const FieldField< Field, Type > &f2)
fileName path() const
Return the path to the caseName.
Definition: argListI.H:66
fvModels source(alpha1, mixture.thermo1().rho())
Input from memory buffer stream.
Definition: IStringStream.H:49
T argRead(const label index) const
Read a value from the argument at index.
Definition: argListI.H:183
List< T > optionReadList(const word &opt) const
Read a List of values from the named option.
Definition: argList.H:316
static void clear()
Clear the options table.
Definition: argList.C:100
bool check(bool checkArgs=true, bool checkOpts=true) const
Check argument list.
Definition: argList.C:1371
static void addBoolOption(const word &opt, const string &usage="")
Add to a bool option to validOptions with usage information.
Definition: argList.C:118
static void addNote(const string &)
Add extra notes for the usage information.
Definition: argList.C:159
static string::size_type usageMin
Min offset for displaying usage (default: 20)
Definition: argList.H:168
const string & commandLine() const
Return the command line string.
Definition: argListI.H:30
Non-intrusive singly-linked list.
void printUsage() const
Print usage.
Definition: argList.C:1217
static string::size_type usageMax
Max screen width for displaying usage (default: 80)
Definition: argList.H:171
static HashTable< string > validOptions
A list of valid options.
Definition: argList.H:156
Signal handler for SEGV interrupt.
Definition: sigSegv.H:54
const string & option(const word &opt) const
Return the argument string associated with the named option.
Definition: argListI.H:108
Namespace for OpenFOAM.
const stringList & args() const
Return arguments.
Definition: argListI.H:72
IStringStream optionLookup(const word &opt) const
Return an IStringStream from the named option.
Definition: argListI.H:120