bugfixing, documentation in global/debug

- catch missing "controlDict" file immediately via findEtcFile() instead of
  checking IFstream::good(). This avoids segfaulting, since the error
  handling in IFstream uses classes that are not yet initialized.
- use new dictionary features (eg, lookupOrAddDefault) to reduce code
- fixed debug::switchSet to use ref-to-pointer so pointer actually gets set!

src/OpenFOAM/global/debug/debug.C

@@ -36,19 +36,16 @@ Description
 
 namespace Foam
 {
-
-// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
-
 namespace debug
 {
 
+//! @cond ignoreDocumentation - local scope
 dictionary* controlDictPtr_(NULL);
 dictionary* debugSwitchesPtr_(NULL);
 dictionary* infoSwitchesPtr_(NULL);
 dictionary* optimisationSwitchesPtr_(NULL);
 
-//- Class to ensure controlDictPtr_ is deleted at the end of the run
+// to ensure controlDictPtr_ is deleted at the end of the run
-//  @cond ignore documentation for this class
 class deleteControlDictPtr
 {
 public:
@@ -61,135 +58,110 @@ public:
         if (controlDictPtr_)
         {
             delete controlDictPtr_;
+            controlDictPtr_ = 0;
         }
     }
 };
-//! @endcond
 
 deleteControlDictPtr deleteControlDictPtr_;
+//! @endcond ignoreDocumentation
 
 
-dictionary& switchSet(const char* switchSetName, dictionary* switchSetPtr)
+} // End namespace debug
-{
+} // End namespace Foam
-    if (!switchSetPtr)
-    {
-        if (!controlDict().found(switchSetName))
-        {
-            cerr<< "debug::switchSet(const char*, dictionary*): " << std::endl
-                << "    Cannot find " <<  switchSetName
-            << " in dictionary " << controlDictPtr_->name().c_str()
-            << std::endl << std::endl;
-
-            ::exit(1);
-        }
-
-        switchSetPtr =
-            const_cast<dictionary*>(&(controlDict().subDict(switchSetName)));
-    }
-
-    return *switchSetPtr;
-}
-
-
-int debugSwitch
-(
-    dictionary& switchSet,
-    const char* switchName,
-    const int defaultValue
-)
-{
-    if (switchSet.found(switchName))
-    {
-        return readInt(switchSet.lookup(switchName));
-    }
-    else
-    {
-        switchSet.add(switchName, defaultValue);
-        return defaultValue;
-    }
-}
-
-}
-
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
-dictionary& debug::controlDict()
+Foam::dictionary& Foam::debug::controlDict()
 {
     if (!controlDictPtr_)
     {
-        fileName controlDictFileName(dotFoam("controlDict"));
+        controlDictPtr_ = new dictionary
-
+        (
-        IFstream dictFile(controlDictFileName);
+            IFstream(findEtcFile("controlDict", true))()
-
+        );
-        if (!dictFile.good())
-        {
-            cerr<< "debug::controlDict(): "
-                << "Cannot open essential file " << controlDictFileName.c_str()
-                << std::endl << std::endl;
-            ::exit(1);
-        }
-
-        controlDictPtr_ = new dictionary(dictFile);
     }
 
     return *controlDictPtr_;
 }
 
 
-dictionary& debug::debugSwitches()
+Foam::dictionary& Foam::debug::switchSet
+(
+    const char* subDictName,
+    dictionary*& subDictPtr
+)
+{
+    if (!subDictPtr)
+    {
+        entry* ePtr = controlDict().lookupEntryPtr
+        (
+            subDictName, false, false
+        );
+
+        if (!ePtr || !ePtr->isDict())
+        {
+            cerr<< "debug::switchSet(const char*, dictionary*&):\n"
+                << "    Cannot find " <<  subDictName << " in dictionary "
+                << controlDict().name().c_str()
+                << std::endl << std::endl;
+
+            ::exit(1);
+        }
+
+        subDictPtr = &ePtr->dict();
+    }
+
+    return *subDictPtr;
+}
+
+
+Foam::dictionary& Foam::debug::debugSwitches()
 {
     return switchSet("DebugSwitches", debugSwitchesPtr_);
 }
 
 
-int debug::debugSwitch(const char* switchName, const int defaultValue)
+Foam::dictionary& Foam::debug::infoSwitches()
-{
-    return debugSwitch
-    (
-        debugSwitches(),
-        switchName,
-        defaultValue
-    );
-}
-
-
-dictionary& debug::infoSwitches()
 {
     return switchSet("InfoSwitches", infoSwitchesPtr_);
 }
 
 
-int debug::infoSwitch(const char* switchName, const int defaultValue)
+Foam::dictionary& Foam::debug::optimisationSwitches()
-{
-    return debugSwitch
-    (
-        infoSwitches(),
-        switchName,
-        defaultValue
-    );
-}
-
-
-dictionary& debug::optimisationSwitches()
 {
     return switchSet("OptimisationSwitches", optimisationSwitchesPtr_);
 }
 
 
-int debug::optimisationSwitch(const char* switchName, const int defaultValue)
+int Foam::debug::debugSwitch(const char* name, const int defaultValue)
 {
-    return debugSwitch
+    return debugSwitches().lookupOrAddDefault
     (
-        optimisationSwitches(),
+        name, defaultValue, false, false
-        switchName,
+    );
-        defaultValue
+}
+
+
+int Foam::debug::infoSwitch(const char* name, const int defaultValue)
+{
+    return infoSwitches().lookupOrAddDefault
+    (
+        name, defaultValue, false, false
+    );
+}
+
+
+int Foam::debug::optimisationSwitch(const char* name, const int defaultValue)
+{
+    return optimisationSwitches().lookupOrAddDefault
+    (
+        name, defaultValue, false, false
     );
 }
 
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
-} // End namespace Foam
 
 // ************************************************************************* //

src/OpenFOAM/global/debug/debug.H

@@ -41,44 +41,40 @@ SourceFiles
 namespace Foam
 {
 
+// Forward declaration of classes
 class dictionary;
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
 namespace debug
 {
+    //- The central control dictionary.
+    //  Located in ~/.OpenFOAM/VERSION or $WM_PROJECT_DIR/etc
+    //  @sa Foam::findEtcFile()
     dictionary& controlDict();
 
-
+    //- The DebugSwitches sub-dictionary in the central controlDict.
-    dictionary& switchSet(const char* switchSetName, dictionary* switchSetPtr);
-
-
     dictionary& debugSwitches();
 
-    int debugSwitch
+    //- The InfoSwitches sub-dictionary in the central controlDict.
-    (
-        const char* switchName,
-        const int defaultValue = 0
-    );
-
-
     dictionary& infoSwitches();
 
-    int infoSwitch
+    //- The OptimisationSwitches sub-dictionary in the central controlDict.
-    (
-        const char* switchName,
-        const int defaultValue = 0
-    );
-
-
     dictionary& optimisationSwitches();
 
-    int optimisationSwitch
+    //- Lookup debug switch or add default value.
-    (
+    int debugSwitch(const char* name, const int defaultValue=0);
-        const char* switchName,
+
-        const int defaultValue = 0
+    //- Lookup info switch or add default value.
-    );
+    int infoSwitch(const char* name, const int defaultValue=0);
-}
+
+    //- Lookup optimisation switch or add default value.
+    int optimisationSwitch(const char* name, const int defaultValue=0);
+
+    //- Internal function to lookup a sub-dictionary from controlDict.
+    dictionary& switchSet(const char* subDictName, dictionary*& subDictPtr);
+
+} // End namespace debug
 
 
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //