Tesseract 0.28.4
Loading...
Searching...
No Matches
tesseract::common::PropertyTree Class Reference

Represents a node in a hierarchical property tree. More...

#include <property_tree.h>

Public Types

using ValidatorFn
 Signature for custom validator callbacks.

Public Member Functions

 PropertyTree ()=default
 Default constructor. Creates an empty tree node.
 PropertyTree (const PropertyTree &other)
 Deep-copy constructor – clones all YAML::Nodes and subtrees.
PropertyTree & operator= (const PropertyTree &other)
 Deep-copy assignment operator.
 PropertyTree (PropertyTree &&) noexcept=default
 Default move constructor/assignment are fine.
PropertyTree & operator= (PropertyTree &&) noexcept=default
std::vector< std::string > applyConfig (const YAML::Node &config, bool allow_extra_properties=false)
 Apply a YAML configuration to this schema, populate defaults, and validate the result.
std::vector< std::string > validate (bool allow_extra_properties=false) const
 Validate the tree, collecting all errors.
void addValidator (ValidatorFn fn)
 Register a custom validator for this node.
PropertyTree & operator[] (std::string_view key)
 Access or create a child node by key.
PropertyTree & at (std::string_view key)
 Access a child node by key.
const PropertyTree & at (std::string_view key) const
 Access a child node by key (const).
const PropertyTree * find (std::string_view key) const
 Find a child node without creating it.
PropertyTree * find (std::string_view key)
 Find a child node without creating it (mutable).
void setValue (const YAML::Node &v)
 Set the YAML value of this node.
const YAML::Node & getValue () const
 Retrieve the YAML value stored at this node.
template<typename T>
T as () const
 Retrieve the YAML value casted to the provided type.
bool isNull () const
 Check if property value is null.
bool isContainer () const
 Check if property is a container of child properties.
std::vector< std::string > keys () const
 List all immediate child keys.
void setAttribute (std::string_view name, const YAML::Node &attr)
 Set a metadata attribute (YAML node form).
void setAttribute (std::string_view name, std::string_view attr)
 Convenience overload to set a string attribute.
void setAttribute (std::string_view name, const char *attr)
void setAttribute (std::string_view name, bool attr)
 Set a boolean attribute.
void setAttribute (std::string_view name, int attr)
 Set an integer attribute.
void setAttribute (std::string_view name, double attr)
 Set a double attribute.
void setAttribute (std::string_view name, const std::vector< std::string > &attr)
 Set a vector of strings attribute.
bool hasAttribute (std::string_view name) const
 Check if an attribute exists and is not null.
std::optional< YAML::Node > getAttribute (std::string_view name) const
 Retrieve an attribute value by name.
std::vector< std::string > getAttributeKeys () const
 List all metadata attribute keys.
bool isRequired () const
 Check if property is requried by checking for attribute and its value.
YAML::Node toYAML (bool exclude_attributes=true) const
 Serialize this tree back into a YAML::Node.
 operator bool () const noexcept
 Indicate if defined, meaning it has children or a value.
std::size_t size () const
 Return number of immediate children.
bool empty () const
 Check if this node has no children.

Static Public Member Functions

static PropertyTree fromYAML (const YAML::Node &node)
 Create a PropertyTree from a YAML::Node.

Friends

std::ostream & operator<< (std::ostream &os, const PropertyTree &tree)
 Stream output – serializes toYAML() to the stream.
void validateCustomType (const PropertyTree &node, const std::string &path, std::vector< std::string > &errors)
 Validator: Retrieve schema for the custom type and run its validators.

Detailed Description

Represents a node in a hierarchical property tree.

Each PropertyTree node may contain:

  • A YAML::Node value (scalar, sequence, or map)
  • A map of metadata attributes (YAML::Node) keyed by string
  • Nested child PropertyTree nodes
  • A list of custom validator functions

Member Typedef Documentation

◆ ValidatorFn

Initial value:
std::function<void(const PropertyTree& node, const std::string& path, std::vector<std::string>& errors)>
PropertyTree()=default
Default constructor. Creates an empty tree node.

Signature for custom validator callbacks.

Parameters
nodeThe PropertyTree node being validated.
pathDot-separated path to this node (for error messages).
errorsOutput vector to append error messages to.

Member Function Documentation

◆ applyConfig()

std::vector< std::string > tesseract::common::PropertyTree::applyConfig ( const YAML::Node & config,
bool allow_extra_properties = false )
nodiscard

Apply a YAML configuration to this schema, populate defaults, and validate the result.

Parameters
configThe user-supplied YAML::Node (possibly null).
allow_extra_propertiesIf false, undeclared keys are reported.
Returns
All independently discoverable configuration diagnostics.
Warning
Do not consume typed values from this tree unless the returned vector is empty.

◆ validate()

std::vector< std::string > tesseract::common::PropertyTree::validate ( bool allow_extra_properties = false) const
nodiscard

