ENH: add directive '#sinclude' (or '#includeIfPresent' as long name)

- consistency with make and more succinct.

- reduce code duplication in findEtcFiles.

applications/test/dictionary/testDict

@@ -14,8 +14,8 @@ FoamFile
 }
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
-#includeIfPresent "someUnknownFile"
+#sinclude   "someUnknownFile"
-#includeIfPresent "$FOAM_CASE/someUnknownFile"
+#sinclude   "$FOAM_CASE/someUnknownFile"
 #includeIfPresent "$FOAM_CASE/someUnknownFile-$FOAM_CASENAME"
 
 internalField   uniform 1;

applications/utilities/miscellaneous/foamDictionary/foamDictionary.C

@@ -59,7 +59,7 @@ Usage
         the resulting dictionary to standard output.
 
       - \par -includes
-        List the \c \#include and \c \#includeIfPresent files to standard output
+        List the \c \#include and \c \#sinclude files to standard output
 
       - \par -disableFunctionEntries
         Do not expand macros or directives (\#include etc)
@@ -307,7 +307,7 @@ int main(int argc, char *argv[])
     argList::addBoolOption
     (
         "includes",
-        "List the #include/#includeIfPresent files to standard output"
+        "List the #include/#sinclude files to standard output"
     );
     argList::addBoolOption
     (

src/OpenFOAM/Make/files

@@ -231,7 +231,6 @@ $(functionEntries)/functionEntry/functionEntry.C
 $(functionEntries)/includeEntry/includeEntry.C
 $(functionEntries)/includeEtcEntry/includeEtcEntry.C
 $(functionEntries)/includeFuncEntry/includeFuncEntry.C
-$(functionEntries)/includeIfPresentEntry/includeIfPresentEntry.C
 $(functionEntries)/inputMode/inputMode.C
 $(functionEntries)/removeEntry/removeEntry.C
 

src/OpenFOAM/db/dictionary/functionEntries/README

@@ -10,8 +10,9 @@
   #remove           | dict              | keyType or List<keyType>
                     |                   |
   #include          | dict/primitive    | string
-  #includeEtc       | dict/primitive    | string
+  #sinclude         | dict/primitive    | string
   #includeIfPresent | dict/primitive    | string
+  #includeEtc       | dict/primitive    | string
   #includeFunc      | dict              | word
                     |                   |
   #calc             | dict/primitive    | string
@@ -27,4 +28,4 @@ Pending future extensions
   #undef            | dict              | keyType or List<keyType>
 
 
-2017-11-26
+2018-05-28

src/OpenFOAM/db/dictionary/functionEntries/includeEntry/includeEntry.C

@@ -3,7 +3,7 @@
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     |
     \\  /    A nd           | Copyright (C) 2011-2017 OpenFOAM Foundation
-     \\/     M anipulation  |
+     \\/     M anipulation  | Copyright (C) 2018 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -57,9 +57,47 @@ namespace functionEntries
         primitiveEntryIstream,
         include
     );
+
+    addNamedToMemberFunctionSelectionTable
+    (
+        functionEntry,
+        sincludeEntry,
+        execute,
+        dictionaryIstream,
+        sinclude
+    );
+
+    addNamedToMemberFunctionSelectionTable
+    (
+        functionEntry,
+        sincludeEntry,
+        execute,
+        primitiveEntryIstream,
+        sinclude
+    );
+
+    // Compat 1712 and earlier
+    addNamedToMemberFunctionSelectionTable
+    (
+        functionEntry,
+        sincludeEntry,
+        execute,
+        dictionaryIstream,
+        includeIfPresent
+    );
+
+    addNamedToMemberFunctionSelectionTable
+    (
+        functionEntry,
+        sincludeEntry,
+        execute,
+        primitiveEntryIstream,
+        includeIfPresent
+    );
 }
 }
 
+
 // * * * * * * * * * * * Protected Member Functions  * * * * * * * * * * * * //
 
 Foam::fileName Foam::functionEntries::includeEntry::resolveFile
@@ -97,7 +135,7 @@ bool Foam::functionEntries::includeEntry::execute
     const fileName fName(resolveFile(is.name().path(), rawName, parentDict));
 
     autoPtr<ISstream> ifsPtr(fileHandler().NewIFstream(fName));
