dictionary.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-2019 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::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  To add - a merge() member function with a non-const dictionary parameter?
42  This would avoid unnecessary cloning in the add(entry*, bool) method.
43 
44 SourceFiles
45  dictionary.C
46  dictionaryIO.C
47 
48 \*---------------------------------------------------------------------------*/
49 
50 #ifndef dictionary_H
51 #define dictionary_H
52 
53 #include "entry.H"
54 #include "IDLList.H"
55 #include "DLList.H"
56 #include "fileName.H"
57 #include "ITstream.H"
58 #include "HashTable.H"
59 #include "wordList.H"
60 #include "className.H"
61 
62 #include "VectorSpace.H"
63 
64 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
65 
66 namespace Foam
67 {
68 
69 // Forward declaration of friend functions and operators
70 class regExp;
71 class dictionary;
72 class SHA1Digest;
73 
74 Istream& operator>>(Istream&, dictionary&);
75 Ostream& operator<<(Ostream&, const dictionary&);
76 
77 /*---------------------------------------------------------------------------*\
78  Class dictionaryName Declaration
79 \*---------------------------------------------------------------------------*/
80 
81 class dictionaryName
82 {
83  // Private Data
84 
85  fileName name_;
86 
87 
88 public:
89 
90  // Constructors
91 
92  //- Construct dictionaryName null
94  {}
95 
96  //- Construct dictionaryName as copy of the given fileName
98  :
99  name_(name)
100  {}
101 
102  //- Move constructor
104  :
105  name_(move(name.name_))
106  {}
107 
108 
109  // Member Functions
110 
111  //- Return the dictionary name
112  const fileName& name() const
113  {
114  return name_;
115  }
116 
117  //- Return the dictionary name
118  fileName& name()
119  {
120  return name_;
121  }
122 
123  //- Return the local dictionary name (final part of scoped name)
124  const word dictName() const
125  {
126  const word scopedName = name_.name();
127 
128  string::size_type i = scopedName.rfind('.');
129 
130  if (i == scopedName.npos)
131  {
132  return scopedName;
133  }
134  else
135  {
136  return scopedName.substr(i + 1, scopedName.npos);
137  }
138  }
139 
140 
141  // Member Operators
143  void operator=(const dictionaryName& name)
144  {
145  name_ = name.name_;
146  }
149  {
150  name_ = move(name.name_);
151  }
152 };
153 
154 
155 /*---------------------------------------------------------------------------*\
156  Class dictionary Declaration
157 \*---------------------------------------------------------------------------*/
159 class dictionary
160 :
161  public dictionaryName,
162  public IDLList<entry>
163 {
164  // Private Data
165 
166  //- If true write optional keywords and values
167  // if not present in dictionary
168  static bool writeOptionalEntries;
169 
170  //- HashTable of the entries held on the DL-list for quick lookup
171  HashTable<entry*> hashedEntries_;
172 
173  //- Parent dictionary
174  const dictionary& parent_;
175 
176  //- Entries of matching patterns
177  DLList<entry*> patternEntries_;
178 
179  //- Patterns as precompiled regular expressions
180  DLList<autoPtr<regExp>> patternRegexps_;
181 
182 
183  // Private Member Functions
184 
185  //- Find and return an entry data stream pointer if present
186  // otherwise return nullptr. Allows scoping using '.'
187  const entry* lookupScopedSubEntryPtr
188  (
189  const word&,
190  bool recursive,
191  bool patternMatch
192  ) const;
193 
194  //- Search patterns table for exact match or regular expression match
195  bool findInPatterns
196  (
197  const bool patternMatch,
198  const word& Keyword,
201  ) const;
202 
203  //- Search patterns table for exact match or regular expression match
204  bool findInPatterns
205  (
206  const bool patternMatch,
207  const word& Keyword,
208  DLList<entry*>::iterator& wcLink,
210  );
211 
212 
213 public:
214 
215  //- Declare friendship with the entry class for IO
216  friend class entry;
217 
218 
219  // Declare name of the class and its debug switch
220  ClassName("dictionary");
221 
222 
223  //- Null dictionary
224  static const dictionary null;
225 
226 
227  // Constructors
228 
229  //- Construct top-level dictionary null
230  dictionary();
231 
232  //- Construct top-level empty dictionary with given name
233  dictionary(const fileName& name);
234 
235  //- Construct given the entry name, parent dictionary and Istream,
236  // reading entries until lastEntry or EOF
237  dictionary
238  (
239  const fileName& name,
240  const dictionary& parentDict,
241  Istream&
242  );
243 
244  //- Construct top-level dictionary from Istream,
245  // reading entries until EOF
247 
248  //- Construct top-level dictionary from Istream,
249  // reading entries until EOF, optionally keeping the header
250  dictionary(Istream&, const bool keepHeader);
251 
252  //- Construct as copy given the parent dictionary
253  dictionary(const dictionary& parentDict, const dictionary&);
254 
255  //- Construct top-level dictionary as copy
256  dictionary(const dictionary&);
257 
258  //- Construct top-level dictionary as copy from pointer to dictionary.
259  // A null pointer is treated like an empty dictionary.
260  dictionary(const dictionary*);
261 
262  //- Move constructor transferring parameter contents
263  // given parent dictionary
264  dictionary(const dictionary& parentDict, dictionary&&);
265 
266  //- Move constructor
268 
269  //- Construct and return clone
270  autoPtr<dictionary> clone() const;
271 
272  //- Construct top-level dictionary on freestore from Istream
274 
275 
276  //- Destructor
277  virtual ~dictionary();
278 
279 
280  // Member Functions
281 
282  //- Return the parent dictionary
283  const dictionary& parent() const
284  {
285  return parent_;
286  }
287 
288  //- Return whether this dictionary is null
289  bool isNull() const
290  {
291  return this == &null;
292  }
293 
294  //- Return the top of the tree
295  const dictionary& topDict() const;
296 
297  //- Return line number of first token in dictionary
298  label startLineNumber() const;
299 
300  //- Return line number of last token in dictionary
301  label endLineNumber() const;
302 
303  //- Return the SHA1 digest of the dictionary contents
304  SHA1Digest digest() const;
305 
306  //- Return the dictionary as a list of tokens
307  tokenList tokens() const;
308 
309 
310  // Search and lookup
311 
312  //- Search dictionary for given keyword
313  // If recursive, search parent dictionaries
314  // If patternMatch, use regular expressions
315  bool found
316  (
317  const word&,
318  bool recursive=false,
319  bool patternMatch = true
320  ) const;
321 
322  //- Find and return an entry data stream pointer if present
323  // otherwise return nullptr.
324  // If recursive, search parent dictionaries.
325  // If patternMatch, use regular expressions
326  const entry* lookupEntryPtr
327  (
328  const word&,
329  bool recursive,
330  bool patternMatch
331  ) const;
332 
333  //- Find and return an entry data stream pointer for manipulation
334  // if present otherwise return nullptr.
335  // If recursive, search parent dictionaries.
336  // If patternMatch, use regular expressions.
337  entry* lookupEntryPtr
338  (
339  const word&,
340  bool recursive,
341  bool patternMatch
342  );
343 
344  //- Find and return an entry data stream if present otherwise error.
345  // If recursive, search parent dictionaries.
346  // If patternMatch, use regular expressions.
347  const entry& lookupEntry
348  (
349  const word&,
350  bool recursive,
351  bool patternMatch
352  ) const;
353 
354  //- Find and return an entry data stream
355  // If recursive, search parent dictionaries.
356  // If patternMatch, use regular expressions.
358  (
359  const word&,
360  bool recursive=false,
361  bool patternMatch=true
362  ) const;
363 
364  //- Find and return a T,
365  // if not found throw a fatal error.
366  // If recursive, search parent dictionaries.
367  // If patternMatch, use regular expressions.
368  template<class T>
369  T lookupType
370  (
371  const word&,
372  bool recursive=false,
373  bool patternMatch=true
374  ) const;
375 
376  //- Find and return a T,
377  // if not found return the given default value.
378  // If recursive, search parent dictionaries.
379  // If patternMatch, use regular expressions.
380  template<class T>
381  T lookupOrDefault
382  (
383  const word&,
384  const T&,
385  bool recursive=false,
386  bool patternMatch=true
387  ) const;
388 
389  //- Find and return a T, if not found return the given
390  // default value, and add to dictionary.
391  // If recursive, search parent dictionaries.
392  // If patternMatch, use regular expressions.
393  template<class T>
394  T lookupOrAddDefault
395  (
396  const word&,
397  const T&,
398  bool recursive=false,
399  bool patternMatch=true
400  );
401 
402  //- Find an entry if present, and assign to T
403  // Returns true if the entry was found.
404  // If recursive, search parent dictionaries.
405  // If patternMatch, use regular expressions.
406  template<class T>
407  bool readIfPresent
408  (
409  const word&,
410  T&,
411  bool recursive=false,
412  bool patternMatch=true
413  ) const;
414 
415  //- Find and return an entry data stream pointer if present
416  // otherwise return nullptr. Allows scoping using '.'.
417  // Special handling for ':' at start of keyword and '..'.
418  const entry* lookupScopedEntryPtr
419  (
420  const word&,
421  bool recursive,
422  bool patternMatch
423  ) const;
424 
425  //- Check if entry is a sub-dictionary
426  bool isDict(const word&) const;
427 
428  //- Find and return a sub-dictionary pointer if present
429  // otherwise return nullptr.
430  const dictionary* subDictPtr(const word&) const;
431 
432  //- Find and return a sub-dictionary pointer if present
433  // otherwise return nullptr.
434  dictionary* subDictPtr(const word&);
435 
436  //- Find and return a sub-dictionary
437  const dictionary& subDict(const word&) const;
438 
439  //- Find and return a sub-dictionary for manipulation
440  dictionary& subDict(const word&);
441 
442  //- Find and return a sub-dictionary as a copy, or
443  // return an empty dictionary if the sub-dictionary does not exist
444  dictionary subOrEmptyDict
445  (
446  const word&,
447  const bool mustRead = false
448  ) const;
449 
450  //- Find and return a sub-dictionary if found
451  // otherwise return this dictionary
452  const dictionary& optionalSubDict(const word&) const;
453 
454  //- Return the table of contents
455  wordList toc() const;
456 
457  //- Return the sorted table of contents
458  wordList sortedToc() const;
459 
460  //- Return the list of available keys or patterns
461  List<keyType> keys(bool patterns=false) const;
462 
463 
464  // Editing
465 
466  //- Substitute the given keyword prepended by '$' with the
467  // corresponding sub-dictionary entries
468  bool substituteKeyword(const word& keyword);
469 
470  //- Substitute the given scoped keyword prepended by '$' with the
471  // corresponding sub-dictionary entries
472  bool substituteScopedKeyword(const word& keyword);
473 
474  //- Add a new entry
475  // With the merge option, dictionaries are interwoven and
476  // primitive entries are overwritten
477  bool add(entry*, bool mergeEntry=false);
478 
479  //- Add an entry
480  // With the merge option, dictionaries are interwoven and
481  // primitive entries are overwritten
482  void add(const entry&, bool mergeEntry=false);
483 
484  //- Add a word entry
485  // optionally overwrite an existing entry
486  void add(const keyType&, const word&, bool overwrite=false);
487 
488  //- Add a string entry
489  // optionally overwrite an existing entry
490  void add(const keyType&, const string&, bool overwrite=false);
491 
492  //- Add a label entry
493  // optionally overwrite an existing entry
494  void add(const keyType&, const label, bool overwrite=false);
495 
496  //- Add a scalar entry
497  // optionally overwrite an existing entry
498  void add(const keyType&, const scalar, bool overwrite=false);
499 
500  //- Add a dictionary entry
501  // optionally merge with an existing sub-dictionary
502  void add
503  (
504  const keyType&,
505  const dictionary&,
506  bool mergeEntry=false
507  );
508 
509  //- Add a T entry
510  // optionally overwrite an existing entry
511  template<class T>
512  void add(const keyType&, const T&, bool overwrite=false);
513 
514  //- Assign a new entry, overwrite any existing entry
515  void set(entry*);
516 
517  //- Assign a new entry, overwrite any existing entry
518  void set(const entry&);
519 
520  //- Assign a dictionary entry, overwrite any existing entry
521  void set(const keyType&, const dictionary&);
522 
523  //- Assign a T entry, overwrite any existing entry
524  template<class T>
525  void set(const keyType&, const T&);
526 
527  //- Remove an entry specified by keyword
528  bool remove(const word&);
529 
530  //- Change the keyword for an entry,
531  // optionally forcing overwrite of an existing entry
532  bool changeKeyword
533  (
534  const keyType& oldKeyword,
535  const keyType& newKeyword,
536  bool forceOverwrite=false
537  );
538 
539  //- Merge entries from the given dictionary.
540  // Also merge sub-dictionaries as required.
541  bool merge(const dictionary&);
542 
543  //- Clear the dictionary
544  void clear();
545 
546  //- Transfer the contents of the argument and annul the argument.
547  void transfer(dictionary&);
548 
549 
550  // Read
551 
552  //- Read dictionary from Istream
553  bool read(Istream&);
554 
555  //- Read dictionary from Istream, optionally keeping the header
556  bool read(Istream&, const bool keepHeader);
557 
558 
559  // Write
560 
561  //- Write dictionary, normally with sub-dictionary formatting
562  void write(Ostream&, const bool subDict=true) const;
563 
564 
565  // Member Operators
566 
567  //- Find and return entry
568  ITstream& operator[](const word&) const;
569 
570  void operator=(const dictionary&);
571 
572  void operator=(dictionary&&);
573 
574  //- Include entries from the given dictionary.
575  // Warn, but do not overwrite existing entries.
576  void operator+=(const dictionary&);
577 
578  //- Conditionally include entries from the given dictionary.
579  // Do not overwrite existing entries.
580  void operator|=(const dictionary&);
581 
582  //- Unconditionally include entries from the given dictionary.
583  // Overwrite existing entries.
584  void operator<<=(const dictionary&);
585 
586 
587  // IOstream Operators
588 
589  //- Read dictionary from Istream
590  friend Istream& operator>>(Istream&, dictionary&);
591 
592  //- Write dictionary to Ostream
593  friend Ostream& operator<<(Ostream&, const dictionary&);
594 };
595 
596 
597 // Global Operators
598 
599 //- Combine dictionaries.
600 // Starting from the entries in dict1 and then including those from dict2.
601 // Warn, but do not overwrite the entries from dict1.
602 dictionary operator+(const dictionary& dict1, const dictionary& dict2);
603 
604 //- Combine dictionaries.
605 // Starting from the entries in dict1 and then including those from dict2.
606 // Do not overwrite the entries from dict1.
607 dictionary operator|(const dictionary& dict1, const dictionary& dict2);
608 
609 
610 // Global Functions
611 
612 //- Write a dictionary entry
613 void writeEntry(Ostream& os, const dictionary& dict);
614 
615 //- Helper function to write the keyword and entry
616 template<class EntryType>
617 void writeEntry(Ostream& os, const word& entryName, const EntryType& value);
618 
619 //- Helper function to write the keyword and entry only if the
620 // values are not equal. The value is then output as value2
621 template<class EntryType>
623 (
624  Ostream& os,
625  const word& entryName,
626  const EntryType& value1,
627  const EntryType& value2
628 );
629 
630 
631 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
632 
633 } // End namespace Foam
634 
635 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
636 
637 #ifdef NoRepository
638  #include "dictionaryTemplates.C"
639 #endif
640 
641 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
642 
643 #endif
644 
645 // ************************************************************************* //
Template class for intrusive linked lists.
Definition: ILList.H:50
A class for handling keywords in dictionaries.
Definition: keyType.H:64
dictionary dict
HashSet< Key, Hash > operator|(const HashSet< Key, Hash > &hash1, const HashSet< Key, Hash > &hash2)
Combine entries from HashSets.
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
A list of keyword definitions, which are a keyword followed by any number of values (e...
Definition: dictionary.H:158
tUEqn clear()
A 1D array of objects of type <T>, where the size of the vector is known and used for subscript bound...
Definition: HashTable.H:59
Template class for non-intrusive linked lists.
Definition: LList.H:51
An Istream is an abstract base class for all input systems (streams, files, token lists etc)...
Definition: Istream.H:57
dictionaryName()
Construct dictionaryName null.
Definition: dictionary.H:92
void writeEntryIfDifferent(Ostream &os, const word &entryName, const EntryType &value1, const EntryType &value2)
Helper function to write the keyword and entry only if the.
An STL-conforming const_iterator.
Definition: LList.H:297
The SHA1 message digest.
Definition: SHA1Digest.H:62
An STL-conforming iterator.
Definition: LList.H:246
An STL-conforming const_iterator.
Definition: UILList.H:234
tmp< DimensionedField< TypeR, GeoMesh > > New(const tmp< DimensionedField< TypeR, GeoMesh >> &tdf1, const word &name, const dimensionSet &dimensions)
const word dictName() const
Return the local dictionary name (final part of scoped name)
Definition: dictionary.H:123
#define ClassName(TypeNameString)
Add typeName information from argument TypeNameString to a class.
Definition: className.H:65
void write(Ostream &, const label, const dictionary &)
Write with dictionary lookup.
bool read(const char *, int32_t &)
Definition: int32IO.C:85
stressControl lookup("compactNormalStress") >> compactNormalStress
T clone(const T &t)
Definition: List.H:54
bool isNull(const T &t)
Return true if t is a reference to the nullObject of type T.
Definition: nullObjectI.H:46
const fileName & name() const
Return the dictionary name.
Definition: dictionary.H:111
Intrusive doubly-linked list.
A class for handling words, derived from string.
Definition: word.H:59
Istream & operator>>(Istream &, directionInfo &)
word name() const
Return file name (part beyond last /)
Definition: fileName.C:183
An STL-conforming iterator.
Definition: UILList.H:185
tmp< fvMatrix< Type > > operator+(const fvMatrix< Type > &, const fvMatrix< Type > &)
An STL-conforming hash table.
Definition: HashTable.H:61
graph_traits< Graph >::vertices_size_type size_type
Definition: SloanRenumber.C:73
An Ostream is an abstract base class for all output systems (streams, files, token lists...
Definition: Ostream.H:53
void add(FieldField< Field1, typename typeOfSum< Type1, Type2 >::type > &f, const FieldField< Field1, Type1 > &f1, const FieldField< Field2, Type2 > &f2)
void T(FieldField< Field, Type > &f1, const FieldField< Field, Type > &f2)
void writeEntry(Ostream &os, const HashTable< T, Key, Hash > &ht)
Definition: HashTableIO.C:96
void operator=(const dictionaryName &name)
Definition: dictionary.H:142
Macro definitions for declaring ClassName(), NamespaceName(), etc.
Ostream & operator<<(Ostream &, const ensightPart &)
Non-intrusive doubly-linked list.
An auto-pointer similar to the STL auto_ptr but with automatic casting to a reference to the type and...
Definition: PtrList.H:52
bool found
Input token stream.
Definition: ITstream.H:49
Namespace for OpenFOAM.
A keyword and a list of tokens is an &#39;entry&#39;.
Definition: entry.H:65