]> https://gitweb.dealii.org/ - dealii-svn.git/commitdiff
Add documentation to declared entries of parameterhandler objects. Remove some old...
authorwolf <wolf@0785d39b-7218-0410-832d-ea1e28bc413d>
Thu, 14 Aug 2003 15:12:15 +0000 (15:12 +0000)
committerwolf <wolf@0785d39b-7218-0410-832d-ea1e28bc413d>
Thu, 14 Aug 2003 15:12:15 +0000 (15:12 +0000)
git-svn-id: https://svn.dealii.org/trunk@7922 0785d39b-7218-0410-832d-ea1e28bc413d

12 files changed:
deal.II/base/include/base/parameter_handler.h
deal.II/base/source/parameter_handler.cc
deal.II/doc/news/c-4-0.html
tests/bits/Makefile
tests/bits/parameter_handler_3.cc [new file with mode: 0644]
tests/bits/parameter_handler_4.cc [new file with mode: 0644]
tests/results/i686-pc-linux-gnu+gcc2.95/bits/parameter_handler_3.output [new file with mode: 0644]
tests/results/i686-pc-linux-gnu+gcc2.95/bits/parameter_handler_4.output [new file with mode: 0644]
tests/results/i686-pc-linux-gnu+gcc3.2/bits/parameter_handler_3.output [new file with mode: 0644]
tests/results/i686-pc-linux-gnu+gcc3.2/bits/parameter_handler_4.output [new file with mode: 0644]
tests/results/sparc-sun-solaris2.7+gcc2.95/bits/parameter_handler_3.output [new file with mode: 0644]
tests/results/sparc-sun-solaris2.7+gcc2.95/bits/parameter_handler_4.output [new file with mode: 0644]

index 2fafa0aee15cfcca94436b32f23503374da94ebf..a8d10d782a3b989cdd5601e470bf16a5181cb27f 100644 (file)
@@ -764,17 +764,28 @@ namespace Patterns
  *     ParameterHandler prm;
  *     prm.declare_entry ("Time step size",
  *                       "0.2",
- *                       Patterns::Double());
+ *                       Patterns::Double(),
+ *                       "Some documentation");
  *     prm.declare_entry ("Geometry",
  *                       "[0,1]x[0,1]",
  *                       Patterns::Anything());
  *     ...
  *   @end{verbatim}
- *   Each entry is declared using the function @p{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 @p{Patterns}.
+ *   Each entry is declared using the function @p{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
+ *   @p{Patterns}. This parameter can be omitted, in which case it
+ *   will default to @p{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
+ *   @p{ParameterHandler} object using the @p{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
@@ -790,7 +801,8 @@ namespace Patterns
  *       prm.enter_subsection("Linear solver");
  *       prm.declare_entry ("Solver",
  *                          "CG",
- *                         Patterns::Selection("CG|GMRES|GaussElim"));
+ *                         Patterns::Selection("CG|GMRES|GaussElim"),
+ *                         "Name of a linear solver for the inner iteration");
  *       prm.declare_entry ("Maximum number of iterations",
  *                          "20",
  *                         ParameterHandler::RegularExpressions::Integer());
@@ -887,17 +899,18 @@ namespace Patterns
  *   once will be overwritten everytime they are used. It is suggested to let the name of
  *   parameter input end in @p{.prm}.
  *
- *   You should not try to declare entries using @p{declare_entry} and @p{enter_subsection} with as
- *   yet unknown subsection names after using @p{read_input}. The results in this case are
- *   unspecified.
+ *   You should not try to declare entries using @p{declare_entry} and
+ *   @p{enter_subsection} with as yet unknown subsection names after
+ *   using @p{read_input}. The results in this case are unspecified.
  *
- *   If an error occurs upon reading the input, error messages are written to @p{std::cerr}.
+ *   If an error occurs upon reading the input, error messages are
+ *   written to @p{std::cerr}.
  *
  *   
  *   @sect3{Getting entry values out of a @p{ParameterHandler} object}
  *   
- *   Each class gets its data out of a @p{ParameterHandler} object by calling the @p{get (...)}
- *   member functions like this:
+ *   Each class gets its data out of a @p{ParameterHandler} object by
+ *   calling the @p{get (...)}  member functions like this:
  *   @begin{verbatim}
  *      void NonLinEq::get_parameters (ParameterHandler &prm) {
  *       prm.enter_subsection ("Nonlinear solver");
@@ -1001,7 +1014,8 @@ namespace Patterns
  *       prm.enter_subsection ("Linear solver");
  *       prm.declare_entry ("Solver",
  *                          "CG",
- *                          Patterns::Selection("CG|BiCGStab|GMRES"));
+ *                          Patterns::Selection("CG|BiCGStab|GMRES"),
+ *                          "Name of a linear solver for the inner iteration");
  *       prm.declare_entry ("Maximum number of iterations",
  *                          "20",
  *                          Patterns::Integer());
@@ -1023,10 +1037,13 @@ namespace Patterns
  *                                        // first some global parameter entries
  *       prm.declare_entry ("Output file",
  *                          "out",
- *                          Patterns::Anything());
+ *                          Patterns::Anything(),
+ *                          "Name of the output file, either relative to the present"
+ *                          "path or absolute");
  *       prm.declare_entry ("Equation 1",
  *                          "Laplace",
- *                          Patterns::Anything());
+ *                          Patterns::Anything(),
+ *                          "String identifying the equation we want to solve");
  *       prm.declare_entry ("Equation 2",
  *                          "Elasticity",
  *                          Patterns::Anything());
@@ -1036,7 +1053,9 @@ namespace Patterns
  *       prm.enter_subsection ("Equation 1");
  *       prm.declare_entry ("Matrix type",
  *                          "Sparse",
- *                          Patterns::Selection("Full|Sparse|Diagonal"));
+ *                          Patterns::Selection("Full|Sparse|Diagonal"),
+ *                          "Type of the matrix to be used, either full,"
+ *                          "sparse, or diagonal");
  *       LinEq::declare_parameters (prm);  // for eq1
  *       prm.leave_subsection ();
  *           
