ENH: allow top-level definition of function object name scoping

- this refines commit c233961d45, which added prefix scoping.

  Default is now off (v2106 behaviour).

  The 'useNamePrefix' keyword can be specified on a per function basis
  or at the top-level of "functions".

  ```
      functions
      {
          errors          warn;
          useNamePrefix   true;

          func1
          {
              type  ...;
              useNamePrefix   false;
          }

          func2
          {
              type  ...;
              // Uses current default for useNamePrefix
          }
      }
  ```

src/OpenFOAM/db/functionObjects/functionObject/functionObject.C

@@ -41,6 +41,8 @@ namespace Foam
 
 bool Foam::functionObject::postProcess(false);
 
+bool Foam::functionObject::defaultUseNamePrefix(false);
+
 Foam::word Foam::functionObject::outputPrefix("postProcessing");
 
 
@@ -48,7 +50,7 @@ Foam::word Foam::functionObject::outputPrefix("postProcessing");
 
 Foam::word Foam::functionObject::scopedName(const word& name) const
 {
-    if (scopedNames_)
+    if (useNamePrefix_)
     {
         return IOobject::scopedName(name_, name);
     }
@@ -62,11 +64,11 @@ Foam::word Foam::functionObject::scopedName(const word& name) const
 Foam::functionObject::functionObject
 (
     const word& name,
-    const bool scopedNames
+    const bool withNamePrefix
 )
 :
     name_(name),
-    scopedNames_(scopedNames),
+    useNamePrefix_(withNamePrefix),
     log(postProcess)
 {}
 
@@ -144,17 +146,36 @@ const Foam::word& Foam::functionObject::name() const noexcept
 }
 
 
