From 0f7ba03449de413bf25a52c81c7c3f597fd04345 Mon Sep 17 00:00:00 2001 From: Matthias Maier Date: Sat, 13 Jul 2013 12:39:06 +0000 Subject: [PATCH] Reindent comments in parameter_handler.h Also 30k get. git-svn-id: https://svn.dealii.org/trunk@29996 0785d39b-7218-0410-832d-ea1e28bc413d --- .../include/deal.II/base/parameter_handler.h | 1832 ++++++----------- 1 file changed, 660 insertions(+), 1172 deletions(-) diff --git a/deal.II/include/deal.II/base/parameter_handler.h b/deal.II/include/deal.II/base/parameter_handler.h index bf9aad7c0e..09c2435c14 100644 --- a/deal.II/include/deal.II/base/parameter_handler.h +++ b/deal.II/include/deal.II/base/parameter_handler.h @@ -55,241 +55,147 @@ namespace Patterns { /** - * Base class to declare common - * interface. The purpose of this - * class is mostly to define the - * interface of patterns, and to - * force derived classes to have a - * clone function. It is thus, - * in the languages of the "Design - * Patterns" book (Gamma et al.), a - * "prototype". + * Base class to declare common interface. The purpose of this class is + * mostly to define the interface of patterns, and to force derived + * classes to have a clone function. It is thus, in the + * languages of the "Design Patterns" book (Gamma et al.), a "prototype". */ class PatternBase { public: /** - * Make destructor of this and all - * derived classes virtual. + * Make destructor of this and all derived classes virtual. */ virtual ~PatternBase (); /** - * Return true if the given string - * matches the pattern. + * Return true if the given string matches the pattern. */ virtual bool match (const std::string &test_string) const = 0; /** - * Return a string describing the - * pattern. + * Return a string describing the pattern. */ virtual std::string description () const = 0; /** - * Return a pointer to an - * exact copy of the - * object. This is necessary - * since we want to store - * objects of this type in - * containers, were we need - * to copy objects without - * knowledge of their actual - * data type (we only have - * pointers to the base - * class). + * Return a pointer to an exact copy of the object. This is necessary + * since we want to store objects of this type in containers, were we + * need to copy objects without knowledge of their actual data type (we + * only have pointers to the base class). * - * Ownership of the objects - * returned by this function - * is passed to the caller of - * this function. + * Ownership of the objects returned by this function is passed to the + * caller of this function. */ virtual PatternBase *clone () const = 0; /** - * Determine an estimate for - * the memory consumption (in - * bytes) of this object. To - * avoid unnecessary - * overhead, we do not force - * derived classes to provide - * this function as a virtual - * overloaded one, but rather - * try to cast the present - * object to one of the known - * derived classes and if - * that fails then take the - * size of this base class - * instead and add 32 byte - * (this value is arbitrary, - * it should account for - * virtual function tables, - * and some possible data - * elements). Since there are - * usually not many thousands - * of objects of this type - * around, and since the - * memory_consumption - * mechanism is used to find - * out where memory in the - * range of many megabytes - * is, this seems like a + * Determine an estimate for the memory consumption (in bytes) of this + * object. To avoid unnecessary overhead, we do not force derived + * classes to provide this function as a virtual overloaded one, but + * rather try to cast the present object to one of the known derived + * classes and if that fails then take the size of this base class + * instead and add 32 byte (this value is arbitrary, it should account + * for virtual function tables, and some possible data elements). Since + * there are usually not many thousands of objects of this type around, + * and since the memory_consumption mechanism is used to find out where + * memory in the range of many megabytes is, this seems like a * reasonable approximation. * - * On the other hand, if you - * know that your class - * deviates from this - * assumption significantly, - * you can still overload - * this function. + * On the other hand, if you know that your class deviates from this + * assumption significantly, you can still overload this function. */ virtual std::size_t memory_consumption () const; }; /** - * Returns pointer to the correct - * derived class based on description. + * Returns pointer to the correct derived class based on description. */ PatternBase *pattern_factory (const std::string &description); /** - * Test for the string being an - * integer. If bounds are given - * to the constructor, then the - * integer given also needs to be - * within the interval specified - * by these bounds. Note that - * unlike common convention in - * the C++ standard library, both - * bounds of this interval are - * inclusive; the reason is that - * in practice in most cases, one - * needs closed intervals, but - * these can only be realized - * with inclusive bounds for - * non-integer values. We thus - * stay consistent by always - * using closed intervals. + * Test for the string being an integer. If bounds are given to the + * constructor, then the integer given also needs to be within the + * interval specified by these bounds. Note that unlike common convention + * in the C++ standard library, both bounds of this interval are + * inclusive; the reason is that in practice in most cases, one needs + * closed intervals, but these can only be realized with inclusive bounds + * for non-integer values. We thus stay consistent by always using closed + * intervals. * - * If the upper bound given to - * the constructor is smaller - * than the lower bound, then the - * infinite interval is implied, - * i.e. every integer is allowed. + * If the upper bound given to the constructor is smaller than the lower + * bound, then the infinite interval is implied, i.e. every integer is + * allowed. * - * Giving bounds may be useful if - * for example a value can only - * be positive and less than a - * reasonable upper bound (for - * example the number of - * refinement steps to be - * performed), or in many other - * cases. + * Giving bounds may be useful if for example a value can only be + * positive and less than a reasonable upper bound (for example the + * number of refinement steps to be performed), or in many other cases. */ class Integer : public PatternBase { public: /** - * Minimal integer value. If - * the numeric_limits class - * is available use this - * information to obtain the - * extremal values, otherwise - * set it so that this class - * understands that all values - * are allowed. + * Minimal integer value. If the numeric_limits class is available use + * this information to obtain the extremal values, otherwise set it so + * that this class understands that all values are allowed. */ static const int min_int_value; /** - * Maximal integer value. If - * the numeric_limits class - * is available use this - * information to obtain the - * extremal values, otherwise - * set it so that this class - * understands that all values - * are allowed. + * Maximal integer value. If the numeric_limits class is available use + * this information to obtain the extremal values, otherwise set it so + * that this class understands that all values are allowed. */ static const int max_int_value; /** - * Constructor. Bounds can be - * specified within which a - * valid parameter has to - * be. If the upper bound is - * smaller than the lower - * bound, then the infinite - * interval is meant. The - * default values are chosen - * such that no bounds are - * enforced on parameters. + * Constructor. Bounds can be specified within which a valid parameter + * has to be. If the upper bound is smaller than the lower bound, then + * the infinite interval is meant. The default values are chosen such + * that no bounds are enforced on parameters. */ Integer (const int lower_bound = min_int_value, const int upper_bound = max_int_value); /** - * Return true if the - * string is an integer and - * its value is within the - * specified range. + * Return true if the string is an integer and its value is + * within the specified range. */ virtual bool match (const std::string &test_string) const; /** - * Return a description of - * the pattern that valid - * strings are expected to - * match. If bounds were - * specified to the - * constructor, then include - * them into this - * description. + * Return a description of the pattern that valid strings are expected + * to match. If bounds were specified to the constructor, then include + * them into this description. */ virtual std::string description () const; /** - * Return a copy of the - * present object, which is - * newly allocated on the - * heap. Ownership of that - * object is transferred to - * the caller of this + * Return a copy of the present object, which is newly allocated on the + * heap. Ownership of that object is transferred to the caller of this * function. */ virtual PatternBase *clone () const; /** - * Creates new object if the start of - * description matches - * description_init. Ownership of that - * object is transferred to the caller - * of this function. + * Creates new object if the start of description matches + * description_init. Ownership of that object is transferred to the + * caller of this function. */ static Integer *create (const std::string &description); private: /** - * Value of the lower - * bound. A number that - * satisfies the @ref match - * operation of this class - * must be equal to this - * value or larger, if the - * bounds of the interval for - * a valid range. + * Value of the lower bound. A number that satisfies the @ref match + * operation of this class must be equal to this value or larger, if + * the bounds of the interval for a valid range. */ const int lower_bound; /** - * Value of the upper - * bound. A number that - * satisfies the @ref match - * operation of this class - * must be equal to this - * value or less, if the - * bounds of the interval for - * a valid range. + * Value of the upper bound. A number that satisfies the @ref match + * operation of this class must be equal to this value or less, if the + * bounds of the interval for a valid range. */ const int upper_bound; @@ -300,144 +206,90 @@ namespace Patterns }; /** - * Test for the string being a - * double. If bounds are - * given to the constructor, then - * the integer given also needs - * to be within the interval - * specified by these - * bounds. Note that unlike - * common convention in the C++ - * standard library, both bounds - * of this interval are - * inclusive; the reason is that - * in practice in most cases, one - * needs closed intervals, but - * these can only be realized - * with inclusive bounds for - * non-integer values. We thus - * stay consistent by always - * using closed intervals. + * Test for the string being a double. If bounds are given to + * the constructor, then the integer given also needs to be within the + * interval specified by these bounds. Note that unlike common convention + * in the C++ standard library, both bounds of this interval are + * inclusive; the reason is that in practice in most cases, one needs + * closed intervals, but these can only be realized with inclusive bounds + * for non-integer values. We thus stay consistent by always using closed + * intervals. * - * If the upper bound given to - * the constructor is smaller - * than the lower bound, then the - * infinite interval is implied, - * i.e. every integer is allowed. + * If the upper bound given to the constructor is smaller than the lower + * bound, then the infinite interval is implied, i.e. every integer is + * allowed. * - * Giving bounds may be useful if - * for example a value can only - * be positive and less than a - * reasonable upper bound (for - * example damping parameters are - * frequently only reasonable if - * between zero and one), or in - * many other cases. + * Giving bounds may be useful if for example a value can only be + * positive and less than a reasonable upper bound (for example damping + * parameters are frequently only reasonable if between zero and one), or + * in many other cases. */ class Double : public PatternBase { public: /** - * Minimal double value. If the - * std::numeric_limits - * class is available use this - * information to obtain the - * extremal values, otherwise - * set it so that this class - * understands that all values - * are allowed. + * Minimal double value. If the std::numeric_limits class is + * available use this information to obtain the extremal values, + * otherwise set it so that this class understands that all values are + * allowed. */ static const double min_double_value; /** - * Maximal double value. If the - * numeric_limits class is - * available use this - * information to obtain the - * extremal values, otherwise - * set it so that this class - * understands that all values - * are allowed. + * Maximal double value. If the numeric_limits class is available use + * this information to obtain the extremal values, otherwise set it so + * that this class understands that all values are allowed. */ static const double max_double_value; /** - * Constructor. Bounds can be - * specified within which a - * valid parameter has to - * be. If the upper bound is - * smaller than the lower - * bound, then the infinite - * interval is meant. The - * default values are chosen - * such that no bounds are - * enforced on parameters. + * Constructor. Bounds can be specified within which a valid parameter + * has to be. If the upper bound is smaller than the lower bound, then + * the infinite interval is meant. The default values are chosen such + * that no bounds are enforced on parameters. */ Double (const double lower_bound = min_double_value, const double upper_bound = max_double_value); /** - * Return true if the - * string is a number and its - * value is within the - * specified range. + * Return true if the string is a number and its value is + * within the specified range. */ virtual bool match (const std::string &test_string) const; /** - * Return a description of - * the pattern that valid - * strings are expected to - * match. If bounds were - * specified to the - * constructor, then include - * them into this - * description. + * Return a description of the pattern that valid strings are expected + * to match. If bounds were specified to the constructor, then include + * them into this description. */ virtual std::string description () const; /** - * Return a copy of the - * present object, which is - * newly allocated on the - * heap. Ownership of that - * object is transferred to - * the caller of this + * Return a copy of the present object, which is newly allocated on the + * heap. Ownership of that object is transferred to the caller of this * function. */ virtual PatternBase *clone () const; /** - * Creates new object if the start of - * description matches - * description_init. Ownership of that - * object is transferred to the caller - * of this function. + * Creates new object if the start of description matches + * description_init. Ownership of that object is transferred to the + * caller of this function. */ static Double *create (const std::string &description); private: /** - * Value of the lower - * bound. A number that - * satisfies the @ref match - * operation of this class - * must be equal to this - * value or larger, if the - * bounds of the interval for - * a valid range. + * Value of the lower bound. A number that satisfies the @ref match + * operation of this class must be equal to this value or larger, if + * the bounds of the interval for a valid range. */ const double lower_bound; /** - * Value of the upper - * bound. A number that - * satisfies the @ref match - * operation of this class - * must be equal to this - * value or less, if the - * bounds of the interval for - * a valid range. + * Value of the upper bound. A number that satisfies the @ref match + * operation of this class must be equal to this value or less, if the + * bounds of the interval for a valid range. */ const double upper_bound; @@ -448,83 +300,59 @@ namespace Patterns }; /** - * Test for the string being one - * of a sequence of values given - * like a regular expression. For - * example, if the string given - * to the constructor is - * "red|blue|black", then the - * @ref match function returns - * true exactly if the string - * is either "red" or "blue" or - * "black". Spaces around the - * pipe signs do not matter and - * are eliminated. + * Test for the string being one of a sequence of values given like a + * regular expression. For example, if the string given to the + * constructor is "red|blue|black", then the @ref match function + * returns true exactly if the string is either "red" or "blue" + * or "black". Spaces around the pipe signs do not matter and are + * eliminated. */ class Selection : public PatternBase { public: /** - * Constructor. Take the - * given parameter as the - * specification of valid + * Constructor. Take the given parameter as the specification of valid * strings. */ Selection (const std::string &seq); /** - * Return true if the - * string is an element of - * the description list - * passed to the constructor. + * Return true if the string is an element of the description + * list passed to the constructor. */ virtual bool match (const std::string &test_string) const; /** - * Return a description of - * the pattern that valid - * strings are expected to - * match. Here, this is the - * list of valid strings - * passed to the constructor. + * Return a description of the pattern that valid strings are expected + * to match. Here, this is the list of valid strings passed to the + * constructor. */ virtual std::string description () const; /** - * Return a copy of the - * present object, which is - * newly allocated on the - * heap. Ownership of that - * object is transferred to - * the caller of this + * Return a copy of the present object, which is newly allocated on the + * heap. Ownership of that object is transferred to the caller of this * function. */ virtual PatternBase *clone () const; /** - * Determine an estimate for - * the memory consumption (in - * bytes) of this object. + * Determine an estimate for the memory consumption (in bytes) of this + * object. */ std::size_t memory_consumption () const; /** - * Creates new object if the start of - * description matches - * description_init. Ownership of that - * object is transferred to the caller - * of this function. + * Creates new object if the start of description matches + * description_init. Ownership of that object is transferred to the + * caller of this function. */ static Selection *create (const std::string &description); private: /** - * List of valid strings as - * passed to the - * constructor. We don't make - * this string constant, as - * we process it somewhat in - * the constructor. + * List of valid strings as passed to the constructor. We don't make + * this string constant, as we process it somewhat in the constructor. */ std::string sequence; @@ -536,40 +364,28 @@ namespace Patterns /** - * This pattern matches a list of - * comma-separated values each of which - * have to match a pattern given to the - * constructor. With two additional - * parameters, the number of elements this - * list has to have can be specified. If - * none is specified, the list may have - * zero or more entries. + * This pattern matches a list of comma-separated values each of which + * have to match a pattern given to the constructor. With two additional + * parameters, the number of elements this list has to have can be + * specified. If none is specified, the list may have zero or more + * entries. */ class List : public PatternBase { public: /** - * Maximal integer value. If - * the numeric_limits class - * is available use this - * information to obtain the - * extremal values, otherwise - * set it so that this class - * understands that all values - * are allowed. + * Maximal integer value. If the numeric_limits class is available use + * this information to obtain the extremal values, otherwise set it so + * that this class understands that all values are allowed. */ static const unsigned int max_int_value; /** - * Constructor. Take the - * given parameter as the - * specification of valid + * Constructor. Take the given parameter as the specification of valid * elements of the list. * - * The two other arguments can - * be used to denote minimal - * and maximal allowable - * lengths of the list. + * The two other arguments can be used to denote minimal and maximal + * allowable lengths of the list. */ List (const PatternBase &base_pattern, const unsigned int min_elements = 0, @@ -582,45 +398,34 @@ namespace Patterns /** * Return true if the - * string is a comma-separated - * list of strings each of - * which match the pattern - * given to the constructor. + * string is a comma-separated list of strings each of which match the + * pattern given to the constructor. */ virtual bool match (const std::string &test_string) const; /** - * Return a description of - * the pattern that valid - * strings are expected to - * match. + * Return a description of the pattern that valid strings are expected + * to match. */ virtual std::string description () const; /** - * Return a copy of the - * present object, which is - * newly allocated on the - * heap. Ownership of that - * object is transferred to - * the caller of this + * Return a copy of the present object, which is newly allocated on the + * heap. Ownership of that object is transferred to the caller of this * function. */ virtual PatternBase *clone () const; /** - * Creates new object if the start of - * description matches - * description_init. Ownership of that - * object is transferred to the caller - * of this function. + * Creates new object if the start of description matches + * description_init. Ownership of that object is transferred to the + * caller of this function. */ static List *create (const std::string &description); /** - * Determine an estimate for - * the memory consumption (in - * bytes) of this object. + * Determine an estimate for the memory consumption (in bytes) of this + * object. */ std::size_t memory_consumption () const; @@ -637,21 +442,17 @@ namespace Patterns //@} private: /** - * Copy of the pattern that - * each element of the list has - * to satisfy. + * Copy of the pattern that each element of the list has to satisfy. */ PatternBase *pattern; /** - * Minimum number of elements - * the list must have. + * Minimum number of elements the list must have. */ const unsigned int min_elements; /** - * Maximum number of elements - * the list must have. + * Maximum number of elements the list must have. */ const unsigned int max_elements; @@ -663,47 +464,33 @@ namespace Patterns /** - * This pattern matches a list of - * comma-separated values each of which - * denotes a pair of key and value. Both key and value - * have to match a pattern given to the - * constructor. For each entry of the map, - * parameters have to be entered in the form - * key: value. In other words, a - * map is described in the form + * This pattern matches a list of comma-separated values each of which + * denotes a pair of key and value. Both key and value have to match a + * pattern given to the constructor. For each entry of the map, + * parameters have to be entered in the form key: value. In + * other words, a map is described in the form * key1: value1, key2: value2, key3: value3, .... * - * With two additional - * parameters, the number of elements this - * list has to have can be specified. If - * none is specified, the map may have - * zero or more entries. + * With two additional parameters, the number of elements this list has + * to have can be specified. If none is specified, the map may have zero + * or more entries. */ class Map : public PatternBase { public: /** - * Maximal integer value. If - * the numeric_limits class - * is available use this - * information to obtain the - * extremal values, otherwise - * set it so that this class - * understands that all values - * are allowed. + * Maximal integer value. If the numeric_limits class is available use + * this information to obtain the extremal values, otherwise set it so + * that this class understands that all values are allowed. */ static const unsigned int max_int_value; /** - * Constructor. Take the - * given parameter as the - * specification of valid + * Constructor. Take the given parameter as the specification of valid * elements of the list. * - * The two other arguments can - * be used to denote minimal - * and maximal allowable - * lengths of the list. + * The two other arguments can be used to denote minimal and maximal + * allowable lengths of the list. */ Map (const PatternBase &key_pattern, const PatternBase &value_pattern, @@ -716,46 +503,34 @@ namespace Patterns virtual ~Map (); /** - * Return true if the - * string is a comma-separated - * list of strings each of - * which match the pattern - * given to the constructor. + * Return true if the string is a comma-separated list of + * strings each of which match the pattern given to the constructor. */ virtual bool match (const std::string &test_string) const; /** - * Return a description of - * the pattern that valid - * strings are expected to - * match. + * Return a description of the pattern that valid strings are expected + * to match. */ virtual std::string description () const; /** - * Return a copy of the - * present object, which is - * newly allocated on the - * heap. Ownership of that - * object is transferred to - * the caller of this + * Return a copy of the present object, which is newly allocated on the + * heap. Ownership of that object is transferred to the caller of this * function. */ virtual PatternBase *clone () const; /** - * Creates new object if the start of - * description matches - * description_init. Ownership of that - * object is transferred to the caller - * of this function. + * Creates new object if the start of description matches + * description_init. Ownership of that object is transferred to the + * caller of this function. */ static Map *create (const std::string &description); /** - * Determine an estimate for - * the memory consumption (in - * bytes) of this object. + * Determine an estimate for the memory consumption (in bytes) of this + * object. */ std::size_t memory_consumption () const; @@ -772,22 +547,19 @@ namespace Patterns //@} private: /** - * Copy of the patterns that - * each key and each value of the map has - * to satisfy. + * Copy of the patterns that each key and each value of the map has to + * satisfy. */ PatternBase *key_pattern; PatternBase *value_pattern; /** - * Minimum number of elements - * the list must have. + * Minimum number of elements the list must have. */ const unsigned int min_elements; /** - * Maximum number of elements - * the list must have. + * Maximum number of elements the list must have. */ const unsigned int max_elements; @@ -799,80 +571,55 @@ namespace Patterns /** - * This class is much like the - * Selection class, but it - * allows the input to be a - * comma-separated list of values - * which each have to be given in - * the constructor - * argument. Alternatively, it - * could be viewed as a - * specialization of the List - * class. For example, if the - * string to the constructor was - * "ucd|gmv|eps", then the - * following would be legal input: - * eps, gmv. You may give an - * arbitrarily long list of values, - * where there may be as many - * spaces around commas as you - * like. However, commas are not - * allowed inside the values given + * This class is much like the Selection class, but it allows the input + * to be a comma-separated list of values which each have to be given in + * the constructor argument. Alternatively, it could be viewed as a + * specialization of the List class. For example, if the string to the + * constructor was "ucd|gmv|eps", then the following would be + * legal input: eps, gmv. You may give an arbitrarily + * long list of values, where there may be as many spaces around commas + * as you like. However, commas are not allowed inside the values given * to the constructor. */ class MultipleSelection : public PatternBase { public: /** - * Constructor. Take the - * given parameter as the - * specification of valid + * Constructor. Take the given parameter as the specification of valid * strings. */ MultipleSelection (const std::string &seq); /** - * Return true if the - * string is an element of - * the description list - * passed to the constructor. + * Return true if the string is an element of the description + * list passed to the constructor. */ virtual bool match (const std::string &test_string) const; /** - * Return a description of - * the pattern that valid - * strings are expected to - * match. Here, this is the - * list of valid strings - * passed to the constructor. + * Return a description of the pattern that valid strings are expected + * to match. Here, this is the list of valid strings passed to the + * constructor. */ virtual std::string description () const; /** - * Return a copy of the - * present object, which is - * newly allocated on the - * heap. Ownership of that - * object is transferred to - * the caller of this + * Return a copy of the present object, which is newly allocated on the + * heap. Ownership of that object is transferred to the caller of this * function. */ virtual PatternBase *clone () const; /** - * Creates new object if the start of - * description matches - * description_init. Ownership of that - * object is transferred to the caller - * of this function. + * Creates new object if the start of description matches + * description_init. Ownership of that object is transferred to the + * caller of this function. */ static MultipleSelection *create (const std::string &description); /** - * Determine an estimate for - * the memory consumption (in - * bytes) of this object. + * Determine an estimate for the memory consumption (in bytes) of this + * object. */ std::size_t memory_consumption () const; @@ -889,12 +636,8 @@ namespace Patterns //@} private: /** - * List of valid strings as - * passed to the - * constructor. We don't make - * this string constant, as - * we process it somewhat in - * the constructor. + * List of valid strings as passed to the constructor. We don't make + * this string constant, as we process it somewhat in the constructor. */ std::string sequence; @@ -905,10 +648,8 @@ namespace Patterns }; /** - * Test for the string being - * either "true" or "false". This - * is mapped to the Selection - * class. + * Test for the string being either "true" or "false". This is mapped to + * the Selection class. */ class Bool : public Selection { @@ -919,30 +660,22 @@ namespace Patterns Bool (); /** - * Return a description of - * the pattern that valid - * strings are expected to - * match. + * Return a description of the pattern that valid strings are expected + * to match. */ virtual std::string description () const; /** - * Return a copy of the - * present object, which is - * newly allocated on the - * heap. Ownership of that - * object is transferred to - * the caller of this + * Return a copy of the present object, which is newly allocated on the + * heap. Ownership of that object is transferred to the caller of this * function. */ virtual PatternBase *clone () const; /** - * Creates new object if the start of - * description matches - * description_init. Ownership of that - * object is transferred to the caller - * of this function. + * Creates new object if the start of description matches + * description_init. Ownership of that object is transferred to the + * caller of this function. */ static Bool *create (const std::string &description); @@ -954,54 +687,40 @@ namespace Patterns }; /** - * Always returns true when testing a - * string. + * Always returns true when testing a string. */ class Anything : public PatternBase { public: /** - * Constructor. (Allow for at - * least one non-virtual - * function in this class, as - * otherwise sometimes no - * virtual table is emitted.) + * Constructor. (Allow for at least one non-virtual function in this + * class, as otherwise sometimes no virtual table is emitted.) */ Anything (); /** - * Return true if the - * string matches its - * constraints, i.e. always. + * Return true if the string matches its constraints, i.e. + * always. */ virtual bool match (const std::string &test_string) const; /** - * Return a description of - * the pattern that valid - * strings are expected to - * match. Here, this is the - * string "[Anything]". + * Return a description of the pattern that valid strings are expected + * to match. Here, this is the string "[Anything]". */ virtual std::string description () const; /** - * Return a copy of the - * present object, which is - * newly allocated on the - * heap. Ownership of that - * object is transferred to - * the caller of this + * Return a copy of the present object, which is newly allocated on the + * heap. Ownership of that object is transferred to the caller of this * function. */ virtual PatternBase *clone () const; /** - * Creates new object if the start of - * description matches - * description_init. Ownership of that - * object is transferred to the caller - * of this function. + * Creates new object if the start of description matches + * description_init. Ownership of that object is transferred to the + * caller of this function. */ static Anything *create (const std::string &description); @@ -1014,70 +733,51 @@ namespace Patterns /** - * A pattern that can be used to indicate - * when a parameter is intended to be the - * name of a file. By itself, this class - * does not check whether the string that - * is given in a parameter file actually - * corresponds to an existing file (it - * could, for example, be the name of a - * file to which you want to write - * output). Functionally, the class is - * therefore equivalent to the Anything - * class. However, it allows to specify the - * intent of a parameter. The flag - * given to the constructor also allows to - * specify whether the file is supposed to - * be an input or output file. + * A pattern that can be used to indicate when a parameter is intended to + * be the name of a file. By itself, this class does not check whether + * the string that is given in a parameter file actually corresponds to + * an existing file (it could, for example, be the name of a file to + * which you want to write output). Functionally, the class is therefore + * equivalent to the Anything class. However, it allows to specify the + * intent of a parameter. The flag given to the constructor also + * allows to specify whether the file is supposed to be an input or + * output file. * - * The reason for the existence of this - * class is to support graphical user - * interfaces for editing parameter - * files. These may open a file selection - * dialog if the filename is supposed to - * represent an input file. + * The reason for the existence of this class is to support graphical + * user interfaces for editing parameter files. These may open a file + * selection dialog if the filename is supposed to represent an input + * file. */ class FileName : public PatternBase { public: /** - * Files can be used for input - * or output. This can be - * specified in the constructor - * by choosing the flag type. + * Files can be used for input or output. This can be specified in the + * constructor by choosing the flag type. */ enum FileType {input = 0, output = 1}; /** - * Constructor. The type of the file - * can be specified by choosing the + * Constructor. The type of the file can be specified by choosing the * flag. */ FileName (const FileType type = input); /** - * Return true if the - * string matches its - * constraints, i.e. always. + * Return true if the string matches its constraints, i.e. + * always. */ virtual bool match (const std::string &test_string) const; /** - * Return a description of - * the pattern that valid - * strings are expected to - * match. Here, this is the - * string "[Filename]". + * Return a description of the pattern that valid strings are expected + * to match. Here, this is the string "[Filename]". */ virtual std::string description () const; /** - * Return a copy of the - * present object, which is - * newly allocated on the - * heap. Ownership of that - * object is transferred to - * the caller of this + * Return a copy of the present object, which is newly allocated on the + * heap. Ownership of that object is transferred to the caller of this * function. */ virtual PatternBase *clone () const; @@ -1088,11 +788,9 @@ namespace Patterns FileType file_type; /** - * Creates new object if the start of - * description matches - * description_init. Ownership of that - * object is transferred to the caller - * of this function. + * Creates new object if the start of description matches + * description_init. Ownership of that object is transferred to the + * caller of this function. */ static FileName *create (const std::string &description); @@ -1105,22 +803,16 @@ namespace Patterns /** - * A pattern that can be used to indicate - * when a parameter is intended to be the - * name of a directory. By itself, this - * class does not check whether the string - * that is given in a parameter file - * actually corresponds to an existing - * directory. Functionally, the class is - * therefore equivalent to the Anything - * class. However, it allows to specify the - * intent of a parameter. + * A pattern that can be used to indicate when a parameter is intended to + * be the name of a directory. By itself, this class does not check + * whether the string that is given in a parameter file actually + * corresponds to an existing directory. Functionally, the class is + * therefore equivalent to the Anything class. However, it allows to + * specify the intent of a parameter. * - * The reason for the existence of this - * class is to support graphical user - * interfaces for editing parameter - * files. These may open a file selection - * dialog to select or create a directory. + * The reason for the existence of this class is to support graphical + * user interfaces for editing parameter files. These may open a file + * selection dialog to select or create a directory. */ class DirectoryName : public PatternBase { @@ -1131,38 +823,28 @@ namespace Patterns DirectoryName (); /** - * Return true if the - * string matches its - * constraints, i.e. always. + * Return true if the string matches its constraints, i.e. + * always. */ virtual bool match (const std::string &test_string) const; /** - * Return a description of - * the pattern that valid - * strings are expected to - * match. Here, this is the - * string "[Filename]". + * Return a description of the pattern that valid strings are expected + * to match. Here, this is the string "[Filename]". */ virtual std::string description () const; /** - * Return a copy of the - * present object, which is - * newly allocated on the - * heap. Ownership of that - * object is transferred to - * the caller of this + * Return a copy of the present object, which is newly allocated on the + * heap. Ownership of that object is transferred to the caller of this * function. */ virtual PatternBase *clone () const; /** - * Creates new object if the start of - * description matches - * description_init. Ownership of that - * object is transferred to the caller - * of this function. + * Creates new object if the start of description matches + * description_init. Ownership of that object is transferred to the + * caller of this function. */ static DirectoryName *create (const std::string &description); @@ -1176,10 +858,11 @@ namespace Patterns /** - * The ParameterHandler class provides a standard interface to an input file - * which provides at run-time for program parameters such as time step - * sizes, geometries, right hand sides etc. The input for the program is - * given in files, streams or strings in memory using text like + * The ParameterHandler class provides a standard interface to an input + * file which provides at run-time for program parameters such as time + * step sizes, geometries, right hand sides etc. The input for the + * program is given in files, streams or strings in memory using text + * like * @code * set Time step size = 0.3 * set Geometry = [0,1]x[0,3] @@ -1187,16 +870,15 @@ namespace Patterns * Input may be sorted into subsection trees in order to give the input a * logical structure. * - * The ParameterHandler class is discussed in detail in the @ref - * step_19 "step-19" example program, and is used in more realistic - * situations in step-29, step-33 - * and step-34. + * The ParameterHandler class is discussed in detail in the @ref step_19 + * "step-19" example program, and is used in more realistic situations in + * step-29, step-33 and step-34. * *

