]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Create a way to mark aliases for deprecation. 680/head
authorWolfgang Bangerth <bangerth@math.tamu.edu>
Mon, 23 Mar 2015 02:00:32 +0000 (21:00 -0500)
committerWolfgang Bangerth <bangerth@math.tamu.edu>
Tue, 24 Mar 2015 12:33:31 +0000 (07:33 -0500)
include/deal.II/base/parameter_handler.h
source/base/parameter_handler.cc
tests/bits/parameter_handler_4a_with_alias_deprecated.cc [new file with mode: 0644]
tests/bits/parameter_handler_4a_with_alias_deprecated.output [new file with mode: 0644]

index 50f65328c6d56a4953c2bb1d2f5415d035a75a24..a93832476bf323b660406eaf93d8ec754db235f4 100644 (file)
@@ -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.
index 5f80e2b06f5af8bc54ec871b35682a0c6057e415..6c25ff6057d85a4b6229c1ad2c06326a262b2322 100644 (file)
@@ -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<std::string>(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<std::string>("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<std::string>(path + path_separator + "alias"))
-        path = get_current_full_path(entries->get<std::string>(path + path_separator + "alias"));
+        {
+          if (entries->get<std::string>(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<std::string>(path + path_separator + "alias")
+                        << ">." << std::endl;
+            }
+          path = get_current_full_path(entries->get<std::string>(path + path_separator + "alias"));
+        }
 
-      // assert that the entry is indeed
-      // declared
+      // assert that the entry is indeed declared
       if (entries->get_optional<std::string> (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 (file)
index 0000000..7e120cd
--- /dev/null
@@ -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 <deal.II/base/logstream.h>
+#include <deal.II/base/parameter_handler.h>
+#include <fstream>
+#include <iomanip>
+
+
+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 (file)
index 0000000..19a83f1
--- /dev/null
@@ -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}

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.