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