argList.H
Go to the documentation of this file.
1 /*---------------------------------------------------------------------------*\
2  ========= |
3  \\ / F ield | OpenFOAM: The Open Source CFD Toolbox
4  \\ / O peration |
5  \\ / A nd | Copyright (C) 2011-2015 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  \par Default command-line options
43  \param -case <dir> \n
44  select a case directory instead of the current working directory
45  \param -parallel \n
46  specify case as a parallel job
47  \param -doc \n
48  display the documentation in browser
49  \param -srcDoc \n
50  display the source documentation in browser
51  \param -help \n
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  static bool bannerEnabled;
107 
108  //- Switch on/off parallel mode. Has to be first to be constructed
109  // so destructor is done last.
110  ParRunControl parRunControl_;
111 
112  stringList args_;
113  HashTable<string> options_;
114 
115  word executable_;
116  fileName rootPath_;
117  fileName globalCase_;
118  fileName case_;
119  string argListStr_;
120 
121  // Signal handlers
122  sigFpe sigFpe_;
123  sigInt sigInt_;
124  sigQuit sigQuit_;
125  sigSegv sigSegv_;
126 
127 
128  // Private Member Functions
129 
130  //- Helper function for printUsage
131  static void printOptionUsage
132  (
133  const label location,
134  const string& str
135  );
136 
137  //- Get rootPath_ / globalCase_ from one of the following forms
138  // * [-case dir]
139  // * cwd
140  //
141  // Also export FOAM_CASE and FOAM_CASENAME environment variables
142  // so they can be used immediately (eg, in decomposeParDict)
143  void getRootCase();
144 
145  //- Transcribe argv into internal args_
146  // return true if any "(" ... ")" sequences were captured
147  bool regroupArgv(int& argc, char**& argv);
148 
149 
150 public:
151 
152  // Static data members
153 
154  //- A list of valid (mandatory) arguments
155  static SLList<string> validArgs;
156 
157  //- A list of valid options
159 
160  //- A list of valid parallel options
162 
163  //- Short usage information for validOptions
165 
166  //- Additional notes for usage
167  static SLList<string> notes;
168 
169  //- Min offset for displaying usage (default: 20)
171 
172  //- Max screen width for displaying usage (default: 80)
174 
176  class initValidTables
177  {
178  public:
179 
180  initValidTables();
181  };
183 
184 
185  // Constructors
186 
187  //- Construct from argc and argv
188  // checking the arguments and options as requested
189  argList
190  (
191  int& argc,
192  char**& argv,
193  bool checkArgs = true,
194  bool checkOpts = true,
195  bool initialise = true
196  );
197 
198  //- Construct copy with new options
199  argList
200  (
201  const argList& args,
202  const HashTable<string>& options,
203  bool checkArgs = true,
204  bool checkOpts = true,
205  bool initialise = true
206  );
207 
208 
209  //- Destructor
210  virtual ~argList();
211 
212 
213  // Member functions
214 
215  //- Parse
216  void parse
217  (
218  bool checkArgs,
219  bool checkOpts,
220  bool initialise
221  );
222 
223 
224  // Access
225 
226  //- Name of executable without the path
227  inline const word& executable() const;
228 
229  //- Return root path
230  inline const fileName& rootPath() const;
231 
232  //- Return case name (parallel run) or global case (serial run)
233  inline const fileName& caseName() const;
234 
235  //- Return case name
236  inline const fileName& globalCaseName() const;
237 
238  //- Return parRunControl
239  inline const ParRunControl& parRunControl() const;
240 
241  //- Return the path to the caseName
242  inline fileName path() const;
243 
244  //- Return arguments
245  inline const stringList& args() const;
246 
247  //- Return non-const access to arguments
248  inline stringList& args();
249 
250  //- Return the argument corresponding to index.
251  inline const string& arg(const label index) const;
252 
253  //- Return the number of arguments
254  inline label size() const;
255 
256  //- Read a value from the argument at index.
257  // Index 0 corresponds to the name of the executable.
258  // Index 1 corresponds to the first argument.
259  template<class T>
260  inline T argRead(const label index) const;
261 
262  //- Return arguments that are additional to the executable
263  // \deprecated use operator[] directly (deprecated Feb 2010)
265  {
266  return stringList::subList(args_, args_.size()-1, 1);
267  }
268 
269 
270  //- Return options
271  inline const Foam::HashTable<string>& options() const;
272 
273  //- Return non-const access to options
275 
276  //- Return the argument string associated with the named option
277  inline const string& option(const word& opt) const;
278 
279  //- Return true if the named option is found
280  inline bool optionFound(const word& opt) const;
281 
282  //- Return an IStringStream from the named option
283  inline IStringStream optionLookup(const word& opt) const;
284 
285  //- Read a value from the named option
286  template<class T>
287  inline T optionRead(const word& opt) const;
288 
289  //- Read a value from the named option if present.
290  // Return true if the named option was found.
291  template<class T>
292  inline bool optionReadIfPresent(const word& opt, T&) const;
293 
294  //- Read a value from the named option if present.
295  // Return true if the named option was found, otherwise
296  // use the supplied default and return false.
297  template<class T>
298  inline bool optionReadIfPresent
299  (
300  const word& opt,
301  T&,
302  const T& deflt
303  ) const;
304 
305  //- Read a value from the named option if present.
306  // Return supplied default otherwise.
307  template<class T>
308  inline T optionLookupOrDefault
309  (
310  const word& opt,
311  const T& deflt
312  ) const;
313 
314  //- Read a List of values from the named option
315  template<class T>
316  List<T> optionReadList(const word& opt) const
317  {
318  return readList<T>(optionLookup(opt)());
319  }
320 
321 
322  //- Return the argument corresponding to index.
323  // Index 0 corresponds to the name of the executable.
324  // Index 1 corresponds to the first argument.
325  inline const string& operator[](const label index) const;
326 
327  //- Return the argument string associated with the named option
328  // \sa option()
329  inline const string& operator[](const word& opt) const;
330 
331 
332  // Edit
333 
334  //- Add to a bool option to validOptions with usage information
335  static void addBoolOption
336  (
337  const word& opt,
338  const string& usage = ""
339  );
340 
341  //- Add to an option to validOptions with usage information
342  // An option with an empty param is a bool option
343  static void addOption
344  (
345  const word& opt,
346  const string& param = "",
347  const string& usage = ""
348  );
349 
350  //- Add option usage information to optionUsage
351  static void addUsage
352  (
353  const word& opt,
354  const string& usage
355  );
356 
357  //- Add extra notes for the usage information
358  // This string is used "as-is" without additional formatting
359  static void addNote(const string&);
360 
361  //- Remove option from validOptions and from optionUsage
362  static void removeOption(const word& opt);
363 
364  //- Disable emitting the banner information
365  static void noBanner();
366 
367  //- Remove the parallel options
368  static void noParallel();
369 
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 // ************************************************************************* //
Input from memory buffer stream.
Definition: IStringStream.H:49
static HashTable< string > validOptions
A list of valid options.
Definition: argList.H:157
const ParRunControl & parRunControl() const
Return parRunControl.
Definition: argListI.H:54
const fileName & rootPath() const
Return root path.
Definition: argListI.H:36
Non-intrusive singly-linked list.
Definition: SLList.H:47
static void addOption(const word &opt, const string &param="", const string &usage="")
Add to an option to validOptions with usage information.
Definition: argList.C:93
static SLList< string > validArgs
A list of valid (mandatory) arguments.
Definition: argList.H:154
T optionRead(const word &opt) const
Read a value from the named option.
Definition: argListI.H:187
Signal handler for INT interupt.
Definition: sigInt.H:54
void T(FieldField< Field, Type > &f1, const FieldField< Field, Type > &f2)
T argRead(const label index) const
Read a value from the argument at index.
Definition: argListI.H:177
const Foam::HashTable< string > & options() const
Return options.
Definition: argListI.H:90
void parse(bool checkArgs, bool checkOpts, bool initialise)
Parse.
Definition: argList.C:490
fileName path() const
Return the path to the caseName.
Definition: argListI.H:60
An STL-conforming hash table.
Definition: HashTable.H:61
Functions used by OpenFOAM that are specific to POSIX compliant operating systems and need to be repl...
A class for handling words, derived from string.
Definition: word.H:59
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
const string & option(const word &opt) const
Return the argument string associated with the named option.
Definition: argListI.H:102
bool checkRootCase() const
Check root path and case path.
Definition: argList.C:1187
void size(const label)
Override size to be inconsistent with allocated storage.
Definition: ListI.H:76
void printUsage() const
Print usage.
Definition: argList.C:1007
static void removeOption(const word &opt)
Remove option from validOptions and from optionUsage.
Definition: argList.C:133
Signal handler for QUIT interupt.
Definition: sigQuit.H:54
void displayDoc(bool source=false) const
Display documentation in browser.
Definition: argList.C:1086
static HashTable< string > validParOptions
A list of valid parallel options.
Definition: argList.H:160
static SLList< string > notes
Additional notes for usage.
Definition: argList.H:166
Namespace for OpenFOAM.
static void noBanner()
Disable emitting the banner information.
Definition: argList.C:140
graph_traits< Graph >::vertices_size_type size_type
Definition: SloanRenumber.C:73
Set up trapping for floating point exceptions (signal FPE).
Definition: sigFpe.H:67
virtual ~argList()
Destructor.
Definition: argList.C:875
void printNotes() const
Print notes (if any)
Definition: argList.C:993
static string::size_type usageMax
Max screen width for displaying usage (default: 80)
Definition: argList.H:172
static string::size_type usageMin
Min offset for displaying usage (default: 20)
Definition: argList.H:169
bool optionFound(const word &opt) const
Return true if the named option is found.
Definition: argListI.H:108
IStringStream optionLookup(const word &opt) const
Return an IStringStream from the named option.
Definition: argListI.H:114
bool setOption(const word &opt, const string &param="")
Set option directly (use with caution)
Definition: argList.C:883
label size() const
Return the number of arguments.
Definition: argListI.H:84
bool optionReadIfPresent(const word &opt, T &) const
Read a value from the named option if present.
Definition: argListI.H:198
static void addBoolOption(const word &opt, const string &usage="")
Add to a bool option to validOptions with usage information.
Definition: argList.C:83
Extract command arguments and options from the supplied argc and argv parameters. ...
Definition: argList.H:102
const fileName & caseName() const
Return case name (parallel run) or global case (serial run)
Definition: argListI.H:42
const stringList & args() const
Return arguments.
Definition: argListI.H:66
Helper class for initializing parallel jobs from the command arguments.
Definition: parRun.H:46
const word & executable() const
Name of executable without the path.
Definition: argListI.H:30
stringList::subList additionalArgs() const
Return arguments that are additional to the executable.
Definition: argList.H:263
bool check(bool checkArgs=true, bool checkOpts=true) const
Check argument list.
Definition: argList.C:1146
A class for handling file names.
Definition: fileName.H:69
static HashTable< string > optionUsage
Short usage information for validOptions.
Definition: argList.H:163
const string & operator[](const label index) const
Return the argument corresponding to index.
Definition: argListI.H:255
SubList< string > subList
Declare type of subList.
Definition: List.H:153
List< T > optionReadList(const word &opt) const
Read a List of values from the named option.
Definition: argList.H:315
A List obtained as a section of another List.
Definition: SubList.H:53
static void addNote(const string &)
Add extra notes for the usage information.
Definition: argList.C:124
const string & arg(const label index) const
Return the argument corresponding to index.
Definition: argListI.H:78
argList(int &argc, char **&argv, bool checkArgs=true, bool checkOpts=true, bool initialise=true)
Construct from argc and argv.
Definition: argList.C:372
const fileName & globalCaseName() const
Return case name.
Definition: argListI.H:48
bool unsetOption(const word &opt)
Unset option directly (use with caution)
Definition: argList.C:958
T optionLookupOrDefault(const word &opt, const T &deflt) const
Read a value from the named option if present.
Definition: argListI.H:237
Signal handler for SEGV interupt.
Definition: sigSegv.H:54
static void addUsage(const word &opt, const string &usage)
Add option usage information to optionUsage.
Definition: argList.C:108
static void noParallel()
Remove the parallel options.
Definition: argList.C:146