Validate the tree, collecting all errors.

Recursively invokes all validators on this node and its children, collecting every error rather than stopping at the first one.

Parameters
allow_extra_propertiesIndicate if extra properties are allowed.
Returns
Vector of error strings (empty on success). Each entry includes the dot-separated path to the offending node.

◆ addValidator()

void tesseract::common::PropertyTree::addValidator ( ValidatorFn fn)

Register a custom validator for this node.

Parameters
fnCallback to invoke during validation.

◆ operator[]()

PropertyTree & tesseract::common::PropertyTree::operator[] ( std::string_view key)

Access or create a child node by key.

Parameters
keyChild identifier (string key).
Returns
Reference to the child PropertyTree.

◆ at() [1/2]

PropertyTree & tesseract::common::PropertyTree::at ( std::string_view key)

Access a child node by key.

Parameters
keyChild identifier.
Returns
Reference to the child.
Exceptions
std::out_of_rangeif key not found.

◆ at() [2/2]

const PropertyTree & tesseract::common::PropertyTree::at ( std::string_view key) const

Access a child node by key (const).

Parameters
keyChild identifier.
Returns
Const reference to the child.
Exceptions
std::out_of_rangeif key not found.

◆ find() [1/2]

const PropertyTree * tesseract::common::PropertyTree::find ( std::string_view key) const

Find a child node without creating it.

Parameters
keyChild identifier.
Returns
Pointer to child or nullptr if not present.

◆ find() [2/2]

PropertyTree * tesseract::common::PropertyTree::find ( std::string_view key)

Find a child node without creating it (mutable).

Parameters
keyChild identifier.
Returns
Pointer to child or nullptr if not present.

◆ setValue()

void tesseract::common::PropertyTree::setValue ( const YAML::Node & v)

Set the YAML value of this node.

Parameters
vYAML::Node representing the new value.

◆ getValue()

const YAML::Node & tesseract::common::PropertyTree::getValue ( ) const

Retrieve the YAML value stored at this node.

Returns
Const reference to a YAML::Node.

◆ as()

template<typename T>
T tesseract::common::PropertyTree::as ( ) const
inline

Retrieve the YAML value casted to the provided type.

Returns
The casted value

◆ isNull()

bool tesseract::common::PropertyTree::isNull ( ) const

Check if property value is null.

Returns
True if required, otherwise false

◆ isContainer()

bool tesseract::common::PropertyTree::isContainer ( ) const

Check if property is a container of child properties.

Returns
True if container, otherwise false

◆ keys()

std::vector< std::string > tesseract::common::PropertyTree::keys ( ) const

List all immediate child keys.

Returns
Vector of child key strings.

◆ setAttribute()

void tesseract::common::PropertyTree::setAttribute ( std::string_view name,
const YAML::Node & attr )

Set a metadata attribute (YAML node form).

Parameters
nameAttribute name.
attrYAML::Node value.

◆ hasAttribute()

bool tesseract::common::PropertyTree::hasAttribute ( std::string_view name) const

Check if an attribute exists and is not null.

Parameters
nameAttribute name.
Returns
True if present and non-null, false otherwise.

◆ getAttribute()

std::optional< YAML::Node > tesseract::common::PropertyTree::getAttribute ( std::string_view name) const

Retrieve an attribute value by name.

Parameters
nameAttribute name.
Returns
Optional containing YAML::Node if found.

◆ getAttributeKeys()

std::vector< std::string > tesseract::common::PropertyTree::getAttributeKeys ( ) const

List all metadata attribute keys.

Returns
Vector of attribute names.

◆ isRequired()

bool tesseract::common::PropertyTree::isRequired ( ) const

Check if property is requried by checking for attribute and its value.

Returns
True if required, otherwise false

◆ fromYAML()

PropertyTree tesseract::common::PropertyTree::fromYAML ( const YAML::Node & node)
static

Create a PropertyTree from a YAML::Node.

Parameters
nodeRoot YAML::Node to convert.
Returns
Populated PropertyTree hierarchy.

◆ toYAML()

YAML::Node tesseract::common::PropertyTree::toYAML ( bool exclude_attributes = true) const

Serialize this tree back into a YAML::Node.

Parameters
exclude_attributesIf true, omit the attributes map.
Returns
YAML::Node representation of the tree.

◆ size()

std::size_t tesseract::common::PropertyTree::size ( ) const

Return number of immediate children.

Returns
Child count.

◆ empty()

bool tesseract::common::PropertyTree::empty ( ) const

Check if this node has no children.

Returns
True if no children.

◆ validateCustomType

void validateCustomType ( const PropertyTree & node,
const std::string & path,
std::vector< std::string > & errors )
friend

Validator: Retrieve schema for the custom type and run its validators.

Parameters
nodeNode to validate.
pathDot-separated path for error messages.
errorsOutput vector to append errors to.