@@ -1092,7 +1111,7 @@ namespace Patterns
  *           
  *                                        // print parameters to std::cout as ASCII text
  *       std::cout << std::endl << std::endl;
- *       prm.print_parameters (std::cout, Text);
+ *       prm.print_parameters (std::cout, ParameterHandler::Text);
  *           
  *                                        // get parameters into the program
  *       std::cout << std::endl << std::endl
@@ -1285,15 +1304,28 @@ class ParameterHandler
                                      * @p{entry}, default and for
                                      * which any input has to match
                                      * the @p{pattern} (default: any
-                                     * pattern).  Return @p{false} if
-                                     * entry already exists or
-                                     * default value does not match
-                                     * the regular expression;
-                                     * @p{true} otherwise.
+                                     * 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 @ref{print_parameters}
+                                     * function.
+                                     *
+                                     * The function generates an
+                                     * exception if an entry with
+                                     * this name already exists, or
+                                     * if the default value doesn't
+                                     * match the given pattern.
                                      */
-    bool declare_entry    (const std::string           &entry,
-                          const std::string           &default_value,
-                          const Patterns::PatternBase &pattern = Patterns::Anything());
+    void declare_entry (const std::string           &entry,
+                        const std::string           &default_value,
+                        const Patterns::PatternBase &pattern = Patterns::Anything(),
+                        const std::string           &documentation = std::string());
     
                                     /**
                                      * Enter a subsection; if not yet
@@ -1357,22 +1389,42 @@ class ParameterHandler
                                      * that it is possible to use it
                                      * for later input again. This is
                                      * most useful to record the
-                                     * parameters set for a specific
-                                     * run, since if you output 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 as well as the
+                                     * documenting string given to
+                                     * the @ref{declare_entry}
+                                     * function if available.
                                      */
     std::ostream & print_parameters (std::ostream      &out,
                                     const OutputStyle  style);
 
                                     /**
                                      * Print out the parameters of
-                                     * the subsection given by the
+                                     * the present subsection as
+                                     * given by the
                                      * @p{subsection_path} member
-                                     * variable.
+                                     * variable. This variable is
+                                     * controlled by entering and
+                                     * leaving subsections through
+                                     * the @ref{enter_subsection} and
+                                     * @ref{leave_subsection}
+                                     * functions.
+                                     *
+                                     * 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,
@@ -1389,11 +1441,22 @@ class ParameterHandler
     void log_parameters (LogStream& out);
 
                                     /**
-                                     * Log parameters in
+                                     * Log parameters in the present
                                      * subsection. The subsection is
                                      * determined by the
                                      * @p{subsection_path} member
-                                     * variable.
+                                     * variable. This variable is
+                                     * controlled by entering and
+                                     * leaving subsections through
+                                     * the @ref{enter_subsection} and
+                                     * @ref{leave_subsection}
+                                     * functions.
+                                     *
+                                     * 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);    
 
@@ -1451,9 +1514,37 @@ class ParameterHandler
     {
        ~Section ();
 
-       typedef std::map<std::string, std::pair<std::string,Patterns::PatternBase*> > EntryType;
-       
+        struct EntryContent
+        {
+            std::string            value;
+            std::string            documentation;
+            Patterns::PatternBase *pattern;
+        };
+        
+                                         /**
+                                          * Typedef for a type
+                                          * describing all the entries
+                                          * in a subsection: this is a
+                                          * map from the entry keys to
+                                          * a pair of values, one for
+                                          * the default string and one
+                                          * describing the pattern
+                                          * that the entry must match.
+                                          */
+       typedef
+        std::map<std::string, EntryContent>
+        EntryType;
+
+                                         /**
+                                          * List of entries for this
+                                          * section.
+                                          */
        EntryType                       entries;
+
+                                         /**
+                                          * List of subsections of
+                                          * this section.
+                                          */
        std::map<std::string, Section*> subsections;
 
                                         /**
@@ -1771,7 +1862,6 @@ class ParameterHandler
  *   This class is inspired by the @p{Multipleloop} class of @p{DiffPack}.
  *
  *   @author Wolfgang Bangerth, October 1997
- *   @version 1.0
  *   @ref ParameterHandler
  */
 class MultipleParameterLoop : public ParameterHandler
index d2e7729c02f7fac5bfe11529e74f473bbc6ad84c..9cd1c8daf91d7ade968afc3a9628b042d6330180 100644 (file)
@@ -584,9 +584,7 @@ bool ParameterHandler::read_input (const std::string &filename)
 
       std::ofstream output (filename.c_str());
       if (output)
-       {
-         print_parameters (output, Text);
-       }
+        print_parameters (output, Text);
       
       return false;
     }
