From b2618a32147044d2d12c169442edf2071e687679 Mon Sep 17 00:00:00 2001 From: wolf Date: Mon, 12 Sep 2005 00:44:49 +0000 Subject: [PATCH] Finish intro. git-svn-id: https://svn.dealii.org/trunk@11401 0785d39b-7218-0410-832d-ea1e28bc413d --- .../step-19.data/intro.html | 74 ++++++++++++++++++- 1 file changed, 73 insertions(+), 1 deletion(-) diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-19.data/intro.html b/deal.II/doc/tutorial/chapter-2.step-by-step/step-19.data/intro.html index d343cd41c5..bb0e891cb2 100644 --- a/deal.II/doc/tutorial/chapter-2.step-by-step/step-19.data/intro.html +++ b/deal.II/doc/tutorial/chapter-2.step-by-step/step-19.data/intro.html @@ -48,4 +48,76 @@ program can then get their values back from this class.

-what these three steps do... +In order to perform these three steps, the ParameterHandler offers +three sets of functions: first, the +ParameterHandler::declare_entry function is used to declare the +existence of a named parameter in the present section of the input file (one +can enter and leave subsections in a parameter file just like you would +navigate through a directory tree in a file system, with the functions +ParameterHandler::enter_subsection and +ParameterHandler::leave_subsection taking on the roles of the +commands cd dir and cd ..; the only difference being +that if you enter a subsection that has never been visited before, it is +created: it isn't necessary to "create" subsections explicitly). When declaring +a parameter, one has to specify its name and default value, in case the +parameter isn't later listed explicitly in the parameter file. In addition to +that, there are optional arguments indicating a pattern that a parameter has to +satisfy, such as being an integer (see the discussion above), and a help text +that might later give an explanation of what the parameter stands for. +

+ +

+Once all parameters have been declared, parameters can be read, using the +ParameterHandler::read_input family of functions. There are +versions of this function that can read from a file stream, that take a file +name, or that simply take a string and parse it. When reading parameters, the +class makes sure that only parameters are listed in the input that have been +declared before, and that the values of parameters satisfy the pattern that has +been given to describe the kind of values a parameter can have. Input that uses +undeclared parameters or values for parameters that do not conform to the +pattern are rejected by raising an exception. +

+ +

+A typical input file will look like this: + +

+set Output format  = dx
+set Output file    = my_output_file.dx
+
+set Maximal number of iterations = 13
+
+subsection Application
+  set Color of output = blue
+  set Generate output = false
+end
+
+ +Note that subsections can be nested. +

+ +

+Finally, the application program can get the values of declared parameters back +by traversing the subsections of the parameter tree and using the +ParameterHandler::get and related functions. The +ParameterHandler::get simply returns the value of a parameter as a +string, whereas ParameterHandler::get_integer, +ParameterHandler::get_double, and +ParameterHandler::get_bool already convert them to the indicated +type. +

+ +

+Using the ParameterHandler class therefore provides for a pretty +flexible mechanism to handle all sorts of moderately complex input files without +much effort on the side of the application programmer. We will use this to +provide all sorts of options to the step-19 program in order to convert from +intermediate file format to any other graphical file format. +

+ +

+The rest of the story is probably best told by looking at the source of step-19 +itself. Let us, however, end this introduction by pointing the reader at the +extensive class documentation of the ParameterHandler class for +more information on specific details of that class. +

-- 2.39.5