From: Jonathan Robey Date: Wed, 20 Jul 2016 19:13:51 +0000 (-0700) Subject: Allow varying description output for patterns X-Git-Tag: v8.5.0-rc1~854^2~2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4026f81654834a812a2d34bd16ef9efec0c315de;p=dealii.git Allow varying description output for patterns --- diff --git a/include/deal.II/base/parameter_handler.h b/include/deal.II/base/parameter_handler.h index 62a66099d6..d4709fe219 100644 --- a/include/deal.II/base/parameter_handler.h +++ b/include/deal.II/base/parameter_handler.h @@ -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 "[Anything]". */ - 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 "[Filename]". */ - 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 "[Filename]". */ - 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 diff --git a/source/base/parameter_handler.cc b/source/base/parameter_handler.cc index 98e8ee8097..fa50f9ea77 100644 --- a/source/base/parameter_handler.cc +++ b/source/base/parameter_handler.cc @@ -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 ("pattern"); + const std::string desc_str = patterns[pattern_index]->description (Patterns::PatternBase::LaTeX); out << "{\\it Possible values:} " - << p->second.get ("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 ("pattern"); + const std::string full_desc_str = patterns[pattern_index]->description (Patterns::PatternBase::Text); const std::vector description_str - = Utilities::break_text_into_lines (p->second.get - ("pattern_description"), + = Utilities::break_text_into_lines (full_desc_str, 78 - overall_indent_level*2 - 2, '|'); if (description_str.size() > 1) {