]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Allow varying description output for patterns
authorJonathan Robey <class4kayaker@gmail.com>
Wed, 20 Jul 2016 19:13:51 +0000 (12:13 -0700)
committerJonathan Robey <class4kayaker@gmail.com>
Thu, 21 Jul 2016 21:18:38 +0000 (14:18 -0700)
include/deal.II/base/parameter_handler.h
source/base/parameter_handler.cc

index 62a66099d6e080f3d2efb71203357dcdc0520d66..d4709fe2197640ede4934b17b077e8006a9faa17 100644 (file)
@@ -67,10 +67,35 @@ namespace Patterns
      */
     virtual bool match (const std::string &test_string) const = 0;
 
+    /**
+     * List of possible description output formats.
+     *
+     * Capitalization chosen for similarity to ParameterHandler::OutputStyle.
+     */
+    enum OutputStyle
+    {
+      /**
+       * Simple text suitable for machine parsing in the static public member
+       * functions for all of the built in inheriting classes.
+       *
+       * Preferably human readable, but machine parsing is more critical.
+       */
+      Machine,
+      /**
+       * Easily human readable plain text format suitable for plain text
+       * documentation.
+       */
+      Text,
+      /**
+       * Easily human readable LaTeX format suitable for printing in manuals.
+       */
+      LaTeX
+    };
+
     /**
      * Return a string describing the pattern.
      */
-    virtual std::string description () const = 0;
+    virtual std::string description (const OutputStyle style=Machine) const = 0;
 
     /**
      * Return a pointer to an exact copy of the object. This is necessary
@@ -160,7 +185,7 @@ namespace Patterns
      * match. If bounds were specified to the constructor, then include them
      * into this description.
      */
-    virtual std::string description () const;
+    virtual std::string description (const OutputStyle style=Machine) const;
 
     /**
      * Return a copy of the present object, which is newly allocated on the
@@ -252,7 +277,7 @@ namespace Patterns
      * match. If bounds were specified to the constructor, then include them
      * into this description.
      */
-    virtual std::string description () const;
+    virtual std::string description (const OutputStyle style=Machine) const;
 
     /**
      * Return a copy of the present object, which is newly allocated on the
@@ -322,7 +347,7 @@ namespace Patterns
      * match. Here, this is the list of valid strings passed to the
      * constructor.
      */
-    virtual std::string description () const;
+    virtual std::string description (const OutputStyle style=Machine) const;
 
     /**
      * Return a copy of the present object, which is newly allocated on the
@@ -403,7 +428,7 @@ namespace Patterns
      * Return a description of the pattern that valid strings are expected to
      * match.
      */
-    virtual std::string description () const;
+    virtual std::string description (const OutputStyle style=Machine) const;
 
     /**
      * Return a copy of the present object, which is newly allocated on the
@@ -518,7 +543,7 @@ namespace Patterns
      * Return a description of the pattern that valid strings are expected to
      * match.
      */
-    virtual std::string description () const;
+    virtual std::string description (const OutputStyle style=Machine) const;
 
     /**
      * Return a copy of the present object, which is newly allocated on the
@@ -612,7 +637,7 @@ namespace Patterns
      * match. Here, this is the list of valid strings passed to the
      * constructor.
      */
-    virtual std::string description () const;
+    virtual std::string description (const OutputStyle style=Machine) const;
 
     /**
      * Return a copy of the present object, which is newly allocated on the
@@ -676,7 +701,7 @@ namespace Patterns
      * Return a description of the pattern that valid strings are expected to
      * match.
      */
-    virtual std::string description () const;
+    virtual std::string description (const OutputStyle style=Machine) const;
 
     /**
      * Return a copy of the present object, which is newly allocated on the
@@ -721,7 +746,7 @@ namespace Patterns
      * Return a description of the pattern that valid strings are expected to
      * match. Here, this is the string <tt>"[Anything]"</tt>.
      */
