Data structure for information about which behavior tree node plugin to load and how to configure them. More...

#include <auto_apms_behavior_tree_core/node/node_manifest.hpp>

Public Types
using	Map = std::map<std::string, NodeRegistrationOptions>
	Mapping of a node's name and its registration parameters.

Public Member Functions
	NodeManifest (const Map &map={})
	Constructor of a NodeManifest data structure.

void	toFile (const std::string &file_path) const
	Write the node manifest to a file.

bool	contains (const std::string &node_name) const
	Determine if a behavior tree node has been added to the manifest.

RegistrationOptions &	operator[] (const std::string &node_name)
	Access the node manifest and retrieve registration options for a specific behavior tree node.

const RegistrationOptions &	operator[] (const std::string &node_name) const
	Access the node manifest and retrieve registration options for a specific behavior tree node.

NodeManifest &	add (const std::string &node_name, const RegistrationOptions &opt)
	Add registration options for a behavior tree node to the manifest.

NodeManifest &	remove (const std::string &node_name)
	Remove registration options for a behavior tree node.

NodeManifest &	merge (const NodeManifest &other, bool replace=false)
	Merges another NodeManifest with this one.

NodeManifest &	mergeWithNamespace (const NodeManifest &other, const std::string &with_namespace, const std::string &sep=_AUTO_APMS_BEHAVIOR_TREE_CORE__NODE_NAMESPACE_DEFAULT_SEP)
	Merges another NodeManifest with this one using a namespace for the registration names.

NodeManifest &	applyNodeNamespace (const std::string &ns, const std::string &sep=_AUTO_APMS_BEHAVIOR_TREE_CORE__NODE_NAMESPACE_DEFAULT_SEP)
	Apply a namespace prefix to all node names in this manifest.

std::vector< std::string >	getNodeNames ()
	Get all names of the behavior tree nodes specified by the manifest.

size_t	size () const
	Get the number of behavior tree nodes this manifest holds registration options for.

bool	empty () const
	Determine whether any node registration options have been added to the manifest.

const Map &	map () const
	Get a view of the internal map.

Static Public Member Functions
static NodeManifest	fromFiles (const std::vector< std::string > &paths)
	Create a node plugin manifest from multiple files. They are loaded in the given order.

static NodeManifest	fromResource (const NodeManifestResourceIdentity &search_identity)
	Create a node manifest from a resource insinde the process-local lookup table or the ament index.

static void	registerLocalManifest (const NodeManifestResourceIdentity &id, const NodeManifest &manifest, bool allow_override=false)
	Register a manifest in the process-local lookup table.

Detailed Description

Data structure for information about which behavior tree node plugin to load and how to configure them.

The concept of a node manifest is introduced to enable TreeDocument to dynamically load and register an arbitrary amount of behavior tree node plugins implemented by ROS 2 packages. The node manifest contains information about the individual registration options required at construction time and the names that must be used inside the behavior tree to refer to respective node implementations.

Usually, the user doesn't need to worry about creating instances of this class manually, since a node manifest is automatically assembled when creating a behavior tree using a behavior tree resource. These resources are generated by the CMake macro auto_apms_behavior_tree_register_trees inside a CMakeLists.txt of a package. It's also possible to create node manifest resources using the CMake macro auto_apms_behavior_tree_register_nodes. Both macros may take an argument named NODE_MANIFEST that accepts multiple paths to YAML files specifying the corresponding node manifest. The content of the files will be concatenated to a single node manifest.

# Creates a behavior tree resource
auto_apms_behavior_tree_register_trees(
    ... # Behavior tree XML file paths
    NODE_MANIFEST
    "path/to/manifest/file1.yaml"
    "path/to/manifest/file2.yaml"
    ...
)
 
# Creates a node manifest resource
auto_apms_behavior_tree_register_nodes(node_library_target
    ... # Fully qualified class names of the node plugins
    NODE_MANIFEST
    "path/to/manifest/file1.yaml"
    "path/to/manifest/file2.yaml"
    ...
)