@@ -641,8 +639,9 @@ void ParameterHandler::clear ()
 
   for (p=defaults.subsections.begin(); p!=defaults.subsections.end(); ++p)
     delete p->second;
+  
   for (p=changed_entries.subsections.begin(); p!=changed_entries.subsections.end(); ++p)
-    if (p->second) 
+    if (p->second)
       {
        delete p->second;
        Assert (false, ExcInternalError());
@@ -654,9 +653,11 @@ void ParameterHandler::clear ()
 
 
 
-bool ParameterHandler::declare_entry (const std::string           &entry,
-                                     const std::string           &default_value,
-                                     const Patterns::PatternBase &pattern)
+void
+ParameterHandler::declare_entry (const std::string           &entry,
+                                 const std::string           &default_value,
+                                 const Patterns::PatternBase &pattern,
+                                 const std::string           &documentation)
 {
   Section* p = get_present_defaults_subsection ();
 
@@ -669,20 +670,11 @@ bool ParameterHandler::declare_entry (const std::string           &entry,
          ExcDefaultDoesNotMatchPattern(default_value,
                                        pattern.description()));
   
-                                  // does entry already exist?
-  if (p->entries.find (entry) != p->entries.end())
-    return false;
-
                                    // entry doesn't yet exist, but
                                    // map::operator[] will create it
-  p->entries[entry] = std::make_pair(default_value, pattern.clone());
-
-                                  // check whether default answer
-                                  // matches the pattern
-  if (!pattern.match(default_value))
-    return false;
-
-  return true;
+  p->entries[entry].value         = default_value;
+  p->entries[entry].documentation = documentation;
+  p->entries[entry].pattern       = pattern.clone();
 }
 
 
@@ -750,11 +742,11 @@ const std::string & ParameterHandler::get (const std::string &entry_string) cons
   Section::EntryType::const_iterator ptr;
   ptr = pc->entries.find (entry_string);
   if (ptr != pc->entries.end())
-    return ptr->second.first;
+    return ptr->second.value;
 
-                                  // not changed
-  ptr = pd->entries.find (entry_string);
-  return ptr->second.first;
+                                  // not changed. take the value from
+                                  // the defaults tree
+  return pd->entries.find(entry_string)->second.value;
 }
 
 
@@ -800,8 +792,9 @@ bool ParameterHandler::get_bool (const std::string &entry_string) const
 
 
 
