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-2024 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 Class
65  Foam::typeIOobject
66 
67 Description
68  Templated form of IOobject providing type information for file reading and
69  header type checking.
70 
71 SourceFiles
72  IOobject.C
73  IOobjectReadHeader.C
74  IOobjectWriteHeader.C
75  IOobjectPrint.C
76 
77 \*---------------------------------------------------------------------------*/
78 
79 #ifndef IOobject_H
80 #define IOobject_H
81 
82 #include "fileName.H"
83 #include "typeInfo.H"
84 #include "autoPtr.H"
85 #include "InfoProxy.H"
86 #include "NamedEnum.H"
87 
88 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
89 
90 namespace Foam
91 {
92 
93 class Time;
94 class objectRegistry;
95 
96 /*---------------------------------------------------------------------------*\
97  Class IOobject Declaration
98 \*---------------------------------------------------------------------------*/
99 
100 class IOobject
101 {
102 
103 public:
104 
105  //- Keyword for the FoamFile header sub-dictionary
106  static constexpr const char* foamFile = "FoamFile";
107 
108  // Public data types
109 
110  //- Enumeration defining the valid states of an IOobject
112  {
114  BAD
115  };
116 
117  //- Enumeration defining the read options
119  {
123  NO_READ
124  };
125 
126  //- Enumeration defining the write options
128  {
130  NO_WRITE = 1
131  };
132 
133  //- Enumeration defining the file checking options
135  {
140  };
141 
143 
144 
145 private:
146 
147  // Private Data
148 
149  //- Name
150  word name_;
151 
152  //- Class name read from header
153  word headerClassName_;
154 
155  //- Optional note
156  string note_;
157 
158  //- Instance path component
159  mutable fileName instance_;
160 
161  //- Local path component
162  fileName local_;
163 
164  //- objectRegistry reference
165  const objectRegistry& db_;
166 
167  //- Read option
168  readOption rOpt_;
169 
170  //- Write option
171  writeOption wOpt_;
172 
173  //- Register object created from this IOobject with registry if true
174  bool registerObject_;
175 
176  //- IOobject state
177  objectState objState_;
178 
179 
180 protected:
181 
182  // Protected Member Functions
183 
184  //- Set the object state to bad
185  void setBad(const string&);
186 
187  //- Read header using typeGlobalFile to find file
188  // and optionally check the headerClassName against Type
189  template<class Type>
190  bool typeHeaderOk(const bool checkType);
191 
192 
193 public:
194 
195  //- Runtime type information
196  TypeName("IOobject");
197 
198 
199  // Static Member Functions
200 
201  //- Split path into instance, local, name components
202  // input IOobject(instance, local, name)
203  // ----- ------
204  // "foo" ("", "", "foo")
205  // "foo/bar" ("foo", "", "bar")
206  // "/XXX/bar" ("/XXX", "", "bar")
207  // "foo/bar/" ERROR - no name
208  // "foo/xxx/bar" ("foo", "xxx", "bar")
209  // "foo/xxx/yyy/bar" ("foo", "xxx/yyy", "bar")
210  static bool fileNameComponents
211  (
212  const fileName& path,
214  fileName& local,
215  word& name
216  );
217 
218  template<class Name>
219  static inline word groupName(Name name, const word& group);
220 
221  //- Return group (extension part of name)
222  static word group(const word& name);
223 
224  //- Return member (name without the extension)
225  static word member(const word& name);
226 
227  //- Type of file modification checking
229 
230 
231  // Constructors
232 
233  //- Construct from name, instance, registry, io options
234  IOobject
235  (
236  const word& name,
237  const fileName& instance,
238  const objectRegistry& registry,
241  bool registerObject=true
242  );
243 
244  //- Construct from name, instance, local, registry, io options
245  IOobject
246  (
247  const word& name,
248  const fileName& instance,
249  const fileName& local,
250  const objectRegistry& registry,
253  bool registerObject=true
254  );
255 
256  //- Construct from path, registry, io options
257  // Uses fileNameComponents() to split path into components.
258  IOobject
259  (
260  const fileName& path,
261  const objectRegistry& registry,
264  bool registerObject=true
265  );
266 
267  //- Construct from copy resetting registry
268  IOobject
269  (
270  const IOobject& io,
271  const objectRegistry& registry
272  );
273 
274  //- Construct from copy resetting name
275  IOobject
276  (
277  const IOobject& io,
278  const word& name
279  );
280 
281  //- Copy constructor
282  IOobject(const IOobject& io) = default;
283 
284  //- Clone
285  autoPtr<IOobject> clone() const
286  {
287  return autoPtr<IOobject>(new IOobject(*this));
288  }
289 
290  //- Clone resetting registry
291  autoPtr<IOobject> clone(const objectRegistry& registry) const
292  {
293  return autoPtr<IOobject>(new IOobject(*this, registry));
294  }
295 
296 
297  //- Destructor
298  virtual ~IOobject();
299 
300 
301  // Member Functions
302 
303  // General access
304 
305  //- Return time
306  const Time& time() const;
307 
308  //- Return the local objectRegistry
309  const objectRegistry& db() const;
310 
311  //- Return name
312  const word& name() const
313  {
314  return name_;
315  }
316 
317  //- Return name of the class name read from header
318  const word& headerClassName() const
319  {
320  return headerClassName_;
321  }
322 
323  //- Return name of the class name read from header
325  {
326  return headerClassName_;
327  }
328 
329  //- Return non-constant access to the optional note
330  string& note()
331  {
332  return note_;
333  }
334 
335  //- Return the optional note
336  const string& note() const
337  {
338  return note_;
339  }
340 
341  //- Rename
342  virtual void rename(const word& newName)
343  {
344  name_ = newName;
345  }
346 
347  //- Register object created from this IOobject with registry if true
348  bool& registerObject()
349  {
350  return registerObject_;
351  }
352 
353  //- Register object created from this IOobject with registry if true
354  bool registerObject() const
355  {
356  return registerObject_;
357  }
358 
359 
360  // Read/write options
361 
362  readOption readOpt() const
363  {
364  return rOpt_;
365  }
366 
368  {
369  return rOpt_;
370  }
371 
372  writeOption writeOpt() const
373  {
374  return wOpt_;
375  }
376 
378  {
379  return wOpt_;
380  }
381 
382 
383  // Path components
384 
385  //- Return group (extension part of name)
386  word group() const;
387 
388  //- Return member (name without the extension)
389  word member() const;
390 
391  const fileName& rootPath() const;
392 
393  const fileName& caseName(const bool global) const;
394 
395  //- Return the instance directory, constant, system, <time> etc.
396  // Allows modification of the instance
397  fileName& instance() const;
398 
399  //- If the instance is a time directory update to the current time
400  void updateInstance() const;
401 
402  const fileName& local() const
403  {
404  return local_;
405  }
406 
407  //- Return complete path including the processor sub-directory
408  // for a parallel run if global is set false
409  fileName path(const bool global) const;
410 
411  //- Return complete path + object name including the processor
412  // sub-directory for a parallel run if global is set false
413  fileName objectPath(const bool global) const
414  {
415  return path(global)/name();
416  }
417 
418  //- Return the path relative to the case directory
419  fileName relativePath() const;
420 
421  //- Return complete relativePath + object name
423  {
424  return relativePath()/name();
425  }
426 
427  //- Return complete path + object name if the file exists
428  // in the case directory otherwise null.
429  //
430  // If global and parallel searches up into the global case
431  // directory.
432  fileName filePath(const word& typeName, const bool global) const;
433 
434 
435  // Reading
436 
437  //- Read header
438  bool readHeader(Istream&);
439 
440  //- Read header of local object without type-checking
441  // Mainly used to create IOobjectLists
442  bool headerOk();
443 
444  //- Helper: warn that type does not support re-reading
445  template<class Type>
446  void warnNoRereading() const;
447 
448 
449  // Writing
450 
451  //- Write the standard OpenFOAM file/dictionary banner
452  // Optionally without -*- C++ -*- editor hint (eg, for logs)
453  template<class Stream>
454  static inline Stream& writeBanner(Stream& os, bool noHint=false);
455 
456  //- Write the standard file section divider
457  template<class Stream>
458  static inline Stream& writeDivider(Stream& os);
459 
460  //- Write the standard end file divider
461  template<class Stream>
462  static inline Stream& writeEndDivider(Stream& os);
463 
464  //- Write header
465  bool writeHeader(Ostream&) const;
466 
467  //- Write header. Allow override of type
468  bool writeHeader(Ostream&, const word& objectType) const;
469 
470 
471  // Error Handling
472 
473  bool good() const
474  {
475  return objState_ == GOOD;
476  }
477 
478  bool bad() const
479  {
480  return objState_ == BAD;
481  }
482 
483 
484  // Info
485 
486  //- Return info proxy.
487  // Used to print token information to a stream
488  InfoProxy<IOobject> info() const
489  {
490  return *this;
491  }
492 
493 
494  // Member Operators
495 
496  void operator=(const IOobject&);
497 };
498 
499 
500 template<>
501 Ostream& operator<<(Ostream& os, const InfoProxy<IOobject>& ip);
502 
503 //- Trait for obtaining global status
504 template<class Type>
506 {
507  static const bool global = false;
508 };
509 
510 //- Trait for obtaining global write status
511 template<class Type>
513 {
514  static const bool global = typeGlobal<Type>::global;
515 };
516 
517 inline IOobject unregister(const IOobject& io)
518 {
519  IOobject uio(io);
520  uio.registerObject() = false;
521  return uio;
522 }
523 
524 
525 /*---------------------------------------------------------------------------*\
526  Class typeIOobject Declaration
527 \*---------------------------------------------------------------------------*/
528 
529 template<class Type>
530 class typeIOobject
531 :
532  public IOobject
533 {
534 
535 public:
536 
537  // Constructors
538 
540 
541  typeIOobject(const IOobject& io)
542  :
543  IOobject(io)
544  {}
545 
546 
547  // Member Functions
548 
549  // Reading
550 
551  //- Read header (uses typeGlobalFile to find file) and check
552  bool headerOk();
553 
554  using IOobject::objectPath;
555 
556  //- Return the object path for this Type
557  inline fileName objectPath() const
558  {
560  }
561 
562  using IOobject::filePath;
563 
564  //- Return the path for the file for this Type
565  inline fileName filePath() const
566  {
567  return filePath(Type::typeName, typeGlobalFile<Type>::global);
568  }
569 };
570 
571 
572 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
573 
574 } // End namespace Foam
575 
576 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
577 
578 #include "IOobjectI.H"
579 
580 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
581 
582 #ifdef NoRepository
583 # include "IOobjectTemplates.C"
584 #endif
585 
586 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
587 
588 #endif
589 
590 // ************************************************************************* //
IOobject defines the attributes of an object for which implicit objectRegistry management is supporte...
Definition: IOobject.H:99
static Stream & writeBanner(Stream &os, bool noHint=false)
Write the standard OpenFOAM file/dictionary banner.
Definition: IOobjectI.H:45
const fileName & local() const
Definition: IOobject.H:400
bool typeHeaderOk(const bool checkType)
Read header using typeGlobalFile to find file.
const fileName & caseName(const bool global) const
Definition: IOobject.C:342
fileName filePath(const word &typeName, const bool global) const
Return complete path + object name if the file exists.
Definition: IOobject.C:407
const Time & time() const
Return time.
Definition: IOobject.C:318
readOption
Enumeration defining the read options.
Definition: IOobject.H:117
@ MUST_READ_IF_MODIFIED
Definition: IOobject.H:119
writeOption writeOpt() const
Definition: IOobject.H:370
fileName relativeObjectPath() const
Return complete relativePath + object name.
Definition: IOobject.H:420
void warnNoRereading() const
Helper: warn that type does not support re-reading.
static Stream & writeEndDivider(Stream &os)
Write the standard end file divider.
Definition: IOobjectI.H:103
void setBad(const string &)
Set the object state to bad.
Definition: IOobject.C:416
bool & registerObject()
Register object created from this IOobject with registry if true.
Definition: IOobject.H:346
fileName relativePath() const
Return the path relative to the case directory.
Definition: IOobject.C:393
fileName & instance() const
Return the instance directory, constant, system, <time> etc.
Definition: IOobject.C:355
const objectRegistry & db() const
Return the local objectRegistry.
Definition: IOobject.C:312
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:167
string & note()
Return non-constant access to the optional note.
Definition: IOobject.H:328
static bool fileNameComponents(const fileName &path, fileName &instance, fileName &local, word &name)
Split path into instance, local, name components.
Definition: IOobject.C:64
readOption readOpt() const
Definition: IOobject.H:360
void updateInstance() const
If the instance is a time directory update to the current time.
Definition: IOobject.C:361
static constexpr const char * foamFile
Keyword for the FoamFile header sub-dictionary.
Definition: IOobject.H:104
autoPtr< IOobject > clone() const
Clone.
Definition: IOobject.H:283
bool headerOk()
Read header of local object without type-checking.
const word & headerClassName() const
Return name of the class name read from header.
Definition: IOobject.H:316
bool bad() const
Definition: IOobject.H:476
word group() const
Return group (extension part of name)
Definition: IOobject.C:324
objectState
Enumeration defining the valid states of an IOobject.
Definition: IOobject.H:110
TypeName("IOobject")
Runtime type information.
static fileCheckTypes fileModificationChecking
Type of file modification checking.
Definition: IOobject.H:226
virtual void rename(const word &newName)
Rename.
Definition: IOobject.H:340
static Stream & writeDivider(Stream &os)
Write the standard file section divider.
Definition: IOobjectI.H:93
bool good() const
Definition: IOobject.H:471
InfoProxy< IOobject > info() const
Return info proxy.
Definition: IOobject.H:486
void operator=(const IOobject &)
Definition: IOobject.C:435
word member() const
Return member (name without the extension)
Definition: IOobject.C:330
bool readHeader(Istream &)
Read header.
const word & name() const
Return name.
Definition: IOobject.H:310
const fileName & rootPath() const
Definition: IOobject.C:336
static const NamedEnum< fileCheckTypes, 4 > fileCheckTypesNames
Definition: IOobject.H:140
static word groupName(Name name, const word &group)
fileCheckTypes
Enumeration defining the file checking options.
Definition: IOobject.H:133
writeOption
Enumeration defining the write options.
Definition: IOobject.H:126
bool writeHeader(Ostream &) const
Write header.
virtual ~IOobject()
Destructor.
Definition: IOobject.C:306
fileName objectPath(const bool global) const
Return complete path + object name including the processor.
Definition: IOobject.H:411
fileName path(const bool global) const
Return complete path including the processor sub-directory.
Definition: IOobject.C:380
A helper class for outputting values to Ostream.
Definition: InfoProxy.H:50
An Istream is an abstract base class for all input systems (streams, files, token lists etc)....
Definition: Istream.H:60
An Ostream is an abstract base class for all output systems (streams, files, token lists,...
Definition: Ostream.H:57
Class to control time during OpenFOAM simulations that is also the top-level objectRegistry.
Definition: Time.H:76
An auto-pointer similar to the STL auto_ptr but with automatic casting to a reference to the type and...
Definition: autoPtr.H:51
A class for handling file names.
Definition: fileName.H:82
Registry of regIOobjects.
Templated form of IOobject providing type information for file reading and header type checking.
Definition: IOobject.H:531
fileName objectPath() const
Return the object path for this Type.
Definition: IOobject.H:555
typeIOobject(const IOobject &io)
Definition: IOobject.H:539
bool headerOk()
Read header (uses typeGlobalFile to find file) and check.
fileName filePath() const
Return the path for the file for this Type.
Definition: IOobject.H:563
A class for handling words, derived from string.
Definition: word.H:62
Namespace for OpenFOAM.
IOobject unregister(const IOobject &io)
Definition: IOobject.H:515
Ostream & operator<<(Ostream &os, const fvConstraints &constraints)
Trait for obtaining global write status.
Definition: IOobject.H:511
static const bool global
Definition: IOobject.H:512
Trait for obtaining global status.
Definition: IOobject.H:504
static const bool global
Definition: IOobject.H:505
Basic run-time type information using word as the type's name. Used to enhance the standard RTTI to c...