yaml_utils.h File Reference

YAML Type conversions. More...

#include <string>
#include <set>
#include <filesystem>

Functions
void	tesseract::common::processYamlIncludeDirective (YAML::Node &node, const ResourceLocator &locator)
	Recursively expands !include directives in a YAML node, in-place.
YAML::Node	tesseract::common::loadYamlFile (const std::string &file_path, const ResourceLocator &locator)
	Loads a YAML file and processes !include directives recursively.
YAML::Node	tesseract::common::loadYamlString (const std::string &yaml_string, const ResourceLocator &locator)
void	tesseract::common::writeYamlToFile (const YAML::Node &node, const std::string &file_path)
	Writes a YAML::Node to a file.
void	tesseract::common::checkForUnknownKeys (const YAML::Node &node, const std::set< std::string > &expected_keys)
	Check node map for unknown keys.
std::string	tesseract::common::toYAMLString (const YAML::Node &node)
	Converts a YAML::Node to a yaml string.
YAML::Node	tesseract::common::fromYAMLString (const std::string &string)
	Converts yaml string to a YAML::Node.
bool	tesseract::common::compareYAML (const YAML::Node &node1, const YAML::Node &node2)
	Checks if the YAML::Nodes are identical.

Detailed Description

YAML Type conversions.

Author

Levi Armstrong

Date

September 5, 2021

Copyright

Copyright (c) 2021, Southwest Research Institute

License

Software License Agreement (Apache License)

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Function Documentation

processYamlIncludeDirective()

void tesseract::common::processYamlIncludeDirective	(	YAML::Node &	node,
		const ResourceLocator &	locator
	)

Recursively expands !include directives in a YAML node, in-place.

This function walks the given node and:

• When it encounters a node tagged !include, it loads the referenced file (via the provided ResourceLocator), replaces the tagged node with the parsed content of that file, clears the !include tag, and then continues processing the newly loaded subtree.
• When it encounters a mapping, it recurses into each value in-place.
• When it encounters a sequence, it recurses into each element in-place.

After this call returns, node and its entire subtree will have had all !include directives resolved and removed. Subsequent calls on the same expanded tree are no-ops.

Parameters

node	The YAML node to process. Must be non-const so it can be mutated in-place as includes are expanded.
locator	The locator used to resolve file paths or URLs for !include directives. May maintain internal state (e.g. cache) between calls.

Exceptions

std::runtime_error

if an !include tag is not a scalar string, or if the specified file cannot be located or loaded.

loadYamlFile()

YAML::Node tesseract::common::loadYamlFile	(	const std::string &	file_path,
		const ResourceLocator &	locator
	)

Loads a YAML file and processes !include directives recursively.

This function loads a YAML file and replaces any node tagged with !include with the content of the specified file. It handles nested !include directives and works with both maps and sequences.

Parameters

file_path	The path to the YAML file/url to be loaded.
locator	The locator used to resolve urls and relative file paths.

Returns

A YAML::Node object containing the fully processed YAML structure.

Exceptions

std::runtime_error

if an !include tag is used improperly (e.g., not scalar), or if a file specified in an !include directive cannot be loaded.

writeYamlToFile()

void tesseract::common::writeYamlToFile	(	const YAML::Node &	node,
		const std::string &	file_path
	)

Writes a YAML::Node to a file.

Parameters

node	The YAML::Node to write.
file_path	The path to the output file.

Exceptions

std::runtime_error

if the file cannot be opened.

checkForUnknownKeys()

void tesseract::common::checkForUnknownKeys	(	const YAML::Node &	node,
		const std::set< std::string > &	expected_keys
	)

Check node map for unknown keys.

Parameters

node	The node to check
expected_keys	The expected keys

toYAMLString()

std::string tesseract::common::toYAMLString

(

const YAML::Node &

node

)

Converts a YAML::Node to a yaml string.

Parameters

node	Input node

Returns

String containing the yaml

fromYAMLString()

YAML::Node tesseract::common::fromYAMLString

(

const std::string &

string

)

Converts yaml string to a YAML::Node.

Parameters

string

Input string containing the yaml

Returns

Resulting YAML::Node

compareYAML()

bool tesseract::common::compareYAML	(	const YAML::Node &	node1,
		const YAML::Node &	node2
	)

Checks if the YAML::Nodes are identical.

The == operator checks if they reference the same memory. This checks if they contain the same information

Parameters

node1	Input YAML::Node
node2	Input YAML::Node