-    ISstream& ifs = ifsPtr();
+    auto& ifs = *ifsPtr;
 
     if (ifs)
     {
@@ -144,7 +182,7 @@ bool Foam::functionEntries::includeEntry::execute
     const fileName fName(resolveFile(is.name().path(), rawName, parentDict));
 
     autoPtr<ISstream> ifsPtr(fileHandler().NewIFstream(fName));
-    ISstream& ifs = ifsPtr();
+    auto& ifs = *ifsPtr;
 
     if (ifs)
     {
@@ -180,4 +218,79 @@ bool Foam::functionEntries::includeEntry::execute
 }
 
 
+bool Foam::functionEntries::sincludeEntry::execute
+(
+    dictionary& parentDict,
+    Istream& is
+)
+{
+    const fileName rawName(is);
+    const fileName fName(resolveFile(is.name().path(), rawName, parentDict));
+
+    autoPtr<ISstream> ifsPtr(fileHandler().NewIFstream(fName));
+    auto& ifs = *ifsPtr;
+
+    if (ifs)
+    {
+        if (Foam::functionEntries::includeEntry::log)
+        {
+            Info<< fName << endl;
+        }
+
+        // Add watch on included file
+        const dictionary& top = parentDict.topDict();
+        if (isA<regIOobject>(top))
+        {
+            regIOobject& rio = const_cast<regIOobject&>
+            (
+                dynamic_cast<const regIOobject&>(top)
+            );
+            rio.addWatch(fName);
+        }
+
+        parentDict.read(ifs);
+    }
+
+    return true; // Never fails
+}
+
+
+bool Foam::functionEntries::sincludeEntry::execute
+(
+    const dictionary& parentDict,
+    primitiveEntry& entry,
+    Istream& is
+)
+{
+    const fileName rawName(is);
+    const fileName fName(resolveFile(is.name().path(), rawName, parentDict));
+
+    autoPtr<ISstream> ifsPtr(fileHandler().NewIFstream(fName));
+    auto& ifs = *ifsPtr;
+
+    if (ifs)
+    {
+        if (Foam::functionEntries::includeEntry::log)
+        {
+            Info<< fName << endl;
+        }
+
+        // Add watch on included file
+        const dictionary& top = parentDict.topDict();
+        if (isA<regIOobject>(top))
+        {
+            regIOobject& rio = const_cast<regIOobject&>
+            (
+                dynamic_cast<const regIOobject&>(top)
+            );
+            rio.addWatch(fName);
+        }
+
+        entry.read(parentDict, ifs);
+    }
+
+    return true; // Never fails
+}
+
+
 // ************************************************************************* //

src/OpenFOAM/db/dictionary/functionEntries/includeEntry/includeEntry.H

@@ -3,7 +3,7 @@
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     |
     \\  /    A nd           | Copyright (C) 2011-2016 OpenFOAM Foundation
-     \\/     M anipulation  |
+     \\/     M anipulation  | Copyright (C) 2018 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -25,19 +25,25 @@ Class
     Foam::functionEntries::includeEntry
 
 Description
-    Specify an include file when reading dictionaries, expects a
+    A dictionary directive for including a file, expects a single string
-    single string to follow.
+    to follow.
 
-    An example of the \c \#include directive:
+    An example of the \c \#include directive to include a file:
     \verbatim
-        #include "includeFile"
+        #include "includeFileMustExist"
     \endverbatim
 
-    The usual expansion of environment variables and other constructs
+    An example of the \c \#sinclude directive to conditionally include a file
-    (eg, the \c ~OpenFOAM/ expansion) is retained.
+    when it exists.
+    \verbatim
+        #sinclude "includeFileCanBeMissing"
+    \endverbatim
+
+    The usual expansion of environment variables and other expansions
+    (eg, a leading "<case>/", "<system>/", "<etc>/", ...) are retained.
 
 See also
-    fileName, string::expand()
+    fileName, string::expand(), functionEntries::sincludeEntry
 
 SourceFiles
     includeEntry.C
@@ -97,7 +103,35 @@ public:
             primitiveEntry& entry,
             Istream& is
         );
+};
 
+
+/*---------------------------------------------------------------------------*\
+                        Class sincludeEntry Declaration
+\*---------------------------------------------------------------------------*/
+
+//- A dictionary directive for conditionally including a file,
+//- expects a single string to follow.
+//
+//  The \c \#sinclude directive (and the \c \#includeIfPresent alias) behaves
+//  identically to the \c \#include directive, but does not generate an error
+//  if the file does not exist.
+class sincludeEntry
+:
+    public includeEntry
+{
+public:
+
+    //- Include file (if it exists) in a sub-dict context
+    static bool execute(dictionary& parentDict, Istream& is);
+
+    //- Include file (if it exists) in a primitiveEntry context
+    static bool execute
+    (
+        const dictionary& parentDict,
+        primitiveEntry& entry,
+        Istream& is
+    );
 };
 
 