Declaring entries

* - * In order to use the facilities of a ParameterHandler object, one first has - * to make known the different entries the input file may or may not contain. This - * is done in the following way: + * In order to use the facilities of a ParameterHandler object, one first + * has to make known the different entries the input file may or may not + * contain. This is done in the following way: * * @code * ... @@ -1210,26 +892,24 @@ namespace Patterns * Patterns::Anything()); * ... * @endcode - * Each entry is declared using the function declare_entry(). The - * first parameter is the name of the entry (in short: the - * entry). The second is the default answer to be taken in case the - * entry is not specified in the input file. The third parameter is - * a regular expression which the input (and the default answer) has - * to match. Several such regular expressions are defined in - * Patterns. This parameter can be omitted, in which case it - * will default to Patterns::Anything, i.e. a pattern that + * Each entry is declared using the function declare_entry(). The first + * parameter is the name of the entry (in short: the entry). The second + * is the default answer to be taken in case the entry is not specified + * in the input file. The third parameter is a regular expression which + * the input (and the default answer) has to match. Several such regular + * expressions are defined in Patterns. This parameter can be omitted, in + * which case it will default to Patterns::Anything, i.e. a pattern that * matches every input string. The fourth parameter can be used to * document the intent or expected format of an entry; its value is - * printed as a comment when writing all entries of a - * ParameterHandler object using the print_parameters() - * function to allow for easier understanding of a parameter - * file. It can be omitted as well, in which case no such - * documentation will be printed. - * - * Entries may be located in subsections which form a kind of input tree. For example - * input parameters for linear solver routines should be classified in a subsection - * named Linear solver or any other suitable name. This is accomplished in the - * following way: + * printed as a comment when writing all entries of a ParameterHandler + * object using the print_parameters() function to allow for easier + * understanding of a parameter file. It can be omitted as well, in which + * case no such documentation will be printed. + * + * Entries may be located in subsections which form a kind of input tree. + * For example input parameters for linear solver routines should be + * classified in a subsection named Linear solver or any other + * suitable name. This is accomplished in the following way: * @code * ... * LinEq eq; @@ -1252,9 +932,10 @@ namespace Patterns * } * @endcode * - * Subsections may be nested. For example a nonlinear solver may have a linear solver - * as member object. Then the function call tree would be something like (if the class - * NonLinEq has a member variables eq of type LinEq): + * Subsections may be nested. For example a nonlinear solver may have a + * linear solver as member object. Then the function call tree would be + * something like (if the class NonLinEq has a member variables + * eq of type LinEq): * @code * void NonLinEq::declare_parameters (ParameterHandler &prm) { * prm.enter_subsection ("Nonlinear solver"); @@ -1268,15 +949,15 @@ namespace Patterns * } * @endcode * - * For class member functions which declare the different entries we propose - * to use the common name declare_parameters. In normal cases this - * method can be static since the entries will not depend on any - * previous knowledge. Classes for which entries should logically be grouped - * into subsections should declare these subsections themselves. If a class - * has two or more member variables of the same type both of which should - * have their own parameters, this parent class' method - * declare_parameters is responsible to group them into different - * subsections: + * For class member functions which declare the different entries we + * propose to use the common name declare_parameters. In normal + * cases this method can be static since the entries will not + * depend on any previous knowledge. Classes for which entries should + * logically be grouped into subsections should declare these subsections + * themselves. If a class has two or more member variables of the same + * type both of which should have their own parameters, this parent + * class' method declare_parameters is responsible to group them + * into different subsections: * @code * void NonLinEq::declare_parameters (ParameterHandler &prm) { * prm.enter_subsection ("Nonlinear solver"); @@ -1313,27 +994,30 @@ namespace Patterns * end * ... # other stuff * @endcode - * The words subsection, set and end may be either written in lowercase or uppercase - * letters. Leading and trailing whitespace is removed, multiple whitespace is condensed into - * only one. Since the latter applies also to the name of an entry, an entry name will not - * be recognized if in the declaration multiple whitespace is used. + * The words subsection, set and end may be + * either written in lowercase or uppercase letters. Leading and trailing + * whitespace is removed, multiple whitespace is condensed into only one. + * Since the latter applies also to the name of an entry, an entry name + * will not be recognized if in the declaration multiple whitespace is + * used. * - * In entry names and values the following characters are not allowed: \#, {, - * }, |. Their use is reserved for the MultipleParameterLoop class. + * In entry names and values the following characters are not allowed: + * \#, {, }, |. Their use is reserved + * for the MultipleParameterLoop class. * * Comments starting with \# are skipped. * - * We propose to use the following - * scheme to name entries: start the first word with a capital letter and use lowercase - * letters further on. The same applies to the possible entry values to the right of the + * We propose to use the following scheme to name entries: start the + * first word with a capital letter and use lowercase letters further on. + * The same applies to the possible entry values to the right of the * = sign. * * *

Reading data from input sources

* - * In order to read input you can use three possibilities: reading from an - * std::istream object, reading from a file of which the name is - * given and reading from a string in memory in which the lines are + * In order to read input you can use three possibilities: reading from + * an std::istream object, reading from a file of which the name + * is given and reading from a string in memory in which the lines are * separated by @\n characters. These possibilities are used as * follows: * @code @@ -1349,40 +1033,42 @@ namespace Patterns * prm.read_input_from_string (in); * ... * @endcode - * You can use several sources of input successively. Entries which are changed more than - * once will be overwritten every time they are used. + * You can use several sources of input successively. Entries which are + * changed more than once will be overwritten every time they are used. * * You should not try to declare entries using declare_entry() and * enter_subsection() with as yet unknown subsection names after * using read_input(). The results in this case are unspecified. * - * If an error occurs upon reading the input, error messages are written to - * std::cerr and the reader function returns with a return value of - * false. This is opposed to almost all other functions in - * deal.II, which would normally throw an exception if an error occurs; this - * difference in behavior is a relic of the fact that this class predates - * deal.II and had previously been written for a different project. + * If an error occurs upon reading the input, error messages are written + * to std::cerr and the reader function returns with a return + * value of false. This is opposed to almost all other + * functions in deal.II, which would normally throw an exception if an + * error occurs; this difference in behavior is a relic of the fact that + * this class predates deal.II and had previously been written for a + * different project. * * *

Using the %ParameterHandler Graphical User Interface

* * An alternative to using the hand-written input files shown above is to - * use the graphical user interface (GUI) that accompanies this class. For - * this, you first need to write a description of all the parameters, their - * default values, patterns and documentation strings into a file in a - * format that the GUI can understand; this is done using the - * ParameterHandler::print_parameters() function with ParameterHandler::XML - * as second argument, as discussed in more detail below in the - * Representation of Parameters section. This file can then be loaded - * using the executable for the GUI, which should be located in - * lib/bin/dealii_parameter_gui of your deal.II installation, - * assuming that you have a sufficiently recent version of the Qt toolkit installed. + * use the graphical user interface (GUI) that accompanies this class. + * For this, you first need to write a description of all the parameters, + * their default values, patterns and documentation strings into a file + * in a format that the GUI can understand; this is done using the + * ParameterHandler::print_parameters() function with + * ParameterHandler::XML as second argument, as discussed in more detail + * below in the Representation of Parameters section. This file + * can then be loaded using the executable for the GUI, which should be + * located in lib/bin/dealii_parameter_gui of your deal.II + * installation, assuming that you have a sufficiently recent version of + * the Qt toolkit installed. * * Once loaded, the GUI displays subsections and individual parameters in * tree form (see also the discussion in the Representation of - * Parameters section below). Here is a screen shot with some - * sub-sections expanded and one parameter selected for editing: + * Parameters section below). Here is a screen shot + * with some sub-sections expanded and one parameter selected for + * editing: * * @image html parameter_gui.png "Parameter GUI" * @@ -1403,54 +1089,61 @@ namespace Patterns * prm.leave_subsection (); * } * @endcode - * get() returns the value of the given entry. If the entry was not specified in the input - * source(s), the default value is returned. You have to enter and leave subsections - * exactly as you did when declaring subsection. You may chose the order in which to - * transverse the subsection tree. - * - * It is guaranteed that only entries matching the given regular expression are returned, - * i.e. an input entry value which does not match the regular expression is not stored. - * - * You can use get() to retrieve the parameter in text form, get_integer() to get an integer - * or get_double() to get a double. You can also use get_bool(). - * It will cause an internal error if the string could not be - * converted to an integer, double or a bool. This should, though, not - * happen if you correctly specified the regular expression for this entry; you should not - * try to get out an integer or a double from an entry for which no according regular - * expression was set. The internal error is raised through the Assert() macro family - * which only works in debug mode. + * get() returns the value of the given entry. If the entry was not + * specified in the input source(s), the default value is returned. You + * have to enter and leave subsections exactly as you did when declaring + * subsection. You may chose the order in which to transverse the + * subsection tree. + * + * It is guaranteed that only entries matching the given regular + * expression are returned, i.e. an input entry value which does not + * match the regular expression is not stored. + * + * You can use get() to retrieve the parameter in text form, + * get_integer() to get an integer or get_double() to get a double. You + * can also use get_bool(). It will cause an internal error if the string + * could not be converted to an integer, double or a bool. This should, + * though, not happen if you correctly specified the regular expression + * for this entry; you should not try to get out an integer or a double + * from an entry for which no according regular expression was set. The + * internal error is raised through the Assert() macro family which only + * works in debug mode. * * If you want to print out all user selectable features, use the - * print_parameters() function. It is generally a good idea to print all parameters - * at the beginning of a log file, since this way input and output are together in - * one file which makes matching at a later time easier. Additionally, the function - * also print those entries which have not been modified in the input file und are - * thus set to default values; since default values may change in the process of - * program development, you cannot know the values of parameters not specified in the - * input file. + * print_parameters() function. It is generally a good idea to print all + * parameters at the beginning of a log file, since this way input and + * output are together in one file which makes matching at a later time + * easier. Additionally, the function also print those entries which have + * not been modified in the input file und are thus set to default + * values; since default values may change in the process of program + * development, you cannot know the values of parameters not specified in + * the input file. * * *

