YAML

YAML#

We use yaml-cpp to provide import/export from/to YAML. The code in navground/yaml specializes templates of struct YAML::convert, which is how yaml-cpp is extended to custom classes.

You can therefore use yaml-cpp APIs, which allows to

  • parse a YAML string:

    #include "yaml-cpp/yaml.h"

YAML::Node node = YAML::Load("...");

  • convert a YAML::Node to a C++ object:

    T object = node.as<T>();

  • convert a C++ object to a YAML::Node

    T object;
YAML::Node node(object);

  • emit YAML from a YAML::Node:

    #include "yaml-cpp/yaml.h"

YAML::Node node;
YAML::Emitter out;
out << node;
const char * yaml = out.c_str();

In particular, we specialize the conversion from/to the following classes:

For classes T with a register, the conversion from and to std::shared_ptr<T> write/reads the type name and all the registered properties. For example, when you convert from a YAML::node corresponding to

type: MySubClass
my_property: false

to a T object, navground::core::HasRegister::make_type() is called. If successful, it then reads all properties from the YAML fields, calling navground::core::HasProperties::set() for any MySubClass registered property.

auto obj = node.as<std::shared_ptr<T>>();

will call:

  • auto obj = make_type("MySubClass");

  • obj.set("my_property", false);

in addition to setup the common fields of T.

Moreover, we expose templated functions that returns the JSON Schema for the types listed above, which are also used to document the YAML representations in YAML Schemas.

Public API#

#include "navground/core/yaml/yaml.h"
namespace YAML#
template<typename T>
inline std::shared_ptr<T> YAML::load_node(const Node &node)#

Load an object from a YAML node.

Parameters:

node – [in] The YAML node

Template Parameters:

T – The type of the object

Returns:

A shared pointer with the loaded object or nullptr if loading fails.

template<typename T>
inline std::shared_ptr<T> YAML::load_string(const std::string &value)#

Load an object from a YAML string.

Parameters:

value – [in] The YAML string

Template Parameters:

T – The type of the object

Returns:

A shared pointer with the loaded object or nullptr if loading fails.

template<typename T>
std::string YAML::dump(const T *object)#

Dump an object to a YAML-string.

Parameters:

object – [in] The object

Template Parameters:

T – The type of the object

Returns:

The YAML string (empty if the pointer is null)

Schema#

Partial schema#

#include "navground/core/yaml/schema.h"
template<typename T>
Node YAML::schema::schema()#

Returns the json-schema for a C++ type.

Template Parameters:

T – The type

Returns:

A json-schema encoded as a YAML::Node.

template<typename T>
Node YAML::schema::schema(bool reference_register_schema, const std::optional<std::string> &type = std::nullopt)#

Returns the json-schema of a component.

Parameters:

  • reference_register_schema – [in] Whether to reference registered components schema in the base class schema.

  • type – [in] An optional registered type. If not specified, it returns the schema of the base class.

Template Parameters:

T – The component type (should be a sub-class of navground::core::HasRegister<T>)

Returns:

A json-schema encoded as a YAML::Node.

template<typename T>
Node YAML::schema::register_schema()#

Returns the json-schema that includes registered components.

Template Parameters:

T – The component type (should be a sub-class of navground::core::HasRegister<T>)

Returns:

“anyOf” json-schema of all registered components encoded as a YAML::Node.

Bundle#

#include "navground/sim/yaml/schema_core.h"
inline YAML::Node navground::core::bundle_schema()#

Returns the bundle json-schema for navground::core.

Returns:

A json-schema encoded as a YAML::Node.

Contents