1 /*---------------------------------------------------------------------------*\
3 \\ / F ield | OpenFOAM: The Open Source CFD Toolbox
5 \\ / A nd | Copyright (C) 1991-2009 OpenCFD Ltd.
7 -------------------------------------------------------------------------------
9 This file is part of OpenFOAM.
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 the
13 Free Software Foundation; either version 2 of the License, or (at your
14 option) any later version.
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
21 You should have received a copy of the GNU General Public License
22 along with OpenFOAM; if not, write to the Free Software Foundation,
23 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
29 A list of keyword definitions, which are a keyword followed by any number
30 of values (e.g. words and numbers). The keywords can represent patterns
31 which are matched using Posix regular expressions. The general order for
32 searching is as follows:
34 - pattern match (in reverse order)
35 - optional recursion into the enclosing (parent) dictionaries
37 The dictionary class is the base class for IOdictionary.
38 It also serves as a bootstrap dictionary for the objectRegistry data
39 dictionaries since, unlike the IOdictionary class, it does not use an
40 objectRegistry itself to work.
43 A merge() member function with a non-const dictionary parameter.
44 This would avoid unnecessary cloning in the add(entry*, bool) method.
50 \*---------------------------------------------------------------------------*/
60 #include "HashTable.H"
62 #include "className.H"
64 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
69 // Forward declaration of friend functions and operators
74 Istream& operator>>(Istream&, dictionary&);
75 Ostream& operator<<(Ostream&, const dictionary&);
77 /*---------------------------------------------------------------------------*\
78 Class dictionaryName Declaration
79 \*---------------------------------------------------------------------------*/
92 //- Construct dictionaryName null
96 //- Construct dictionaryName as copy of the given fileName
97 dictionaryName(const fileName& name)
105 //- Return the dictionary name
106 const fileName& name() const
111 //- Return the dictionary name
119 /*---------------------------------------------------------------------------*\
120 Class dictionary Declaration
121 \*---------------------------------------------------------------------------*/
125 public dictionaryName,
126 public IDLList<entry>
130 //- HashTable of the entries held on the DL-list for quick lookup
131 HashTable<entry*> hashedEntries_;
133 //- Parent dictionary
134 const dictionary& parent_;
136 //- Entries of matching patterns
137 DLList<entry*> patternEntries_;
139 //- Patterns as precompiled regular expressions
140 DLList<autoPtr<regExp> > patternRegexps_;
143 // Private Member Functions
145 //- Search patterns table for exact match or regular expression match
148 const bool patternMatch,
150 DLList<entry*>::const_iterator& wcLink,
151 DLList<autoPtr<regExp> >::const_iterator& reLink
154 //- Search patterns table for exact match or regular expression match
157 const bool patternMatch,
159 DLList<entry*>::iterator& wcLink,
160 DLList<autoPtr<regExp> >::iterator& reLink
166 //- Declare friendship with the entry class for IO
170 // Declare name of the class and its debug switch
171 ClassName("dictionary");
175 static const dictionary null;
180 //- Construct top-level dictionary null
183 //- Construct top-level empty dictionary with given name
184 dictionary(const fileName& name);
186 //- Construct given the entry name, parent dictionary and Istream,
187 // reading entries until lastEntry or EOF
190 const fileName& name,
191 const dictionary& parentDict,
195 //- Construct top-level dictionary from Istream, reading entries
197 dictionary(Istream&);
199 //- Construct as copy given the parent dictionary
200 dictionary(const dictionary& parentDict, const dictionary&);
202 //- Construct top-level dictionary as copy
203 dictionary(const dictionary&);
205 //- Construct top-level dictionary as copy from pointer to dictionary.
206 // A null pointer is treated like an empty dictionary.
207 dictionary(const dictionary*);
209 //- Construct by transferring parameter contents given parent dictionary
210 dictionary(const dictionary& parentDict, const Xfer<dictionary>&);
212 //- Construct top-level dictionary by transferring parameter contents
213 dictionary(const Xfer<dictionary>&);
215 //- Construct and return clone
216 autoPtr<dictionary> clone() const;
218 //- Construct top-level dictionary on freestore from Istream
219 static autoPtr<dictionary> New(Istream&);
229 //- Return the parent dictionary
230 const dictionary& parent() const
235 //- Return line number of first token in dictionary
236 label startLineNumber() const;
238 //- Return line number of last token in dictionary
239 label endLineNumber() const;
241 //- Return the SHA1 digest of the dictionary contents
242 SHA1Digest digest() const;
247 //- Search dictionary for given keyword
248 // If recursive, search parent dictionaries
249 bool found(const word&, bool recursive=false) const;
251 //- Find and return an entry data stream pointer if present
252 // otherwise return NULL.
253 // If recursive, search parent dictionaries.
254 // If patternMatch, use regular expressions
255 const entry* lookupEntryPtr
262 //- Find and return an entry data stream pointer for manipulation
263 // if present otherwise return NULL.
264 // If recursive, search parent dictionaries.
265 // If patternMatch, use regular expressions.
266 entry* lookupEntryPtr
273 //- Find and return an entry data stream if present otherwise error.
274 // If recursive, search parent dictionaries.
275 // If patternMatch, use regular expressions.
276 const entry& lookupEntry
283 //- Find and return an entry data stream
284 // If recursive, search parent dictionaries.
285 // If patternMatch, use regular expressions.
289 bool recursive=false,
290 bool patternMatch=true
293 //- Find and return a T,
294 // if not found return the given default value
295 // If recursive, search parent dictionaries.
296 // If patternMatch, use regular expressions.
302 bool recursive=false,
303 bool patternMatch=true
306 //- Find and return a T, if not found return the given
307 // default value, and add to dictionary.
308 // If recursive, search parent dictionaries.
309 // If patternMatch, use regular expressions.
315 bool recursive=false,
316 bool patternMatch=true
319 //- Find an entry if present, and assign to T
320 // Returns true if the entry was found.
321 // If recursive, search parent dictionaries.
322 // If patternMatch, use regular expressions.
328 bool recursive=false,
329 bool patternMatch=true
332 //- Check if entry is a sub-dictionary
333 bool isDict(const word&) const;
335 //- Find and return a sub-dictionary pointer if present
336 // otherwise return NULL.
337 const dictionary* subDictPtr(const word&) const;
339 //- Find and return a sub-dictionary
340 const dictionary& subDict(const word&) const;
342 //- Find and return a sub-dictionary for manipulation
343 dictionary& subDict(const word&);
345 //- Find and return a sub-dictionary as a copy, or
346 // return an empty dictionary if the sub-dictionary does not exist
347 dictionary subOrEmptyDict(const word&) const;
349 //- Return the table of contents
350 wordList toc() const;
352 //- Return the list of available keys or patterns
353 List<keyType> keys(bool patterns=false) const;
358 //- Substitute the given keyword prepended by '$' with the
359 // corresponding sub-dictionary entries
360 bool substituteKeyword(const word& keyword);
363 // With the merge option, dictionaries are interwoven and
364 // primitive entries are overwritten
365 bool add(entry*, bool mergeEntry=false);
368 // With the merge option, dictionaries are interwoven and
369 // primitive entries are overwritten
370 void add(const entry&, bool mergeEntry=false);
373 // optionally overwrite an existing entry
374 void add(const keyType&, const word&, bool overwrite=false);
376 //- Add a string entry
377 // optionally overwrite an existing entry
378 void add(const keyType&, const string&, bool overwrite=false);
380 //- Add a label entry
381 // optionally overwrite an existing entry
382 void add(const keyType&, const label, bool overwrite=false);
384 //- Add a scalar entry
385 // optionally overwrite an existing entry
386 void add(const keyType&, const scalar, bool overwrite=false);
388 //- Add a dictionary entry
389 // optionally merge with an existing sub-dictionary
394 bool mergeEntry=false
398 // optionally overwrite an existing entry
400 void add(const keyType&, const T&, bool overwrite=false);
402 //- Assign a new entry, overwrite any existing entry
405 //- Assign a new entry, overwrite any existing entry
406 void set(const entry&);
408 //- Assign a dictionary entry, overwrite any existing entry
409 void set(const keyType&, const dictionary&);
411 //- Assign a T entry, overwrite any existing entry
413 void set(const keyType&, const T&);
415 //- Remove an entry specified by keyword
416 bool remove(const word&);
418 //- Change the keyword for an entry,
419 // optionally forcing overwrite of an existing entry
422 const keyType& oldKeyword,
423 const keyType& newKeyword,
424 bool forceOverwrite=false
427 //- Merge entries from the given dictionary.
428 // Also merge sub-dictionaries as required.
429 bool merge(const dictionary&);
431 //- Clear the dictionary
434 //- Transfer the contents of the argument and annul the argument.
435 void transfer(dictionary&);
437 //- Transfer contents to the Xfer container
438 Xfer<dictionary> xfer();
443 //- Read dictionary from Istream
449 void write(Ostream&, bool subDict=true) const;
454 //- Find and return entry
455 ITstream& operator[](const word&) const;
457 void operator=(const dictionary&);
459 //- Include entries from the given dictionary.
460 // Warn, but do not overwrite existing entries.
461 void operator+=(const dictionary&);
463 //- Conditionally include entries from the given dictionary.
464 // Do not overwrite existing entries.
465 void operator|=(const dictionary&);
467 //- Unconditionally include entries from the given dictionary.
468 // Overwrite existing entries.
469 void operator<<=(const dictionary&);
472 // IOstream operators
474 //- Read dictionary from Istream
475 friend Istream& operator>>(Istream&, dictionary&);
477 //- Write dictionary to Ostream
478 friend Ostream& operator<<(Ostream&, const dictionary&);
484 //- Combine dictionaries.
485 // Starting from the entries in dict1 and then including those from dict2.
486 // Warn, but do not overwrite the entries from dict1.
487 dictionary operator+(const dictionary& dict1, const dictionary& dict2);
489 //- Combine dictionaries.
490 // Starting from the entries in dict1 and then including those from dict2.
491 // Do not overwrite the entries from dict1.
492 dictionary operator|(const dictionary& dict1, const dictionary& dict2);
495 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
497 } // End namespace Foam
499 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
502 # include "dictionaryTemplates.C"
505 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
509 // ************************************************************************* //