Style guide for data retrieval

* - * We propose that every class which gets data out of a - * ParameterHandler object provides a function named - * get_parameters. This should be declared - * virtual. get_parameters functions in derived classes - * should call the BaseClass::get_parameters function. + * We propose that every class which gets data out of a ParameterHandler + * object provides a function named get_parameters. This should + * be declared virtual. get_parameters functions in + * derived classes should call the BaseClass::get_parameters + * function. * * *

Experience with large parameter lists

* - * Experience has shown that in programs defining larger numbers of parameters (more than, - * say, fifty) it is advantageous to define an additional class holding these parameters. - * This class is more like a C-style structure, having a large number of variables, - * usually public. It then has at least two functions, which declare and parse the - * parameters. In the main program, the main class has an object of this parameter class - * and delegates declaration and parsing of parameters to this object. + * Experience has shown that in programs defining larger numbers of + * parameters (more than, say, fifty) it is advantageous to define an + * additional class holding these parameters. This class is more like a + * C-style structure, having a large number of variables, usually public. + * It then has at least two functions, which declare and parse the + * parameters. In the main program, the main class has an object of this + * parameter class and delegates declaration and parsing of parameters to + * this object. * - * The advantage of this approach is that you can keep out the technical details - * (declaration and parsing) out of the main class and additionally don't clutter - * up your main class with dozens or more variables denoting the parameters. + * The advantage of this approach is that you can keep out the technical + * details (declaration and parsing) out of the main class and + * additionally don't clutter up your main class with dozens or more + * variables denoting the parameters. * * * @@ -1701,9 +1394,9 @@ namespace Patterns * prm.leave_subsection (); * @endcode * - * We can think of the parameters so arranged as a file system in which every - * parameter is a directory. The name of this directory is the name of the - * parameter, and in this directory lie files that describe the + * We can think of the parameters so arranged as a file system in which + * every parameter is a directory. The name of this directory is the name + * of the parameter, and in this directory lie files that describe the * parameter. These files are: * - value: The content of this file is the current value of this * parameter; initially, the content of the file equals the default value of @@ -1720,13 +1413,13 @@ namespace Patterns * With the exception of the value file, the contents of files * are never changed after declaration of a parameter. * - * Alternatively, a directory in this file system may not have a file called - * value in it. In that case, the directory represents a - * subsection as declared above, and the directory's name will correspond to - * the name of the subsection. It will then have no files in it at all, but - * it may have further directories in it: some of these directories will be - * parameters (indicates by the presence of files) or further nested - * subsections. + * Alternatively, a directory in this file system may not have a file + * called value in it. In that case, the directory + * represents a subsection as declared above, and the directory's name + * will correspond to the name of the subsection. It will then have no + * files in it at all, but it may have further directories in it: some of + * these directories will be parameters (indicates by the presence of + * files) or further nested subsections. * * Given this explanation, the code above will lead to a hierarchical * representation of data that looks like this (the content of files is @@ -1791,74 +1484,57 @@ class ParameterHandler : public Subscriptor { private: /** - * Inhibit automatic - * CopyConstructor. + * Inhibit automatic CopyConstructor. */ ParameterHandler (const ParameterHandler &); /** - * Inhibit automatic - * assignment operator. + * Inhibit automatic assignment operator. */ ParameterHandler &operator= (const ParameterHandler &); public: /** - * List of possible output - * formats. + * List of possible output formats. * - * The formats down the list with - * prefix Short and bit - * 6 and 7 set reproduce the old - * behavior of not writing - * comments or original values to - * the files. + * The formats down the list with prefix Short and bit 6 and 7 + * set reproduce the old behavior of not writing comments or original + * values to the files. */ enum OutputStyle { /** - * Write human readable - * output suitable to be - * read by ParameterHandler + * Write human readable output suitable to be read by ParameterHandler * again. */ Text = 1, /** - * Write parameters as a - * LaTeX table. + * Write parameters as a LaTeX table. */ LaTeX = 2, /** - * Write out declared parameters - * with description and possible - * values. + * Write out declared parameters with description and possible values. */ Description = 3, /** - * Write out everything as - * an XML - * file. + * Write out everything as an XML file. * - * See the general - * documentation of this - * class for an example of + * See the general documentation of this class for an example of * output. */ XML = 4, /** - * Write out everything as - * a JSON - * file. + * Write out everything as a JSON file. */ JSON = 5, /** - * Write input for - * ParameterHandler without - * comments or changed - * default values. + * Write input for ParameterHandler without comments or changed default + * values. */ ShortText = 193 }; @@ -1871,73 +1547,51 @@ public: ParameterHandler (); /** - * Destructor. Declare this only - * to have a virtual destructor, - * which is safer as we have - * virtual functions. It - * actually does nothing + * Destructor. Declare this only to have a virtual destructor, which is + * safer as we have virtual functions. It actually does nothing * spectacular. */ virtual ~ParameterHandler (); /** - * Read input from a stream until - * stream returns eof - * condition or error. + * Read input from a stream until stream returns eof condition + * or error. * - * Return whether the read was - * successful. + * Return whether the read was successful. */ virtual bool read_input (std::istream &input); /** - * Read input from a file the - * name of which is given. The - * PathSearch class "PARAMETERS" - * is used to find the file. + * Read input from a file the name of which is given. The PathSearch + * class "PARAMETERS" is used to find the file. * - * Return whether the read was - * successful. + * Return whether the read was successful. * - * Unless optional is - * true, this function - * will automatically generate - * the requested file with - * default values if the file did - * not exist. This file will not - * contain additional comments if - * write_stripped_file - * is true. + * Unless optional is true, this function will + * automatically generate the requested file with default values if the + * file did not exist. This file will not contain additional comments if + * write_stripped_file is true. */ virtual bool read_input (const std::string &filename, const bool optional = false, const bool write_stripped_file = false); /** - * Read input from a string in - * memory. The lines in memory - * have to be separated by @\n - * characters. + * Read input from a string in memory. The lines in memory have to be + * separated by @\n characters. * - * Return whether the read was - * successful. + * Return whether the read was successful. */ virtual bool read_input_from_string (const char *s); /** - * Read a parameter file in XML - * format. This could be from a file - * originally written by the - * print_parameters() function using the - * XML output style and then modified by - * hand as necessary; or from a file - * written using this method and then - * modified by the graphical parameter - * GUI (see the general documentation of - * this class). + * Read a parameter file in XML format. This could be from a file + * originally written by the print_parameters() function using the XML + * output style and then modified by hand as necessary; or from a file + * written using this method and then modified by the graphical parameter + * GUI (see the general documentation of this class). * - * Return whether the read was - * successful. + * Return whether the read was successful. */ virtual bool read_input_from_xml (std::istream &input); @@ -1948,30 +1602,17 @@ public: /** - * Declare a new entry with name - * entry, default and for - * which any input has to match - * the pattern (default: any - * pattern). + * Declare a new entry with name entry, default and for which + * any input has to match the pattern (default: any pattern). * - * The last parameter defaulting - * to an empty string is used to - * add a documenting text to each - * entry which will be printed as - * a comment when this class is - * asked to write out all - * declarations to a stream using - * the print_parameters() - * function. + * The last parameter defaulting to an empty string is used to add a + * documenting text to each entry which will be printed as a comment when + * this class is asked to write out all declarations to a stream using + * the print_parameters() function. * - * The function generates an - * exception if the default value - * doesn't match the given - * pattern. An entry can be - * declared more than once - * without generating an error, - * for example to override an - * earlier default value. + * The function generates an exception if the default value doesn't match + * the given pattern. An entry can be declared more than once without + * generating an error, for example to override an earlier default value. */ void declare_entry (const std::string &entry, const std::string &default_value, @@ -1979,221 +1620,146 @@ public: const std::string &documentation = std::string()); /** - * Enter a subsection; if not yet - * existent, declare it. + * Enter a subsection; if not yet existent, declare it. */ void enter_subsection (const std::string &subsection); /** - * Leave present subsection. - * Return false if there is - * no subsection to leave; true - * otherwise. + * Leave present subsection. Return false if there is no + * subsection to leave; true otherwise. */ bool leave_subsection (); /** - * Return value of entry - * entry_string. If the - * entry was changed, then the - * changed value is returned, - * otherwise the default - * value. If the value of an - * undeclared entry is required, - * an exception will be thrown. + * Return value of entry entry_string. If the entry was + * changed, then the changed value is returned, otherwise the default + * value. If the value of an undeclared entry is required, an exception + * will be thrown. */ std::string get (const std::string &entry_string) const; /** - * Return value of entry - * entry_string as long - * int. (A long int is chosen so - * that even very large unsigned values - * can be returned by this function). + * Return value of entry entry_string as long int. (A + * long int is chosen so that even very large unsigned values can be + * returned by this function). */ long int get_integer (const std::string &entry_string) const; /** - * Return value of entry - * entry_name as - * double. + * Return value of entry entry_name as double. */ double get_double (const std::string &entry_name) const; /** - * Return value of entry - * entry_name as bool. - * The entry may be "true" or "yes" - * for true, "false" or - * "no" for false respectively. + * Return value of entry entry_name as bool. The entry + * may be "true" or "yes" for true, "false" or "no" for + * false respectively. */ bool get_bool (const std::string &entry_name) const; /** - * Change the value presently stored for - * entry_name to the one given - * in the second argument. + * Change the value presently stored for entry_name to the one + * given in the second argument. * - * The parameter must already exist in - * the present subsection. + * The parameter must already exist in the present subsection. * - * The function throws an - * exception of type - * ExcValueDoesNotMatchPattern - * if the new value does not - * conform to the pattern for - * this entry. + * The function throws an exception of type ExcValueDoesNotMatchPattern + * if the new value does not conform to the pattern for this entry. */ void set (const std::string &entry_name, const std::string &new_value); /** - * Same as above, but an overload where - * the second argument is a character - * pointer. This is necessary, since - * otherwise the call to - * set("abc","def") will be - * mapped to the function taking one - * string and a bool as arguments, which - * is certainly not what is most often - * intended. + * Same as above, but an overload where the second argument is a + * character pointer. This is necessary, since otherwise the call to + * set("abc","def") will be mapped to the function taking one + * string and a bool as arguments, which is certainly not what is most + * often intended. * - * The function throws an - * exception of type - * ExcValueDoesNotMatchPattern - * if the new value does not - * conform to the pattern for - * this entry. + * The function throws an exception of type ExcValueDoesNotMatchPattern + * if the new value does not conform to the pattern for this entry. */ void set (const std::string &entry_name, const char *new_value); /** - * Change the value presently stored for - * entry_name to the one given - * in the second argument. + * Change the value presently stored for entry_name to the one + * given in the second argument. * - * The parameter must already exist in - * the present subsection. + * The parameter must already exist in the present subsection. * - * The function throws an - * exception of type - * ExcValueDoesNotMatchPattern - * if the new value does not - * conform to the pattern for - * this entry. + * The function throws an exception of type ExcValueDoesNotMatchPattern + * if the new value does not conform to the pattern for this entry. */ void set (const std::string &entry_name, const long int &new_value); /** - * Change the value presently stored for - * entry_name to the one given - * in the second argument. + * Change the value presently stored for entry_name to the one + * given in the second argument. * - * The parameter must already exist in - * the present subsection. + * The parameter must already exist in the present subsection. * - * For internal purposes, the new value - * needs to be converted to a - * string. This is done using 16 digits - * of accuracy, so the set value and the - * one you can get back out using - * get_double() may differ in the 16th + * For internal purposes, the new value needs to be converted to a + * string. This is done using 16 digits of accuracy, so the set value and + * the one you can get back out using get_double() may differ in the 16th * digit. * - * The function throws an - * exception of type - * ExcValueDoesNotMatchPattern - * if the new value does not - * conform to the pattern for - * this entry. + * The function throws an exception of type ExcValueDoesNotMatchPattern + * if the new value does not conform to the pattern for this entry. */ void set (const std::string &entry_name, const double &new_value); /** - * Change the value presently stored for - * entry_name to the one given - * in the second argument. + * Change the value presently stored for entry_name to the one + * given in the second argument. * - * The parameter must already exist in - * the present subsection. + * The parameter must already exist in the present subsection. * - * The function throws an - * exception of type - * ExcValueDoesNotMatchPattern - * if the new value does not - * conform to the pattern for - * this entry. + * The function throws an exception of type ExcValueDoesNotMatchPattern + * if the new value does not conform to the pattern for this entry. */ void set (const std::string &entry_name, const bool &new_value); /** - * Print all parameters with the - * given style to - * out. Presently only - * Text and LaTeX are - * implemented. + * Print all parameters with the given style to out. Presently + * only Text and LaTeX are implemented. * - * In Text format, the output - * is formatted in such a way - * that it is possible to use it - * for later input again. This is - * most useful to record the - * parameters for a specific run, - * since if you output the - * parameters using this function - * into a log file, you can - * always recover the results by - * simply copying the output to - * your input file. + * In Text format, the output is formatted in such a way that it + * is possible to use it for later input again. This is most useful to + * record the parameters for a specific run, since if you output the + * parameters using this function into a log file, you can always recover + * the results by simply copying the output to your input file. * - * Besides the name and value of - * each entry, the output also - * contains the default value of - * entries if it is different - * from the actual value, as well - * as the documenting string - * given to the - * declare_entry() function + * Besides the name and value of each entry, the output also contains the + * default value of entries if it is different from the actual value, as + * well as the documenting string given to the declare_entry() function * if available. * - * In Text format, the - * output contains the same information - * but in a format so that the - * resulting file can be input into - * a latex document such as a manual - * for the code for which this object - * handles run-time parameters. - * The various sections of parameters - * are then represented by latex - * section and subsection commands - * as well as by nested enumerations. + * In Text format, the output contains the same information but + * in a format so that the resulting file can be input into a latex + * document such as a manual for the code for which this object handles + * run-time parameters. The various sections of parameters are then + * represented by latex section and subsection commands as well as by + * nested enumerations. * - * In addition, all parameter names - * are listed with @\index - * statements in two indices called - * prmindex (where the - * name of each parameter is listed - * in the index) and prmindexfull - * where parameter names are listed - * sorted by the section in which - * they exist. By default, the LaTeX - * program ignores these @\index - * commands, but they can be used to - * generate an index by using the - * following commands in the preamble - * of the latex file: + * In addition, all parameter names are listed with @\index + * statements in two indices called prmindex (where the name + * of each parameter is listed in the index) and + * prmindexfull where parameter names are listed sorted by + * the section in which they exist. By default, the LaTeX program ignores + * these @\index commands, but they can be used to generate + * an index by using the following commands in the preamble of the latex + * file: * @code * \usepackage{imakeidx} * \makeindex[name=prmindex, title=Index of run-time parameter entries] * \makeindex[name=prmindexfull, title=Index of run-time parameters with section names] * @endcode - * and at the end of the file - * this: + * and at the end of the file this: * @code * \printindex[prmindex] * \printindex[prmindexfull] @@ -2203,76 +1769,51 @@ public: const OutputStyle style); /** - * Print out the parameters of - * the present subsection as - * given by the - * subsection_path member - * variable. This variable is - * controlled by entering and - * leaving subsections through - * the enter_subsection() and - * leave_subsection() - * functions. + * Print out the parameters of the present subsection as given by the + * subsection_path member variable. This variable is controlled + * by entering and leaving subsections through the enter_subsection() and + * leave_subsection() functions. * - * In most cases, you will not - * want to use this function - * directly, but have it called - * recursively by the previous - * function. + * In most cases, you will not want to use this function directly, but + * have it called recursively by the previous function. */ void print_parameters_section (std::ostream &out, const OutputStyle style, const unsigned int indent_level); /** - * Print parameters to a - * logstream. This function - * allows to print all parameters - * into a log-file. Sections - * will be indented in the usual + * Print parameters to a logstream. This function allows to print all + * parameters into a log-file. Sections will be indented in the usual * log-file style. */ void log_parameters (LogStream &out); /** - * Log parameters in the present - * subsection. The subsection is - * determined by the - * subsection_path member - * variable. This variable is - * controlled by entering and - * leaving subsections through - * the enter_subsection() and - * leave_subsection() - * functions. + * Log parameters in the present subsection. The subsection is determined + * by the subsection_path member variable. This variable is + * controlled by entering and leaving subsections through the + * enter_subsection() and leave_subsection() functions. * - * In most cases, you will not - * want to use this function - * directly, but have it called - * recursively by the previous - * function. + * In most cases, you will not want to use this function directly, but + * have it called recursively by the previous function. */ void log_parameters_section (LogStream &out); /** - * Determine an estimate for - * the memory consumption (in - * bytes) of this + * Determine an estimate for the memory consumption (in bytes) of this * object. */ std::size_t memory_consumption () const; /** - * Write the data of this object to a - * stream for the purpose of + * Write the data of this object to a stream for the purpose of * serialization. */ template void save (Archive &ar, const unsigned int version) const; /** - * Read the data of this object from a - * stream for the purpose of + * Read the data of this object from a stream for the purpose of * serialization. */ template @@ -2320,104 +1861,73 @@ public: //@} private: /** - * The separator used when - * accessing elements of a path - * into the parameter tree. + * The separator used when accessing elements of a path into the + * parameter tree. */ static const char path_separator = '.'; /** - * The complete tree of sections - * and entries. See the general - * documentation of this class - * for a description how data is - * stored in this variable. + * The complete tree of sections and entries. See the general + * documentation of this class for a description how data is stored in + * this variable. * - * The variable is a pointer so - * that we can use an incomplete - * type, rather than having to - * include all of the - * property_tree stuff from - * boost. This works around a - * problem with gcc 4.5. + * The variable is a pointer so that we can use an incomplete type, + * rather than having to include all of the property_tree stuff from + * boost. This works around a problem with gcc 4.5. */ std::auto_ptr entries; /** - * A list of patterns that are - * used to describe the - * parameters of this object. The - * are indexed by nodes in the - * property tree. + * A list of patterns that are used to describe the parameters of this + * object. The are indexed by nodes in the property tree. */ std::vector > patterns; /** - * Mangle a string so that it - * doesn't contain any special - * characters or spaces. + * Mangle a string so that it doesn't contain any special characters or + * spaces. */ static std::string mangle (const std::string &s); /** - * Unmangle a string into its - * original form. + * Unmangle a string into its original form. */ static std::string demangle (const std::string &s); /** - * Return whether a given node is - * a parameter node or a - * subsection node. + * Return whether a given node is a parameter node or a subsection node. */ static bool is_parameter_node (const boost::property_tree::ptree &); /** - * Path of presently selected - * subsections; empty list means - * top level + * Path of presently selected subsections; empty list means top level */ std::vector subsection_path; /** - * Return the string that - * identifies the current path - * into the property tree. This - * is only a path, i.e. it is not - * terminated by the + * Return the string that identifies the current path into the property + * tree. This is only a path, i.e. it is not terminated by the * path_separator character. */ std::string get_current_path () const; /** - * Given the name of an entry as - * argument, the function - * computes a full path into the - * parameter tree using the - * current subsection. + * Given the name of an entry as argument, the function computes a full + * path into the parameter tree using the current subsection. */ std::string get_current_full_path (const std::string &name) const; /** - * Scan one line of input. - * lineno is the number of - * the line presently scanned - * (for the logs if there are - * messages). Return false if - * line contained stuff that - * could not be understood, the - * uppermost subsection was to be - * left by an END or end - * statement, a value for a - * non-declared entry was given - * or the entry value did not - * match the regular - * expression. true otherwise. + * Scan one line of input. lineno is the number of the line + * presently scanned (for the logs if there are messages). Return + * false if line contained stuff that could not be understood, + * the uppermost subsection was to be left by an END or + * end statement, a value for a non-declared entry was given or + * the entry value did not match the regular expression. true + * otherwise. * - * The function modifies its - * argument, but also takes it by - * value, so the caller's - * variable is not changed. + * The function modifies its argument, but also takes it by value, so the + * caller's variable is not changed. */ bool scan_line (std::string line, const unsigned int lineno); @@ -2428,57 +1938,64 @@ private: /** - * The class MultipleParameterLoop offers an easy possibility to test several - * parameter sets during one run of the program. For this it uses the - * ParameterHandler class to read in data in a standardized form, searches for - * variant entry values and performs a loop over all combinations of parameters. + * The class MultipleParameterLoop offers an easy possibility to test + * several parameter sets during one run of the program. For this it uses + * the ParameterHandler class to read in data in a standardized form, + * searches for variant entry values and performs a loop over all + * combinations of parameters. * * Variant entry values are given like this: * @verbatim * set Time step size = { 0.1 | 0.2 | 0.3 } * @endverbatim - * The loop will then perform three runs of the program, one for each value - * of Time step size, while all other parameters are as specified or with their - * default value. If there are several variant entry values in the input, a loop is - * performed for each combination of variant values: + * The loop will then perform three runs of the program, one for each + * value of Time step size, while all other parameters are as + * specified or with their default value. If there are several variant + * entry values in the input, a loop is performed for each combination of + * variant values: * @verbatim * set Time step size = { 0.1 | 0.2 } * set Solver = { CG | GMRES } * @endverbatim - * will result in four runs of the programs, with time step 0.1 and 0.2 for each - * of the two solvers. + * will result in four runs of the programs, with time step 0.1 and 0.2 + * for each of the two solvers. * - * In addition to variant entries, this class also supports array entries that look like this: + * In addition to variant entries, this class also supports array + * entries that look like this: * @verbatim * set Output file = ofile.{{ 1 | 2 | 3 | 4 }} * @endverbatim - * This indicates that if there are variant entries producing a total of four - * different runs, then we will write their results to the files ofile.1, ofile.2, - * ofile.3 and ofile.4, respectively. Array entries do not generate multiple - * runs of the main loop themselves, but if there are variant entries, then in - * the nth run of the main loop, also the nth value of an array is returned. - * - * Since the different variants are constructed in the order of declaration, not in - * the order in which the variant entries appear in the input file, it may be - * difficult to guess the mapping between the different variants and the appropriate - * entry in an array. You will have to check the order of declaration, or use - * only one variant entry. - * - * It is guaranteed that only selections which match the regular expression (pattern) given - * upon declaration of an entry are given back to the program. If a variant value - * does not match the regular expression, the default value is stored and an error - * is issued. Before the first run of the loop, all possible values are checked - * for their conformance, so that the error is issued at the very beginning of the + * This indicates that if there are variant entries producing a total of + * four different runs, then we will write their results to the files + * ofile.1, ofile.2, ofile.3 and + * ofile.4, respectively. Array entries do not generate multiple + * runs of the main loop themselves, but if there are variant entries, + * then in the nth run of the main loop, also the nth value + * of an array is returned. + * + * Since the different variants are constructed in the order of + * declaration, not in the order in which the variant entries appear in + * the input file, it may be difficult to guess the mapping between the + * different variants and the appropriate entry in an array. You will + * have to check the order of declaration, or use only one variant entry. + * + * It is guaranteed that only selections which match the regular + * expression (pattern) given upon declaration of an entry are given back + * to the program. If a variant value does not match the regular + * expression, the default value is stored and an error is issued. Before + * the first run of the loop, all possible values are checked for their + * conformance, so that the error is issued at the very beginning of the * program. * * *

Usage

* - * The usage of this class is similar to the ParameterHandler class. First the - * entries and subsections have to be declared, then a loop is performed in which - * the different parameter sets are set, a new instance of a user class is created - * which is then called. Taking the classes of the example for the - * ParameterHandler class, the extended program would look like this: + * The usage of this class is similar to the ParameterHandler class. + * First the entries and subsections have to be declared, then a loop is + * performed in which the different parameter sets are set, a new + * instance of a user class is created which is then called. Taking the + * classes of the example for the ParameterHandler class, the extended + * program would look like this: * @code * class HelperClass : public MultipleParameterLoop::UserClass { * public: @@ -2525,25 +2042,25 @@ private: * } * @endcode * - * As can be seen, first a new helper class has to be set up. This must contain - * a virtual constructor for a problem class. You can also derive your problem - * class from MultipleParameterLoop::UserClass and let create_new clear all - * member variables. If you have access to all inherited member variables in - * some way this is the recommended procedure. A third possibility is to use - * multiple inheritance and derive a helper class from both the - * MultipleParameterLoop::UserClass and the problem class. In any case, - * create_new has to provide a clean problem object which is the problem in - * the second and third possibility. - * - * The derived class also - * has to provide for member functions which declare the entries and which run - * the program. Running the program includes getting the parameters out of the - * ParameterHandler object. + * As can be seen, first a new helper class has to be set up. This must + * contain a virtual constructor for a problem class. You can also derive + * your problem class from MultipleParameterLoop::UserClass and let + * create_new clear all member variables. If you have access to + * all inherited member variables in some way this is the recommended + * procedure. A third possibility is to use multiple inheritance and + * derive a helper class from both the MultipleParameterLoop::UserClass + * and the problem class. In any case, create_new has to provide + * a clean problem object which is the problem in the second and third + * possibility. + * + * The derived class also has to provide for member functions which + * declare the entries and which run the program. Running the program + * includes getting the parameters out of the ParameterHandler object. * * After defining an object of this helper class and an object of the - * MultipleParameterLoop class, the entries have to be declared in the same way - * as for the ParameterHandler class. Then the input has to be read. Finally - * the loop is called. This executes the following steps: + * MultipleParameterLoop class, the entries have to be declared in the + * same way as for the ParameterHandler class. Then the input has to be + * read. Finally the loop is called. This executes the following steps: * @code * for (each combination) * { @@ -2554,9 +2071,9 @@ private: * UserObject.run (*this); * } * @endcode - * UserObject is the parameter to the loop function. create_new is given the number - * of the run (starting from one) to enable naming output files differently for each - * run. + * UserObject is the parameter to the loop function. + * create_new is given the number of the run (starting from one) + * to enable naming output files differently for each run. * * *

Syntax for variant and array entry values

@@ -2574,8 +2091,8 @@ private: * *

Worked example

* - * Given the above extensions to the example program for the ParameterHandler and the - * following input file + * Given the above extensions to the example program for the + * ParameterHandler and the following input file * @verbatim * set Equation 1 = Poisson * set Equation 2 = Navier-Stokes @@ -2630,8 +2147,8 @@ private: * eq1=Poisson, eq2=Navier-Stokes * Matrix1=Sparse, Matrix2=Full * @endverbatim - * Since create_new gets the number of the run it would also be possible to output - * the number of the run. + * Since create_new gets the number of the run it would also be + * possible to output the number of the run. * * * @ingroup input @@ -2641,37 +2158,32 @@ class MultipleParameterLoop : public ParameterHandler { public: /** - * This is the class the helper class or the - * problem class has to be derived of. + * This is the class the helper class or the problem class has to be + * derived of. */ class UserClass { public: /** - * Destructor. It doesn't actually do - * anything, but is declared to force - * derived classes to have a virtual - * destructor. + * Destructor. It doesn't actually do anything, but is declared to + * force derived classes to have a virtual destructor. */ virtual ~UserClass (); /** - * create_new must provide a clean - * object, either by creating a new one - * or by cleaning an old one. + * create_new must provide a clean object, either by creating + * a new one or by cleaning an old one. */ virtual void create_new (const unsigned int run_no) = 0; /** - * This should declare parameters and call - * the declare_parameters function of the - * problem class. + * This should declare parameters and call the + * declare_parameters function of the problem class. */ virtual void declare_parameters (ParameterHandler &prm) = 0; /** - * Get the parameters and run any - * necessary action. + * Get the parameters and run any necessary action. */ virtual void run (ParameterHandler &prm) = 0; }; @@ -2682,10 +2194,9 @@ public: MultipleParameterLoop (); /** - * Destructor. Declare this only to have - * a virtual destructor, which is safer - * as we have virtual functions. - * It actually does nothing spectacular. + * Destructor. Declare this only to have a virtual destructor, which is + * safer as we have virtual functions. It actually does nothing + * spectacular. */ virtual ~MultipleParameterLoop (); @@ -2695,9 +2206,8 @@ public: const bool write_stripped_file = false); /** - * Read input from a string in memory. The - * lines in memory have to be separated by - * @\n characters. + * Read input from a string in memory. The lines in memory have to be + * separated by @\n characters. */ virtual bool read_input_from_string (const char *s); @@ -2707,9 +2217,7 @@ public: void loop (UserClass &uc); /** - * Determine an estimate for - * the memory consumption (in - * bytes) of this + * Determine an estimate for the memory consumption (in bytes) of this * object. */ std::size_t memory_consumption () const; @@ -2717,17 +2225,14 @@ public: private: /** - * An object in the list of entries with - * multiple values. + * An object in the list of entries with multiple values. */ class Entry { public: /** - * Declare what a multiple entry - * is: a variant * entry (in - * curly braces {, }) or an - * array (in double curly braces + * Declare what a multiple entry is: a variant * entry (in curly braces + * {, }) or an array (in double curly braces * {{, }}). */ enum MultipleEntryType @@ -2741,18 +2246,16 @@ private: Entry () : type (array) {} /** - * Construct an object with given subsection - * path, name and value. The splitting up - * into the different variants is done - * later by split_different_values. + * Construct an object with given subsection path, name and value. The + * splitting up into the different variants is done later by + * split_different_values. */ Entry (const std::vector &Path, const std::string &Name, const std::string &Value); /** - * Split the entry value into the different - * branches. + * Split the entry value into the different branches. */ void split_different_values (); @@ -2772,22 +2275,18 @@ private: std::string entry_value; /** - * List of entry values constructed out of - * what was given in the input file (that - * is stored in EntryValue. + * List of entry values constructed out of what was given in the input + * file (that is stored in EntryValue. */ std::vector different_values; /** - * Store whether this entry is a variant - * entry or an array. + * Store whether this entry is a variant entry or an array. */ MultipleEntryType type; /** - * Determine an estimate for - * the memory consumption (in - * bytes) of this + * Determine an estimate for the memory consumption (in bytes) of this * object. */ std::size_t memory_consumption () const; @@ -2799,37 +2298,26 @@ private: std::vector multiple_choices; /** - * Number of branches constructed - * from the different - * combinations of the variants. - * This obviously equals the - * number of runs to be - * performed. + * Number of branches constructed from the different combinations of the + * variants. This obviously equals the number of runs to be performed. */ unsigned int n_branches; /** - * Initialize the different - * branches, i.e. construct the - * combinations. + * Initialize the different branches, i.e. construct the combinations. */ void init_branches (); /** - * Traverse the section currently - * set by - * enter_subsection()/leave_subsection() - * and see which of the entries - * are variante/array - * entries. Then fill the - * multiple_choices variable - * using this information. + * Traverse the section currently set by + * enter_subsection()/leave_subsection() and see which of the entries are + * variante/array entries. Then fill the multiple_choices variable using + * this information. */ void init_branches_current_section (); /** - * Transfer the entry values for one run - * to the entry tree. + * Transfer the entry values for one run to the entry tree. */ void fill_entry_values (const unsigned int run_no); }; -- 2.39.5