ENH: properly trap incorrect enumerations (#1372)

- the Enum::readEntry() method was previously as bit sloppy with
  respect to the enumeration that it accepted. If the input was
  non-mandatory, typos would go unnoticed. Now tighten things so that
  if an enumeration is found, it must also be valid.

STYLE: remove unused/deprecated Enum::lookupOrFailsafe() method

- this was only used in a few places internally in 1712 and 1806 but
  has since then been superseded by getOrDefault() with an optional
  'failsafe' flag.

src/OpenFOAM/primitives/enums/Enum.C

@@ -164,7 +164,7 @@ EnumType Foam::Enum<EnumType>::getOrDefault
             IOWarningInFunction(dict)
                 << enumName << " is not in enumeration: " << *this << nl
                 << "using failsafe " << get(deflt)
-                << " (value " << int(deflt) << ")" << endl;
+                << " (value " << int(deflt) << ')' << endl;
         }
         else
         {
@@ -184,7 +184,7 @@ bool Foam::Enum<EnumType>::readEntry
     const word& key,
     const dictionary& dict,
     EnumType& val,
-    bool mandatory
+    const bool mandatory
 ) const
 {
     const entry* eptr = dict.findEntry(key, keyType::LITERAL);
@@ -198,16 +198,12 @@ bool Foam::Enum<EnumType>::readEntry
         if (idx >= 0)
         {
             val = EnumType(vals_[idx]);
-
             return true;
         }
 
-        if (mandatory)
-        {
-            FatalIOErrorInFunction(dict)
-                << enumName << " is not in enumeration: " << *this << nl
-                << exit(FatalIOError);
-        }
+        FatalIOErrorInFunction(dict)
+            << enumName << " is not in enumeration: " << *this << nl
+            << exit(FatalIOError);
     }
     else if (mandatory)
     {

src/OpenFOAM/primitives/enums/Enum.H

@@ -26,7 +26,7 @@ Class
 
 Description
     Enum is a wrapper around a list of names/values that represent particular
-    enumeration values.
+    enumeration values. All dictionary searches use a literal (not regex).
 
 SourceFiles
     Enum.C
@@ -143,7 +143,7 @@ public:
 
         //- Get the key in the dictionary and return the corresponding
         //- enumeration element based on its name.
-        //  FatalError if anything is incorrect.
+        //  FatalIOError if anything is incorrect.
         EnumType get
         (
             const word& key,        //!< Lookup key. Uses LITERAL (not REGEX)
@@ -154,7 +154,8 @@ public:
         //- enumeration element based on its name.
         //
         //  \return The value found or default if not found in dictionary.
-        //  FatalError (or Warning) if the enumerated name was incorrect.
+        //  FatalIOError if the enumeration is incorrect.
+        //  Specifying failsafe downgrades the FatalIOError to an IOWarning.
         EnumType getOrDefault
         (
             const word& key,        //!< Lookup key. Uses LITERAL (not REGEX)
@@ -164,8 +165,8 @@ public:
         ) const;
 
         //- Find entry and assign to T val.
-        //- FatalIOError if it is found and the number of tokens is incorrect,
-        //- or it is mandatory and not found.
+        //  FatalIOError if the enumeration is incorrect,
+        //  or when it is mandatory but was not found.
         //
         //  \return true if the entry was found.
         bool readEntry
@@ -173,11 +174,11 @@ public:
             const word& key,        //!< Lookup key. Uses LITERAL (not REGEX)
             const dictionary& dict, //!< dictionary
             EnumType& val,          //!< the value to read into
-            bool mandatory = true   //!< the keyword is mandatory
+            const bool mandatory = true   //!< the keyword is mandatory
         ) const;
 
         //- Find an entry if present, and assign to T val.
-        //- FatalIOError if it is found and the number of tokens is incorrect.
+        //  FatalIOError if the enumeration is incorrect.
         //  Default search: non-recursive with patterns.
         //
         //  \return true if the entry was found.
@@ -230,7 +231,7 @@ public:
         //- enumeration element based on its name.
         //
         //  \return The value found or default if not found in dictionary.
-        //  FatalError (or Warning) if the enumerated name was incorrect.
+        //  FatalError (or Warning) if the enumeration was incorrect.
         EnumType lookupOrDefault
         (
             const word& key,        //!< Lookup key. Uses LITERAL (not REGEX)
@@ -249,19 +250,6 @@ public:
         {
             return get(key, dict);
         }
-
-        //- Deprecated(2018-10) lookupOrDefault with warnings instead of error.
-        //  \deprecated(2018-10) - use getOrDefault() with failsafe option
-        EnumType FOAM_DEPRECATED_FOR(2018-10, "getOrDefault() method")
-        lookupOrFailsafe
-        (
-            const word& key,
-            const dictionary& dict,
-            const EnumType deflt
-        ) const
-        {
-            return getOrDefault(key, dict, deflt, true);
-        }
 };