FreeFOAM The Cross-Platform CFD Toolkit
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) 1991-2010 OpenCFD Ltd.
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 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 <OpenFOAM/entry.H>
55 #include <OpenFOAM/IDLList.H>
56 #include <OpenFOAM/DLList.H>
57 #include <OpenFOAM/fileName.H>
58 #include <OpenFOAM/ITstream.H>
59 #include <OpenFOAM/HashTable.H>
60 #include <OpenFOAM/wordList.H>
61 #include <OpenFOAM/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 
81 {
82  // Private data
83 
84  fileName name_;
85 
86 
87 public:
88 
89  // Constructors
90 
91  //- Construct dictionaryName null
93  {}
94 
95  //- Construct dictionaryName as copy of the given fileName
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
112  {
113  return name_;
114  }
115 };
116 
117 
118 /*---------------------------------------------------------------------------*\
119  Class dictionary Declaration
120 \*---------------------------------------------------------------------------*/
121 
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,
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
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 given parent dictionary
209  dictionary(const dictionary& parentDict, const Xfer<dictionary>&);
210 
211  //- Construct top-level dictionary by transferring parameter contents
213 
214  //- Construct and return clone
215  autoPtr<dictionary> clone() const;
216 
217  //- Construct top-level dictionary on freestore from Istream
219 
220 
221  // Destructor
222 
223  ~dictionary();
224 
225 
226  // Member functions
227 
228  //- Return the parent dictionary
229  const dictionary& parent() const
230  {
231  return parent_;
232  }
233 
234  //- Return line number of first token in dictionary
235  label startLineNumber() const;
236 
237  //- Return line number of last token in dictionary
238  label endLineNumber() const;
239 
240  //- Return the SHA1 digest of the dictionary contents
241  SHA1Digest digest() const;
242 
243 
244  // Search and lookup
245 
246  //- Search dictionary for given keyword
247  // If recursive, search parent dictionaries
248  bool found(const word&, bool recursive=false) const;
249 
250  //- Find and return an entry data stream pointer if present
251  // otherwise return NULL.
252  // If recursive, search parent dictionaries.
253  // If patternMatch, use regular expressions
254  const entry* lookupEntryPtr
255  (
256  const word&,
257  bool recursive,
258  bool patternMatch
259  ) const;
260 
261  //- Find and return an entry data stream pointer for manipulation
262  // if present otherwise return NULL.
263  // If recursive, search parent dictionaries.
264  // If patternMatch, use regular expressions.
266  (
267  const word&,
268  bool recursive,
269  bool patternMatch
270  );
271 
272  //- Find and return an entry data stream if present otherwise error.
273  // If recursive, search parent dictionaries.
274  // If patternMatch, use regular expressions.
275  const entry& lookupEntry
276  (
277  const word&,
278  bool recursive,
279  bool patternMatch
280  ) const;
281 
282  //- Find and return an entry data stream
283  // If recursive, search parent dictionaries.
284  // If patternMatch, use regular expressions.
286  (
287  const word&,
288  bool recursive=false,
289  bool patternMatch=true
290  ) const;
291 
292  //- Find and return a T,
293  // if not found return the given default value
294  // If recursive, search parent dictionaries.
295  // If patternMatch, use regular expressions.
296  template<class T>
298  (
299  const word&,
300  const T&,
301  bool recursive=false,
302  bool patternMatch=true
303  ) const;
304 
305  //- Find and return a T, if not found return the given
306  // default value, and add to dictionary.
307  // If recursive, search parent dictionaries.
308  // If patternMatch, use regular expressions.
309  template<class T>
311  (
312  const word&,
313  const T&,
314  bool recursive=false,
315  bool patternMatch=true
316  );
317 
318  //- Find an entry if present, and assign to T
319  // Returns true if the entry was found.
320  // If recursive, search parent dictionaries.
321  // If patternMatch, use regular expressions.
322  template<class T>
323  bool readIfPresent
324  (
325  const word&,
326  T&,
327  bool recursive=false,
328  bool patternMatch=true
329  ) const;
330 
331  //- Check if entry is a sub-dictionary
332  bool isDict(const word&) const;
333 
334  //- Find and return a sub-dictionary pointer if present
335  // otherwise return NULL.
336  const dictionary* subDictPtr(const word&) const;
337 
338  //- Find and return a sub-dictionary
339  const dictionary& subDict(const word&) const;
340 
341  //- Find and return a sub-dictionary for manipulation
342  dictionary& subDict(const word&);
343 
344  //- Find and return a sub-dictionary as a copy, or
345  // return an empty dictionary if the sub-dictionary does not exist
346  dictionary subOrEmptyDict(const word&) const;
347 
348  //- Return the table of contents
349  wordList toc() const;
350 
351  //- Return the list of available keys or patterns
352  List<keyType> keys(bool patterns=false) const;
353 
354 
355  // Editing
356 
357  //- Substitute the given keyword prepended by '$' with the
358  // corresponding sub-dictionary entries
359  bool substituteKeyword(const word& keyword);
360 
361  //- Add a new entry
362  // With the merge option, dictionaries are interwoven and
363  // primitive entries are overwritten
364  bool add(entry*, bool mergeEntry=false);
365 
366  //- Add an entry
367  // With the merge option, dictionaries are interwoven and
368  // primitive entries are overwritten
369  void add(const entry&, bool mergeEntry=false);
370 
371  //- Add a word entry
372  // optionally overwrite an existing entry
373  void add(const keyType&, const word&, bool overwrite=false);
374 
375  //- Add a string entry
376  // optionally overwrite an existing entry
377  void add(const keyType&, const string&, bool overwrite=false);
378 
379  //- Add a label entry
380  // optionally overwrite an existing entry
381  void add(const keyType&, const label, bool overwrite=false);
382 
383  //- Add a scalar entry
384  // optionally overwrite an existing entry
385  void add(const keyType&, const scalar, bool overwrite=false);
386 
387  //- Add a dictionary entry
388  // optionally merge with an existing sub-dictionary
389  void add
390  (
391  const keyType&,
392  const dictionary&,
393  bool mergeEntry=false
394  );
395 
396  //- Add a T entry
397  // optionally overwrite an existing entry
398  template<class T>
399  void add(const keyType&, const T&, bool overwrite=false);
400 
401  //- Assign a new entry, overwrite any existing entry
402  void set(entry*);
403 
404  //- Assign a new entry, overwrite any existing entry
405  void set(const entry&);
406 
407  //- Assign a dictionary entry, overwrite any existing entry
408  void set(const keyType&, const dictionary&);
409 
410  //- Assign a T entry, overwrite any existing entry
411  template<class T>
412  void set(const keyType&, const T&);
413 
414  //- Remove an entry specified by keyword
415  bool remove(const word&);
416 
417  //- Change the keyword for an entry,
418  // optionally forcing overwrite of an existing entry
419  bool changeKeyword
420  (
421  const keyType& oldKeyword,
422  const keyType& newKeyword,
423  bool forceOverwrite=false
424  );
425 
426  //- Merge entries from the given dictionary.
427  // Also merge sub-dictionaries as required.
428  bool merge(const dictionary&);
429 
430  //- Clear the dictionary
431  void clear();
432 
433  //- Transfer the contents of the argument and annul the argument.
434  void transfer(dictionary&);
435 
436  //- Transfer contents to the Xfer container
438 
439 
440  // Read
441 
442  //- Read dictionary from Istream
443  bool read(Istream&);
444 
445 
446  // Write
447 
448  void write(Ostream&, bool subDict=true) const;
449 
450 
451  // Member Operators
452 
453  //- Find and return entry
454  ITstream& operator[](const word&) const;
455 
456  void operator=(const dictionary&);
457 
458  //- Include entries from the given dictionary.
459  // Warn, but do not overwrite existing entries.
460  void operator+=(const dictionary&);
461 
462  //- Conditionally include entries from the given dictionary.
463  // Do not overwrite existing entries.
464  void operator|=(const dictionary&);
465 
466  //- Unconditionally include entries from the given dictionary.
467  // Overwrite existing entries.
468  void operator<<=(const dictionary&);
469 
470 
471  // IOstream operators
472 
473  //- Read dictionary from Istream
474  friend Istream& operator>>(Istream&, dictionary&);
475 
476  //- Write dictionary to Ostream
477  friend Ostream& operator<<(Ostream&, const dictionary&);
478 };
479 
480 
481 // Global Operators
482 
483 //- Combine dictionaries.
484 // Starting from the entries in dict1 and then including those from dict2.
485 // Warn, but do not overwrite the entries from dict1.
486 dictionary operator+(const dictionary& dict1, const dictionary& dict2);
487 
488 //- Combine dictionaries.
489 // Starting from the entries in dict1 and then including those from dict2.
490 // Do not overwrite the entries from dict1.
491 dictionary operator|(const dictionary& dict1, const dictionary& dict2);
492 
493 
494 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
495 
496 } // End namespace Foam
497 
498 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
499 
500 #ifdef NoRepository
501 # include "dictionaryTemplates.C"
502 #endif
503 
504 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
505 
506 #endif
507 
508 // ************************ vim: set sw=4 sts=4 et: ************************ //