* this:
* @code
* <?xml version="1.0" encoding="utf-8"?>
- * <Maximal_20number_20of_20iterations>
- * <value>10</value>
- * <default_value>10</default_value>
- * <documentation>A parameter that describes the maximal number of iterations the CG method is to take before giving up on a matrix.</documentation>
- * <pattern>0</pattern>
- * <pattern_description>[Integer range 1...1000 (inclusive)]</pattern_description>
- * </Maximal_20number_20of_20iterations>
- * <Preconditioner>
- * <Kind><value>SSOR</value>
- * <default_value>SSOR</default_value>
- * <documentation>A string that describes the kind of preconditioner to use.</documentation>
- * <pattern>1</pattern>
- * <pattern_description>SSOR|Jacobi</pattern_description>
- * </Kind>
- * <Relaxation_20factor>
- * <value>1.0</value>
- * <default_value>1.0</default_value>
- * <documentation>The numerical value (between zero and one) for the relaxation factor to use in the preconditioner.</documentation>
- * <pattern>2</pattern>
- * <pattern_description>[Floating point range 0...1 (inclusive)]</pattern_description>
- * </Relaxation_20factor>
- * </Preconditioner>
+ * <ParameterHandler>
+ * <Maximal_20number_20of_20iterations>
+ * <value>10</value>
+ * <default_value>10</default_value>
+ * <documentation>A parameter that describes the maximal number of iterations the CG method is to take before giving up on a matrix.</documentation>
+ * <pattern>0</pattern>
+ * <pattern_description>[Integer range 1...1000 (inclusive)]</pattern_description>
+ * </Maximal_20number_20of_20iterations>
+ * <Preconditioner>
+ * <Kind><value>SSOR</value>
+ * <default_value>SSOR</default_value>
+ * <documentation>A string that describes the kind of preconditioner to use.</documentation>
+ * <pattern>1</pattern>
+ * <pattern_description>SSOR|Jacobi</pattern_description>
+ * </Kind>
+ * <Relaxation_20factor>
+ * <value>1.0</value>
+ * <default_value>1.0</default_value>
+ * <documentation>The numerical value (between zero and one) for the relaxation factor to use in the preconditioner.</documentation>
+ * <pattern>2</pattern>
+ * <pattern_description>[Floating point range 0...1 (inclusive)]</pattern_description>
+ * </Relaxation_20factor>
+ * </Preconditioner>
+ * <ParameterHandler>
* @endcode
* This representation closely resembles the directory/file structure
* discussed above. The only difference is that directory and file
* names are mangled: since they should only contain letters and
* numbers, every character in their names that's not one is replaced
* by an underscore followed by its two-digit hexadecimal representation.
+ * In addition, the entire tree is wrapped into a tag
+ * <code>ParameterHandler</code> to satisfy the XML requirement that there
+ * be only a single top-level construct in each file.
*
*
* @ingroup input
* Write out everything as
* an <a href="http://en.wikipedia.org/wiki/XML>XML</a>
* file.
+ *
+ * See the general
+ * documentation of this
+ * class for an example of
+ * output.
*/
XML = 4,
// if necessary create subsection
if (!entries->get_child_optional (get_current_full_path(subsection)))
entries->add_child (get_current_full_path(subsection),
- boost::property_tree::ptree());
+ boost::property_tree::ptree());
// then enter it
subsection_path.push_back (subsection);
switch (style)
{
case XML:
- // call the writer
- // function and exit as
- // there is nothing
- // further to do down in
- // this function
- write_xml (out, *entries);
- return out;
+ {
+ // call the writer
+ // function and exit as
+ // there is nothing
+ // further to do down in
+ // this function
+ //
+ // XML has a requirement that
+ // there can only be one
+ // single top-level entry,
+ // but we may have multiple
+ // entries and sections. we
+ // work around this by
+ // creating a tree just for
+ // this purpose with the
+ // single top-level node
+ // "ParameterHandler" and
+ // assign the existing tree
+ // under it
+ boost::property_tree::ptree single_node_tree;
+ single_node_tree.add_child("ParameterHandler",
+ *entries);
+
+ write_xml (out, single_node_tree);
+ return out;
+ }
+
case JSON:
// call the writer
<?xml version="1.0" encoding="utf-8"?>
-<int1><value>1</value><default_value>1</default_value><documentation>doc 1</documentation><pattern>0</pattern><pattern_description>[Integer range -2147483648...2147483647 (inclusive)]</pattern_description></int1><int2><value>2</value><default_value>2</default_value><documentation>doc 2</documentation><pattern>1</pattern><pattern_description>[Integer range -2147483648...2147483647 (inclusive)]</pattern_description></int2><ss1><double_201><value>1.234</value><default_value>1.234</default_value><documentation>doc 3</documentation><pattern>2</pattern><pattern_description>[Floating point range -1.79769e+308...1.79769e+308 (inclusive)]</pattern_description></double_201><ss2><double_202><value>4.321</value><default_value>4.321</default_value><documentation>doc 4</documentation><pattern>3</pattern><pattern_description>[Floating point range -1.79769e+308...1.79769e+308 (inclusive)]</pattern_description></double_202></ss2></ss1><Testing_25testing><string_26list><value>< & > ; /</value><default_value>< & > ; /</default_value><documentation>docs 1</documentation><pattern>4</pattern><pattern_description>[Anything]</pattern_description></string_26list><int_2aint><value>2</value><default_value>2</default_value><documentation/>
-<pattern>5</pattern><pattern_description>[Integer range -2147483648...2147483647 (inclusive)]</pattern_description></int_2aint><double_2bdouble><value>6.1415926</value><default_value>6.1415926</default_value><documentation>docs 3</documentation><pattern>6</pattern><pattern_description>[Floating point range -1.79769e+308...1.79769e+308 (inclusive)]</pattern_description></double_2bdouble></Testing_25testing>
+<ParameterHandler><int1><value>1</value><default_value>1</default_value><documentation>doc 1</documentation><pattern>0</pattern><pattern_description>[Integer range -2147483648...2147483647 (inclusive)]</pattern_description></int1><int2><value>2</value><default_value>2</default_value><documentation>doc 2</documentation><pattern>1</pattern><pattern_description>[Integer range -2147483648...2147483647 (inclusive)]</pattern_description></int2><ss1><double_201><value>1.234</value><default_value>1.234</default_value><documentation>doc 3</documentation><pattern>2</pattern><pattern_description>[Floating point range -1.79769e+308...1.79769e+308 (inclusive)]</pattern_description></double_201><ss2><double_202><value>4.321</value><default_value>4.321</default_value><documentation>doc 4</documentation><pattern>3</pattern><pattern_description>[Floating point range -1.79769e+308...1.79769e+308 (inclusive)]</pattern_description></double_202></ss2></ss1><Testing_25testing><string_26list><value>< & > ; /</value><default_value>< & > ; /</default_value><documentation>docs 1</documentation><pattern>4</pattern><pattern_description>[Anything]</pattern_description></string_26list><int_2aint><value>2</value><default_value>2</default_value><documentation/>
+<pattern>5</pattern><pattern_description>[Integer range -2147483648...2147483647 (inclusive)]</pattern_description></int_2aint><double_2bdouble><value>6.1415926</value><default_value>6.1415926</default_value><documentation>docs 3</documentation><pattern>6</pattern><pattern_description>[Floating point range -1.79769e+308...1.79769e+308 (inclusive)]</pattern_description></double_2bdouble></Testing_25testing></ParameterHandler>