src/OpenFOAM/db/dictionary/dictionary.H

   1 /*---------------------------------------------------------------------------*\
   2   =========                 |
   3   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
   4    \\    /   O peration     |
   5     \\  /    A nd           | Copyright (C) 1991-2008 OpenCFD Ltd.
   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 the
  13     Free Software Foundation; either version 2 of the License, or (at your
  14     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, write to the Free Software Foundation,
  23     Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
  24
  25 Class
  26     Foam::dictionary
  27
  28 Description
  29     A list of keyword definitions, which are a keyword followed by any number
  30     of values (e.g. words and numbers).
  31
  32     The dictionary class is the base class for IOdictionary.
  33     It also serves as a bootstrap dictionary for the objectRegistry data
  34     dictionaries since, unlike the IOdictionary class, it does not use an
  35     objectRegistry itself to work.
  36
  37 ToDo
  38     A merge() member function with a non-const dictionary parameter.
  39     This would avoid unnecessary cloning in the add(entry*,bool) method
  40
  41 SourceFiles
  42     dictionary.C
  43     dictionaryIO.C
  44
  45 \*---------------------------------------------------------------------------*/
  46
  47 #ifndef dictionary_H
  48 #define dictionary_H
  49
  50 #include "entry.H"
  51 #include "IDLList.H"
  52 #include "fileName.H"
  53 #include "ITstream.H"
  54 #include "HashTable.H"
  55 #include "wordList.H"
  56 #include "className.H"
  57
  58 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
  59
  60 namespace Foam
  61 {
  62
  63 // Forward declaration of friend functions and operators
  64
  65 class dictionary;
  66 Istream& operator>>(Istream&, dictionary&);
  67 Ostream& operator<<(Ostream&, const dictionary&);
  68
  69
  70 /*---------------------------------------------------------------------------*\
  71                            Class dictionary Declaration
  72 \*---------------------------------------------------------------------------*/
  73
  74 class dictionary
  75 :
  76     public IDLList<entry>
  77 {
  78     // Private data
  79
  80         //- Dictionary name
  81         fileName name_;
  82
  83         //- HashTable of the enries held on the DL-list for quick lookup
  84         HashTable<entry*> hashedEntries_;
  85
  86         //- Parent dictionary
  87         const dictionary& parent_;
  88
  89
  90 public:
  91
  92         //- Read dictionary from Istream
  93         bool read(Istream&);
  94
  95         //- Substitute the given keyword prepended by '$' with the
  96         //  corresponding sub-dictionary entries
  97         bool substituteKeyword(const word& keyword);
  98
  99
 100 public:
 101
 102     //- Declare friendship with the entry class for IO
 103     friend class entry;
 104
 105
 106     // Declare name of the class and its debug switch
 107     ClassName("dictionary");
 108
 109
 110     //- Null dictionary
 111     static const dictionary null;
 112
 113
 114     // Constructors
 115
 116         //- Construct top-level dictionary null
 117         dictionary();
 118
 119         //- Construct from the parent dictionary and Istream, reading entries
 120         //  until lastEntry or EOF
 121         dictionary
 122         (
 123             const dictionary& parentDict,
 124             Istream&
 125         );
 126
 127         //- Construct top-level dictionary from Istream, reading entries
 128         //  until EOF
 129         dictionary(Istream&);
 130
 131         //- Construct as copy given the parent dictionary
 132         dictionary(const dictionary& parentDict, const dictionary& dict);
 133
 134         //- Construct top-level dictionary as copy
 135         dictionary(const dictionary& dict);
 136
 137         //- Construct and return clone
 138         Foam::autoPtr<dictionary> clone() const;
 139
 140         //- Construct top-level dictionary on freestore from Istream
 141         static Foam::autoPtr<dictionary> New(Istream& is);
 142
 143
 144     // Destructor
 145
 146         ~dictionary();
 147
 148
 149     // Member functions
 150
 151         //- Return the dictionary name
 152         const fileName& name() const
 153         {
 154             return name_;
 155         }
 156
 157         //- Return the dictionary name
 158         fileName& name()
 159         {
 160             return name_;
 161         }
 162
 163         //- Return the parent dictionary
 164         const dictionary& parent() const
 165         {
 166             return parent_;
 167         }
 168
 169         //- Return line number of first token in dictionary
 170         label startLineNumber() const;
 171
 172         //- Return line number of last token in dictionary
 173         label endLineNumber() const;
 174
 175
 176         // Search and lookup
 177
 178             //- Search dictionary for given keyword
 179             //  If recursive search parent dictionaries
 180             bool found(const word& keyword, bool recursive=false) const;
 181
 182             //- Find and return an entry data stream pointer if present
 183             //  otherwise return NULL.
 184             //  If recursive search parent dictionaries
 185             const entry* lookupEntryPtr
 186             (
 187                 const word&, bool recursive=false
 188             ) const;
 189
 190             //- Find and return an entry data stream pointer for manipulation
 191             //  if present otherwise return NULL.
 192             //  If recursive search parent dictionaries
 193             entry* lookupEntryPtr(const word&, bool recursive=false);
 194
 195             //- Find and return an entry data stream if present otherwise error.
 196             //  If recursive search parent dictionaries
 197             const entry& lookupEntry(const word&, bool recursive=false) const;
 198
 199             //- Find and return an entry data stream
 200             //  If recursive search parent dictionaries
 201             ITstream& lookup(const word&, bool recursive=false) const;
 202
 203             //- Find and return a T,
 204             //  if not found return the given default value
 205             //  If recursive search parent dictionaries
 206             template<class T>
 207             T lookupOrDefault
 208             (
 209                 const word&,
 210                 const T&,
 211                 bool recursive=false
 212             ) const;
 213
 214             //- Find and return a T, if not found return the given
 215             //  default value, and add to dictionary.
 216             //  If recursive search parent dictionaries
 217             template<class T>
 218             T lookupOrAddDefault
 219             (
 220                 const word&,
 221                 const T&,
 222                 bool recursive=false
 223             );
 224
 225             //- Find an entry if present, and assign to T
 226             //  Returns true if the entry was found
 227             template<class T>
 228             bool readIfPresent
 229             (
 230                 const word&,
 231                 T&,
 232                 bool recursive=false
 233             ) const;
 234
 235             //- Check if entry is a sub-dictionary
 236             bool isDict(const word&) const;
 237
 238             //- Find and return a sub-dictionary pointer if present
 239             //  otherwise return NULL.
 240             const dictionary* subDictPtr(const word&) const;
 241
 242             //- Find and return a sub-dictionary
 243             const dictionary& subDict(const word&) const;
 244
 245             //- Find and return a sub-dictionary for manipulation
 246             dictionary& subDict(const word&);
 247
 248             //- Return the table of contents
 249             wordList toc() const;
 250
 251
 252         // Editing
 253
 254             //- Add a new entry
 255             //  With the merge option, dictionaries are interwoven and
 256             //  primitive entries are overwritten
 257             bool add(entry*, bool mergeEntry=false);
 258
 259             //- Add an entry
 260             //  With the merge option, dictionaries are interwoven and
 261             //  primitive entries are overwritten
 262             void add(const entry&, bool mergeEntry=false);
 263
 264             //- Add a word entry
 265             //  optionally overwrite an existing entry
 266             void add(const word& keyword, const word&, bool overwrite=false);
 267
 268             //- Add a string entry
 269             //  optionally overwrite an existing entry
 270             void add(const word& keyword, const string&, bool overwrite=false);
 271
 272             //- Add a label entry
 273             //  optionally overwrite an existing entry
 274             void add(const word& keyword, const label, bool overwrite=false);
 275
 276             //- Add a scalar entry
 277             //  optionally overwrite an existing entry
 278             void add (const word& keyword, const scalar, bool overwrite=false);
 279
 280             //- Add a dictionary entry
 281             //  optionally merge with an existing sub-dictionary
 282             void add
 283             (
 284                 const word& keyword,
 285                 const dictionary&,
 286                 bool mergeEntry=false
 287             );
 288
 289             //- Add a T entry
 290             //  optionally overwrite an existing entry
 291             template<class T>
 292             void add(const word& keyword, const T&, bool overwrite=false);
 293
 294             //- Assign a new entry, overwrite any existing entry
 295             void set(entry*);
 296
 297             //- Assign a new entry, overwrite any existing entry
 298             void set(const entry&);
 299
 300             //- Assign a dictionary entry, overwrite any existing entry
 301             void set(const word& keyword, const dictionary&);
 302
 303             //- Assign a T entry, overwrite any existing entry
 304             template<class T>
 305             void set(const word& keyword, const T&);
 306
 307             //- Remove an entry specified by keyword
 308             bool remove(const word& keyword);
 309
 310             //- Change the keyword for an entry,
 311             //  optionally forcing overwrite of an existing entry
 312             bool changeKeyword
 313             (
 314                 const word& oldKeyword,
 315                 const word& newKeyword,
 316                 bool forceOverwrite = false
 317             );
 318
 319             //- Merge entries from the given dictionary.
 320             //  Also merge sub-dictionaries as required.
 321             bool merge(const dictionary&);
 322
 323             //- Clear the dictionary
 324             void clear();
 325
 326
 327         // Write
 328
 329             void write(Ostream& os, bool subDict = true) const;
 330
 331
 332     // Member Operators
 333
 334         //- Find and return entry
 335         ITstream& operator[](const word&) const;
 336
 337         void operator=(const dictionary&);
 338
 339         //- Include entries from the given dictionary.
 340         //  Warn, but do not overwrite existing entries
 341         void operator+=(const dictionary&);
 342
 343         //- Conditionally include entries from the given dictionary.
 344         //  Do not overwrite existing entries.
 345         void operator|=(const dictionary&);
 346
 347         //- Unconditionally include entries from the given dictionary.
 348         //  Overwrite existing entries.
 349         void operator<<=(const dictionary&);
 350
 351
 352     // IOstream operators
 353
 354         //- Read dictionary from Istream
 355         friend Istream& operator>>(Istream&, dictionary&);
 356
 357         //- Write dictionary to Ostream
 358         friend Ostream& operator<<(Ostream&, const dictionary&);
 359 };
 360
 361
 362 // Global Operators
 363
 364 //- Combine dictionaries starting from the entries in dict1 and then including those from dict2.
 365 //  Warn, but do not overwrite the entries from dict1.
 366 dictionary operator+(const dictionary& dict1, const dictionary& dict2);
 367
 368 //- Combine dictionaries starting from the entries in dict1 and then including those from dict2.
 369 //  Do not overwrite the entries from dict1.
 370 dictionary operator|(const dictionary& dict1, const dictionary& dict2);
 371
 372
 373 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 374
 375 } // End namespace Foam
 376
 377 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 378
 379 #ifdef NoRepository
 380 #   include "dictionaryTemplates.C"
 381 #endif
 382
 383 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 384
 385 #endif
 386
 387 // ************************************************************************* //