src/OpenFOAM/db/dictionary/functionEntries/includeEtcEntry/includeEtcEntry.C

@@ -96,7 +96,7 @@ bool Foam::functionEntries::includeEtcEntry::execute
     const fileName fName(resolveEtcFile(rawName, parentDict));
 
     autoPtr<ISstream> ifsPtr(fileHandler().NewIFstream(fName));
-    ISstream& ifs = ifsPtr();
+    auto& ifs = *ifsPtr;
 
     if (ifs)
     {
@@ -131,7 +131,7 @@ bool Foam::functionEntries::includeEtcEntry::execute
     const fileName fName(resolveEtcFile(rawName, parentDict));
 
     autoPtr<ISstream> ifsPtr(fileHandler().NewIFstream(fName));
-    ISstream& ifs = ifsPtr();
+    auto& ifs = *ifsPtr;
 
     if (ifs)
     {

src/OpenFOAM/db/dictionary/functionEntries/includeEtcEntry/includeEtcEntry.H

@@ -25,6 +25,9 @@ Class
     Foam::functionEntries::includeEtcEntry
 
 Description
+    A dictionary directive for including a file found using the findEtcFile()
+    mechanism.
+
     Specify an etc file to include when reading dictionaries, expects a
     single string to follow.
 

src/OpenFOAM/db/dictionary/functionEntries/includeIfPresentEntry/includeIfPresentEntry.C

@@ -1,136 +0,0 @@
-/*---------------------------------------------------------------------------*\
-  =========                 |
-  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
-   \\    /   O peration     |
-    \\  /    A nd           | Copyright (C) 2011-2017 OpenFOAM Foundation
-     \\/     M anipulation  |
--------------------------------------------------------------------------------
-License
-    This file is part of OpenFOAM.
-
-    OpenFOAM is free software: you can redistribute it and/or modify it
-    under the terms of the GNU General Public License as published by
-    the Free Software Foundation, either version 3 of the License, or
-    (at your option) any later version.
-
-    OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
-    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
-    for more details.
-
-    You should have received a copy of the GNU General Public License
-    along with OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
-
-\*---------------------------------------------------------------------------*/
-
-#include "includeIfPresentEntry.H"
-#include "dictionary.H"
-#include "IFstream.H"
-#include "regIOobject.H"
-#include "addToMemberFunctionSelectionTable.H"
-#include "fileOperation.H"
-
-// * * * * * * * * * * * * * * Static Data Members * * * * * * * * * * * * * //
-
-namespace Foam
-{
-namespace functionEntries
-{
-    addNamedToMemberFunctionSelectionTable
-    (
-        functionEntry,
-        includeIfPresentEntry,
-        execute,
-        dictionaryIstream,
-        includeIfPresent
-    );
-
-    addNamedToMemberFunctionSelectionTable
-    (
-        functionEntry,
-        includeIfPresentEntry,
-        execute,
-        primitiveEntryIstream,
-        includeIfPresent
-    );
-}
-}
-
-// * * * * * * * * * * * * * * * Member Functions  * * * * * * * * * * * * * //
-
-bool Foam::functionEntries::includeIfPresentEntry::execute
-(
-    dictionary& parentDict,
-    Istream& is
-)
-{
-    const fileName rawName(is);
-    const fileName fName(resolveFile(is.name().path(), rawName, parentDict));
-
-    autoPtr<ISstream> ifsPtr(fileHandler().NewIFstream(fName));
-    ISstream& ifs = ifsPtr();
-
-    if (ifs)
-    {
-        if (Foam::functionEntries::includeEntry::log)
-        {
-            Info<< fName << endl;
-        }
-
-        // Add watch on included file
-        const dictionary& top = parentDict.topDict();
-        if (isA<regIOobject>(top))
-        {
-            regIOobject& rio = const_cast<regIOobject&>
-            (
-                dynamic_cast<const regIOobject&>(top)
-            );
-            rio.addWatch(fName);
-        }
-
-        parentDict.read(ifs);
-    }
-
-    return true;
-}
-
-
-bool Foam::functionEntries::includeIfPresentEntry::execute
-(
-    const dictionary& parentDict,
-    primitiveEntry& entry,
-    Istream& is
-)
-{
-    const fileName rawName(is);
-    const fileName fName(resolveFile(is.name().path(), rawName, parentDict));
-
-    autoPtr<ISstream> ifsPtr(fileHandler().NewIFstream(fName));
-    ISstream& ifs = ifsPtr();
-
-    if (ifs)
-    {
-        if (Foam::functionEntries::includeEntry::log)
-        {
-            Info<< fName << endl;
-        }
-
-        // Add watch on included file
-        const dictionary& top = parentDict.topDict();
-        if (isA<regIOobject>(top))
-        {
-            regIOobject& rio = const_cast<regIOobject&>
-            (
-                dynamic_cast<const regIOobject&>(top)
-            );
-            rio.addWatch(fName);
-        }
-
-        entry.read(parentDict, ifs);
-    }
-
-    return true;
-}
-
-
-// ************************************************************************* //

src/OpenFOAM/db/dictionary/functionEntries/includeIfPresentEntry/includeIfPresentEntry.H

@@ -1,86 +0,0 @@
-/*---------------------------------------------------------------------------*\
-  =========                 |
-  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
-   \\    /   O peration     |
-    \\  /    A nd           | Copyright (C) 2011-2016 OpenFOAM Foundation
-     \\/     M anipulation  |
--------------------------------------------------------------------------------
-License
-    This file is part of OpenFOAM.
-
-    OpenFOAM is free software: you can redistribute it and/or modify it
-    under the terms of the GNU General Public License as published by
-    the Free Software Foundation, either version 3 of the License, or
-    (at your option) any later version.
-
-    OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
-    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
-    for more details.
-
-    You should have received a copy of the GNU General Public License
-    along with OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
-
-Class
-    Foam::functionEntries::includeIfPresentEntry
-
-Description
-    Specify a file to include if it exists. Expects a single string to follow.
-
-    The \c \#includeIfPresent directive is similar to the \c \#include
-    directive, but does not generate an error if the file does not exist.
-
-See also
-    Foam::functionEntries::includeEntry
-
-SourceFiles
-    includeIfPresentEntry.C
-
-\*---------------------------------------------------------------------------*/
-
-#ifndef includeIfPresentEntry_H
-#define includeIfPresentEntry_H
-
-#include "includeEntry.H"
-
-// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
-
-namespace Foam
-{
-namespace functionEntries
-{
-
-/*---------------------------------------------------------------------------*\
-                    Class includeIfPresentEntry Declaration
-\*---------------------------------------------------------------------------*/
-
-class includeIfPresentEntry
-:
-    public includeEntry
-{
-public:
-
-    //- Include (if present) in a sub-dict context
-    static bool execute(dictionary& parentDict, Istream& is);
-
-    //- Include (if present) in a primitiveEntry context
-    static bool execute
-    (
-        const dictionary& parentDict,
-        primitiveEntry& entry,
-        Istream& is
-    );
-
-};
-
-
-// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
-
-} // End namespace functionEntries
-} // End namespace Foam
-
-// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
-
-#endif
-
-// ************************************************************************* //

src/OpenFOAM/global/etcFiles/etcFiles.C

@@ -3,7 +3,7 @@
   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
    \\    /   O peration     |
     \\  /    A nd           | Copyright (C) 2016 OpenFOAM Foundation
-     \\/     M anipulation  | Copyright (C) 2017 OpenCFD Ltd.
+     \\/     M anipulation  | Copyright (C) 2017-2018 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -32,8 +32,10 @@ License
 //
 // These could be exposed too (if required), but are fairly special purpose.
 //
-//! \cond fileScope
+
-//
+namespace
+{
+
 // Assign 'queried' parameter to the user resource directory.
 // Return true if this directory exists.
 //
@@ -62,9 +64,15 @@ static inline bool groupResourceDir(Foam::fileName& queried)
         return Foam::isDir(queried);
     }
 
-    // Fallback (when WM_PROJECT_SITE is unset)
+    // When WM_PROJECT_SITE is unset:
     queried = Foam::getEnv("WM_PROJECT_INST_DIR")/"site";
-    return (queried.size() > 5 && Foam::isDir(queried));
+    return (queried.size() > 4 && Foam::isDir(queried));
+
+    // NOTE: this alternative bit of code corresponds to how we patch things
+    // for spack (and EasyBuild?) to avoid leaking out to the parent directory
+    //
+    // queried = Foam::getEnv("WM_PROJECT_DIR")/"site";
+    // return (queried.size() > 4 && Foam::isDir(queried));
 }
 
 
@@ -77,46 +85,40 @@ static inline bool groupResourceDir(Foam::fileName& queried)
 static inline bool projectResourceDir(Foam::fileName& queried)
 {
     queried = Foam::getEnv("WM_PROJECT_DIR")/"etc";
-    return (queried.size() > 4 && Foam::isDir(queried));
+    return (queried.size() > 3 && Foam::isDir(queried));
 }
 
-//! \endcond
 
-
+Foam::fileNameList searchEtc
-// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
-
-Foam::fileNameList Foam::findEtcDirs
 (
-    const fileName& name,
+    const Foam::fileName& name,
-    const bool findFirst
+    const bool findFirst,
+    bool (*accept)(const Foam::fileName&)
 )
 {
-    fileNameList results;
+    Foam::fileNameList list;
-
+    Foam::fileName dir, candidate;
-    do
-    {
-        fileName dir, candidate;
 
     // User resource directories
     if (userResourceDir(dir))
     {
-            candidate = dir/FOAMversion/name;
+        candidate = dir/Foam::FOAMversion/name;
-            if (isDir(candidate))
+        if (accept(candidate))
         {
-                results.append(candidate);
+            list.append(std::move(candidate));
             if (findFirst)
             {
-                    break;
+                return list;
             }
         }
 
         candidate = dir/name;
-            if (isDir(candidate))
+        if (accept(candidate))
         {
-                results.append(candidate);
+            list.append(std::move(candidate));
             if (findFirst)
             {
-                    break;
+                return list;
             }
         }
     }
@@ -124,23 +126,23 @@ Foam::fileNameList Foam::findEtcDirs
     // Group resource directories
     if (groupResourceDir(dir))
     {
-            candidate = dir/FOAMversion/name;
+        candidate = dir/Foam::FOAMversion/name;
-            if (isDir(candidate))
+        if (accept(candidate))
         {
-                results.append(candidate);
+            list.append(std::move(candidate));
             if (findFirst)
             {
-                    break;
+                return list;
             }
         }
 
         candidate = dir/name;
-            if (isDir(candidate))
+        if (accept(candidate))
         {
-                results.append(candidate);
+            list.append(std::move(candidate));
             if (findFirst)
             {
-                    break;
+                return list;
             }
         }
     }
@@ -149,15 +151,34 @@ Foam::fileNameList Foam::findEtcDirs
     if (projectResourceDir(dir))
     {
         candidate = dir/name;
-            if (isDir(dir) && isDir(candidate))
+        if (accept(candidate))
         {
-                results.append(candidate);
+            list.append(std::move(candidate));
         }
     }
-    }
-    while (false);  // Run exactly once
 
-    return results;
+    return list;
+}
+
+} // End anonymous namespace
+
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+
+Foam::fileNameList Foam::findEtcDirs
+(
+    const fileName& name,
+    const bool findFirst
+)
+{
+    return
+        searchEtc
+        (
+            name,
+            findFirst,
+            [](const fileName& f){ return isDir(f); }
+        );
 }
 
 
