ENH: IOobjectOption isAnyRead() for checking against NO_READ

- encompasses isReadOptional or isReadRequired check

STYLE: allow LAZY_READ as a shorter synonym for READ_IF_PRESENT

- add helper for downgrading MUST_READ... to LAZY_READ

src/OpenFOAM/Make/files

@@ -240,11 +240,12 @@ containers/Lists/ListOps/ListOps.C
 containers/LinkedLists/linkTypes/SLListBase/SLListBase.C
 containers/LinkedLists/linkTypes/DLListBase/DLListBase.C
 
+db/options/IOstreamOption.C
+
 Streams = db/IOstreams
 $(Streams)/token/tokenIO.C
 
 IOstreams = $(Streams)/IOstreams
-$(IOstreams)/IOstreamOption.C
 $(IOstreams)/IOstream.C
 $(IOstreams)/Istream.C
 $(IOstreams)/Ostream.C

src/OpenFOAM/db/IOobject/IOobject.H

@@ -50,7 +50,7 @@ Description
         Error if Istream does not exist or cannot be read. If object is
         registered its timestamp will be checked every timestep and possibly
         re-read.
-      - \par READ_IF_PRESENT
+      - \par LAZY_READ (READ_IF_PRESENT)
         Read object from Istream, but only if Istream exists. \n
         Error only if Istream exists but cannot be read.
         Does not check timestamp or re-read.

src/OpenFOAM/db/IOobjects/IOPtrList/IOPtrList.C

