mola-yaml: YAML parsing helper functions

Overview

// structs

struct mola::YAMLParseOptions;

// global functions

std::string mola::parse_yaml(const std::string& text, const YAMLParseOptions& opts = YAMLParseOptions());
mrpt::containers::yaml mola::parse_yaml(const mrpt::containers::yaml& input, const YAMLParseOptions& opts = YAMLParseOptions());
mrpt::containers::yaml mola::load_yaml_file(const std::string& fileName, const YAMLParseOptions& opts = YAMLParseOptions());
std::string mola::yaml_to_string(const mrpt::containers::yaml& cfg);

// macros

#define ENSURE_YAML_ENTRY_EXISTS( \
    _c, \
    _name \
    )

#define YAML_LOAD_MEMBER_OPT( \
    _varname, \
    _type \
    )

#define YAML_LOAD_MEMBER_REQ( \
    _varname, \
    _type \
    )

#define YAML_LOAD_OPT(...)

#define YAML_LOAD_OPT2( \
    _varname, \
    _type \
    )

#define YAML_LOAD_OPT3( \
    _param_str, \
    _varname, \
    _type \
    )

#define YAML_LOAD_OPT_DEG(...)

#define YAML_LOAD_OPT_DEG2( \
    _varname, \
    _type \
    )

#define YAML_LOAD_OPT_DEG3( \
    _param_str, \
    _varname, \
    _type \
    )

#define YAML_LOAD_REQ(...)

#define YAML_LOAD_REQ2( \
    _varname, \
    _type \
    )

#define YAML_LOAD_REQ3( \
    _param_str, \
    _varname, \
    _type \
    )

#define YAML_LOAD_REQ_DEG(...)

#define YAML_LOAD_REQ_DEG2( \
    _varname, \
    _type \
    )

#define YAML_LOAD_REQ_DEG3( \
    _param_str, \
    _varname, \
    _type \
    )

Global Functions

std::string mola::parse_yaml(const std::string& text, const YAMLParseOptions& opts = YAMLParseOptions())

Pre-process a raw YAML string, expanding $include{}, $(), and ${} expressions according to opts.