@@ -168,79 +189,20 @@ Foam::fileNameList Foam::findEtcFiles
     const bool findFirst
 )
 {
-    fileNameList results;
+    fileNameList list;
 
-    do
+    if (name.size())
     {
-        fileName dir, candidate;
+        // A file must have a name!
-
+        list = searchEtc
-        // User resource directories
+        (
-        if (userResourceDir(dir))
+            name,
-        {
+            findFirst,
-            candidate = dir/FOAMversion/name;
+            [](const fileName& f){ return isFile(f); }
-            if (isFile(candidate))
+        );
-            {
-                results.append(candidate);
-                if (findFirst)
-                {
-                    break;
-                }
     }
 
-            candidate = dir/name;
+    if (mandatory && list.empty())
-            if (isFile(candidate))
-            {
-                results.append(candidate);
-                if (findFirst)
-                {
-                    break;
-                }
-            }
-        }
-
-        // Group resource directories
-        if (groupResourceDir(dir))
-        {
-            candidate = dir/FOAMversion/name;
-            if (isFile(candidate))
-            {
-                results.append(candidate);
-                if (findFirst)
-                {
-                    break;
-                }
-            }
-
-            candidate = dir/name;
-            if (isFile(candidate))
-            {
-                results.append(candidate);
-                if (findFirst)
-                {
-                    break;
-                }
-            }
-        }
-
-        // Other (project) resource directory
-        if (projectResourceDir(dir))
-        {
-            candidate = dir/name;
-            if (isDir(dir) && isFile(candidate))
-            {
-                results.append(candidate);
-            }
-        }
-    }
-    while (false);  // Run exactly once
-
-    // No name?  It cannot be a file!
-    if (name.empty())
-    {
-        results.clear();
-    }
-
-    if (mandatory && results.empty())
     {
         // Abort if file is mandatory but not found
         std::cerr
@@ -250,21 +212,21 @@ Foam::fileNameList Foam::findEtcFiles
         ::exit(1);
     }
 
-    return results;
+    return list;
 }
 
 
 Foam::fileName Foam::findEtcFile(const fileName& name, const bool mandatory)
 {
-    fileNameList results(findEtcFiles(name, mandatory, true));
+    fileName file;
 
-    if (results.size())
+    fileNameList list(findEtcFiles(name, mandatory, true));
+    if (list.size())
     {
-        return results[0];
+        file = std::move(list.first());
     }
 
-    // Return null-constructed fileName rather than fileName::null
+    return file;
-    return fileName();
 }
 
 

