Teuchos_YamlParser_decl.hpp File Reference

Functions to convert between ParameterList and YAML. More...

#include "Teuchos_ParameterList.hpp"
#include "Teuchos_ParameterEntry.hpp"
#include "Teuchos_RCP.hpp"
#include "Teuchos_PtrDecl.hpp"
#include "Teuchos_FileInputSource.hpp"
#include <iostream>
#include <string>

Include dependency graph for Teuchos_YamlParser_decl.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Namespaces
	Teuchos
	Teuchos::YAMLParameterList

Typedefs
typedef Teuchos::ParameterList::ConstIterator	Teuchos::YAMLParameterList::PLIter

Functions
std::string	Teuchos::convertXmlToYaml (const std::string &xmlFileName)
void	Teuchos::convertXmlToYaml (const std::string &xmlFileName, const std::string &yamlFileName)
void	Teuchos::convertXmlToYaml (std::istream &xmlStream, std::ostream &yamlStream)
Teuchos::RCP < Teuchos::ParameterList >	Teuchos::YAMLParameterList::parseYamlText (const std::string &text, const std::string &name)
Teuchos::RCP < Teuchos::ParameterList >	Teuchos::YAMLParameterList::parseYamlFile (const std::string &yamlFile)
Teuchos::RCP < Teuchos::ParameterList >	Teuchos::YAMLParameterList::parseYamlStream (std::istream &yaml)
void	Teuchos::YAMLParameterList::writeYamlStream (std::ostream &yaml, const Teuchos::ParameterList &pl)
void	Teuchos::YAMLParameterList::writeYamlFile (const std::string &yamlFile, const Teuchos::ParameterList &pl)
void	Teuchos::YAMLParameterList::writeParameterList (const Teuchos::ParameterList &pl, std::ostream &yaml, int indentLevel)
void	Teuchos::YAMLParameterList::writeParameter (const std::string &paramName, const Teuchos::ParameterEntry &entry, std::ostream &yaml, int indentLevel)
void	Teuchos::YAMLParameterList::generalWriteString (const std::string &str, std::ostream &yaml)
void	Teuchos::YAMLParameterList::generalWriteDouble (double d, std::ostream &yaml)
bool	Teuchos::YAMLParameterList::stringNeedsQuotes (const std::string &s)

Detailed Description

Functions to convert between ParameterList and YAML.

YAML is a human-readable data serialization format. In addition to supporting the yaml-cpp TPL, Teuchos provides an in-house YAML parameter list interpreter. It produces Teuchos::ParameterList objects equivalent to those produced by the Teuchos XML helper functions.

Here is a simple example XML parameter list:

<ParameterList>
  <ParameterList Input>
    <Parameter name="values" type="Array(double)" value="{54.3 -4.5 2.0}"/>
    <Parameter name="myfunc" type="string" value="
def func(a, b):
  return a * 2 - b"/>
  </ParameterList>
  <ParameterList Solver>
    <Parameter name="iterations" type="int" value="5"/>
    <Parameter name="tolerance" type="double" value="1e-7"/>
    <Parameter name="do output" type="bool" value="true"/>
    <Parameter name="output file" type="string" value="output.txt"/>
  </ParameterList>
</ParameterList>

Here is an equivalent YAML parameter list:

%YAML 1.1
---
ANONYMOUS:
  Input:
    values: [54.3, -4.5, 2.0]
    myfunc: |-

      def func(a, b):
        return a * 2 - b
  Solver:
    iterations: 5
    tolerance: 1e-7
    do output: yes
    output file: output.txt
...

The nested structure and key-value pairs of these two lists are identical. To a program querying them for settings, they are indistinguishable.

These are the general rules for creating a YAML parameter list:

1. First line must be &#37YAML 1.1, second must be —, and last must be ...
2. Nested map structure is determined by indentation. SPACES ONLY, NO TABS!
3. As with the above example, for a top-level anonymous parameter list, ANONYMOUS: must be explicit
4. Type is inferred. 5 is an int, 5.0 is a double, and '5.0' is a string
5. Quotation marks (single or double) are optional for strings, but required for strings with special characters: :{}[],&*#?|<>=!%\.
6. Quotation marks also turn non-string types into strings: '3' is a string
7. As with XML parameter lists, keys are regular strings
8. Even though YAML supports several names for bool true/false, only true and false are supported by the parameter list reader.
9. Arrays of int, double and string supported. exampleArray: [hello, world, goodbye]
10. [3, 4, 5] is an int array, [3, 4, 5.0] is a double array, and [3, '4', 5.0] is a string array
11. For multi-line strings, place | after the key: and then indent the string one level deeper than the key
12. To preserve indentation in a multiline string, place |2 after the key: and then indent your string's content by 2 spaces relative to the key.

Note that the |- and empty line after myfunc: in this example remove the trailing newline from the myfunc content and add a newline to the start of it, respectively. This is only done to mimic the fact that the XML value has a newline at the beginning and not the end due to the way it was placed for readability in the XML file. However, a more idiomatic way to include a multi-line string in YAML is:

myfunc: |
  def func(a, b):
    return a * 2 - b

This will create a string with a newline at the end and not the beginning, which is more natural, will print better to other file formats, looks more like the contents of its own file from the perspective of the parser handling it (e.g. the RTCompiler) and looks better in YAML itself.

Definition in file Teuchos_YamlParser_decl.hpp.