Handle class for value tree compounds. More...

#include <eagine/value_tree/wrappers.hpp>

Public Types
using	visit_handler = callable_ref< bool(compound &, const attribute &, const basic_string_path &)>
	Type of traverse/visit handler.

using	stack_visit_handler = callable_ref< bool(compound &, const attribute &, const basic_string_path &, span< const attribute >)>
	Type of traverse/visit handler using full attribute stack.

Public Member Functions
	compound () noexcept=default
	Default constructor. Constructs an empty compound.

	operator bool () const noexcept
	Indicates if this compound actually refers to some tree.

auto	type_id () const noexcept -> identifier_t
	Returns the implementation type id of this attribute.

auto	structure () const -> attribute
	Returns the root of attribute hierarchy describing the tree structure. More...

auto	root () const -> compound_attribute
	Returns the structure root as an compound_attribute. More...

auto	attribute_name (const attribute &attrib) const -> string_view
	Returns the name of an attribute. More...

auto	canonical_type (const attribute &attrib) const -> value_type
	Returns the caninical value type of an attribute. More...

auto	is_link (const attribute &attrib) const -> bool
	Indicates if the specified attribute is a reference or link in the tree. More...

auto	nested_count (const attribute &attrib) const -> span_size_t
	Returns the count of nested attributes of an attribute. More...

auto	has_nested (const attribute &attrib) const -> bool
	Indicates if an attribute has nested attribute accessible by index. More...

auto	nested (const attribute &attrib, span_size_t index) const -> attribute
	Returns nested attribute of an attribute at the specified index. More...

auto	nested (const attribute &attrib, string_view name) const -> attribute
	Returns nested attribute of an attribute with the specified name. More...

auto	nested (string_view name) const -> attribute
	Returns nested attribute of the root attribute with the specified name. More...

auto	find (const attribute &attrib, const basic_string_path &path) const -> attribute
	Returns nested attribute of an attribute at the specified path. More...

auto	find (const attribute &attrib, const basic_string_path &path, span< const string_view > tags) const -> attribute
	Returns nested attribute of an attribute at path with tags. More...

auto	find (const basic_string_path &path) const -> attribute
	Returns nested attribute of root attribute at the specified path. More...

auto	find (const basic_string_path &path, span< const string_view > tags) const -> attribute
	Returns nested attribute of root attribute at path with tags. More...

auto	value_count (const attribute &attrib) const -> span_size_t
	Returns the number of value elements accessible through an attribute.

auto	value_count (const basic_string_path &path) const -> span_size_t
	Returns the number of value elements at the specified path.

auto	value_count (string_view name) -> span_size_t
	Returns the number of value elements at attribute with the given name.

template<typename T >
auto	fetch_values (const attribute &attrib, span_size_t offset, span< T > dest) const -> span< T >
	Fetches values at the given attribute, starting at offset into `dest`.

template<typename T >
auto	fetch_values (const basic_string_path &path, span_size_t offset, span< T > dest) const -> span< T >
	Fetches values at the given path, starting at offset into `dest`.

template<typename T >
auto	fetch_values (string_view name, span_size_t offset, span< T > dest) const -> span< T >
	Fetches values at the given name, starting at offset into `dest`.

template<typename T >
auto	fetch_values (const attribute &attrib, span< T > dest) const -> span< T >
	Fetches values at the given attribute, into `dest`.

template<typename T >
auto	fetch_values (const basic_string_path &path, span< T > dest) const -> span< T >
	Fetches values at the attribute with the specified path, into `dest`.

template<typename T >
auto	fetch_values (string_view name, span< T > dest) const -> span< T >
	Fetches values at the attribute with the specified name, into `dest`.

auto	fetch_blob (const attribute &attrib, memory::block dest) const -> memory::block
	Fetches a BLOB at the given attribute, into `dest`.

auto	fetch_blob (const basic_string_path &path, memory::block dest) const -> memory::block
	Fetches a BLOB at the attribute with the specified path, into `dest`.

auto	fetch_blob (string_view name, memory::block dest) const -> memory::block
	Fetches a BLOB at the attribute with the specified name, into `dest`.

template<typename T , identifier_t V>
auto	select_value (const attribute &attrib, span_size_t offset, T &dest, selector< V > sel) const -> bool
	Fetches a single value at the specified attribute, with a selector.

template<typename T >
auto	fetch_value (const attribute &attrib, span_size_t offset, T &dest) const -> bool
	Fetches a single value at the specified attribute, at offset into `dest`.

template<typename T , identifier_t V>
auto	select_values (const attribute &attrib, span_size_t offset, span< T > dest, selector< V > sel) const -> span< T >
	Fetches values at the specified attribute, with a selector, into dest.

template<typename T , identifier_t V>
auto	select_value (string_view name, span_size_t offset, T &dest, selector< V > sel) const -> bool
	Fetches values through the specified name, with a selector, into dest.