src/OpenFOAM/global/etcFiles/etcFiles.H

@@ -45,19 +45,8 @@ namespace Foam
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
 //- Search for directories from user/group/other directories.
-//  The search scheme allows for version-specific and
+//
-//  version-independent files using the following hierarchy:
+// \note Uses search hierarchy as per findEtcFiles().
-//  - \b user settings:
-//    - ~/.OpenFOAM/\<VERSION\>
-//    - ~/.OpenFOAM/
-//  - \b group (site) settings (when $WM_PROJECT_SITE is set):
-//    - $WM_PROJECT_SITE/\<VERSION\>
-//    - $WM_PROJECT_SITE
-//  - \b group (site) settings (when $WM_PROJECT_SITE is not set):
-//    - $WM_PROJECT_INST_DIR/site/\<VERSION\>
-//    - $WM_PROJECT_INST_DIR/site/
-//  - \b other (project) settings:
-//    - $WM_PROJECT_DIR/etc/
 //
 //  \return The list of full paths of all the matching directories or
 //  an empty list if the name cannot be found.
@@ -68,19 +57,22 @@ fileNameList findEtcDirs
     const bool findFirst = false
 );
 
+
 //- Search for files from user/group/other directories.
-//  The search scheme allows for version-specific and
+//
-//  version-independent files using the following hierarchy:
+//  \note
+//  The following search hierarchy is also used by the foamEtcFile shell
+//  script, which allows for version-specific and version-independent files:
 //  - \b user settings:
 //    - ~/.OpenFOAM/\<VERSION\>
 //    - ~/.OpenFOAM/
