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-2015 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  //- Search patterns table for exact match or regular expression match
165  bool findInPatterns
166  (
167  const bool patternMatch,
168  const word& Keyword,
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,
178  DLList<entry*>::iterator& wcLink,
179  DLList<autoPtr<regExp> >::iterator& reLink
180  );
181 
182 
183 public:
184 
185  //- Declare friendship with the entry class for IO
186  friend class entry;
187 
188 
189  // Declare name of the class and its debug switch
190  ClassName("dictionary");
191 
192 
193  //- Null dictionary
194  static const dictionary null;
195 
196 
197  // Constructors
198 
199  //- Construct top-level dictionary null
200  dictionary();
201 
202  //- Construct top-level empty dictionary with given name
203  dictionary(const fileName& name);
204 
205  //- Construct given the entry name, parent dictionary and Istream,
206  // reading entries until lastEntry or EOF
207  dictionary
208  (
209  const fileName& name,
210  const dictionary& parentDict,
211  Istream&
212  );
213 
214  //- Construct top-level dictionary from Istream,
215  // reading entries until EOF
217 
218  //- Construct top-level dictionary from Istream,
219  // reading entries until EOF, optionally keeping the header
220  dictionary(Istream&, const bool keepHeader);
221 
222  //- Construct as copy given the parent dictionary
223  dictionary(const dictionary& parentDict, const dictionary&);
224 
225  //- Construct top-level dictionary as copy
226  dictionary(const dictionary&);
227 
228  //- Construct top-level dictionary as copy from pointer to dictionary.
229  // A null pointer is treated like an empty dictionary.
230  dictionary(const dictionary*);
231 
232  //- Construct by transferring parameter contents given parent dictionary
233  dictionary(const dictionary& parentDict, const Xfer<dictionary>&);
234 
235  //- Construct top-level dictionary by transferring parameter contents
237 
238  //- Construct and return clone
239  autoPtr<dictionary> clone() const;
240 
241  //- Construct top-level dictionary on freestore from Istream
243 
244 
245  //- Destructor
246  virtual ~dictionary();
247 
248 
249  // Member functions
250 
251  //- Return the parent dictionary
252  const dictionary& parent() const
253  {
254  return parent_;
255  }
256 
257  //- Return the top of the tree
258  const dictionary& topDict() const;
259 
260  //- Return line number of first token in dictionary
261  label startLineNumber() const;
262 
263  //- Return line number of last token in dictionary
264  label endLineNumber() const;
265 
266  //- Return the SHA1 digest of the dictionary contents
267  SHA1Digest digest() const;
268 
269  //- Return the dictionary as a list of tokens
270  tokenList tokens() const;
271 
272 
273  // Search and lookup
274 
275  //- Search dictionary for given keyword
276  // If recursive, search parent dictionaries
277  // If patternMatch, use regular expressions
278  bool found
279  (
280  const word&,
281  bool recursive=false,
282  bool patternMatch = true
283  ) const;
284 
285  //- Find and return an entry data stream pointer if present
286  // otherwise return NULL.
287  // If recursive, search parent dictionaries.
288  // If patternMatch, use regular expressions
289  const entry* lookupEntryPtr
290  (
291  const word&,
292  bool recursive,
293  bool patternMatch
294  ) const;
295 
296  //- Find and return an entry data stream pointer for manipulation
297  // if present otherwise return NULL.
298  // If recursive, search parent dictionaries.
299  // If patternMatch, use regular expressions.
300  entry* lookupEntryPtr
301  (
302  const word&,
303  bool recursive,
304  bool patternMatch
305  );
306 
307  //- Find and return an entry data stream if present otherwise error.
308  // If recursive, search parent dictionaries.
309  // If patternMatch, use regular expressions.
310  const entry& lookupEntry
311  (
312  const word&,
313  bool recursive,
314  bool patternMatch
315  ) const;
316 
317  //- Find and return an entry data stream
318  // If recursive, search parent dictionaries.
319  // If patternMatch, use regular expressions.
321  (
322  const word&,
323  bool recursive=false,
324  bool patternMatch=true
325  ) const;
326 
327  //- Find and return a T,
328  // if not found return the given default value
329  // If recursive, search parent dictionaries.
330  // If patternMatch, use regular expressions.
331  template<class T>
332  T lookupOrDefault
333  (
334  const word&,
335  const T&,
336  bool recursive=false,
337  bool patternMatch=true
338  ) const;
339 
340  //- Find and return a T, if not found return the given
341  // default value, and add to dictionary.
342  // If recursive, search parent dictionaries.
343  // If patternMatch, use regular expressions.
344  template<class T>
345  T lookupOrAddDefault
346  (
347  const word&,
348  const T&,
349  bool recursive=false,
350  bool patternMatch=true
351  );
352 
353  //- Find an entry if present, and assign to T
354  // Returns true if the entry was found.
355  // If recursive, search parent dictionaries.
356  // If patternMatch, use regular expressions.
357  template<class T>
358  bool readIfPresent
359  (
360  const word&,
361  T&,
362  bool recursive=false,
363  bool patternMatch=true
364  ) const;
365 
366  //- Find and return an entry data stream pointer if present
367  // otherwise return NULL. Allows scoping using '.'
368  const entry* lookupScopedEntryPtr
369  (
370  const word&,
371  bool recursive,
372  bool patternMatch
373  ) const;
374 
375  //- Check if entry is a sub-dictionary
376  bool isDict(const word&) const;
377 
378  //- Find and return a sub-dictionary pointer if present
379  // otherwise return NULL.
380  const dictionary* subDictPtr(const word&) const;
381 
382  //- Find and return a sub-dictionary
383  const dictionary& subDict(const word&) const;
384 
385  //- Find and return a sub-dictionary for manipulation
386  dictionary& subDict(const word&);
387 
388  //- Find and return a sub-dictionary as a copy, or
389  // return an empty dictionary if the sub-dictionary does not exist
390  dictionary subOrEmptyDict
391  (
392  const word&,
393  const bool mustRead = false
394  ) const;
395 
396  //- Return the table of contents
397  wordList toc() const;
398 
399  //- Return the list of available keys or patterns
400  List<keyType> keys(bool patterns=false) const;
401 
402 
403  // Editing
404 
405  //- Substitute the given keyword prepended by '$' with the
406  // corresponding sub-dictionary entries
407  bool substituteKeyword(const word& keyword);
408 
409  //- Substitute the given scoped keyword prepended by '$' with the
410  // corresponding sub-dictionary entries
411  bool substituteScopedKeyword(const word& keyword);
412 
413  //- Add a new entry
414  // With the merge option, dictionaries are interwoven and
415  // primitive entries are overwritten
416  bool add(entry*, bool mergeEntry=false);
417 
418  //- Add an entry
419  // With the merge option, dictionaries are interwoven and
420  // primitive entries are overwritten
421  void add(const entry&, bool mergeEntry=false);
422 
423  //- Add a word entry
424  // optionally overwrite an existing entry
425  void add(const keyType&, const word&, bool overwrite=false);
426 
427  //- Add a string entry
428  // optionally overwrite an existing entry
429  void add(const keyType&, const string&, bool overwrite=false);
430 
431  //- Add a label entry
432  // optionally overwrite an existing entry
433  void add(const keyType&, const label, bool overwrite=false);
434 
435  //- Add a scalar entry
436  // optionally overwrite an existing entry
437  void add(const keyType&, const scalar, bool overwrite=false);
438 
439  //- Add a dictionary entry
440  // optionally merge with an existing sub-dictionary
441  void add
442  (
443  const keyType&,
444  const dictionary&,
445  bool mergeEntry=false
446  );
447 
448  //- Add a T entry
449  // optionally overwrite an existing entry
450  template<class T>
451  void add(const keyType&, const T&, bool overwrite=false);
452 
453  //- Assign a new entry, overwrite any existing entry
454  void set(entry*);
455 
456  //- Assign a new entry, overwrite any existing entry
457  void set(const entry&);
458 
459  //- Assign a dictionary entry, overwrite any existing entry
460  void set(const keyType&, const dictionary&);
461 
462  //- Assign a T entry, overwrite any existing entry
463  template<class T>
464  void set(const keyType&, const T&);
465 
466  //- Remove an entry specified by keyword
467  bool remove(const word&);
468 
469  //- Change the keyword for an entry,
470  // optionally forcing overwrite of an existing entry
471  bool changeKeyword
472  (
473  const keyType& oldKeyword,
474  const keyType& newKeyword,
475  bool forceOverwrite=false
476  );
477 
478  //- Merge entries from the given dictionary.
479  // Also merge sub-dictionaries as required.
480  bool merge(const dictionary&);
481 
482  //- Clear the dictionary
483  void clear();
484 
485  //- Transfer the contents of the argument and annul the argument.
486  void transfer(dictionary&);
487 
488  //- Transfer contents to the Xfer container
489  Xfer<dictionary> xfer();
490 
491 
492  // Read
493 
494  //- Read dictionary from Istream
495  bool read(Istream&);
496 
497  //- Read dictionary from Istream, optionally keeping the header
498  bool read(Istream&, const bool keepHeader);
499 
500 
501  // Write
502 
503  //- Write dictionary, normally with sub-dictionary formatting
504  void write(Ostream&, const bool subDict=true) const;
505 
506 
507  // Member Operators
508 
509  //- Find and return entry
510  ITstream& operator[](const word&) const;
511 
512  void operator=(const dictionary&);
513 
514  //- Include entries from the given dictionary.
515  // Warn, but do not overwrite existing entries.
516  void operator+=(const dictionary&);
517 
518  //- Conditionally include entries from the given dictionary.
519  // Do not overwrite existing entries.
520  void operator|=(const dictionary&);
521 
522  //- Unconditionally include entries from the given dictionary.
523  // Overwrite existing entries.
524  void operator<<=(const dictionary&);
525 
526 
527  // IOstream operators
528 
529  //- Read dictionary from Istream
530  friend Istream& operator>>(Istream&, dictionary&);
531 
532  //- Write dictionary to Ostream
533  friend Ostream& operator<<(Ostream&, const dictionary&);
534 };
535 
536 
537 // Global Operators
538 
539 //- Combine dictionaries.
540 // Starting from the entries in dict1 and then including those from dict2.
541 // Warn, but do not overwrite the entries from dict1.
542 dictionary operator+(const dictionary& dict1, const dictionary& dict2);
543 
544 //- Combine dictionaries.
545 // Starting from the entries in dict1 and then including those from dict2.
546 // Do not overwrite the entries from dict1.
547 dictionary operator|(const dictionary& dict1, const dictionary& dict2);
548 
549 
550 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
551 
552 } // End namespace Foam
553 
554 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
555 
556 #ifdef NoRepository
557 # include "dictionaryTemplates.C"
558 #endif
559 
560 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
561 
562 #endif
563 
564 // ************************************************************************* //
word name() const
Return file name (part beyond last /)
Definition: fileName.C:206
Input token stream.
Definition: ITstream.H:49
void T(FieldField< Field, Type > &f1, const FieldField< Field, Type > &f2)
tmp< fvMatrix< Type > > operator+(const fvMatrix< Type > &, const fvMatrix< Type > &)
An STL-conforming hash table.
Definition: HashTable.H:61
An Istream is an abstract base class for all input systems (streams, files, token lists etc)...
Definition: Istream.H:57
A simple container for copying or transferring objects of type <T>.
Definition: Xfer.H:85
dictionaryName()
Construct dictionaryName null.
Definition: dictionary.H:90
A class for handling words, derived from string.
Definition: word.H:59
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
const fileName & name() const
Return the dictionary name.
Definition: dictionary.H:103
A list of keyword definitions, which are a keyword followed by any number of values (e...
Definition: dictionary.H:137
Ostream & operator<<(Ostream &, const edgeMesh &)
Definition: edgeMeshIO.C:133
Intrusive doubly-linked list.
Definition: IDLList.H:47
Namespace for OpenFOAM.
autoPtr< BasicCompressibleTurbulenceModel > New(const volScalarField &rho, const volVectorField &U, const surfaceScalarField &phi, const typename BasicCompressibleTurbulenceModel::transportModel &transport, const word &propertiesName)
A class for handling keywords in dictionaries.
Definition: keyType.H:56
runTime write()
#define ClassName(TypeNameString)
Add typeName information from argument TypeNameString to a class.
Definition: className.H:69
graph_traits< Graph >::vertices_size_type size_type
Definition: SloanRenumber.C:73
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
Macro definitions for declaring ClassName(), NamespaceName(), etc.
stressControl lookup("compactNormalStress") >> compactNormalStress
An STL-conforming const_iterator.
Definition: DLListBase.H:228
Non-intrusive doubly-linked list.
Definition: DLList.H:47
bool found
A keyword and a list of tokens is an &#39;entry&#39;.
Definition: entry.H:65
HashSet< Key, Hash > operator|(const HashSet< Key, Hash > &hash1, const HashSet< Key, Hash > &hash2)
Combine entries from HashSets.
A class for handling file names.
Definition: fileName.H:69
Istream & operator>>(Istream &, edgeMesh &)
Definition: edgeMeshIO.C:144
An Ostream is an abstract base class for all output systems (streams, files, token lists...
Definition: Ostream.H:53
bool read(const char *, int32_t &)
Definition: int32IO.C:87
An STL-conforming iterator.
Definition: DLListBase.H:181
const word dictName() const
Return the local dictionary name (final part of scoped name)
Definition: dictionary.H:115
UEqn clear()
The SHA1 message digest.
Definition: SHA1Digest.H:62
void add(FieldField< Field1, typename typeOfSum< Type1, Type2 >::type > &f, const FieldField< Field1, Type1 > &f1, const FieldField< Field2, Type2 > &f2)
An auto-pointer similar to the STL auto_ptr but with automatic casting to a reference to the type and...
Definition: PtrList.H:117