template<typename T >
auto	fetch_value (string_view name, span_size_t offset, T &dest) const -> bool
	Fetches values through the specified name, into dest.

template<typename T , identifier_t V>
auto	select_value (const basic_string_path &path, span_size_t offset, T &dest, selector< V > sel) const -> bool
	Fetches values through the specified path, with a selector, into dest.

template<typename T >
auto	fetch_value (const basic_string_path &path, span_size_t offset, T &dest) const -> bool
	Fetches values through the specified path, into dest.

template<typename T , identifier_t V>
auto	select_value (string_view name, T &dest, selector< V > sel) const -> bool
	Fetches values through the specified name, with a selector, into dest.

template<typename T >
auto	fetch_value (string_view name, T &dest) const -> bool
	Fetches values through the specified name, into dest.

template<typename T , identifier_t V>
auto	select_value (const attribute &attrib, T &dest, selector< V > sel) const -> bool
	Fetches a value at the specified attribute, with a selector, into dest.

template<typename T , identifier_t V>
auto	select_values (const attribute &attrib, span< T > dest, selector< V > sel) const -> span< T >
	Fetches values at the specified attribute, with a selector, into dest.

template<typename T >
auto	fetch_value (const attribute &attrib, T &dest) const -> bool
	Fetches a single value at the specified attribute, into dest.

template<typename T , identifier_t V>
auto	select_value (const basic_string_path &path, T &dest, selector< V > sel) const -> bool
	Fetches a value through the specified path, with selector, into dest.

template<typename T >
auto	fetch_value (const basic_string_path &path, T &dest) const -> bool
	Fetches a value through the specified path, into dest.

template<std::size_t L>
auto	has_value (const attribute &attrib, const char(&what)[L]) const -> bool
	Tests if there is an value at an attribute, that starts with `what`.

template<typename T , identifier_t V>
auto	get (const attribute &attrib, span_size_t offset, type_identity< T >, selector< V > sel) const -> optionally_valid< T >
	Returns the value of type T at an attribute, at offset, with selector.

template<typename T >
auto	get (const attribute &attrib, span_size_t offset, type_identity< T > tid={}) const -> optionally_valid< T >
	Returns the value of type T at an attribute, at the given offset.

template<typename T , identifier_t V>
auto	get (const basic_string_path &path, span_size_t offset, type_identity< T >, selector< V > sel) const -> optionally_valid< T >
	Returns the value of type T at path, at given offset, with selector.

template<typename T >
auto	get (const basic_string_path &path, span_size_t offset, type_identity< T > tid={}) const -> optionally_valid< T >
	Returns the value of type T at path, at given offset.

template<typename T , identifier_t V>
auto	get (string_view name, span_size_t offset, type_identity< T >, selector< V > sel) const -> optionally_valid< T >
	Returns the value of type T at name, at given offset, with selector.

template<typename T >
auto	get (string_view name, span_size_t offset, type_identity< T > tid={}) const -> optionally_valid< T >
	Returns the value of type T at name, at given offset.

template<typename T , identifier_t V>
auto	get (const attribute &attrib, type_identity< T > tid, selector< V > sel) const -> optionally_valid< T >
	Returns the value of type T at an attribute, with selector.

template<typename T >
auto	get (const attribute &attrib, type_identity< T > tid={}) const -> optionally_valid< T >
	Returns the value of type T at an attribute.

template<typename T , identifier_t V>
auto	get (const basic_string_path &path, type_identity< T > tid, selector< V > sel) const -> optionally_valid< T >
	Returns the value of type T at path, with selector.

template<typename T >
auto	get (const basic_string_path &path, type_identity< T > tid={}) const -> optionally_valid< T >
	Returns the value of type T at path.

template<typename T , identifier_t V>
auto	get (string_view name, type_identity< T > tid, selector< V > sel) const -> optionally_valid< T >
	Returns the value of type T at name, with selector.

template<typename T >
auto	get (string_view name, type_identity< T > tid={}) const -> optionally_valid< T >
	Returns the value of type T at name.

void	traverse (visit_handler visitor)
	Traverses the tree, calls the `visitor` function on each node.

void	traverse (stack_visit_handler visitor)
	Traverses the tree, calls the `visitor` function on each node.

Static Public Member Functions
template<typename Compound , typename... Args>
static auto	make (Args &&... args) -> std::enable_if_t< std::is_base_of_v< compound_interface, Compound >, compound >
	Instantiates a particular implementation. More...

Detailed Description

Handle class for value tree compounds.

See also: compound; compound_attribute

Compounds own, manage and parse the actual tree data of some structured tree hierarchy (JSON, YAML, XML, filesystem hierarchy, etc.). A compound represents the parsed or "open" instance of such a tree and allows to traverse and explore the tree structure and access the stored data through an unified interface.

Member Function Documentation

◆ attribute_name()

auto eagine::valtree::compound::attribute_name ( const attribute & attrib ) const -> string_view

inline

Returns the name of an attribute.

Precondition: this->type_id() == attrib.type_id().