-bool Foam::functionObject::scopedNames() const noexcept
+bool Foam::functionObject::useNamePrefix() const noexcept
 {
-    return scopedNames_;
+    return useNamePrefix_;
+}
+
+
+bool Foam::functionObject::useNamePrefix(bool on) noexcept
+{
+    bool old(useNamePrefix_);
+    useNamePrefix_ = on;
+    return old;
 }
 
 
 bool Foam::functionObject::read(const dictionary& dict)
 {
+// OR
+// useNamePrefix_ = Switch("useNamePrefix", dict, defaultUseNamePrefix);
+
+    useNamePrefix_ =
+        dict.getOrDefault
+        (
+            "useNamePrefix",
+            defaultUseNamePrefix,
+            keyType::LITERAL
+        );
+
+
     if (!postProcess)
     {
-        scopedNames_ = dict.getOrDefault("scopedNames", true);
         log = dict.getOrDefault("log", true);
     }
 

src/OpenFOAM/db/functionObjects/functionObject/functionObject.H

@@ -103,10 +103,11 @@ Description
         Property | Description                            | Type | Reqd | Deflt
         type     | Type name of function object           | word |  yes  | -
         libs     | Library name(s) for implementation     | words | no  | -
-        errors   | Error handling (default/warn/ignore/strict) | word | no | inherits
-        region   | Name of region for multi-region cases  | word | no | region0
         enabled  | Switch to turn function object on/off  | bool | no | true
+        errors   | Error handling (default/warn/ignore/strict) | word | no | inherits
         log     | Switch to write log info to standard output | bool | no | true
+        useNamePrefix | Add scoping prefix to names       | bool | no | inherits
+        region   | Name of region for multi-region cases  | word | no | region0
         timeStart | Start time for function object execution | scalar | no | 0
         timeEnd   | End time for function object execution   | scalar | no | inf
         executeControl  | See time controls below     | word | no    | timeStep
@@ -118,6 +119,10 @@ Description
     If the \c errors entry is missing, it uses the value (if any)
     specified within the top-level functionObjectList.
 
+    If the \c useNamePrefix entry is missing, it uses the value (if any)
+    specified within the top-level functionObjectList or otherwise
+    uses the current value of functionObject::defaultUseNamePrefix
+
     Time controls:
     \table
         Option            | Description
@@ -218,40 +223,47 @@ class functionObject
 {
     // Private Data
 
-        //- Name
+        //- Function object name
         const word name_;
 
-        //- Flag to indicate that names should be scoped
+        //- Flag to indicate that names should be prefixed
-        bool scopedNames_;
+        bool useNamePrefix_;
 
 
 protected:
 
     // Protected Member Functions
 
-        //- Return a scoped name, e.g. used to construct local field names
+        //- Return a scoped (prefixed) name
+        //  Used to construct local field names, controlled by useNamePrefix_
         word scopedName(const word& name) const;
 
 
 public:
 
-    // Forward declarations
+    // Forward Declarations
     class unavailableFunctionObject;
 
-    //- Runtime type information
-    virtual const word& type() const = 0;
 
-    //- Flag to execute debug content
+    // Public Data
-    static int debug;
 
-    //- Global post-processing mode switch
+        //- Flag to write log into Info
-    static bool postProcess;
+        bool log;
 
-    //- Directory prefix
-    static word outputPrefix;
 
-    //- Flag to write log into Info
+    // Static Data Members
-    bool log;
+
+        //- Flag to execute debug content
+        static int debug;
+
+        //- Global post-processing mode switch
+        static bool postProcess;
+
+        //- Global default for useNamePrefix
+        static bool defaultUseNamePrefix;
+
+        //- Directory prefix
+        static word outputPrefix;
 
 
     // Declare run-time constructor selection tables
@@ -272,7 +284,7 @@ public:
         explicit functionObject
         (
             const word& name,
-            const bool scopedNames = true
+            const bool withNamePrefix = defaultUseNamePrefix
         );
 
         //- Return clone
@@ -300,11 +312,18 @@ public:
 
     // Member Functions
 
+        //- Runtime type information
+        virtual const word& type() const = 0;
+
         //- Return the name of this functionObject
         const word& name() const noexcept;
 
-        //- Return the scoped names flag
+        //- Return the flag for adding a scoping name prefix
-        bool scopedNames() const noexcept;
+        bool useNamePrefix() const noexcept;
+
+        //- Modify the flag for adding a scoping name prefix
+        //  \return previous value.
+        bool useNamePrefix(bool on) noexcept;
 
         //- Read and set the function object if its data have changed
         virtual bool read(const dictionary& dict);

src/OpenFOAM/db/functionObjects/functionObjectList/functionObjectList.C

@@ -34,6 +34,7 @@ License
 #include "timeControlFunctionObject.H"
 #include "dictionaryEntry.H"
 #include "stringOps.H"
+#include "Switch.H"
 #include "Tuple2.H"
 #include "etcFiles.H"
 #include "IOdictionary.H"
@@ -1009,10 +1010,27 @@ bool Foam::functionObjectList::read()
 
             if (!dEntry.isDict())
             {
-                if (key != "errors" && key != "libs")
+                // Handle or ignore some known/expected keywords
+
+                if (key == "useNamePrefix")  // As per functionObject
+                {
+                    Switch sw(dEntry.stream().peekFirst());
+                    if (sw.good())
+                    {
+                        functionObject::defaultUseNamePrefix = sw;
+                    }
+                    else
+                    {
+                        IOWarningInFunction(parentDict_)
+                            << "Entry '" << key << "' is not a valid switch"
+                            << endl;
+                    }
+                }
+                else if (key != "errors" && key != "libs")
                 {
                     IOWarningInFunction(parentDict_)
-                        << "Entry " << key << " is not a dictionary" << endl;
+                        << "Entry '" << key << "' is not a dictionary"
+                        << endl;
                 }
 
                 continue;

src/OpenFOAM/db/functionObjects/functionObjectList/functionObjectList.H

@@ -58,6 +58,7 @@ Description
         Property | Description                            | Type | Reqd | Deflt
         libs     | Preloaded library names                | words | no  | -
         errors   | Error handling (default/warn/ignore/strict) | word | no | inherits
+        useNamePrefix | Default enable/disable scoping prefix | bool | no | no-op
     \endtable
 
     The optional \c errors entry controls how FatalError is caught

tutorials/combustion/XiEngineFoam/kivaTest/system/momentum

@@ -5,6 +5,7 @@ momentum
     type    momentum;
     libs    (fieldFunctionObjects);
     log     true;
+    useNamePrefix   true;
 
     writeControl    writeTime;
     // executeInterval 10;

tutorials/incompressible/pisoFoam/RAS/cavity/system/FOmomentum

@@ -1,7 +1,7 @@
 /*--------------------------------*- C++ -*----------------------------------*\
 | =========                 |                                                 |
 | \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox           |
-|  \\    /   O peration     | Version:  v2106                                 |
+|  \\    /   O peration     | Version:  v2112                                 |
 |   \\  /    A nd           | Website:  www.openfoam.com                      |
 |    \\/     M anipulation  |                                                 |
 \*---------------------------------------------------------------------------*/
@@ -33,10 +33,13 @@ momentum1
     log             true;
     timeStart       0;
     timeEnd         1000;
+
     executeControl  timeStep;
     executeInterval 1;
     writeControl    writeTime;
     writeInterval   -1;
+
+    useNamePrefix   true;
 }
 
 

tutorials/incompressible/simpleFoam/pipeCyclic/system/momentum

@@ -5,6 +5,7 @@ momentum
     type    momentum;
     libs    (fieldFunctionObjects);
     log     true;
+    useNamePrefix   true;
 
     executeInterval 10;
     writeControl    writeTime;