src/foam/db/dictionary/dictionary.H

   1 /*---------------------------------------------------------------------------*\
   2   =========                 |
   3   \\      /  F ield         | foam-extend: Open Source CFD
   4    \\    /   O peration     | Version:     3.2
   5     \\  /    A nd           | Web:         http://www.foam-extend.org
   6      \\/     M anipulation  | For copyright notice see file Copyright
   7 -------------------------------------------------------------------------------
   8 License
   9     This file is part of foam-extend.
  10
  11     foam-extend 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 3 of the License, or (at your
  14     option) any later version.
  15
  16     foam-extend is distributed in the hope that it will be useful, but
  17     WITHOUT ANY WARRANTY; without even the implied warranty of
  18     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19     General Public License for more details.
  20
  21     You should have received a copy of the GNU General Public License
  22     along with foam-extend.  If not, see <http://www.gnu.org/licenses/>.
  23
  24 Class
  25     Foam::dictionary
  26
  27 Description
  28     A list of keyword definitions, which are a keyword followed by any number
  29     of values (e.g. words and numbers). The keywords can represent patterns
  30     which are matched using Posix regular expressions. The general order for
  31     searching is as follows:
  32     - exact match
  33     - pattern match (in reverse order)
  34     - optional recursion into the enclosing (parent) dictionaries
  35
  36     The dictionary class is the base class for IOdictionary.
  37     It also serves as a bootstrap dictionary for the objectRegistry data
  38     dictionaries since, unlike the IOdictionary class, it does not use an
  39     objectRegistry itself to work.
  40
  41 ToDo
  42     A merge() member function with a non-const dictionary parameter.
  43     This would avoid unnecessary cloning in the add(entry*, bool) method.
  44
  45 SourceFiles
  46     dictionary.C
  47     dictionaryIO.C
  48
  49 \*---------------------------------------------------------------------------*/
  50
  51 #ifndef dictionary_H
  52 #define dictionary_H
  53
  54 #include "entry.H"
  55 #include "IDLList.H"
  56 #include "DLList.H"
  57 #include "fileName.H"
  58 #include "ITstream.H"
  59 #include "HashTable.H"
  60 #include "wordList.H"
  61 #include "className.H"
  62
  63 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
  64
  65 namespace Foam
  66 {
  67
  68 // Forward declaration of friend functions and operators
  69 class regExp;
  70 class dictionary;
  71 class SHA1Digest;
  72
  73 Istream& operator>>(Istream&, dictionary&);
  74 Ostream& operator<<(Ostream&, const dictionary&);
  75
  76 /*---------------------------------------------------------------------------*\
  77                         Class dictionaryName Declaration
  78 \*---------------------------------------------------------------------------*/
  79
  80 class dictionaryName
  81 {
  82     // Private data
  83
  84         fileName name_;
  85
  86
  87 public:
  88
  89     // Constructors
  90
  91         //- Construct dictionaryName null
  92         dictionaryName()
  93         {}
  94
  95         //- Construct dictionaryName as copy of the given fileName
  96         dictionaryName(const fileName& name)
  97         :
  98             name_(name)
  99         {}
 100
 101
 102     // Member functions
 103
 104         //- Return the dictionary name
 105         const fileName& name() const
 106         {
 107             return name_;
 108         }
 109
 110         //- Return the dictionary name
 111         fileName& name()
 112         {
 113             return name_;
 114         }
 115 };
 116
 117
 118 /*---------------------------------------------------------------------------*\
 119                            Class dictionary Declaration
 120 \*---------------------------------------------------------------------------*/
 121
 122 class dictionary
 123 :
 124     public dictionaryName,
 125     public IDLList<entry>
 126 {
 127     // Private data
 128
 129         //- HashTable of the entries held on the DL-list for quick lookup
 130         HashTable<entry*> hashedEntries_;
 131
 132         //- Parent dictionary
 133         const dictionary& parent_;
 134
 135         //- Entries of matching patterns
 136         DLList<entry*> patternEntries_;
 137
 138         //- Patterns as precompiled regular expressions
 139         DLList<autoPtr<regExp> > patternRegexps_;
 140
 141
 142    // Private Member Functions
 143
 144         //- Search patterns table for exact match or regular expression match
 145         bool findInPatterns
 146         (
 147             const bool patternMatch,
 148             const word& Keyword,
 149             DLList<entry*>::const_iterator& wcLink,
 150             DLList<autoPtr<regExp> >::const_iterator& reLink
 151         ) const;
 152
 153         //- Search patterns table for exact match or regular expression match
 154         bool findInPatterns
 155         (
 156             const bool patternMatch,
 157             const word& Keyword,
 158             DLList<entry*>::iterator& wcLink,
 159             DLList<autoPtr<regExp> >::iterator& reLink
 160         );
 161
 162
 163 public:
 164
 165     //- Declare friendship with the entry class for IO
 166     friend class entry;
 167
 168
 169     // Declare name of the class and its debug switch
 170     ClassName("dictionary");
 171
 172
 173     //- Null dictionary
 174     static const dictionary null;
 175
 176
 177     // Constructors
 178
 179         //- Construct top-level dictionary null
 180         dictionary();
 181
 182         //- Construct top-level empty dictionary with given name
 183         dictionary(const fileName& name);
 184
 185         //- Construct given the entry name, parent dictionary and Istream,
 186         //  reading entries until lastEntry or EOF
 187         dictionary
 188         (
 189             const fileName& name,
 190             const dictionary& parentDict,
 191             Istream&
 192         );
 193
 194         //- Construct top-level dictionary from Istream, reading entries
 195         //  until EOF
 196         dictionary(Istream&);
 197
 198         //- Construct as copy given the parent dictionary
 199         dictionary(const dictionary& parentDict, const dictionary&);
 200
 201         //- Construct top-level dictionary as copy
 202         dictionary(const dictionary&);
 203
 204         //- Construct top-level dictionary as copy from pointer to dictionary.
 205         //  A null pointer is treated like an empty dictionary.
 206         dictionary(const dictionary*);
 207
 208         //- Construct by transferring parameter contents from
 209         //  given parent dictionary
 210         dictionary(const dictionary& parentDict, const Xfer<dictionary>&);
 211
 212         //- Construct top-level dictionary by transferring parameter contents
 213         dictionary(const Xfer<dictionary>&);
 214
 215         //- Construct and return clone
 216         autoPtr<dictionary> clone() const;
 217
 218         //- Construct top-level dictionary on freestore from Istream
 219         static autoPtr<dictionary> New(Istream&);
 220
 221
 222     // Destructor
 223
 224         ~dictionary();
 225
 226
 227     // Member functions
 228
 229         //- Return the parent dictionary
 230         const dictionary& parent() const
 231         {
 232             return parent_;
 233         }
 234
 235         //- Return line number of first token in dictionary
 236         label startLineNumber() const;
 237
 238         //- Return line number of last token in dictionary
 239         label endLineNumber() const;
 240
 241         //- Return the SHA1 digest of the dictionary contents
 242         SHA1Digest digest() const;
 243
 244
 245         // Search and lookup
 246
 247             //- Search dictionary for given keyword
 248             //  If recursive, search parent dictionaries
 249             bool found(const word&, bool recursive = false) const;
 250
 251             //- Find and return an entry data stream pointer if present
 252             //  otherwise return NULL.
 253             //  If recursive, search parent dictionaries.
 254             //  If patternMatch, use regular expressions
 255             const entry* lookupEntryPtr
 256             (
 257                 const word&,
 258                 bool recursive,
 259                 bool patternMatch
 260             ) const;
 261
 262             //- Find and return an entry data stream pointer for manipulation
 263             //  if present otherwise return NULL.
 264             //  If recursive, search parent dictionaries.
 265             //  If patternMatch, use regular expressions.
 266             entry* lookupEntryPtr
 267             (
 268                 const word&,
 269                 bool recursive,
 270                 bool patternMatch
 271             );
 272
 273             //- Find and return an entry data stream
 274             //  if present otherwise error.
 275             //  If recursive, search parent dictionaries.
 276             //  If patternMatch, use regular expressions.
 277             const entry& lookupEntry
 278             (
 279                 const word&,
 280                 bool recursive,
 281                 bool patternMatch
 282             ) const;
 283
 284             //- Find and return an entry data stream
 285             //  If recursive, search parent dictionaries.
 286             //  If patternMatch, use regular expressions.
 287             ITstream& lookup
 288             (
 289                 const word&,
 290                 bool recursive = false,
 291                 bool patternMatch = true
 292             ) const;
 293
 294             //- Find and return a T,
 295             //  if not found return the given default value
 296             //  If recursive, search parent dictionaries.
 297             //  If patternMatch, use regular expressions.
 298             template<class T>
 299             T lookupOrDefault
 300             (
 301                 const word&,
 302                 const T&,
 303                 bool recursive = false,
 304                 bool patternMatch = true
 305             ) const;
 306
 307             //- Find and return a T, if not found return the given
 308             //  default value, and add to dictionary.
 309             //  If recursive, search parent dictionaries.
 310             //  If patternMatch, use regular expressions.
 311             template<class T>
 312             T lookupOrAddDefault
 313             (
 314                 const word&,
 315                 const T&,
 316                 bool recursive = false,
 317                 bool patternMatch = true
 318             );
 319
 320             //- Find an entry if present, and assign to T
 321             //  Returns true if the entry was found.
 322             //  If recursive, search parent dictionaries.
 323             //  If patternMatch, use regular expressions.
 324             template<class T>
 325             bool readIfPresent
 326             (
 327                 const word&,
 328                 T&,
 329                 bool recursive = false,
 330                 bool patternMatch = true
 331             ) const;
 332
 333             //- Check if entry is a sub-dictionary
 334             bool isDict(const word&) const;
 335
 336             //- Find and return a sub-dictionary pointer if present
 337             //  otherwise return NULL.
 338             const dictionary* subDictPtr(const word&) const;
 339
 340             //- Find and return a sub-dictionary
 341             const dictionary& subDict(const word&) const;
 342
 343             //- Find and return a sub-dictionary for manipulation
 344             dictionary& subDict(const word&);
 345
 346             //- Find and return a sub-dictionary as a copy, or
 347             //  return an empty dictionary if the sub-dictionary does not exist
 348             dictionary subOrEmptyDict(const word&) const;
 349
 350             //- Return the table of contents
 351             wordList toc() const;
 352
 353             //- Return the list of available keys or patterns
 354             List<keyType> keys(bool patterns = false) const;
 355
 356
 357         // Editing
 358
 359             //- Substitute the given keyword prepended by '$' with the
 360             //  corresponding sub-dictionary entries
 361             bool substituteKeyword(const word& keyword);
 362
 363             //- Add a new entry
 364             //  With the merge option, dictionaries are interwoven and
 365             //  primitive entries are overwritten
 366             bool add(entry*, bool mergeEntry = false);
 367
 368             //- Add an entry
 369             //  With the merge option, dictionaries are interwoven and
 370             //  primitive entries are overwritten
 371             void add(const entry&, bool mergeEntry = false);
 372
 373             //- Add a word entry
 374             //  optionally overwrite an existing entry
 375             void add(const keyType&, const word&, bool overwrite = false);
 376
 377             //- Add a string entry
 378             //  optionally overwrite an existing entry
 379             void add(const keyType&, const string&, bool overwrite = false);
 380
 381             //- Add a label entry
 382             //  optionally overwrite an existing entry
 383             void add(const keyType&, const label, bool overwrite = false);
 384
 385             //- Add a scalar entry
 386             //  optionally overwrite an existing entry
 387             void add(const keyType&, const scalar, bool overwrite = false);
 388
 389             //- Add a dictionary entry
 390             //  optionally merge with an existing sub-dictionary
 391             void add
 392             (
 393                 const keyType&,
 394                 const dictionary&,
 395                 bool mergeEntry = false
 396             );
 397
 398             //- Add a T entry
 399             //  optionally overwrite an existing entry
 400             template<class T>
 401             void add(const keyType&, const T&, bool overwrite = false);
 402
 403             //- Assign a new entry, overwrite any existing entry
 404             void set(entry*);
 405
 406             //- Assign a new entry, overwrite any existing entry
 407             void set(const entry&);
 408
 409             //- Assign a dictionary entry, overwrite any existing entry
 410             void set(const keyType&, const dictionary&);
 411
 412             //- Assign a T entry, overwrite any existing entry
 413             template<class T>
 414             void set(const keyType&, const T&);
 415
 416             //- Remove an entry specified by keyword
 417             bool remove(const word&);
 418
 419             //- Change the keyword for an entry,
 420             //  optionally forcing overwrite of an existing entry
 421             bool changeKeyword
 422             (
 423                 const keyType& oldKeyword,
 424                 const keyType& newKeyword,
 425                 bool forceOverwrite = false
 426             );
 427
 428             //- Merge entries from the given dictionary.
 429             //  Also merge sub-dictionaries as required.
 430             bool merge(const dictionary&);
 431
 432             //- Clear the dictionary
 433             void clear();
 434
 435             //- Transfer the contents of the argument and annul the argument.
 436             void transfer(dictionary&);
 437
 438             //- Transfer contents to the Xfer container
 439             Xfer<dictionary> xfer();
 440
 441
 442         // Read
 443
 444             //- Read dictionary from Istream
 445             bool read(Istream&);
 446
 447
 448         // Write
 449
 450             void write(Ostream&, bool subDict = true) const;
 451
 452
 453     // Member Operators
 454
 455         //- Find and return entry
 456         ITstream& operator[](const word&) const;
 457
 458         void operator=(const dictionary&);
 459
 460         //- Include entries from the given dictionary.
 461         //  Warn, but do not overwrite existing entries.
 462         void operator+=(const dictionary&);
 463
 464         //- Conditionally include entries from the given dictionary.
 465         //  Do not overwrite existing entries.
 466         void operator|=(const dictionary&);
 467
 468         //- Unconditionally include entries from the given dictionary.
 469         //  Overwrite existing entries.
 470         void operator<<=(const dictionary&);
 471
 472
 473     // IOstream operators
 474
 475         //- Read dictionary from Istream
 476         friend Istream& operator>>(Istream&, dictionary&);
 477
 478         //- Write dictionary to Ostream
 479         friend Ostream& operator<<(Ostream&, const dictionary&);
 480 };
 481
 482
 483 // Global Operators
 484
 485 //- Combine dictionaries.
 486 //  Starting from the entries in dict1 and then including those from dict2.
 487 //  Warn, but do not overwrite the entries from dict1.
 488 dictionary operator+(const dictionary& dict1, const dictionary& dict2);
 489
 490 //- Combine dictionaries.
 491 //  Starting from the entries in dict1 and then including those from dict2.
 492 //  Do not overwrite the entries from dict1.
 493 dictionary operator|(const dictionary& dict1, const dictionary& dict2);
 494
 495
 496 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 497
 498 } // End namespace Foam
 499
 500 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 501
 502 #ifdef NoRepository
 503 #   include "dictionaryTemplates.C"
 504 #endif
 505
 506 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 507
 508 #endif
 509
 510 // ************************************************************************* //