-    virtual std::string description () const;
+    virtual std::string description (const OutputStyle style=Machine) const;
 
     /**
      * Return a copy of the present object, which is newly allocated on the
@@ -784,7 +809,7 @@ namespace Patterns
      * Return a description of the pattern that valid strings are expected to
      * match. Here, this is the string <tt>"[Filename]"</tt>.
      */
-    virtual std::string description () const;
+    virtual std::string description (const OutputStyle style=Machine) const;
 
     /**
      * Return a copy of the present object, which is newly allocated on the
@@ -843,7 +868,7 @@ namespace Patterns
      * Return a description of the pattern that valid strings are expected to
      * match. Here, this is the string <tt>"[Filename]"</tt>.
      */
-    virtual std::string description () const;
+    virtual std::string description (const OutputStyle style=Machine) const;
 
     /**
      * Return a copy of the present object, which is newly allocated on the
index 98e8ee8097fa0b165e4104d96e41e842bcbe3c51..fa50f9ea775c701cfc4b63c6beca81ae9a115748 100644 (file)
@@ -179,25 +179,65 @@ namespace Patterns
 
 
 
-  std::string Integer::description () const
+  std::string Integer::description (const OutputStyle style) const
   {
-    // check whether valid bounds
-    // were specified, and if so
-    // output their values
-    if (lower_bound <= upper_bound)
+    switch (style)
       {
-        std::ostringstream description;
+      case Machine:
+      {
+        // check whether valid bounds
+        // were specified, and if so
+        // output their values
+        if (lower_bound <= upper_bound)
+          {
+            std::ostringstream description;
 
-        description << description_init
-                    <<" range "
-                    << lower_bound << "..." << upper_bound
-                    << " (inclusive)]";
-        return description.str();
+            description << description_init
+                        <<" range "
+                        << lower_bound << "..." << upper_bound
+                        << " (inclusive)]";
+            return description.str();
+          }
+        else
+          // if no bounds were given, then
+          // return generic string
+          return "[Integer]";
       }
-    else
-      // if no bounds were given, then
-      // return generic string
-      return "[Integer]";
+      case Text:
+      {
+        if (lower_bound <= upper_bound)
+          {
+            std::ostringstream description;
+
+            description << "An integer n such that "
+                        << lower_bound << " <= n <= " << upper_bound;
+
+            return description.str();
+          }
+        else
+          return "An integer";
+      }
+      case LaTeX:
+      {
+        if (lower_bound <= upper_bound)
+          {
+            std::ostringstream description;
+
+            description << "An integer $n$ such that $"
+                        << lower_bound << "\\leq n \\leq " << upper_bound
+                        << "$";
+
+            return description.str();
+          }
+        else
+          return "An integer";
+      }
+      default:
+        AssertThrow(false, ExcNotImplemented());
+      }
+    // Should never occur without an exception, but prevent compiler from
+    // complaining
+    return "";
   }
 
 
@@ -278,34 +318,90 @@ namespace Patterns
 
 
 
-  std::string Double::description () const
+  std::string Double::description (const OutputStyle style) const
   {
-    std::ostringstream description;
-
-    if (lower_bound <= upper_bound)
+    switch (style)
+      {
+      case Machine:
       {
-        // bounds are valid
-        description << description_init << " ";
-        // We really want to compare with ==, but -Wfloat-equal would create
-        // a warning here, so work around it.
-        if (0==std::memcmp(&lower_bound, &min_double_value, sizeof(lower_bound)))
-          description << "-MAX_DOUBLE";
+        std::ostringstream description;
+
+        if (lower_bound <= upper_bound)
+          {
+            // bounds are valid
+            description << description_init << " ";
+            // We really want to compare with ==, but -Wfloat-equal would create
+            // a warning here, so work around it.
+            if (0==std::memcmp(&lower_bound, &min_double_value, sizeof(lower_bound)))
+              description << "-MAX_DOUBLE";
+            else
+              description << lower_bound;
+            description << "...";
+            if (0==std::memcmp(&upper_bound, &max_double_value, sizeof(upper_bound)))
+              description << "MAX_DOUBLE";
+            else
+              description << upper_bound;
+            description << " (inclusive)]";
+            return description.str();
+          }
         else
-          description << lower_bound;
-        description << "...";
-        if (0==std::memcmp(&upper_bound, &max_double_value, sizeof(upper_bound)))
-          description << "MAX_DOUBLE";
+          {
+            // invalid bounds, assume unbounded double:
+            description << description_init << "]";
+            return description.str();
+          }
+      }
+      case Text:
+      {
+        if (lower_bound <= upper_bound)
+          {
+            std::ostringstream description;
+
+            description << "A floating point number v such that ";
+            if (0==std::memcmp(&lower_bound, &min_double_value, sizeof(lower_bound)))
+              description << "-MAX_DOUBLE";
+            else
+              description << lower_bound;
+            description << " <= v <= ";
+            if (0==std::memcmp(&upper_bound, &max_double_value, sizeof(upper_bound)))
+              description << "MAX_DOUBLE";
+            else
+              description << upper_bound;
+
+            return description.str();
+          }
         else
-          description << upper_bound;
-        description << " (inclusive)]";
-        return description.str();
+          return "A floating point number";
       }
-    else
+      case LaTeX:
       {
-        // invalid bounds, assume unbounded double:
-        description << description_init << "]";
-        return description.str();
+        if (lower_bound <= upper_bound)
+          {
+            std::ostringstream description;
+
+            description << "A floating point number $v$ such that $";
+            if (0==std::memcmp(&lower_bound, &min_double_value, sizeof(lower_bound)))
+              description << "-\\text{MAX\\_DOUBLE}";
+            else
+              description << lower_bound;
+            description << " \\leq v \\leq ";
+            if (0==std::memcmp(&upper_bound, &max_double_value, sizeof(upper_bound)))
+              description << "\\text{MAX\\_DOUBLE}";
+            else
+              description << upper_bound;
+            description << "$";
+
+            return description.str();
+          }
+        else
+          return "A floating point number";
+      }
+      default:
+        AssertThrow(false, ExcNotImplemented());
       }
+    // Should never occur without an exception, but prevent compiler from
+    // complaining
+    return "";
   }
 
 
@@ -392,16 +488,37 @@ namespace Patterns
 
 
 
-  std::string Selection::description () const
+  std::string Selection::description (const OutputStyle style) const
   {
-    std::ostringstream description;
+    switch (style)
+      {
+      case Machine:
+      {
+        std::ostringstream description;
+
+        description << description_init
+                    << " "
+                    << sequence
+                    << " ]";
+
+        return description.str();
+      }
+      case Text:
+      case LaTeX:
+      {
+        std::ostringstream description;
 
-    description << description_init
-                << " "
-                << sequence
-                << " ]";
+        description << "Any one of "
+                    << Utilities::replace_in_string(sequence,"|",", ");
 
-    return description.str();
+        return description.str();
+      }
+      default:
+        AssertThrow(false, ExcNotImplemented());
+      }
+    // Should never occur without an exception, but prevent compiler from
+    // complaining
+    return "";
   }
 
 
@@ -516,19 +633,46 @@ namespace Patterns
 
 
 
-  std::string List::description () const
+  std::string List::description (const OutputStyle style) const
   {
-    std::ostringstream description;
+    switch (style)
+      {
+      case Machine:
+      {
+        std::ostringstream description;
 
-    description << description_init
-                << " list of <" << pattern->description() << ">"
-                << " of length " << min_elements << "..." << max_elements
-                << " (inclusive)";
-    if (separator != ",")
-      description << " separated by <" << separator << ">";
-    description << "]";
+        description << description_init
+                    << " list of <" << pattern->description(style) << ">"
+                    << " of length " << min_elements << "..." << max_elements
+                    << " (inclusive)";
+        if (separator != ",")
+          description << " separated by <" << separator << ">";
+        description << "]";
 
-    return description.str();
+        return description.str();
+      }
+      case Text:
+      case LaTeX:
+      {
+        std::ostringstream description;
+
+        description << "A list of "
+                    << min_elements << " to " << max_elements
+                    << " elements ";
+        if (separator != ",")
+          description << "separated by <" << separator << "> ";
+        description  << "where each element is ["
+                     << pattern->description(style)
+                     << "]";
+
+        return description.str();
+      }
+      default:
+        AssertThrow(false, ExcNotImplemented());
+      }
+    // Should never occur without an exception, but prevent compiler from
+    // complaining
+    return "";
   }
 
 
@@ -693,21 +837,51 @@ namespace Patterns
 
 
 
-  std::string Map::description () const
+  std::string Map::description (const OutputStyle style) const
   {
-    std::ostringstream description;
-
-    description << description_init
-                << " map of <"
-                << key_pattern->description() << ":"
-                << value_pattern->description() << ">"
-                << " of length " << min_elements << "..." << max_elements
-                << " (inclusive)";
-    if (separator != ",")
-      description << " separated by <" << separator << ">";
-    description << "]";
-
-    return description.str();
+    switch (style)
+      {
+      case Machine:
+      {
+        std::ostringstream description;
+
+        description << description_init
+                    << " map of <"
+                    << key_pattern->description(style) << ":"
+                    << value_pattern->description(style) << ">"
+                    << " of length " << min_elements << "..." << max_elements
+                    << " (inclusive)";
+        if (separator != ",")
+          description << " separated by <" << separator << ">";
+        description << "]";
+
+        return description.str();
+      }
+      case Text:
+      case LaTeX:
+      {
+        std::ostringstream description;
+
+        description << "A key-value map of "
+                    << min_elements << " to " << max_elements
+                    << " elements ";
+        if (separator != ",")
+          description << " separated by <" << separator << "> ";
+        description << " where each key is ["
+                    << key_pattern->description(style)
+                    << "]"
+                    << " and each value is ["
+                    << value_pattern->description(style)
+                    << "]";
+
+        return description.str();
+      }
+      default:
+        AssertThrow(false, ExcNotImplemented());
+      }
+    // Should never occur without an exception, but prevent compiler from
+    // complaining
+    return "";
   }
 
 
@@ -859,16 +1033,37 @@ namespace Patterns
 
 
 
-  std::string MultipleSelection::description () const
+  std::string MultipleSelection::description (const OutputStyle style) const
   {
-    std::ostringstream description;
+    switch (style)
+      {
+      case Machine:
+      {
+        std::ostringstream description;
+
+        description << description_init
+                    << " "
+                    << sequence
+                    << " ]";
+
+        return description.str();
+      }
+      case Text:
+      case LaTeX:
+      {
+        std::ostringstream description;
 
-    description << description_init
-                << " "
-                << sequence
-                << " ]";
+        description << "A comma-separated list of any of "
+                    << Utilities::replace_in_string(sequence,"|",", ");
 
-    return description.str();
+        return description.str();
+      }
+      default:
+        AssertThrow(false, ExcNotImplemented());
+      }
+    // Should never occur without an exception, but prevent compiler from
+    // complaining
+    return "";
   }
 
 
@@ -916,14 +1111,30 @@ namespace Patterns
 
 
 
-  std::string Bool::description () const
+  std::string Bool::description (const OutputStyle style) const
   {
-    std::ostringstream description;
+    switch (style)
+      {
+      case Machine:
+      {
+        std::ostringstream description;
 
-    description << description_init
-                << "]";
+        description << description_init
+                    << "]";
 
-    return description.str();
+        return description.str();
+      }
+      case Text:
+      case LaTeX:
+      {
+        return "A boolean value (true or false)";
+      }
+      default:
+        AssertThrow(false, ExcNotImplemented());
+      }
+    // Should never occur without an exception, but prevent compiler from
+    // complaining
+    return "";
   }
 
 
@@ -961,14 +1172,30 @@ namespace Patterns
 
 
 
-  std::string Anything::description () const
+  std::string Anything::description (const OutputStyle style) const
   {
-    std::ostringstream description;
+    switch (style)
+      {
+      case Machine:
+      {
+        std::ostringstream description;
 
-    description << description_init
-                << "]";
+        description << description_init
+                    << "]";
 
-    return description.str();
+        return description.str();
+      }
+      case Text:
+      case LaTeX:
+      {
+        return "Any string";
+      }
+      default:
+        AssertThrow(false, ExcNotImplemented());
+      }
+    // Should never occur without an exception, but prevent compiler from
+    // complaining
+    return "";
   }
 
 
@@ -1007,18 +1234,37 @@ namespace Patterns
 
 
 
-  std::string FileName::description () const
+  std::string FileName::description (const OutputStyle style) const
   {
-    std::ostringstream description;
+    switch (style)
+      {
+      case Machine:
+      {
+        std::ostringstream description;
 
-    description << description_init;
+        description << description_init;
 
-    if (file_type == input)
-      description << " (Type: input)]";
-    else
-      description << " (Type: output)]";
+        if (file_type == input)
+          description << " (Type: input)]";
+        else
+          description << " (Type: output)]";
 
-    return description.str();
+        return description.str();
+      }
+      case Text:
+      case LaTeX:
+      {
+        if (file_type == input)
+          return "an input filename";
+        else
+          return "an output filename";
+      }
+      default:
+        AssertThrow(false, ExcNotImplemented());
+      }
+    // Should never occur without an exception, but prevent compiler from
+    // complaining
+    return "";
   }
 
 
@@ -1071,13 +1317,29 @@ namespace Patterns
 
 
 
-  std::string DirectoryName::description () const
+  std::string DirectoryName::description (const OutputStyle style) const
   {
-    std::ostringstream description;
+    switch (style)
+      {
+      case Machine:
+      {
+        std::ostringstream description;
 
-    description << description_init << "]";
+        description << description_init << "]";
 
-    return description.str();
+        return description.str();
+      }
+      case Text:
+      case LaTeX:
+      {
+        return "A directory name";
+      }
+      default:
+        AssertThrow(false, ExcNotImplemented());
+      }
+    // Should never occur without an exception, but prevent compiler from
+    // complaining
+    return "";
   }
 
 
@@ -2274,8 +2536,10 @@ ParameterHandler::print_parameters_section (std::ostream      &out,
                       << std::endl;
 
                 // also output possible values
+                const unsigned int pattern_index = p->second.get<unsigned int> ("pattern");
+                const std::string desc_str = patterns[pattern_index]->description (Patterns::PatternBase::LaTeX);
                 out << "{\\it Possible values:} "
-                    << p->second.get<std::string> ("pattern_description")
+                    << desc_str
                     << std::endl;
               }
             else if (is_alias_node (p->second) == true)
@@ -2358,9 +2622,10 @@ ParameterHandler::print_parameters_section (std::ostream      &out,
                 << " = ";
 
             // print possible values:
+            const unsigned int pattern_index = p->second.get<unsigned int> ("pattern");
+            const std::string full_desc_str = patterns[pattern_index]->description (Patterns::PatternBase::Text);
             const std::vector<std::string> description_str
-              = Utilities::break_text_into_lines (p->second.get<std::string>
-                                                  ("pattern_description"),
+              = Utilities::break_text_into_lines (full_desc_str,
                                                   78 - overall_indent_level*2 - 2, '|');
             if (description_str.size() > 1)
               {

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.