From c9721e12990a8ac3911550fd2853b6a965ad14ac Mon Sep 17 00:00:00 2001 From: wolf Date: Thu, 14 Aug 2003 15:12:15 +0000 Subject: [PATCH] Add documentation to declared entries of parameterhandler objects. Remove some old gunk. git-svn-id: https://svn.dealii.org/trunk@7922 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/base/include/base/parameter_handler.h | 160 ++++++-- deal.II/base/source/parameter_handler.cc | 353 ++++++++++-------- deal.II/doc/news/c-4-0.html | 43 ++- tests/bits/Makefile | 6 +- tests/bits/parameter_handler_3.cc | 75 ++++ tests/bits/parameter_handler_4.cc | 78 ++++ .../bits/parameter_handler_3.output | 10 + .../bits/parameter_handler_4.output | 12 + .../bits/parameter_handler_3.output | 10 + .../bits/parameter_handler_4.output | 12 + .../bits/parameter_handler_3.output | 10 + .../bits/parameter_handler_4.output | 12 + 12 files changed, 587 insertions(+), 194 deletions(-) create mode 100644 tests/bits/parameter_handler_3.cc create mode 100644 tests/bits/parameter_handler_4.cc create mode 100644 tests/results/i686-pc-linux-gnu+gcc2.95/bits/parameter_handler_3.output create mode 100644 tests/results/i686-pc-linux-gnu+gcc2.95/bits/parameter_handler_4.output create mode 100644 tests/results/i686-pc-linux-gnu+gcc3.2/bits/parameter_handler_3.output create mode 100644 tests/results/i686-pc-linux-gnu+gcc3.2/bits/parameter_handler_4.output create mode 100644 tests/results/sparc-sun-solaris2.7+gcc2.95/bits/parameter_handler_3.output create mode 100644 tests/results/sparc-sun-solaris2.7+gcc2.95/bits/parameter_handler_4.output diff --git a/deal.II/base/include/base/parameter_handler.h b/deal.II/base/include/base/parameter_handler.h index 2fafa0aee1..a8d10d782a 100644 --- a/deal.II/base/include/base/parameter_handler.h +++ b/deal.II/base/include/base/parameter_handler.h @@ -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 > 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 + EntryType; + + /** + * List of entries for this + * section. + */ EntryType entries; + + /** + * List of subsections of + * this section. + */ std::map 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 diff --git a/deal.II/base/source/parameter_handler.cc b/deal.II/base/source/parameter_handler.cc index d2e7729c02..9cd1c8daf9 100644 --- a/deal.II/base/source/parameter_handler.cc +++ b/deal.II/base/source/parameter_handler.cc @@ -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::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; ientries[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(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::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::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(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); diff --git a/deal.II/doc/news/c-4-0.html b/deal.II/doc/news/c-4-0.html index 6e403ade26..1c1dd74121 100644 --- a/deal.II/doc/news/c-4-0.html +++ b/deal.II/doc/news/c-4-0.html @@ -65,17 +65,40 @@ contributor's names are abbreviated by WB (Wolfgang Bangerth), GK

base

    +
  1. Improved: The ParameterHandler::declare_entry 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 ParameterHandler::print_parameters function that + can be used to generate a virginial parameter file, or one that contains + the settings of all parameters used in a computation. +
    + (WB 2002/08/13) +

    -
  2. - Improved: Logstream::depth_console, Logstream::depth_file, Logstream::log_execution_time and Logstream::log_time_differences - return the previous value. -
    - (GK 2003/06/22) -

    +
  3. Changed: The ParameterHandler::declare_entry 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. +
    + (WB 2002/08/13) +

    + +
  4. Improved: Logstream::depth_console, Logstream::depth_file, Logstream::log_execution_time and Logstream::log_time_differences return the previous value. +
    + (GK 2003/06/22) +

diff --git a/tests/bits/Makefile b/tests/bits/Makefile index b8dab2f59f..1ebf759747 100644 --- a/tests/bits/Makefile +++ b/tests/bits/Makefile @@ -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 index 0000000000..c592899b01 --- /dev/null +++ b/tests/bits/parameter_handler_3.cc @@ -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 +#include +#include + + +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 index 0000000000..e671a52dd1 --- /dev/null +++ b/tests/bits/parameter_handler_4.cc @@ -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 +#include +#include + + +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 index 0000000000..fb961fe6d3 --- /dev/null +++ b/tests/results/i686-pc-linux-gnu+gcc2.95/bits/parameter_handler_3.output @@ -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 index 0000000000..3d8de1a31d --- /dev/null +++ b/tests/results/i686-pc-linux-gnu+gcc2.95/bits/parameter_handler_4.output @@ -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 index 0000000000..fb961fe6d3 --- /dev/null +++ b/tests/results/i686-pc-linux-gnu+gcc3.2/bits/parameter_handler_3.output @@ -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 index 0000000000..3d8de1a31d --- /dev/null +++ b/tests/results/i686-pc-linux-gnu+gcc3.2/bits/parameter_handler_4.output @@ -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 index 0000000000..fb961fe6d3 --- /dev/null +++ b/tests/results/sparc-sun-solaris2.7+gcc2.95/bits/parameter_handler_3.output @@ -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 index 0000000000..3d8de1a31d --- /dev/null +++ b/tests/results/sparc-sun-solaris2.7+gcc2.95/bits/parameter_handler_4.output @@ -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} -- 2.39.5