IOobject.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-2019 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::IOobject
26 
27 Description
28  IOobject defines the attributes of an object for which implicit
29  objectRegistry management is supported, and provides the infrastructure
30  for performing stream I/O.
31 
32  An IOobject is constructed with an object name, a class name, an instance
33  path, a reference to a objectRegistry, and parameters determining its
34  storage status.
35 
36  \par Read options
37 
38  Define what is done on object construction and explicit reads:
39  - \par MUST_READ
40  Object must be read from Istream on construction. \n
41  Error if Istream does not exist or can't be read.
42  Does not check timestamp or re-read.
43  - \par MUST_READ_IF_MODIFIED
44  Object must be read from Istream on construction. \n
45  Error if Istream does not exist or can't be read. If object is
46  registered its timestamp will be checked every timestep and possibly
47  re-read.
48  - \par READ_IF_PRESENT
49  Read object from Istream if Istream exists, otherwise don't. \n
50  Error only if Istream exists but can't be read.
51  Does not check timestamp or re-read.
52  - \par NO_READ
53  Don't read
54 
55  \par Write options
56 
57  Define what is done on object destruction and explicit writes:
58  - \par AUTO_WRITE
59  Object is written automatically when requested to by the
60  objectRegistry.
61  - \par NO_WRITE
62  No automatic write on destruction but can be written explicitly
63 
64 SourceFiles
65  IOobject.C
66  IOobjectReadHeader.C
67  IOobjectWriteHeader.C
68  IOobjectPrint.C
69 
70 \*---------------------------------------------------------------------------*/
71 
72 #ifndef IOobject_H
73 #define IOobject_H
74 
75 #include "fileName.H"
76 #include "typeInfo.H"
77 #include "autoPtr.H"
78 #include "InfoProxy.H"
79 #include "NamedEnum.H"
80 
81 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
82 
83 namespace Foam
84 {
85 
86 class Time;
87 class objectRegistry;
88 
89 /*---------------------------------------------------------------------------*\
90  Class IOobject Declaration
91 \*---------------------------------------------------------------------------*/
92 
93 class IOobject
94 {
95 
96 public:
97 
98  // Public data types
99 
100  //- Enumeration defining the valid states of an IOobject
101  enum objectState
102  {
104  BAD
105  };
106 
107  //- Enumeration defining the read options
108  enum readOption
109  {
113  NO_READ
114  };
115 
116  //- Enumeration defining the write options
117  enum writeOption
118  {
120  NO_WRITE = 1
121  };
122 
123  //- Enumeration defining the file checking options
124  enum fileCheckTypes
125  {
130  };
133 
134 private:
135 
136  // Private Data
137 
138  //- Name
139  word name_;
140 
141  //- Class name read from header
142  word headerClassName_;
143 
144  //- Optional note
145  string note_;
146 
147  //- Instance path component
148  fileName instance_;
149 
150  //- Local path component
151  fileName local_;
152 
153  //- objectRegistry reference
154  const objectRegistry& db_;
155 
156  //- Read option
157  readOption rOpt_;
158 
159  //- Write option
160  writeOption wOpt_;
161 
162  //- Register object created from this IOobject with registry if true
163  bool registerObject_;
164 
165  //- IOobject state
166  objectState objState_;
167 
168 
169 protected:
170 
171  // Protected Member Functions
172 
173  //- Set the object state to bad
174  void setBad(const string&);
175 
176 
177 public:
178 
179  //- Runtime type information
180  TypeName("IOobject");
181 
182 
183  // Static Member Functions
184 
185  //- Split path into instance, local, name components
186  // input IOobject(instance, local, name)
187  // ----- ------
188  // "foo" ("", "", "foo")
189  // "foo/bar" ("foo", "", "bar")
190  // "/XXX/bar" ("/XXX", "", "bar")
191  // "foo/bar/" ERROR - no name
192  // "foo/xxx/bar" ("foo", "xxx", "bar")
193  // "foo/xxx/yyy/bar" ("foo", "xxx/yyy", "bar")
194  static bool fileNameComponents
195  (
196  const fileName& path,
198  fileName& local,
199  word& name
200  );
201 
202  template<class Name>
203  static inline word groupName(Name name, const word& group);
204 
205  //- Return group (extension part of name)
206  static word group(const word& name);
207 
208  //- Return member (name without the extension)
209  static word member(const word& name);
210 
211  //- Type of file modification checking
213 
214 
215  // Constructors
216 
217  //- Construct from name, instance, registry, io options
218  IOobject
219  (
220  const word& name,
221  const fileName& instance,
222  const objectRegistry& registry,
223  readOption r=NO_READ,
225  bool registerObject=true
226  );
227 
228  //- Construct from name, instance, local, registry, io options
229  IOobject
230  (
231  const word& name,
232  const fileName& instance,
233  const fileName& local,
234  const objectRegistry& registry,
235  readOption r=NO_READ,
237  bool registerObject=true
238  );
239 
240  //- Construct from path, registry, io options
241  // Uses fileNameComponents() to split path into components.
242  IOobject
243  (
244  const fileName& path,
245  const objectRegistry& registry,
246  readOption r=NO_READ,
248  bool registerObject=true
249  );
250 
251  //- Construct from copy resetting registry
252  IOobject
253  (
254  const IOobject& io,
255  const objectRegistry& registry
256  );
257 
258  //- Construct from copy resetting name
259  IOobject
260  (
261  const IOobject& io,
262  const word& name
263  );
264 
265  //- Copy constructor
266  IOobject(const IOobject& io) = default;
267 
268  //- Clone
269  autoPtr<IOobject> clone() const
270  {
271  return autoPtr<IOobject>(new IOobject(*this));
272  }
273 
274  //- Clone resetting registry
275  autoPtr<IOobject> clone(const objectRegistry& registry) const
276  {
277  return autoPtr<IOobject>(new IOobject(*this, registry));
278  }
279 
280 
281  //- Destructor
282  virtual ~IOobject();
283 
284 
285  // Member Functions
286 
287  // General access
288 
289  //- Return time
290  const Time& time() const;
291 
292  //- Return the local objectRegistry
293  const objectRegistry& db() const;
294 
295  //- Return name
296  const word& name() const
297  {
298  return name_;
299  }
300 
301  //- Return name of the class name read from header
302  const word& headerClassName() const
303  {
304  return headerClassName_;
305  }
306 
307  //- Return name of the class name read from header
309  {
310  return headerClassName_;
311  }
312 
313  //- Return non-constant access to the optional note
314  string& note()
315  {
316  return note_;
317  }
318 
319  //- Return the optional note
320  const string& note() const
321  {
322  return note_;
323  }
324 
325  //- Rename
326  virtual void rename(const word& newName)
327  {
328  name_ = newName;
329  }
330 
331  //- Register object created from this IOobject with registry if true
332  bool& registerObject()
333  {
334  return registerObject_;
335  }
336 
337  //- Register object created from this IOobject with registry if true
338  bool registerObject() const
339  {
340  return registerObject_;
341  }
342 
343 
344  // Read/write options
346  readOption readOpt() const
347  {
348  return rOpt_;
349  }
352  {
353  return rOpt_;
354  }
356  writeOption writeOpt() const
357  {
358  return wOpt_;
359  }
362  {
363  return wOpt_;
364  }
365 
366 
367  // Path components
368 
369  //- Return group (extension part of name)
370  word group() const;
371 
372  //- Return member (name without the extension)
373  word member() const;
374 
375  const fileName& rootPath() const;
376 
377  const fileName& caseName() const;
379  const fileName& instance() const
380  {
381  return instance_;
382  }
384  fileName& instance()
385  {
386  return instance_;
387  }
389  const fileName& local() const
390  {
391  return local_;
392  }
393 
394  //- Return complete path
395  fileName path() const;
396 
397  //- Return complete path with alternative instance and local
398  fileName path
399  (
400  const word& instance,
401  const fileName& local = ""
402  ) const;
403 
404  //- Return complete path + object name
405  fileName objectPath() const
406  {
407  return path()/name();
408  }
409 
410  //- Helper for filePath that searches locally.
411  fileName localFilePath(const word& typeName) const;
412 
413  //- Helper for filePath that searches up if in parallel
414  fileName globalFilePath(const word& typeName) const;
415 
416 
417  // Reading
418 
419  //- Read header
420  bool readHeader(Istream&);
421 
422  //- Read header (uses typeFilePath to find file) and check header
423  // info. Optionally checks headerClassName against type
424  template<class Type>
425  bool typeHeaderOk(const bool checkType = true);
426 
427  //- Helper: warn that type does not support re-reading
428  template<class Type>
429  void warnNoRereading() const;
430 
431  // Writing
432 
433  //- Write the standard OpenFOAM file/dictionary banner
434  // Optionally without -*- C++ -*- editor hint (eg, for logs)
435  template<class Stream>
436  static inline Stream& writeBanner(Stream& os, bool noHint=false);
437 
438  //- Write the standard file section divider
439  template<class Stream>
440  static inline Stream& writeDivider(Stream& os);
441 
442  //- Write the standard end file divider
443  template<class Stream>
444  static inline Stream& writeEndDivider(Stream& os);
445 
446  //- Write header
447  bool writeHeader(Ostream&) const;
448 
449  //- Write header. Allow override of type
450  bool writeHeader(Ostream&, const word& objectType) const;
451 
452 
453  // Error Handling
455  bool good() const
456  {
457  return objState_ == GOOD;
458  }
460  bool bad() const
461  {
462  return objState_ == BAD;
463  }
464 
465 
466  // Info
467 
468  //- Return info proxy.
469  // Used to print token information to a stream
470  InfoProxy<IOobject> info() const
471  {
472  return *this;
473  }
474 
475 
476  // Member Operators
477 
478  void operator=(const IOobject&);
479 };
480 
481 
482 template<>
483 Ostream& operator<<(Ostream& os, const InfoProxy<IOobject>& ip);
484 
485 
486 //- Template function for obtaining global status
487 template<class T>
488 inline bool typeGlobal()
489 {
490  return false;
491 }
492 
493 //- Template function for obtaining filePath
494 template<class T>
495 inline fileName typeFilePath(const IOobject& io)
496 {
497  return
498  (
499  typeGlobal<T>()
500  ? io.globalFilePath(T::typeName)
501  : io.localFilePath(T::typeName)
502  );
503 }
505 inline IOobject unregister(const IOobject& io)
506 {
507  IOobject uio(io);
508  uio.registerObject() = false;
509  return uio;
510 }
511 
512 
513 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
514 
515 } // End namespace Foam
516 
517 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
518 
519 #include "IOobjectI.H"
520 
521 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
522 
523 #ifdef NoRepository
524 # include "IOobjectTemplates.C"
525 #endif
526 
527 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
528 
529 #endif
530 
531 // ************************************************************************* //
fileCheckTypes
Enumeration defining the file checking options.
Definition: IOobject.H:123
autoPtr< IOobject > clone() const
Clone.
Definition: IOobject.H:268
writeOption
Enumeration defining the write options.
Definition: IOobject.H:116
static bool fileNameComponents(const fileName &path, fileName &instance, fileName &local, word &name)
Split path into instance, local, name components.
Definition: IOobject.C:106
bool good() const
Definition: IOobject.H:454
const word & name() const
Return name.
Definition: IOobject.H:295
bool typeHeaderOk(const bool checkType=true)
Read header (uses typeFilePath to find file) and check header.
A class for handling file names.
Definition: fileName.H:79
static Stream & writeBanner(Stream &os, bool noHint=false)
Write the standard OpenFOAM file/dictionary banner.
Definition: IOobjectI.H:45
bool typeGlobal()
Template function for obtaining global status.
Definition: IOobject.H:487
void operator=(const IOobject &)
Definition: IOobject.C:447
static Stream & writeDivider(Stream &os)
Write the standard file section divider.
Definition: IOobjectI.H:93
An Istream is an abstract base class for all input systems (streams, files, token lists etc)...
Definition: Istream.H:57
IOobject(const word &name, const fileName &instance, const objectRegistry &registry, readOption r=NO_READ, writeOption w=NO_WRITE, bool registerObject=true)
Construct from name, instance, registry, io options.
Definition: IOobject.C:209
virtual void rename(const word &newName)
Rename.
Definition: IOobject.H:325
word member() const
Return member (name without the extension)
Definition: IOobject.C:378
objectState
Enumeration defining the valid states of an IOobject.
Definition: IOobject.H:100
virtual ~IOobject()
Destructor.
Definition: IOobject.C:348
word group() const
Return group (extension part of name)
Definition: IOobject.C:372
readOption
Enumeration defining the read options.
Definition: IOobject.H:107
Class to control time during OpenFOAM simulations that is also the top-level objectRegistry.
Definition: Time.H:68
fileName path() const
Return complete path.
Definition: IOobject.C:390
fileName localFilePath(const word &typeName) const
Helper for filePath that searches locally.
Definition: IOobject.C:414
bool readHeader(Istream &)
Read header.
string & note()
Return non-constant access to the optional note.
Definition: IOobject.H:313
bool bad() const
Definition: IOobject.H:459
A class for handling words, derived from string.
Definition: word.H:59
static word groupName(Name name, const word &group)
const fileName & local() const
Definition: IOobject.H:388
void setBad(const string &)
Set the object state to bad.
Definition: IOobject.C:428
fileName globalFilePath(const word &typeName) const
Helper for filePath that searches up if in parallel.
Definition: IOobject.C:421
An Ostream is an abstract base class for all output systems (streams, files, token lists...
Definition: Ostream.H:53
static fileCheckTypes fileModificationChecking
Type of file modification checking.
Definition: IOobject.H:211
fileName typeFilePath(const IOobject &io)
Template function for obtaining filePath.
Definition: IOobject.H:494
const fileName & rootPath() const
Definition: IOobject.C:384
static const NamedEnum< fileCheckTypes, 4 > fileCheckTypesNames
Definition: IOobject.H:131
writeOption writeOpt() const
Definition: IOobject.H:355
const fileName & instance() const
Definition: IOobject.H:378
static Stream & writeEndDivider(Stream &os)
Write the standard end file divider.
Definition: IOobjectI.H:103
A helper class for outputting values to Ostream.
Definition: InfoProxy.H:45
const Time & time() const
Return time.
Definition: IOobject.C:360
TypeName("IOobject")
Runtime type information.
bool writeHeader(Ostream &) const
Write header.
An auto-pointer similar to the STL auto_ptr but with automatic casting to a reference to the type and...
Definition: PtrList.H:52
InfoProxy< IOobject > info() const
Return info proxy.
Definition: IOobject.H:469
Registry of regIOobjects.
const objectRegistry & db() const
Return the local objectRegistry.
Definition: IOobject.C:354
bool & registerObject()
Register object created from this IOobject with registry if true.
Definition: IOobject.H:331
readOption readOpt() const
Definition: IOobject.H:345
IOobject unregister(const IOobject &io)
Definition: IOobject.H:504
const word & headerClassName() const
Return name of the class name read from header.
Definition: IOobject.H:301
IOobject defines the attributes of an object for which implicit objectRegistry management is supporte...
Definition: IOobject.H:92
const fileName & caseName() const
Definition: IOobject.C:366
fileName objectPath() const
Return complete path + object name.
Definition: IOobject.H:404
void warnNoRereading() const
Helper: warn that type does not support re-reading.
Namespace for OpenFOAM.