The YAML format for a node manifest file is defined here

Definition at line 132 of file node_manifest.hpp.

Member Typedef Documentation

◆ Map

using Map = std::map<std::string, NodeRegistrationOptions>

Mapping of a node's name and its registration parameters.

Definition at line 138 of file node_manifest.hpp.

Constructor & Destructor Documentation

◆ NodeManifest()

NodeManifest ( const Map & map = {} )

Constructor of a NodeManifest data structure.

The manifest is empty initially, but you may provide a map to initialize it.

Parameters

map	Initial manifest data.

Definition at line 99 of file node_manifest.cpp.

Member Function Documentation

◆ fromFiles()

NodeManifest fromFiles ( const std::vector< std::string > & paths )

static

Create a node plugin manifest from multiple files. They are loaded in the given order.

Parameters

paths Paths to the manifest files.

Exceptions

auto_apms_behavior_tree::exceptions::NodeManifestError if NodeManifest::merge fails for any file.

Definition at line 101 of file node_manifest.cpp.

◆ fromResource()

NodeManifest fromResource ( const NodeManifestResourceIdentity & search_identity )

static

Create a node manifest from a resource insinde the process-local lookup table or the ament index.

Parameters

search_identity Node manifest resource identity used for searching the corresponding resource.

Returns: Node manifest created from the corresponding resource.

Exceptions

auto_apms_util::exceptions::ResourceIdentityFormatError	if `identity` has wrong format.
auto_apms_util::exceptions::ResourceError	if resource cannot be determined using `identity`.

Definition at line 138 of file node_manifest.cpp.

◆ registerLocalManifest()

void registerLocalManifest	(	const NodeManifestResourceIdentity &	id,
		const NodeManifest &	manifest,
		bool	allow_override = false )

static

Register a manifest in the process-local lookup table.

NodeManifest::fromResource checks this table before querying the ament index, which allows developers to also register manifests without relying on the ament index.

Parameters

id	Identity under which the manifest is registered.
manifest	Manifest to store.
allow_override	If `false` (default), throws when `id` is already present in the ament index. Set to `true` to allow the local entry to shadow an installed resource.

Exceptions

exceptions::NodeManifestError if id is already registered locally, or if id resolves to an existing ament index resource and allow_override is false.

Definition at line 119 of file node_manifest.cpp.

◆ toFile()

void toFile ( const std::string & file_path ) const

Write the node manifest to a file.

Parameters

file_path Path to the target file.

Exceptions

auto_apms_behavior_tree::exceptions::NodeManifestError if file cannot be opened.

Definition at line 147 of file node_manifest.cpp.

◆ contains()

bool contains ( const std::string & node_name ) const

Determine if a behavior tree node has been added to the manifest.

Parameters

node_name Name of the behavior tree node.

Returns: true if name is existing, false otherwise.

Definition at line 158 of file node_manifest.cpp.

◆ operator[]() [1/2]

NodeManifest::RegistrationOptions & operator[] ( const std::string & node_name )

Access the node manifest and retrieve registration options for a specific behavior tree node.

Parameters

node_name Name of the behavior tree node.

Returns: Registration options for node_name.

Exceptions

std::out_of_range if node_name doesn't exist.

Definition at line 160 of file node_manifest.cpp.

◆ operator[]() [2/2]

const NodeManifest::RegistrationOptions & operator[] ( const std::string & node_name ) const

Access the node manifest and retrieve registration options for a specific behavior tree node.

Parameters

node_name Name of the behavior tree node.

Returns: Registration options for node_name.

Exceptions

std::out_of_range if node_name doesn't exist.

Definition at line 168 of file node_manifest.cpp.

◆ add()

NodeManifest & add	(	const std::string &	node_name,
		const RegistrationOptions &	opt )

Add registration options for a behavior tree node to the manifest.

Parameters

node_name	Name of the behavior tree node.
opt	Registration options to be used when loading the behavior tree node.