-//  - \b group (site) settings (when $WM_PROJECT_SITE is set):
+//  - \b group settings (when $WM_PROJECT_SITE is set):
 //    - $WM_PROJECT_SITE/\<VERSION\>
 //    - $WM_PROJECT_SITE
-//  - \b group (site) settings (when $WM_PROJECT_SITE is not set):
+//  - \b group settings (when $WM_PROJECT_SITE is not set):
 //    - $WM_PROJECT_INST_DIR/site/\<VERSION\>
 //    - $WM_PROJECT_INST_DIR/site/
-//  - \b other (project) settings:
+//  - \b other (shipped) settings:
 //    - $WM_PROJECT_DIR/etc/
 //
 //  \return The list of full paths of all the matching files or
@@ -94,7 +86,9 @@ fileNameList findEtcFiles
     const bool findFirst = false
 );
 
-//- Search for a single file using findEtcFiles.
+
+//- Search for a single file using findEtcFiles().
+//
 //  \return The full path name of the first file found in the
 //  search hierarchy or an empty fileName if the name cannot be found.
 //  Optionally abort if the file cannot be found but is mandatory.

tutorials/multiphase/interFoam/laminar/damBreak/damBreak/system/controlDict

@@ -52,6 +52,6 @@ maxAlphaCo      1;
 
 maxDeltaT       1;
 
-#includeIfPresent "sampling"
+#sinclude   "sampling"
 
 // ************************************************************************* //