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.

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	fromResourceIdentity (const std::string &identity)
	Create a node manifest from an installed resource.

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 TreeBuilder 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_declare_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_declare_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_declare_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_declare_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 as follows:

FooNode:  # Registration name of behavior tree node used to look up the following parameters.
  class_name: my_package_name::FooNodeImplementation  # Required name of the C++ class (with namespaces)
  port: optional_prefix/(input:port)  # Or you may specify a constant port name
  wait_timeout: 3  # Float number
  request_timeout: 2  # Float number
  allow_unreachable: false  # Boolean value
  logger_level: INFO  # One of DEBUG, INFO, WARN, ERROR, FATAL, UNSET (no case sensitive)
 
BarNode:  # Registration name of behavior tree node used to look up the following parameters.
  class_name: my_package_name::BarNodeImplementation  # Required name of the C++ class (with namespaces)
  port: (input:port)/optional_suffix  # Or you may specify a constant port name
  wait_timeout: 3  # Float number
  request_timeout: 2  # Float number
  allow_unreachable: false  # Boolean value
  logger_level: INFO  # One of DEBUG, INFO, WARN, ERROR, FATAL, UNSET (no case sensitive)
 
# There may be as many keys as you want
...

Only class_name is required, the other registration options may be omitted to indicate that the default value should be used. It's also possible to use a single implementation (C++ class) for multiple nodes, as long as their registration names are not the same.

Definition at line 108 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 114 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 26 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 28 of file node_manifest.cpp.

◆ fromResourceIdentity()

NodeManifest fromResourceIdentity ( const std::string & identity )

static

Create a node manifest from an installed resource.

The resource identity must be specified in the format <package_name>::<file_stem> or simply <file_stem>.

Parameters

identity Identity of the node manifest 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 41 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 99 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 110 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 112 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 120 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 127 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 141 of file node_manifest.cpp.

◆ merge()

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

Merges another NodeManifest with this one.

Parameters

other	Other node manifest.
replace	`true` for automatically replacing entries with the same key. 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 other shares entries and replace is false.

Definition at line 151 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 168 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 176 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 178 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 180 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()

◆ fromResourceIdentity()

◆ toFile()

◆ contains()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ add()

◆ remove()

◆ merge()

◆ getNodeNames()

◆ size()

◆ empty()

◆ map()