From: Wolfgang Bangerth Date: Mon, 23 Mar 2015 02:00:32 +0000 (-0500) Subject: Create a way to mark aliases for deprecation. X-Git-Tag: v8.3.0-rc1~358^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a50d70053514ac893d61186d9fa30a7e0256f812;p=dealii.git Create a way to mark aliases for deprecation. --- diff --git a/include/deal.II/base/parameter_handler.h b/include/deal.II/base/parameter_handler.h index 50f65328c6..a93832476b 100644 --- a/include/deal.II/base/parameter_handler.h +++ b/include/deal.II/base/parameter_handler.h @@ -1684,9 +1684,17 @@ public: * in the current section that the alias should refer to. * @param alias_name An alternate name for the parameter referenced * by the first argument. + * @param alias_is_deprecated If true, mark the alias as deprecated. + * This will then be listed in the description of the alias if you call + * print_parameters(), and you will get a warning on the screen + * when reading an input file that contains this deprecated alias. + * The purpose of this argument is to be able to allow the use of + * an old name for a parameter (see above) but make it clear that + * this old name will eventually be removed. */ void declare_alias (const std::string &existing_entry_name, - const std::string &alias_name); + const std::string &alias_name, + const bool alias_is_deprecated = false); /** * Enter a subsection. If it does not yet exist, create it. diff --git a/source/base/parameter_handler.cc b/source/base/parameter_handler.cc index 5f80e2b06f..6c25ff6057 100644 --- a/source/base/parameter_handler.cc +++ b/source/base/parameter_handler.cc @@ -1636,7 +1636,8 @@ ParameterHandler::declare_entry (const std::string &entry, void ParameterHandler::declare_alias(const std::string &existing_entry_name, - const std::string &alias_name) + const std::string &alias_name, + const bool alias_is_deprecated) { // see if there is anything to refer to already Assert (entries->get_optional(get_current_full_path(existing_entry_name)), @@ -1676,6 +1677,8 @@ ParameterHandler::declare_alias(const std::string &existing_entry_name, entries->put (get_current_full_path(alias_name) + path_separator + "alias", existing_entry_name); + entries->put (get_current_full_path(alias_name) + path_separator + "deprecation_status", + (alias_is_deprecated ? "true" : "false")); } @@ -2224,9 +2227,15 @@ ParameterHandler::print_parameters_section (std::ostream &out, out << demangle(p->first) << "}\n"; - // finally print value and default + // finally print alias and indicate if it is deprecated out << "This parameter is an alias for the parameter ``\\texttt{" - << alias << "}''.\n\n" + << alias << "}''." + << (p->second.get("deprecation_status") == "true" + ? + " Its use is deprecated." + : + "") + << "\n\n" << std::endl; } out << "\\end{itemize}" << std::endl; @@ -2586,13 +2595,25 @@ ParameterHandler::scan_line (std::string line, std::string entry_name (line, 0, line.find('=')); std::string entry_value (line, line.find('=')+1, std::string::npos); - // resolve aliases before we look up the entry + // resolve aliases before we look up the entry. if necessary, print + // a warning that the alias is deprecated std::string path = get_current_full_path(entry_name); if (entries->get_optional(path + path_separator + "alias")) - path = get_current_full_path(entries->get(path + path_separator + "alias")); + { + if (entries->get(path + path_separator + "deprecation_status") == "true") + { + std::cerr << "Warning in line <" << lineno + << "> of file <" << input_filename + << ">: You are using the deprecated spelling <" + << entry_name + << "> of the parameter <" + << entries->get(path + path_separator + "alias") + << ">." << std::endl; + } + path = get_current_full_path(entries->get(path + path_separator + "alias")); + } - // assert that the entry is indeed - // declared + // assert that the entry is indeed declared if (entries->get_optional (path + path_separator + "value")) { // if entry was declared: diff --git a/tests/bits/parameter_handler_4a_with_alias_deprecated.cc b/tests/bits/parameter_handler_4a_with_alias_deprecated.cc new file mode 100644 index 0000000000..7e120cdf42 --- /dev/null +++ b/tests/bits/parameter_handler_4a_with_alias_deprecated.cc @@ -0,0 +1,109 @@ +// --------------------------------------------------------------------- +// +// Copyright (C) 2003 - 2015 by the deal.II authors +// +// This file is part of the deal.II library. +// +// The deal.II library is free software; you can use it, redistribute +// it, and/or modify it under the terms of the GNU Lesser General +// Public License as published by the Free Software Foundation; either +// version 2.1 of the License, or (at your option) any later version. +// The full text of the license can be found in the file LICENSE at +// the top level of the deal.II distribution. +// +// --------------------------------------------------------------------- + + + +// test the output generated by +// ParameterHandler::print_parameters(LaTeX). like the _4a test but +// with aliased parameters + +#include "../tests.h" +#include +#include +#include +#include + + +int main () +{ + try + { + std::ofstream logfile("output"); + deallog.attach(logfile); + deallog.depth_console(0); + deallog.threshold_double(1.e-10); + + ParameterHandler prm; + prm.enter_subsection ("Testing"); + { + prm.enter_subsection ("Testing 2"); + { + prm.declare_entry ("string list 2", + "a", + Patterns::List(Patterns::Selection("a|b|c|d|e|f|g|h")), + "docs 1"); + prm.declare_entry ("int 2", + "1", + Patterns::Integer()); + prm.declare_entry ("double 2", + "3.1415926", + Patterns::Double(), + "docs 3"); + } + prm.leave_subsection (); + + 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_alias ("int", + "int_alias"); + prm.declare_entry ("double", + "3.1415926", + Patterns::Double(), + "docs 3"); + prm.declare_alias ("double", + "double_alias", + true); + } + 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(SOURCE_DIR "/prm/parameter_handler_3.prm"); + prm.print_parameters (logfile, ParameterHandler::LaTeX); + } + catch (std::exception &exc) + { + deallog << std::endl << std::endl + << "----------------------------------------------------" + << std::endl; + deallog << "Exception on processing: " << std::endl + << exc.what() << std::endl + << "Aborting!" << std::endl + << "----------------------------------------------------" + << std::endl; + + return 1; + } + catch (...) + { + deallog << std::endl << std::endl + << "----------------------------------------------------" + << std::endl; + deallog << "Unknown exception!" << std::endl + << "Aborting!" << std::endl + << "----------------------------------------------------" + << std::endl; + return 1; + }; + + return 0; +} diff --git a/tests/bits/parameter_handler_4a_with_alias_deprecated.output b/tests/bits/parameter_handler_4a_with_alias_deprecated.output new file mode 100644 index 0000000000..19a83f190f --- /dev/null +++ b/tests/bits/parameter_handler_4a_with_alias_deprecated.output @@ -0,0 +1,127 @@ + +\subsection{Global parameters} +\label{parameters:global} + + + +\subsection{Parameters in section \tt Testing} +\label{parameters:Testing} + +\begin{itemize} +\item {\it Parameter name:} {\tt double} +\phantomsection\label{parameters:Testing/double} + + +\index[prmindex]{double} +\index[prmindexfull]{Testing!double} +{\it Value:} 3.1415926 + + +{\it Default:} 3.1415926 + + +{\it Description:} docs 3 + + +{\it Possible values:} [Double -1.79769e+308...1.79769e+308 (inclusive)] +\item {\it Parameter name:} {\tt double_alias} +\phantomsection\label{parameters:Testing/double_alias} + + +\index[prmindex]{double_alias} +\index[prmindexfull]{Testing!double_alias} +This parameter is an alias for the parameter ``\texttt{double}''. Its use is deprecated. + + +\item {\it Parameter name:} {\tt int} +\phantomsection\label{parameters:Testing/int} + + +\index[prmindex]{int} +\index[prmindexfull]{Testing!int} +{\it Value:} 3 + + +{\it Default:} 1 + + +{\it Possible values:} [Integer range -2147483648...2147483647 (inclusive)] +\item {\it Parameter name:} {\tt int_alias} +\phantomsection\label{parameters:Testing/int_alias} + + +\index[prmindex]{int_alias} +\index[prmindexfull]{Testing!int_alias} +This parameter is an alias for the parameter ``\texttt{int}''. + + +\item {\it Parameter name:} {\tt string list} +\phantomsection\label{parameters:Testing/string list} + + +\index[prmindex]{string list} +\index[prmindexfull]{Testing!string list} +{\it Value:} a, b, c + + +{\it Default:} a + + +{\it Description:} docs 1 + + +{\it Possible values:} [List list of <[Selection a|b|c|d|e|f|g|h ]> of length 0...4294967295 (inclusive)] +\end{itemize} + + + +\subsection{Parameters in section \tt Testing/Testing 2} +\label{parameters:Testing/Testing_202} + +\begin{itemize} +\item {\it Parameter name:} {\tt double 2} +\phantomsection\label{parameters:Testing/Testing 2/double 2} + + +\index[prmindex]{double 2} +\index[prmindexfull]{Testing!Testing 2!double 2} +{\it Value:} 3.1415926 + + +{\it Default:} 3.1415926 + + +{\it Description:} docs 3 + + +{\it Possible values:} [Double -1.79769e+308...1.79769e+308 (inclusive)] +\item {\it Parameter name:} {\tt int 2} +\phantomsection\label{parameters:Testing/Testing 2/int 2} + + +\index[prmindex]{int 2} +\index[prmindexfull]{Testing!Testing 2!int 2} +{\it Value:} 1 + + +{\it Default:} 1 + + +{\it Possible values:} [Integer range -2147483648...2147483647 (inclusive)] +\item {\it Parameter name:} {\tt string list 2} +\phantomsection\label{parameters:Testing/Testing 2/string list 2} + + +\index[prmindex]{string list 2} +\index[prmindexfull]{Testing!Testing 2!string list 2} +{\it Value:} a + + +{\it Default:} a + + +{\it Description:} docs 1 + + +{\it Possible values:} [List list of <[Selection a|b|c|d|e|f|g|h ]> of length 0...4294967295 (inclusive)] +\end{itemize}