-std::ostream & ParameterHandler::print_parameters (std::ostream &out,
-                                                  const OutputStyle style)
+std::ostream &
+ParameterHandler::print_parameters (std::ostream     &out,
+                                    const OutputStyle style)
 {
                                   // assert that only known formats are
                                   // given as "style"
@@ -812,8 +805,8 @@ std::ostream & ParameterHandler::print_parameters (std::ostream &out,
   switch (style) 
     {
       case Text:
-           out << "#Listing of Parameters" << std::endl
-               << "#---------------------" << std::endl;
+           out << "# Listing of Parameters" << std::endl
+               << "# ---------------------" << std::endl;
            break;
       case LaTeX:
            out << "\\subsubsection*{Listing of parameters}";
@@ -844,21 +837,9 @@ std::ostream & ParameterHandler::print_parameters (std::ostream &out,
 
 
 void
-ParameterHandler::log_parameters (LogStream &out)
-{
-  out.push("parameters");
-                                  // dive recursively into the
-                                  // subsections
-  log_parameters_section (out);
-
-  out.pop();
-}
-
-
-
-void ParameterHandler::print_parameters_section (std::ostream      &out,
-                                                const OutputStyle  style,
-                                                const unsigned int indent_level)
+ParameterHandler::print_parameters_section (std::ostream      &out,
+                                            const OutputStyle  style,
+                                            const unsigned int indent_level)
 {
                                   // assert that only known formats are
                                   // given as "style"
@@ -872,63 +853,112 @@ void ParameterHandler::print_parameters_section (std::ostream      &out,
                                   // traverse entry list
   Section::EntryType::const_iterator ptr;
 
-                                  // first find out the longest entry name
-  unsigned int longest_entry = 0;
-  for (ptr = pd->entries.begin(); ptr != pd->entries.end(); ++ptr)
-    if (ptr->first.length() > longest_entry)
-      longest_entry = ptr->first.length();
-
-                                  // print entries one by one
-  for (ptr = pd->entries.begin(); ptr != pd->entries.end(); ++ptr)
+  switch (style) 
     {
-                                      // check whether this entry is listed
-                                      // in the Changed tree and actually
-                                      // differs from the default value
-      if ((pc->entries.find(ptr->first) != pc->entries.end()) &&
-         (pc->entries[ptr->first].first != pd->entries[ptr->first].first))
-       switch (style) 
-         {
-           case Text:
-                 out << std::setw(indent_level*2) << ""
-                     << "set "
-                     << ptr->first
-                     << std::setw(longest_entry-ptr->first.length()+3) << " = "
-                     << pc->entries[ptr->first].first
-                     << "  #"
-                     << pd->entries[ptr->first].first
-                     << std::endl;
-                 break;
-           case LaTeX:
-                 out << "\\item {\\bf " << ptr->first << ":} "
-                     << pc->entries[ptr->first].first
-                     << " ({\\it default:} "
-                      << pd->entries[ptr->first].first
-                     << ")"
-                     << std::endl;
-                 break;
-           default:
-                 Assert (false, ExcNotImplemented());
-         }
-                                      // not a changed entry
-      else
-       switch (style) 
-         {
-           case Text:
-                 out << std::setw(indent_level*2) << ""
-                     << "set "
-                     << ptr->first
-                     << std::setw(longest_entry-ptr->first.length()+3) << "= "
-                     << ptr->second.first << std::endl;
-                 break;
-           case LaTeX:
-                 out << "\\item {\\bf " << ptr->first << ":} "
-                     << ptr->second.first
-                     << std::endl;
-                 break;
-           default:
-                 Assert (false, ExcNotImplemented());
-         };
-    };
+      case Text:
+      {
+                                         // first find out the longest
+                                         // entry name to be able to
+                                         // align the equal signs
+        unsigned int longest_name = 0;
+        for (ptr = pd->entries.begin(); ptr != pd->entries.end(); ++ptr)
+          if (ptr->first.length() > longest_name)
+            longest_name = ptr->first.length();
+
+                                         // likewise find the longest
+                                         // actual value string to
+                                         // make sure we can align the
+                                         // default and documentation
+                                         // strings
+        unsigned int longest_value = 0;
+        for (ptr = pd->entries.begin(); ptr != pd->entries.end(); ++ptr) 
+          longest_value
+            = std::max (longest_value,         
+                        (pc->entries.find(ptr->first) != pc->entries.end()
+                         ?
+                         pc->entries[ptr->first].value
+                         :
+                         pd->entries[ptr->first].value).length());
+        
+                                         // print entries one by one
+        for (ptr = pd->entries.begin(); ptr != pd->entries.end(); ++ptr) 
+          {
+                                             // see whether the
+                                             // value is listed in
+                                             // the Changed tree and
+                                             // if so take it from
+                                             // there. otherwise
+                                             // take the default
+                                             // value from the
+                                             // Default tree
+            const std::string &value
+              = (pc->entries.find(ptr->first) != pc->entries.end()
+                 ?
+                 pc->entries[ptr->first].value
+                 :
+                 pd->entries[ptr->first].value);
+
+                                             // print name and value
+                                             // of this entry
+            out << std::setw(indent_level*2) << ""
+                << "set "
+                << ptr->first
+                << std::setw(longest_name-ptr->first.length()+1) << " "
+                << "= " << value
+                << std::setw(longest_value-value.length()+1) << " "
+                << "# ";
+
+                                             // if there is
+                                             // documentation, then
+                                             // print that, too. the
+                                             // documentation is
+                                             // always looked up in
+                                             // the Defaults tree
+            if (pd->entries[ptr->first].documentation.length() != 0)
+              out << pd->entries[ptr->first].documentation << ", ";
+            
+                                             // finally print the
+                                             // default value
+            out << "default: " << pd->entries[ptr->first].value
+                << std::endl;
+          }
+        
+        break;
+      }
+      
+      case LaTeX:
+      {
+                                         // print entries one by one
+        for (ptr = pd->entries.begin(); ptr != pd->entries.end(); ++ptr)
+          {
+                                             // print name and value
+            out << "\\item {\\bf " << ptr->first << ":} "
+                << pd->entries[ptr->first].value
+                << " (";
+
+                                             // if there is a
+                                             // documenting string,
+                                             // print it as well
+            if (pd->entries[ptr->first].documentation.length() != 0)
+              out << pd->entries[ptr->first].documentation << ", ";
+
+                                             // finally print default
+                                             // value
+            out << "{\\it default:} "
+                << (pc->entries.find(ptr->first) != pc->entries.end()
+                    ?
+                    pc->entries[ptr->first].value
+                    :
+                    pd->entries[ptr->first].value)
+                << ")"
+                << std::endl;
+          }
+        break;
+      }
+      
+      default:
+            Assert (false, ExcNotImplemented());
+    }
 
 
                                   // now transverse subsections tree
@@ -958,8 +988,10 @@ void ParameterHandler::print_parameters_section (std::ostream      &out,
       switch (style) 
        {
          case Text:
-                                                // write end of subsection. one
-                                                // blank line after each subsection
+                                                // write end of
+                                                // subsection. one
+                                                // blank line after
+                                                // each subsection
                out << std::setw(indent_level*2) << ""
                    << "end" << std::endl
                    << std::endl;
@@ -983,7 +1015,21 @@ void ParameterHandler::print_parameters_section (std::ostream      &out,
 
 
 
-void ParameterHandler::log_parameters_section (LogStream &out)
+void
+ParameterHandler::log_parameters (LogStream &out)
+{
+  out.push("parameters");
+                                  // dive recursively into the
+                                  // subsections
+  log_parameters_section (out);
+
+  out.pop();
+}
+
+
+
+void
+ParameterHandler::log_parameters_section (LogStream &out)
 {
   Section *pd = get_present_defaults_subsection ();
   Section *pc = get_present_changed_subsection ();
@@ -993,19 +1039,18 @@ void ParameterHandler::log_parameters_section (LogStream &out)
 
                                   // print entries one by one
   for (ptr = pd->entries.begin(); ptr != pd->entries.end(); ++ptr)
-    {
-      if ((pc->entries.find(ptr->first) != pc->entries.end()) &&
-         (pc->entries[ptr->first].first != pd->entries[ptr->first].first))
-                                        // check whether this entry is listed
-                                        // in the Changed tree and actually
-                                        // differs from the default value
-       out << ptr->first << ": "
-           << pc->entries[ptr->first].first << std::endl;
-      else
-       out << ptr->first << ": "
-           << ptr->second.first << std::endl;
-    };
-
+                                     // see whether the value is
+                                     // listed in the Changed tree
+                                     // and if so take it from
+                                     // there. otherwise take the
+                                     // default value from the
+                                     // Default tree
+    if (pc->entries.find(ptr->first) != pc->entries.end())
+      out << ptr->first << ": "
+          << pc->entries[ptr->first].value << std::endl;
+    else
+      out << ptr->first << ": "
+          << ptr->second.value << std::endl;
 
                                   // now transverse subsections tree
   std::map<std::string, Section*>::const_iterator ptrss;
@@ -1021,8 +1066,9 @@ void ParameterHandler::log_parameters_section (LogStream &out)
 
 
 
-bool ParameterHandler::scan_line (std::string        line,
-                                 const unsigned int lineno)
+bool
+ParameterHandler::scan_line (std::string        line,
+                             const unsigned int lineno)
 {
                                   // if there is a comment, delete it
   if (line.find('#') != std::string::npos)
@@ -1055,7 +1101,8 @@ bool ParameterHandler::scan_line (std::string        line,
                                       // check whether subsection exists
       if (pc->subsections.find(SecName) == pc->subsections.end()) 
        {
-         std::cerr << "Line " << lineno << ": There is no such subsection to be entered:" << std::endl;
+         std::cerr << "Line " << lineno
+                    << ": There is no such subsection to be entered:" << std::endl;
          for (unsigned int i=0; i<subsection_path.size(); ++i)
            std::cerr << std::setw(i*2+4) << " "
                      << "subsection " << subsection_path[i] << std::endl;
@@ -1121,7 +1168,7 @@ bool ParameterHandler::scan_line (std::string        line,
                                       // which specify it as a multiple loop
                                       // entry, then ignore content
       if (entry_value.find ('{') == std::string::npos)
-       if (!pd->entries[entry_name].second->match(entry_value))
+       if (!pd->entries[entry_name].pattern->match(entry_value))
          {
            std::cerr << "Line " << lineno << ":" << std::endl
                      << "    The entry value" << std::endl
@@ -1129,25 +1176,29 @@ bool ParameterHandler::scan_line (std::string        line,
                      << "    for the entry named" << std::endl
                      << "        " << entry_name << std::endl
                      << "    does not match the given pattern" << std::endl
-                     << "        " << pd->entries[entry_name].second->description() << std::endl;
+                     << "        " << pd->entries[entry_name].pattern->description()
+                      << std::endl;
            return false;
          };
       
       Section* pc = get_present_changed_subsection ();
-                                      // the following line declares this entry
-                                      // if not yet existent and overwrites it
-                                      // otherwise (the pattern is set to a null
-                                      // pointer, since we don't need the
-                                      // pattern in the entries section -- only
+                                      // the following lines declare
+                                      // this entry if not yet
+                                      // existent and overwrites it
+                                      // otherwise (the pattern is
+                                      // set to a null pointer, since
+                                      // we don't need the pattern in
+                                      // the entries section -- only
                                       // in the defaults section)
-      pc->entries[entry_name]
-       = std::make_pair(entry_value, static_cast<Patterns::PatternBase*>(0));
+      pc->entries[entry_name].value   = entry_value;
+      pc->entries[entry_name].pattern = 0;
 
       return true;
     };
 
                                   // this line matched nothing known
-  std::cerr << "Line " << lineno << ": This line matched nothing known:" << std::endl
+  std::cerr << "Line " << lineno
+            << ": This line matched nothing known:" << std::endl
            << "    " << line << std::endl;
   return false;
 }
@@ -1238,7 +1289,7 @@ ParameterHandler::Section::~Section ()
                                   // of that memory through the
                                   // clone() call
   for (EntryType::iterator q=entries.begin(); q!=entries.end(); ++q)
-    delete q->second.second;
+    delete q->second.pattern;
                                   // then clear entire map
   entries.clear ();
 
@@ -1258,9 +1309,11 @@ ParameterHandler::Section::memory_consumption () const
   unsigned int mem = 0;
   for (EntryType::const_iterator i=entries.begin(); i!=entries.end(); ++i)
     mem += (MemoryConsumption::memory_consumption (i->first) +
-           MemoryConsumption::memory_consumption (i->second.first) +
-           MemoryConsumption::memory_consumption (*i->second.second));
-  for (std::map<std::string, Section*>::const_iterator i=subsections.begin(); i!=subsections.end(); ++i)
+           MemoryConsumption::memory_consumption (i->second.value) +
+           MemoryConsumption::memory_consumption (i->second.documentation) +
+           MemoryConsumption::memory_consumption (*i->second.pattern));
+  for (std::map<std::string, Section*>::const_iterator i=subsections.begin();
+       i!=subsections.end(); ++i)
     mem += (MemoryConsumption::memory_consumption (i->first) +
            MemoryConsumption::memory_consumption (*(i->second)));
   return mem;
@@ -1370,7 +1423,8 @@ void MultipleParameterLoop::init_branches ()
                  << "    for the entry named" << std::endl
                  << "        " << multiple_choices[i].entry_name << std::endl
                  << "    does not have the right number of entries for the " << std::endl
-                 << "        " << n_branches << " variant runs that will be performed." << std::endl;
+                 << "        " << n_branches << " variant runs that will be performed."
+                  << std::endl;
 
 
                                   // do a first run on filling the values to
@@ -1389,10 +1443,10 @@ void MultipleParameterLoop::init_branches_section (const ParameterHandler::Secti
                                   // whether it is a multiple entry
   Section::EntryType::const_iterator e;
   for (e = sec.entries.begin(); e != sec.entries.end(); ++e) 
-    if (e->second.first.find('{') != std::string::npos) 
+    if (e->second.value.find('{') != std::string::npos) 
       multiple_choices.push_back (Entry(subsection_path,
                                        e->first,
-                                       e->second.first));
+                                       e->second.value));
 
 
                                   // transverse subsections
@@ -1430,9 +1484,10 @@ void MultipleParameterLoop::fill_entry_values (const unsigned int run_no)
        {
          if (run_no>=choice->different_values.size()) 
            {
-             std::cerr << "The given array for entry "
-                       << pd->entries[choice->entry_name].first
-                       << " does not conatin enough elements! Taking empty string instead." << std::endl;
+             std::cerr << "The given array for entry <"
+                       << choice->entry_name
+                       << "> does not contain enough elements! Taking empty string instead."
+                        << std::endl;
              entry_value = "";
            }
          else
@@ -1440,7 +1495,7 @@ void MultipleParameterLoop::fill_entry_values (const unsigned int run_no)
        };
       
                                       // check conformance with regex
-      if (!pd->entries[choice->entry_name].second->match(entry_value))
+      if (!pd->entries[choice->entry_name].pattern->match(entry_value))
        {
          std::cerr << "In run no.  " << run_no+1 << ":" << std::endl
                    << "    The entry value" << std::endl
@@ -1448,23 +1503,25 @@ void MultipleParameterLoop::fill_entry_values (const unsigned int run_no)
                    << "    for the entry named" << std::endl
                    << "        " << choice->entry_name << std::endl
                    << "    does not match the given pattern" << std::endl
-                   << "        " << pd->entries[choice->entry_name].second->description() << std::endl
+                   << "        " << pd->entries[choice->entry_name].pattern->description() << std::endl
                    << "    Taking default value" << std::endl
-                   << "        " << pd->entries[choice->entry_name].first << std::endl;
+                   << "        " << pd->entries[choice->entry_name].value << std::endl;
          
                                           // select default instead
-         entry_value = pd->entries[choice->entry_name].first;
+         entry_value = pd->entries[choice->entry_name].value;
        };
 
       Section* pc = get_present_changed_subsection ();
-                                      // the following line declares this entry
-                                      // if not yet existent and overwrites it
-                                      // otherwise (the pattern is set to a null
-                                      // pointer, since we don't need the
-                                      // pattern in the entries section -- only
+                                      // the following lines declare
+                                      // this entry if not yet
+                                      // existent and overwrites it
+                                      // otherwise (the pattern is
+                                      // set to a null pointer, since
+                                      // we don't need the pattern in
+                                      // the entries section -- only
                                       // in the defaults section)
-      pc->entries[choice->entry_name]
-       = std::make_pair(entry_value, static_cast<Patterns::PatternBase*>(0));
+      pc->entries[choice->entry_name].value   = entry_value;
+      pc->entries[choice->entry_name].pattern = 0;
             
                                       // get out of subsection again
       subsection_path.swap (choice->subsection_path);
index 6e403ade26f3dd37e46b4aa80871b458c2c5bae8..1c1dd74121328c444e590c705588fcb08d4a6e09 100644 (file)
@@ -65,17 +65,40 @@ contributor's names are abbreviated by WB (Wolfgang Bangerth), GK
 <h3>base</h3>
 
 <ol>
+  <li> <p> Improved: The <code
+       class="member">ParameterHandler::declare_entry</code> now takes an
+       additional parameter (defaulting to the empty string) that can be used
+       to document the intent of a parameter. This string, together with the
+       default value of an entry, is written to the output by the <code
+       class="member">ParameterHandler::print_parameters</code> function that
+       can be used to generate a virginial parameter file, or one that contains
+       the settings of all parameters used in a computation.
+       <br>
+       (WB 2002/08/13)
+       </p>
 
-  <li> <p>
-  Improved: <code class="class">Logstream</code>::<code
-  class="member">depth_console</code>, <code
-  class="class">Logstream</code>::<code class="member">depth_file</code>, <code
-  class="class">Logstream</code>::<code class="member">log_execution_time</code> and <code
-  class="class">Logstream</code>::<code class="member">log_time_differences</code>
-  return the previous value.
-  <br>
-  (GK 2003/06/22)
-  </p>
+  <li> <p> Changed: The <code
+       class="member">ParameterHandler::declare_entry</code> previously
+       returned a value indicating whether the just-declared entry didn't
+       already existed and that the default value matches the given
+       pattern. However, this value could only always be true since these two
+       conditions were already guarded by assertions in the implementation at
+       least in debug mode, so the return value was meaningless. The function
+       has now no return type any more.
+       <br>
+       (WB 2002/08/13)
+       </p>
+
+  <li> <p> Improved: <code class="class">Logstream</code>::<code
+       class="member">depth_console</code>, <code
+       class="class">Logstream</code>::<code class="member">depth_file</code>, <code
+       class="class">Logstream</code>::<code
+       class="member">log_execution_time</code> and <code
+       class="class">Logstream</code>::<code
+       class="member">log_time_differences</code> return the previous value.
+       <br>
+       (GK 2003/06/22)
+       </p>
 </ol>
 
 
index b8dab2f59f35c677014f38b66b398029eceb8387..1ebf759747521ee83d024404794ee361dddd17f3 100644 (file)
@@ -92,6 +92,8 @@ denis_1.exe             : denis_1.g.$(OBJEXT)              $(libraries)
 unit_support_points.exe : unit_support_points.g.$(OBJEXT)  $(libraries)
 parameter_handler_1.exe : parameter_handler_1.g.$(OBJEXT)  $(libraries)
 parameter_handler_2.exe : parameter_handler_2.g.$(OBJEXT)  $(libraries)
+parameter_handler_3.exe : parameter_handler_3.g.$(OBJEXT)  $(libraries)
+parameter_handler_4.exe : parameter_handler_4.g.$(OBJEXT)  $(libraries)
 sparse_lu_decomposition_1.exe: sparse_lu_decomposition_1.g.$(OBJEXT) $(libraries)
 block_sparse_matrix_1.exe:block_sparse_matrix_1.g.$(OBJEXT) $(libraries)
 hyper_ball_3d.exe       : hyper_ball_3d.g.$(OBJEXT)        $(libraries)
@@ -118,7 +120,9 @@ tests = anna_1 anna_2 anna_3 anna_4 anna_5 anna_6 \
        fe_tools_10 fe_tools_11\
        roy_1 \
         denis_1 \
-       unit_support_points parameter_handler_1 parameter_handler_2 \
+       unit_support_points \
+       parameter_handler_1 parameter_handler_2 \
+       parameter_handler_3 parameter_handler_4 \
        sparse_lu_decomposition_1 block_sparse_matrix_1 \
        hyper_ball_3d cylinder
 
diff --git a/tests/bits/parameter_handler_3.cc b/tests/bits/parameter_handler_3.cc
new file mode 100644 (file)
index 0000000..c592899
--- /dev/null
@@ -0,0 +1,75 @@
+//----------------------------  parameter_handler_3.cc  ---------------------------
+//    $Id$
+//    Version: $Name$
+//
+//    Copyright (C) 2003 by the deal.II authors
+//
+//    This file is subject to QPL and may not be  distributed
+//    without copyright and license information. Please refer
+//    to the file deal.II/doc/license.html for the  text  and
+//    further information on this license.
+//
+//----------------------------  parameter_handler_3.cc  ---------------------------
+
+
+// test the output generated by ParameterHandler::print_parameters(Text)
+
+#include <base/logstream.h>
+#include <base/parameter_handler.h>
+#include <fstream>
+
+
+int main () 
+{
+  try 
+    {
+      std::ofstream logfile("parameter_handler_3.output");
+      deallog.attach(logfile);
+      deallog.depth_console(0);
+      
+      ParameterHandler prm;
+      prm.enter_subsection ("Testing");
+      prm.declare_entry ("string list",
+                         "a",
+                         Patterns::List(Patterns::Selection("a|b|c|d|e|f|g|h")),
+                         "docs 1");
+      prm.declare_entry ("int",
+                         "1",
+                         Patterns::Integer());
+      prm.declare_entry ("double",
+                         "3.1415926",
+                         Patterns::Double(),
+                         "docs 3");
+      prm.leave_subsection ();
+      
+                                       // read and then write parameters
+      prm.read_input("parameter_handler_3.prm");
+      prm.print_parameters (logfile, ParameterHandler::Text);
+    }
+  catch (std::exception &exc)
+    {
+      std::cerr << std::endl << std::endl
+               << "----------------------------------------------------"
+               << std::endl;
+      std::cerr << "Exception on processing: " << std::endl
+               << exc.what() << std::endl
+               << "Aborting!" << std::endl
+               << "----------------------------------------------------"
+               << std::endl;
+      
+      return 1;
+    }
+  catch (...) 
+    {
+      std::cerr << std::endl << std::endl
+               << "----------------------------------------------------"
+               << std::endl;
+      std::cerr << "Unknown exception!" << std::endl
+               << "Aborting!" << std::endl
+               << "----------------------------------------------------"
+               << std::endl;
+      return 1;
+    };
+  
+  return 0;
+}
diff --git a/tests/bits/parameter_handler_4.cc b/tests/bits/parameter_handler_4.cc
new file mode 100644 (file)
index 0000000..e671a52
--- /dev/null
@@ -0,0 +1,78 @@
+//----------------------------  parameter_handler_4.cc  ---------------------------
+//    $Id$
+//    Version: $Name$
+//
+//    Copyright (C) 2003 by the deal.II authors
+//
+//    This file is subject to QPL and may not be  distributed
+//    without copyright and license information. Please refer
+//    to the file deal.II/doc/license.html for the  text  and
+//    further information on this license.
+//
+//----------------------------  parameter_handler_4.cc  ---------------------------
+
+
+// test the output generated by ParameterHandler::print_parameters(LaTeX)
+
+#include <base/logstream.h>
+#include <base/parameter_handler.h>
+#include <fstream>
+
+
+int main () 
+{
+  try
+    {
+      std::ofstream logfile("parameter_handler_4.output");
+      deallog.attach(logfile);
+      deallog.depth_console(0);
+
+      ParameterHandler prm;
+      prm.enter_subsection ("Testing");
+      prm.declare_entry ("string list",
+                         "a",
+                         Patterns::List(Patterns::Selection("a|b|c|d|e|f|g|h")),
+                         "docs 1");
+      prm.declare_entry ("int",
+                         "1",
+                         Patterns::Integer());
+      prm.declare_entry ("double",
+                         "3.1415926",
+                         Patterns::Double(),
+                         "docs 3");
+      prm.leave_subsection ();
+
+                                       // read and then write
+                                       // parameters. take same input file
+                                       // as for parameter_handler_3, but
+                                       // use different output format
+      prm.read_input("parameter_handler_3.prm");
+      prm.print_parameters (logfile, ParameterHandler::LaTeX);
+    }
+  catch (std::exception &exc)
+    {
+      std::cerr << std::endl << std::endl
+               << "----------------------------------------------------"
+               << std::endl;
+      std::cerr << "Exception on processing: " << std::endl
+               << exc.what() << std::endl
+               << "Aborting!" << std::endl
+               << "----------------------------------------------------"
+               << std::endl;
+      
+      return 1;
+    }
+  catch (...) 
+    {
+      std::cerr << std::endl << std::endl
+               << "----------------------------------------------------"
+               << std::endl;
+      std::cerr << "Unknown exception!" << std::endl
+               << "Aborting!" << std::endl
+               << "----------------------------------------------------"
+               << std::endl;
+      return 1;
+    };
+  
+  return 0;
+}
diff --git a/tests/results/i686-pc-linux-gnu+gcc2.95/bits/parameter_handler_3.output b/tests/results/i686-pc-linux-gnu+gcc2.95/bits/parameter_handler_3.output
new file mode 100644 (file)
index 0000000..fb961fe
--- /dev/null
@@ -0,0 +1,10 @@
+
+# Listing of Parameters
+# ---------------------
+subsection Testing
+  set double      = 3.1415926 # docs 3, default: 3.1415926
+  set int         = 3         # default: 1
+  set string list = a, b, c   # docs 1, default: a
+end
+
+
diff --git a/tests/results/i686-pc-linux-gnu+gcc2.95/bits/parameter_handler_4.output b/tests/results/i686-pc-linux-gnu+gcc2.95/bits/parameter_handler_4.output
new file mode 100644 (file)
index 0000000..3d8de1a
--- /dev/null
@@ -0,0 +1,12 @@
+
+\subsubsection*{Listing of parameters}
+
+\begin{itemize}
+
+\item {\bf Subsection Testing}
+\begin{itemize}
+\item {\bf double:} 3.1415926 (docs 3, {\it default:} 3.1415926)
+\item {\bf int:} 1 ({\it default:} 3)
+\item {\bf string list:} a (docs 1, {\it default:} a, b, c)
+\end{itemize}
+\end{itemize}
diff --git a/tests/results/i686-pc-linux-gnu+gcc3.2/bits/parameter_handler_3.output b/tests/results/i686-pc-linux-gnu+gcc3.2/bits/parameter_handler_3.output
new file mode 100644 (file)
index 0000000..fb961fe
--- /dev/null
@@ -0,0 +1,10 @@
+
+# Listing of Parameters
+# ---------------------
+subsection Testing
+  set double      = 3.1415926 # docs 3, default: 3.1415926
+  set int         = 3         # default: 1
+  set string list = a, b, c   # docs 1, default: a
+end
+
+
diff --git a/tests/results/i686-pc-linux-gnu+gcc3.2/bits/parameter_handler_4.output b/tests/results/i686-pc-linux-gnu+gcc3.2/bits/parameter_handler_4.output
new file mode 100644 (file)
index 0000000..3d8de1a
--- /dev/null
@@ -0,0 +1,12 @@
+
+\subsubsection*{Listing of parameters}
+
+\begin{itemize}
+
+\item {\bf Subsection Testing}
+\begin{itemize}
+\item {\bf double:} 3.1415926 (docs 3, {\it default:} 3.1415926)
+\item {\bf int:} 1 ({\it default:} 3)
+\item {\bf string list:} a (docs 1, {\it default:} a, b, c)
+\end{itemize}
+\end{itemize}
diff --git a/tests/results/sparc-sun-solaris2.7+gcc2.95/bits/parameter_handler_3.output b/tests/results/sparc-sun-solaris2.7+gcc2.95/bits/parameter_handler_3.output
new file mode 100644 (file)
index 0000000..fb961fe
--- /dev/null
@@ -0,0 +1,10 @@
+
+# Listing of Parameters
+# ---------------------
+subsection Testing
+  set double      = 3.1415926 # docs 3, default: 3.1415926
+  set int         = 3         # default: 1
+  set string list = a, b, c   # docs 1, default: a
+end
+
+
diff --git a/tests/results/sparc-sun-solaris2.7+gcc2.95/bits/parameter_handler_4.output b/tests/results/sparc-sun-solaris2.7+gcc2.95/bits/parameter_handler_4.output
new file mode 100644 (file)
index 0000000..3d8de1a
--- /dev/null
@@ -0,0 +1,12 @@
+
+\subsubsection*{Listing of parameters}
+
+\begin{itemize}
+
+\item {\bf Subsection Testing}
+\begin{itemize}
+\item {\bf double:} 3.1415926 (docs 3, {\it default:} 3.1415926)
+\item {\bf int:} 1 ({\it default:} 3)
+\item {\bf string list:} a (docs 1, {\it default:} a, b, c)
+\end{itemize}
+\end{itemize}

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

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.