The three substitution passes are always run in the order listed in YAMLParseOptions (includes → command runs → variables), regardless of the order in which the expressions appear in the text. Lines that begin with a YAML comment character (#) are skipped for variable expansion.

Parameters:

text	Raw YAML text to process.
opts	Controls which substitutions are active and supplies custom variables / the include base path.
<tt>std::exception</tt>	if a required variable is undefined, a shell command exits with a non-zero status, or a referenced include file cannot be found.

Returns:

Fully substituted YAML text (still a plain string; call mrpt::containers::yaml::FromText() to parse it).

mrpt::containers::yaml mola::parse_yaml(
    const mrpt::containers::yaml& input,
    const YAMLParseOptions& opts = YAMLParseOptions()
    )

Overload that accepts and returns an mrpt::containers::yaml node.

Serializes input to text, runs the same pre-processing as the string overload, then re-parses the result back into a mrpt::containers::yaml node.

Parameters:

input	Source YAML node.
opts	See string overload.

Returns:

New node with all substitutions applied.

mrpt::containers::yaml mola::load_yaml_file(
    const std::string& fileName,
    const YAMLParseOptions& opts = YAMLParseOptions()
    )

Load a YAML file from disk and fully pre-process it.

This is a convenience wrapper equivalent to:

mrpt::containers::yaml::FromFile(fileName)
Setting YAMLParseOptions::includesBasePath to the file’s directory.
parse_yaml(yaml_to_string(raw), opts)
Re-parsing the result with mrpt::containers::yaml::FromText().

Parameters:

fileName	Path to the YAML file to load.
opts	Additional parse options merged with the auto-detected `includesBasePath`.

Returns:

Parsed and fully pre-processed YAML node.

std::string mola::yaml_to_string(const mrpt::containers::yaml& cfg)

Serialize an mrpt::containers::yaml node to a string.

Uses the node’s built-in stream operator. The result can be re-parsed with mrpt::containers::yaml::FromText().

Parameters:

cfg	Node to serialize.

Returns:

YAML text representation.

Macros

#define ENSURE_YAML_ENTRY_EXISTS(_c, _name)

Assert that a required key exists in the YAML node _c.

Throws a descriptive error when the key _name is missing.

Parameters:

_c	`mrpt::containers::yaml` node to check (must support `.has()`).
_name	Key name as a string literal or `std::string`.

#define YAML_LOAD_MEMBER_OPT(_varname, _type)

Optional load into a member variable _varname_.

Use YAML_LOAD_MEMBER_OPT(foo, double) inside a class method to load the YAML key "foo" into the member foo_.

Parameters:

_varname	Base name (YAML key = `#_varname`; member = `_varname##_`).
_type	C++ type for the `getOrDefault` call.

#define YAML_LOAD_MEMBER_REQ(_varname, _type)

Required load into a member variable _varname_.

Throws when the key is absent.

Parameters:

_varname	Base name (YAML key = `#_varname`; member = `_varname##_`).
_type	C++ type for the `getOrDefault` call.

#define YAML_LOAD_OPT(...)

Variadic YAML_LOAD_OPT : 2-arg or 3-arg form selected by count.

YAML_LOAD_OPT(var, Type) → YAML_LOAD_OPT2
YAML_LOAD_OPT(params, var, Type) → YAML_LOAD_OPT3

#define YAML_LOAD_OPT2(_varname, _type)

Optional load: _varname = cfg[_varname] (keeps default when the key is absent).

Parameters:

_varname	Variable name - also used verbatim as the YAML key.
_type	C++ type for the `getOrDefault` call.

#define YAML_LOAD_OPT3(_param_str, _varname, _type)

Optional load: _param_str._varname = cfg[_varname] (or keep the current default when the key is absent).

Parameters:

_param_str	Struct whose field will receive the value.
_varname	Field / YAML key name (used as both identifier and string).
_type	C++ type for the `getOrDefault` call.

#define YAML_LOAD_OPT_DEG(...)

Variadic angle load (optional): 2-arg or 3-arg form selected by count.

#define YAML_LOAD_OPT_DEG2(_varname, _type)

Optional load of an angle: YAML stores degrees, variable holds radians (2-arg form - local variable).

#define YAML_LOAD_OPT_DEG3(_param_str, _varname, _type)

Optional load of an angle into a struct field (3-arg form). YAML stores degrees; _param_str._varname holds radians.

Uses a temporary to avoid leaving _param_str._varname mutated to degrees if the YAML read throws mid-way.

#define YAML_LOAD_REQ(...)

Variadic YAML_LOAD_REQ : 2-arg or 3-arg form selected by count.

YAML_LOAD_REQ(var, Type) → YAML_LOAD_REQ2
YAML_LOAD_REQ(params, var, Type) → YAML_LOAD_REQ3

#define YAML_LOAD_REQ2(_varname, _type)

Required load into a local variable - throws if the key is absent.

Parameters:

_varname	Variable name / YAML key.
_type	C++ type for the `getOrDefault` call.

#define YAML_LOAD_REQ3(_param_str, _varname, _type)

Required load into a struct field - throws if the key is absent.

Parameters:

_param_str	Struct whose field will receive the value.
_varname	Field / YAML key name.
_type	C++ type for the `getOrDefault` call.

#define YAML_LOAD_REQ_DEG(...)

Variadic angle load (required): 2-arg or 3-arg form selected by count.

#define YAML_LOAD_REQ_DEG2(_varname, _type)

Required load of an angle: YAML stores degrees, variable holds radians (2-arg form - local variable). Throws if key is absent.

#define YAML_LOAD_REQ_DEG3(_param_str, _varname, _type)

Required load of an angle into a struct field (3-arg form). YAML stores degrees; _param_str._varname holds radians. Throws if the key is absent.

Uses a temporary so _param_str._varname is never left in degrees if ENSURE_YAML_ENTRY_EXISTS or the YAML read throws.