src/OpenFOAM/global/argList/argList.H

   1 /*---------------------------------------------------------------------------*\
   2   =========                 |
   3   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
   4    \\    /   O peration     |
   5     \\  /    A nd           | Copyright (C) 2011 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 an 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
  73 \*---------------------------------------------------------------------------*/
  74
  75 #ifndef argList_H
  76 #define argList_H
  77
  78 #include "stringList.H"
  79 #include "SubList.H"
  80 #include "SLList.H"
  81 #include "HashTable.H"
  82 #include "word.H"
  83 #include "fileName.H"
  84 #include "parRun.H"
  85 #include "IStringStream.H"
  86 #include "OSspecific.H"
  87
  88 #include "sigFpe.H"
  89 #include "sigInt.H"
  90 #include "sigQuit.H"
  91 #include "sigSegv.H"
  92
  93 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
  94
  95 namespace Foam
  96 {
  97
  98 /*---------------------------------------------------------------------------*\
  99                            Class argList Declaration
 100 \*---------------------------------------------------------------------------*/
 101
 102 class argList
 103 {
 104     // Private data
 105         static bool bannerEnabled;
 106
 107         stringList args_;
 108         HashTable<string> options_;
 109
 110         word executable_;
 111         fileName rootPath_;
 112         fileName globalCase_;
 113         fileName case_;
 114
 115         ParRunControl parRunControl_;
 116
 117         // Signal handlers
 118         sigFpe sigFpe_;
 119         sigInt sigInt_;
 120         sigQuit sigQuit_;
 121         sigSegv sigSegv_;
 122
 123
 124     // Private Member Functions
 125
 126         //- Helper function for printUsage
 127         static void printOptionUsage
 128         (
 129             const label location,
 130             const string& str
 131         );
 132
 133         //- get rootPath_ / globalCase_ from one of the following forms
 134         //   * [-case dir]
 135         //   * cwd
 136         //
 137         // Also export FOAM_CASE and FOAM_CASENAME environment variables
 138         // so they can be used immediately (eg, in decomposeParDict)
 139         void getRootCase();
 140
 141         //- Transcribe argv into internal args_
 142         //  return true if any "(" ... ")" sequences were captured
 143         bool regroupArgv(int& argc, char**& argv);
 144
 145
 146 public:
 147
 148     // Static data members
 149
 150         //- A list of valid (mandatory) arguments
 151         static SLList<string> validArgs;
 152
 153         //- A list of valid options
 154         static HashTable<string> validOptions;
 155
 156         //- A list of valid parallel options
 157         static HashTable<string> validParOptions;
 158
 159         //- Short usage information for validOptions
 160         static HashTable<string> optionUsage;
 161
 162         //- Additional notes for usage
 163         static SLList<string> notes;
 164
 165         //- Min offset for displaying usage (default: 20)
 166         static string::size_type usageMin;
 167
 168         //- Max screen width for displaying usage (default: 80)
 169         static string::size_type usageMax;
 170
 171         //! \cond internalClass
 172         class initValidTables
 173         {
 174         public:
 175
 176             initValidTables();
 177         };
 178         //! \endcond
 179
 180
 181     // Constructors
 182
 183         //- Construct from argc and argv
 184         //  checking the arguments and options as requested
 185         argList
 186         (
 187             int& argc,
 188             char**& argv,
 189             bool checkArgs=true,
 190             bool checkOpts=true
 191         );
 192
 193
 194         //- Destructor
 195         virtual ~argList();
 196
 197
 198     // Member functions
 199
 200         // Access
 201
 202             //- Name of executable without the path
 203             inline const word& executable() const;
 204
 205             //- Return root path
 206             inline const fileName& rootPath() const;
 207
 208             //- Return case name (parallel run) or global case (serial run)
 209             inline const fileName& caseName() const;
 210
 211             //- Return case name
 212             inline const fileName& globalCaseName() const;
 213
 214             //- Return the path to the caseName
 215             inline fileName path() const;
 216
 217             //- Return arguments
 218             inline const stringList& args() const;
 219
 220             //- Return the argument corresponding to index.
 221             inline const string& arg(const label index) const;
 222
 223             //- Return the number of arguments
 224             inline label size() const;
 225
 226             //- Read a value from the argument at index.
 227             //  Index 0 corresponds to the name of the executable.
 228             //  Index 1 corresponds to the first argument.
 229             template<class T>
 230             inline T argRead(const label index) const;
 231
 232             //- Return arguments that are additional to the executable
 233             //  \deprecated use operator[] directly (deprecated Feb 2010)
 234             stringList::subList additionalArgs() const
 235             {
 236                 return stringList::subList(args_, args_.size()-1, 1);
 237             }
 238
 239
 240             //- Return options
 241             inline const Foam::HashTable<string>& options() const;
 242
 243             //- Return the argument string associated with the named option
 244             inline const string& option(const word& opt) const;
 245
 246             //- Return true if the named option is found
 247             inline bool optionFound(const word& opt) const;
 248
 249             //- Return an IStringStream from the named option
 250             inline IStringStream optionLookup(const word& opt) const;
 251
 252             //- Read a value from the named option
 253             template<class T>
 254             inline T optionRead(const word& opt) const;
 255
 256             //- Read a value from the named option if present.
 257             //  Return true if the named option was found.
 258             template<class T>
 259             inline bool optionReadIfPresent(const word& opt, T&) const;
 260
 261             //- Read a value from the named option if present.
 262             //  Return true if the named option was found, otherwise
 263             //  use the supplied default and return false.
 264             template<class T>
 265             inline bool optionReadIfPresent
 266             (
 267                 const word& opt,
 268                 T&,
 269                 const T& deflt
 270             ) const;
 271
 272             //- Read a value from the named option if present.
 273             //  Return true if the named option was found.
 274             template<class T>
 275             inline T optionLookupOrDefault
 276             (
 277                 const word& opt,
 278                 const T& deflt
 279             ) const;
 280
 281             //- Read a List of values from the named option
 282             template<class T>
 283             List<T> optionReadList(const word& opt) const
 284             {
 285                 return readList<T>(optionLookup(opt)());
 286             }
 287
 288
 289             //- Return the argument corresponding to index.
 290             //  Index 0 corresponds to the name of the executable.
 291             //  Index 1 corresponds to the first argument.
 292             inline const string& operator[](const label index) const;
 293
 294             //- Return the argument string associated with the named option
 295             //  \sa option()
 296             inline const string& operator[](const word& opt) const;
 297
 298         // Edit
 299
 300             //- Add to a bool option to validOptions with usage information
 301             static void addBoolOption
 302             (
 303                 const word& opt,
 304                 const string& usage = ""
 305             );
 306
 307             //- Add to an option to validOptions with usage information
 308             //  An option with an empty param is a bool option
 309             static void addOption
 310             (
 311                 const word& opt,
 312                 const string& param = "",
 313                 const string& usage = ""
 314             );
 315
 316             //- Add option usage information to optionUsage
 317             static void addUsage
 318             (
 319                 const word& opt,
 320                 const string& usage
 321             );
 322
 323             //- Add extra notes for the usage information
 324             //  This string is used "as-is" without additional formatting
 325             static void addNote(const string&);
 326
 327             //- Remove option from validOptions and from optionUsage
 328             static void removeOption(const word& opt);
 329
 330             //- Disable emitting the banner information
 331             static void noBanner();
 332
 333             //- Remove the parallel options
 334             static void noParallel();
 335
 336
 337             //- Set option directly (use with caution)
 338             //  An option with an empty param is a bool option.
 339             //  Not all valid options can also be set: eg, -case, -roots, ...
 340             //  Return true if the existing option value needed changing,
 341             //  or if the option did not previously exist.
 342             bool setOption(const word& opt, const string& param = "");
 343
 344             //- Unset option directly (use with caution)
 345             //  Not all valid options can also be unset: eg, -case, -roots ...
 346             //  Return true if the option existed before being unset.
 347             bool unsetOption(const word& opt);
 348
 349
 350         // Print
 351
 352             //- Print notes (if any)
 353             void printNotes() const;
 354
 355             //- Print usage
 356             void printUsage() const;
 357
 358             //- Display documentation in browser
 359             //  Optionally display the application source code
 360             void displayDoc(bool source=false) const;
 361
 362
 363         // Check
 364
 365             //- Check argument list
 366             bool check(bool checkArgs=true, bool checkOpts=true) const;
 367
 368             //- Check root path and case path
 369             bool checkRootCase() const;
 370 };
 371
 372
 373 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 374
 375 } // End namespace Foam
 376
 377 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 378
 379 #include "argListI.H"
 380
 381 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 382
 383 #endif
 384
 385 // ************************************************************************* //