Returns: Modified node manifest.

Exceptions

auto_apms_behavior_tree::exceptions::NodeManifestError if the registration options are invalid or node_name already exists.

Definition at line 175 of file node_manifest.cpp.

◆ remove()

NodeManifest & remove ( const std::string & node_name )

Remove registration options for a behavior tree node.

Parameters

node_name Name of the behavior tree node.

Returns: Modified node manifest.

Exceptions

std::out_of_range if node_name doesn't exist.

Definition at line 190 of file node_manifest.cpp.

◆ merge()

NodeManifest & merge	(	const NodeManifest &	other,
		bool	replace = false )

Merges another NodeManifest with this one.

Since the functional characteristics of a node with the same name but different registration options can be fundamentally different, this method will throw if it comes across a registration name in other that already exists in this node manifest unless replace is true.

Parameters

other	Other node manifest.
replace	`true` for automatically replacing entries with the same key (same registration name). Throws an error if `false` and `other` contains any keys that already exist in this manifest.

Returns: Modified node manifest.

Exceptions

auto_apms_behavior_tree::exceptions::NodeManifestError if any node name from other already exists in this node manifest and replace is false.

Definition at line 200 of file node_manifest.cpp.

◆ mergeWithNamespace()

NodeManifest & mergeWithNamespace	(	const NodeManifest &	other,
		const std::string &	with_namespace,
		const std::string &	sep = _AUTO_APMS_BEHAVIOR_TREE_CORE__NODE_NAMESPACE_DEFAULT_SEP )

Merges another NodeManifest with this one using a namespace for the registration names.

Since the functional characteristics of a node with the same name but different registration options can be fundamentally different, this method will add a namespace as a prefix to all registration names from other.

Parameters

other	Other node manifest.
with_namespace	Prefix to add to all node names from `other`.
sep	Separator string to use between the namespace and the node name.

Returns: Modified node manifest.

Exceptions

auto_apms_behavior_tree::exceptions::NodeManifestError if any node name from other already exists in this manifest (after applying the namespace prefix).

Definition at line 217 of file node_manifest.cpp.

◆ applyNodeNamespace()

NodeManifest & applyNodeNamespace	(	const std::string &	ns,
		const std::string &	sep = _AUTO_APMS_BEHAVIOR_TREE_CORE__NODE_NAMESPACE_DEFAULT_SEP )

Apply a namespace prefix to all node names in this manifest.

Parameters

ns	Namespace prefix to apply.
sep	Separator string to use between the namespace and the node name.

Returns: Modified node manifest.

Definition at line 232 of file node_manifest.cpp.

◆ getNodeNames()

std::vector< std::string > getNodeNames ( )

Get all names of the behavior tree nodes specified by the manifest.

Returns: Vector of all available node names.

Definition at line 243 of file node_manifest.cpp.

◆ size()

size_t size ( ) const

Get the number of behavior tree nodes this manifest holds registration options for.

Returns: Size of this node manifest.

Definition at line 251 of file node_manifest.cpp.

◆ empty()

bool empty ( ) const

Determine whether any node registration options have been added to the manifest.

Returns: true if the node manifest is empty, false otherwise.

Definition at line 253 of file node_manifest.cpp.

◆ map()

const NodeManifest::Map & map ( ) const

Get a view of the internal map.

Returns: Internal map of the node manifest.

Definition at line 255 of file node_manifest.cpp.

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

auto_apms_behavior_tree_core/include/auto_apms_behavior_tree_core/node/node_manifest.hpp
auto_apms_behavior_tree_core/src/node/node_manifest.cpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ Map

Constructor & Destructor Documentation

◆ NodeManifest()

Member Function Documentation

◆ fromFiles()

◆ fromResource()

◆ registerLocalManifest()

◆ toFile()

◆ contains()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ add()

◆ remove()

◆ merge()

◆ mergeWithNamespace()

◆ applyNodeNamespace()

◆ getNodeNames()

◆ size()

◆ empty()

◆ map()