dictionary.H
Go to the documentation of this file.
1 /*---------------------------------------------------------------------------*\
2  ========= |
3  \\ / F ield | OpenFOAM: The Open Source CFD Toolbox
4  \\ / O peration |
5  \\ / A nd | Copyright (C) 2011-2017 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 the top of the tree
267  const dictionary& topDict() const;
268 
269  //- Return line number of first token in dictionary
270  label startLineNumber() const;
271 
272  //- Return line number of last token in dictionary
273  label endLineNumber() const;
274 
275  //- Return the SHA1 digest of the dictionary contents
276  SHA1Digest digest() const;
277 
278  //- Return the dictionary as a list of tokens
279  tokenList tokens() const;
280 
281 
282  // Search and lookup
283 
284  //- Search dictionary for given keyword
285  // If recursive, search parent dictionaries
286  // If patternMatch, use regular expressions
287  bool found
288  (
289  const word&,
290  bool recursive=false,
291  bool patternMatch = true
292  ) const;
293 
294  //- Find and return an entry data stream pointer if present
295  // otherwise return nullptr.
296  // If recursive, search parent dictionaries.
297  // If patternMatch, use regular expressions
298  const entry* lookupEntryPtr
299  (
300  const word&,
301  bool recursive,
302  bool patternMatch
303  ) const;
304 
305  //- Find and return an entry data stream pointer for manipulation
306  // if present otherwise return nullptr.
307  // If recursive, search parent dictionaries.
308  // If patternMatch, use regular expressions.
309  entry* lookupEntryPtr
310  (
311  const word&,
312  bool recursive,
313  bool patternMatch
314  );
315 
316  //- Find and return an entry data stream if present otherwise error.
317  // If recursive, search parent dictionaries.
318  // If patternMatch, use regular expressions.
319  const entry& lookupEntry
320  (
321  const word&,
322  bool recursive,
323  bool patternMatch
324  ) const;
325 
326  //- Find and return an entry data stream
327  // If recursive, search parent dictionaries.
328  // If patternMatch, use regular expressions.
330  (
331  const word&,
332  bool recursive=false,
333  bool patternMatch=true
334  ) const;
335 
336  //- Find and return a T,
337  // if not found throw a fatal error.
338  // If recursive, search parent dictionaries.
339  // If patternMatch, use regular expressions.
340  template<class T>
341  T lookupType
342  (
343  const word&,
344  bool recursive=false,
345  bool patternMatch=true
346  ) const;
347 
348  //- Find and return a T,
349  // if not found return the given default value.
350  // If recursive, search parent dictionaries.
351  // If patternMatch, use regular expressions.
352  template<class T>
353  T lookupOrDefault
354  (
355  const word&,
356  const T&,
357  bool recursive=false,
358  bool patternMatch=true
359  ) const;
360 
361  //- Find and return a T, if not found return the given
362  // default value, and add to dictionary.
363  // If recursive, search parent dictionaries.
364  // If patternMatch, use regular expressions.
365  template<class T>
366  T lookupOrAddDefault
367  (
368  const word&,
369  const T&,
370  bool recursive=false,
371  bool patternMatch=true
372  );
373 
374  //- Find an entry if present, and assign to T
375  // Returns true if the entry was found.
376  // If recursive, search parent dictionaries.
377  // If patternMatch, use regular expressions.
378  template<class T>
379  bool readIfPresent
380  (
381  const word&,
382  T&,
383  bool recursive=false,
384  bool patternMatch=true
385  ) const;
386 
387  //- Find and return an entry data stream pointer if present
388  // otherwise return nullptr. Allows scoping using '.'.
389  // Special handling for ':' at start of keyword and '..'.
390  const entry* lookupScopedEntryPtr
391  (
392  const word&,
393  bool recursive,
394  bool patternMatch
395  ) const;
396 
397  //- Check if entry is a sub-dictionary
398  bool isDict(const word&) const;
399 
400  //- Find and return a sub-dictionary pointer if present
401  // otherwise return nullptr.
402  const dictionary* subDictPtr(const word&) const;
403 
404  //- Find and return a sub-dictionary pointer if present
405  // otherwise return nullptr.
406  dictionary* subDictPtr(const word&);
407 
408  //- Find and return a sub-dictionary
409  const dictionary& subDict(const word&) const;
410 
411  //- Find and return a sub-dictionary for manipulation
412  dictionary& subDict(const word&);
413 
414  //- Find and return a sub-dictionary as a copy, or
415  // return an empty dictionary if the sub-dictionary does not exist
416  dictionary subOrEmptyDict
417  (
418  const word&,
419  const bool mustRead = false
420  ) const;
421 
422  //- Find and return a sub-dictionary if found
423  // otherwise return this dictionary
424  const dictionary& optionalSubDict(const word&) const;
425 
426  //- Return the table of contents
427  wordList toc() const;
428 
429  //- Return the sorted table of contents
430  wordList sortedToc() const;
431 
432  //- Return the list of available keys or patterns
433  List<keyType> keys(bool patterns=false) const;
434 
435 
436  // Editing
437 
438  //- Substitute the given keyword prepended by '$' with the
439  // corresponding sub-dictionary entries
440  bool substituteKeyword(const word& keyword);
441 
442  //- Substitute the given scoped keyword prepended by '$' with the
443  // corresponding sub-dictionary entries
444  bool substituteScopedKeyword(const word& keyword);
445 
446  //- Add a new entry
447  // With the merge option, dictionaries are interwoven and
448  // primitive entries are overwritten
449  bool add(entry*, bool mergeEntry=false);
450 
451  //- Add an entry
452  // With the merge option, dictionaries are interwoven and
453  // primitive entries are overwritten
454  void add(const entry&, bool mergeEntry=false);
455 
456  //- Add a word entry
457  // optionally overwrite an existing entry
458  void add(const keyType&, const word&, bool overwrite=false);
459 
460  //- Add a string entry
461  // optionally overwrite an existing entry
462  void add(const keyType&, const string&, bool overwrite=false);
463 
464  //- Add a label entry
465  // optionally overwrite an existing entry
466  void add(const keyType&, const label, bool overwrite=false);
467 
468  //- Add a scalar entry
469  // optionally overwrite an existing entry
470  void add(const keyType&, const scalar, bool overwrite=false);
471 
472  //- Add a dictionary entry
473  // optionally merge with an existing sub-dictionary
474  void add
475  (
476  const keyType&,
477  const dictionary&,
478  bool mergeEntry=false
479  );
480 
481  //- Add a T entry
482  // optionally overwrite an existing entry
483  template<class T>
484  void add(const keyType&, const T&, bool overwrite=false);
485 
486  //- Assign a new entry, overwrite any existing entry
487  void set(entry*);
488 
489  //- Assign a new entry, overwrite any existing entry
490  void set(const entry&);
491 
492  //- Assign a dictionary entry, overwrite any existing entry
493  void set(const keyType&, const dictionary&);
494 
495  //- Assign a T entry, overwrite any existing entry
496  template<class T>
497  void set(const keyType&, const T&);
498 
499  //- Remove an entry specified by keyword
500  bool remove(const word&);
501 
502  //- Change the keyword for an entry,
503  // optionally forcing overwrite of an existing entry
504  bool changeKeyword
505  (
506  const keyType& oldKeyword,
507  const keyType& newKeyword,
508  bool forceOverwrite=false
509  );
510 
511  //- Merge entries from the given dictionary.
512  // Also merge sub-dictionaries as required.
513  bool merge(const dictionary&);
514 
515  //- Clear the dictionary
516  void clear();
517 
518  //- Transfer the contents of the argument and annul the argument.
519  void transfer(dictionary&);
520 
521  //- Transfer contents to the Xfer container
522  Xfer<dictionary> xfer();
523 
524 
525  // Read
526 
527  //- Read dictionary from Istream
528  bool read(Istream&);
529 
530  //- Read dictionary from Istream, optionally keeping the header
531  bool read(Istream&, const bool keepHeader);
532 
533 
534  // Write
535 
536  //- Write dictionary, normally with sub-dictionary formatting
537  void write(Ostream&, const bool subDict=true) const;
538 
539 
540  // Member Operators
541 
542  //- Find and return entry
543  ITstream& operator[](const word&) const;
544 
545  void operator=(const dictionary&);
546 
547  //- Include entries from the given dictionary.
548  // Warn, but do not overwrite existing entries.
549  void operator+=(const dictionary&);
550 
551  //- Conditionally include entries from the given dictionary.
552  // Do not overwrite existing entries.
553  void operator|=(const dictionary&);
554 
555  //- Unconditionally include entries from the given dictionary.
556  // Overwrite existing entries.
557  void operator<<=(const dictionary&);
558 
559 
560  // IOstream operators
561 
562  //- Read dictionary from Istream
563  friend Istream& operator>>(Istream&, dictionary&);
564 
565  //- Write dictionary to Ostream
566  friend Ostream& operator<<(Ostream&, const dictionary&);
567 };
568 
569 
570 // Global Operators
571 
572 //- Combine dictionaries.
573 // Starting from the entries in dict1 and then including those from dict2.
574 // Warn, but do not overwrite the entries from dict1.
575 dictionary operator+(const dictionary& dict1, const dictionary& dict2);
576 
577 //- Combine dictionaries.
578 // Starting from the entries in dict1 and then including those from dict2.
579 // Do not overwrite the entries from dict1.
580 dictionary operator|(const dictionary& dict1, const dictionary& dict2);
581 
582 
583 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
584 
585 } // End namespace Foam
586 
587 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
588 
589 #ifdef NoRepository
590  #include "dictionaryTemplates.C"
591 #endif
592 
593 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
594 
595 #endif
596 
597 // ************************************************************************* //
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:69
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
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:180
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