@@ -69,7 +69,7 @@ Foam::IOPtrList<T>::IOPtrList(const IOobject& io, const label len)
     regIOobject(io),
     PtrList<T>(len)
 {
-    if (io.readOpt() != IOobject::NO_READ)
+    if (io.isAnyRead())
     {
         FatalErrorInFunction
             << "NO_READ must be set if specifying size" << nl

src/OpenFOAM/db/options/IOobjectOption.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011 OpenFOAM Foundation
-    Copyright (C) 2016-2022 OpenCFD Ltd.
+    Copyright (C) 2016-2023 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -60,7 +60,8 @@ public:
     // Public Data Types
 
         //- Enumeration defining read preferences
-        //  Lowest bit encodes must read
+        //  Lowest bit encodes 'must read'.
+        //  Possible (future) named variants (none | normal | modified | lazy)
         enum readOption : unsigned char
         {
             //! Nothing to be read
@@ -72,7 +73,10 @@ public:
             //! Reading required, file watched for runTime modification
             MUST_READ_IF_MODIFIED = 0x3,
 
-            //! Reading is optional
+            //! Reading is optional [identical to READ_IF_PRESENT]
+            LAZY_READ = 0x4,
+
+            //! Reading is optional [identical to LAZY_READ]
             READ_IF_PRESENT = 0x4
         };
 
@@ -256,28 +260,46 @@ public:
 
     // Checks
 
+        //- True if not (NO_READ)
+        static bool isAnyRead(readOption opt) noexcept
+        {
+            return (opt != readOption::NO_READ);
+        }
+
+        //- True if not (NO_READ)
+        bool isAnyRead() const noexcept
+        {
+            return (readOpt_ != readOption::NO_READ);
+        }
+
         //- True if (MUST_READ | MUST_READ_IF_MODIFIED) bits are set
         static bool isReadRequired(readOption opt) noexcept
         {
-            return static_cast<bool>(opt & readOption::MUST_READ);
+            return (opt & readOption::MUST_READ);
         }
 
         //- True if (MUST_READ | MUST_READ_IF_MODIFIED) bits are set
         bool isReadRequired() const noexcept
         {
-            return static_cast<bool>(readOpt_ & readOption::MUST_READ);
+            return (readOpt_ & readOption::MUST_READ);
         }
 
-        //- True if (READ_IF_PRESENT) bits are set
+        //- True if (LAZY_READ) bits are set [same as READ_IF_PRESENT]
         static bool isReadOptional(readOption opt) noexcept
         {
-            return (opt == readOption::READ_IF_PRESENT);
+            return (opt == readOption::LAZY_READ);
         }
 
-        //- True if (READ_IF_PRESENT) bits are set
+        //- True if (LAZY_READ) bits are set [same as READ_IF_PRESENT]
         bool isReadOptional() const noexcept
         {
-            return (readOpt_ == readOption::READ_IF_PRESENT);
+            return (readOpt_ == readOption::LAZY_READ);
+        }
+
+        //- Downgrade readOption optional (LAZY_READ), leaves NO_READ intact.
+        static readOption lazierRead(readOption opt) noexcept
+        {
+            return (opt == readOption::NO_READ ? opt : readOption::LAZY_READ);
         }
 
 

src/OpenFOAM/primitives/coordinate/systems/coordinateSystem.C

@@ -84,7 +84,7 @@ void Foam::coordinateSystem::assign
      && (dict.dictName() == coordinateSystem::typeName)
     )
     {
-        readOrigin = IOobjectOption::READ_IF_PRESENT;
+        readOrigin = IOobjectOption::lazierRead(readOrigin);
     }
 
     dict.readEntry("origin", origin_, keyType::LITERAL, readOrigin);
@@ -286,10 +286,8 @@ Foam::coordinateSystem::coordinateSystem
     if (dictName.size())
     {
         // Allow 'origin' to be optional if reading from a sub-dict
-        if (IOobjectOption::isReadRequired(readOrigin))
-        {
-            readOrigin = IOobjectOption::READ_IF_PRESENT;
-        }
+        readOrigin = IOobjectOption::lazierRead(readOrigin);
+
         assign(dict.subDict(dictName), readOrigin);
     }
     else

src/OpenFOAM/primitives/coordinate/systems/coordinateSystemNew.C

@@ -157,10 +157,7 @@ Foam::coordinateSystem::New
     {
         // Using a sub-dictionary
         // - the 'origin' can be optional
-        if (IOobjectOption::isReadRequired(readOrigin))
-        {
-            readOrigin = IOobjectOption::READ_IF_PRESENT;
-        }
+        readOrigin = IOobjectOption::lazierRead(readOrigin);
     }
     else
     {

src/dynamicMesh/polyTopoChange/polyTopoChange/hexRef8/refinementHistory.C

@@ -734,7 +734,7 @@ Foam::refinementHistory::refinementHistory
     regIOobject(io),
     active_(false)
 {
-    if (io.readOpt() != IOobject::NO_READ)
+    if (io.isAnyRead())
     {
         WarningInFunction
             << "read option IOobject::MUST_READ or READ_IF_PRESENT "

src/dynamicMesh/polyTopoChange/polyTopoChanger/polyTopoChanger.C

@@ -114,9 +114,9 @@ Foam::polyTopoChanger::polyTopoChanger
                 mesh.meshDir(),
                 "meshModifiers",
                 (
-                    // Safety? promote NO_READ to READ_IF_PRESENT
+                    // Safety? promote NO_READ to LAZY_READ
                     rOpt == IOobject::NO_READ
-                  ? IOobject::READ_IF_PRESENT
+                  ? IOobject::LAZY_READ
                   : rOpt
                 )
             ),

src/meshTools/regionModel/regionProperties/regionProperties.C

@@ -58,7 +58,7 @@ Foam::regionProperties::regionProperties
         )
     );
 
-    if (IOobject::isReadRequired(rOpt) || iodict.size())
+    if (IOobjectOption::isReadRequired(rOpt) || iodict.size())
     {
         iodict.readEntry("regions", props);
     }

src/meshTools/searchableSurfaces/triSurfaceMesh/triSurfaceMesh.C

@@ -420,7 +420,7 @@ Foam::triSurfaceMesh::triSurfaceMesh(const IOobject& io, const readAction r)
     outsideVolType_(volumeType::UNKNOWN)
 {
     // Check IO flags
-    if (io.readOpt() != IOobject::NO_READ)
+    if (io.isAnyRead())
     {
         const bool searchGlobal(r == localOrGlobal || r == masterOnly);
 
@@ -520,7 +520,7 @@ Foam::triSurfaceMesh::triSurfaceMesh
     surfaceClosed_(-1),
     outsideVolType_(volumeType::UNKNOWN)
 {
-    if (io.readOpt() != IOobject::NO_READ)
+    if (io.isAnyRead())
     {
         // Surface type (optional)
         const word surfType(dict.getOrDefault<word>("fileType", word::null));

src/parallel/distributed/distributedTriSurfaceMesh/distributedTriSurfaceMesh.C

@@ -2606,11 +2606,7 @@ Foam::distributedTriSurfaceMesh::distributedTriSurfaceMesh(const IOobject& io)
             searchableSurface::instance(),
             searchableSurface::local(),
             searchableSurface::db(),
-            (
-                searchableSurface::isReadRequired()
-              ? IOobject::READ_IF_PRESENT
-              : searchableSurface::readOpt()
-            ),
+            IOobjectOption::lazierRead(searchableSurface::readOpt()),
             searchableSurface::writeOpt(),
             searchableSurface::registerObject()
         ),
@@ -2719,11 +2715,7 @@ Foam::distributedTriSurfaceMesh::distributedTriSurfaceMesh
             searchableSurface::instance(),
             searchableSurface::local(),
             searchableSurface::db(),
-            (
-                searchableSurface::isReadRequired()
-              ? IOobject::READ_IF_PRESENT
-              : searchableSurface::readOpt()
-            ),
+            IOobjectOption::lazierRead(searchableSurface::readOpt()),
             searchableSurface::writeOpt(),
             searchableSurface::registerObject()
         ),

src/parallel/reconstruct/faReconstruct/faMeshReconstructor.C

@@ -568,7 +568,7 @@ Foam::faMeshReconstructor::faMeshReconstructor
     // Use 'headerClassName' for checking
     bool fileOk
     (
-        (fvFaceProcAddr.readOpt() != IOobjectOption::NO_READ)
+        fvFaceProcAddr.isAnyRead()
      && fvFaceProcAddr.isHeaderClass<labelIOList>()
     );
 

src/surfMesh/writers/common/surfaceWriter.C

@@ -207,9 +207,9 @@ Foam::surfaceWriter::surfaceWriter(const dictionary& options)
     {
         dictptr->readIfPresent("rotationCentre", geometryCentre_);
 
-        // 'origin' (READ_IF_PRESENT)
+        // 'origin' is optional within sub-dictionary
         geometryTransform_ =
-            coordSystem::cartesian(*dictptr, IOobjectOption::READ_IF_PRESENT);
+            coordSystem::cartesian(*dictptr, IOobjectOption::LAZY_READ);
     }
 
     fieldLevel_ = options.subOrEmptyDict("fieldLevel");