Referenced by eagine::valtree::compound_attribute::name().

◆ canonical_type()

auto eagine::valtree::compound::canonical_type ( const attribute & attrib ) const -> value_type

inline

Returns the caninical value type of an attribute.

Precondition: this->type_id() == attrib.type_id().

Tree data referred-to by an attribute can be fetched either using the canonical type or using a different, related value type, if the necessary conversion is implemented.

Referenced by eagine::valtree::compound_attribute::canonical_type().

◆ find() [1/4]

auto eagine::valtree::compound::find	(	const attribute &	attrib,
		const basic_string_path &	path
	)		const -> attribute

inline

Returns nested attribute of an attribute at the specified path.

Precondition: this->type_id() == attrib.type_id()

Returns empty attribute handle if no such nested attribute exists.

Referenced by fetch_values(), find(), eagine::valtree::compound_attribute::find(), select_value(), and value_count().

◆ find() [2/4]

auto eagine::valtree::compound::find	(	const attribute &	attrib,
		const basic_string_path &	path,
		span< const string_view >	tags
	)		const -> attribute

inline

Returns nested attribute of an attribute at path with tags.

Precondition: this->type_id() == attrib.type_id()

Returns empty attribute handle if no such nested attribute exists.

◆ find() [3/4]

auto eagine::valtree::compound::find ( const basic_string_path & path ) const -> attribute

inline

Returns nested attribute of root attribute at the specified path.

Returns empty attribute handle if no such nested attribute exists.

◆ find() [4/4]

auto eagine::valtree::compound::find	(	const basic_string_path &	path,
		span< const string_view >	tags
	)		const -> attribute

inline

Returns nested attribute of root attribute at path with tags.

Returns empty attribute handle if no such nested attribute exists.

◆ has_nested()

auto eagine::valtree::compound::has_nested ( const attribute & attrib ) const -> bool

inline

Indicates if an attribute has nested attribute accessible by index.

Precondition: this->type_id() == attrib.type_id()

Referenced by eagine::valtree::compound_attribute::has_nested().

◆ is_link()

auto eagine::valtree::compound::is_link ( const attribute & attrib ) const -> bool

inline

Indicates if the specified attribute is a reference or link in the tree.

Precondition: this->type_id() == attrib.type_id()

Referenced by eagine::valtree::compound_attribute::is_link().

◆ make()

template<typename Compound , typename... Args>

static auto eagine::valtree::compound::make ( Args &&... args ) -> std:: enable_if_t<std::is_base_of_v<compound_interface, Compound>, compound>

inlinestatic

Instantiates a particular implementation.

Note: Do not use directly in client code. Use one of the constructor functions that know which implementation to pick and how to initialize it.

◆ nested() [1/3]

auto eagine::valtree::compound::nested	(	const attribute &	attrib,
		span_size_t	index
	)		const -> attribute

inline

Returns nested attribute of an attribute at the specified index.

Precondition: this->type_id() == attrib.type_id()

Returns empty attribute handle if no such nested attribute exists.

Referenced by fetch_values(), nested(), eagine::valtree::compound_attribute::nested(), select_value(), and value_count().

◆ nested() [2/3]

auto eagine::valtree::compound::nested	(	const attribute &	attrib,
		string_view	name
	)		const -> attribute

inline

Returns nested attribute of an attribute with the specified name.

Precondition: this->type_id() == attrib.type_id()

Returns empty attribute handle if no such nested attribute exists.

◆ nested() [3/3]

auto eagine::valtree::compound::nested ( string_view name ) const -> attribute

inline

Returns nested attribute of the root attribute with the specified name.

Returns empty attribute handle if no such nested attribute exists.

◆ nested_count()

auto eagine::valtree::compound::nested_count ( const attribute & attrib ) const -> span_size_t

inline

Returns the count of nested attributes of an attribute.

Precondition: this->type_id() == attrib.type_id()

Note: Some implementations may return zero here even if there are nested attributes. In such implementations the nested nodes can be traversed only by name.

Referenced by has_nested(), and eagine::valtree::compound_attribute::nested_count().

◆ root()

auto eagine::valtree::compound::root ( ) const -> compound_attribute

inline

Returns the structure root as an compound_attribute.

See also: structure

◆ structure()

auto eagine::valtree::compound::structure ( ) const -> attribute

inline

Returns the root of attribute hierarchy describing the tree structure.

See also: root

The returned attribute can be used to explore and traverse the tree node hierarchy by getting the names, value types and nested nodes.

Referenced by find(), nested(), and root().

The documentation for this class was generated from the following file:

eagine/value_tree/wrappers.hpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ attribute_name()

◆ canonical_type()

◆ find() [1/4]

◆ find() [2/4]

◆ find() [3/4]

◆ find() [4/4]

◆ has_nested()

◆ is_link()

◆ make()

◆ nested() [1/3]

◆ nested() [2/3]

◆ nested() [3/3]

◆ nested_count()

◆ root()

◆ structure()