TreeResource Class Reference

Class containing behavior tree resource data. More...

#include <auto_apms_behavior_tree_core/tree/tree_resource.hpp>

Inheritance diagram for TreeResource:

Public Member Functions
	TreeResource (const TreeResourceIdentity &search_identity)
	Assemble a behavior tree resource using a TreeResourceIdentity.
	TreeResource (const std::string &search_identity)
	Assemble a behavior tree resource identified by a string.
	TreeResource (const char *search_identity)
	Assemble a behavior tree resource identified by a string.
bool	hasRootTreeName () const
	Determine if this behavior tree resource specifies a root tree.
std::string	getRootTreeName () const
	Get the name of the root tree of this behavior tree resource.
TreeResourceIdentity	createIdentityForTree (const std::string &tree_name="") const
	Create a valid identity string for a specific behavior tree of this resource.
Public Member Functions inherited from BehaviorResourceTemplate< TreeResourceIdentity >
	BehaviorResourceTemplate (const Identity &search_identity)
	Assemble a behavior resource using a BehaviorResourceIdentity.
	BehaviorResourceTemplate (const std::string &search_identity)
	Assemble a behavior resource identified by a string.
	BehaviorResourceTemplate (const char *search_identity)
	Assemble a behavior tree resource identified by a string.
const Identity &	getIdentity () const
	Get the unique identity for this resource.
const std::string &	getBuildRequest () const
	Get the behavior build request associated with this resource.
const std::string &	getDefaultBuildHandlerName () const
	Get the fully qualified class name of the default build handler associated with this behavior resource.
const std::string &	getEntrypoint () const
	Get the entrypoint of this behavior resource.
const NodeManifest &	getNodeManifest () const
	Get the node manifest associated with this resource.

Static Public Member Functions
static TreeResource	findByTreeName (const std::string &tree_name, const std::string &package_name="")
	Find an installed behavior tree resource using a specific behavior tree name.
static TreeResource	findByFileStem (const std::string &file_stem, const std::string &package_name="")
	Find an installed behavior tree resource using a specific behavior tree XML file stem.
Static Public Member Functions inherited from BehaviorResourceTemplate< TreeResourceIdentity >
static BehaviorResourceTemplate	find (const std::string &behavior_alias, const std::string &package_name="", const std::string &category_name="")
	Find an installed behavior resource using a specific behavior tree name.

Detailed Description

Class containing behavior tree resource data.

Behavior tree resources are registered by calling the CMake macro auto_apms_behavior_tree_register_trees in the CMakeLists.txt of a package. They can be discovered once the corresponding package has been installed to the ROS 2 workspace.

Note

auto_apms_behavior_tree_register_trees replaces auto_apms_behavior_tree_register_behavior when registering behavior trees and the user should only invoke the former. Registering the corresponding behavior resource information is handled fully automatically for tree resources.

The user may refer to a specific resource using an identity string that may contain the tokens <package_name>, <tree_file_stem> and <tree_name> separated by :: in that order. Depending on the number of registered resources, it might be convenient to use shorter, less precise signatures. Additionally, if the delimiter :: is not present, the string is assumed to be the stem of a behavior tree file <tree_file_stem>. All possible identity strings are listed below:

• <package_name>::<tree_file_stem>::<tree_name>

  Fully qualified identity string of a specific behavior tree.

• ::<tree_file_stem>::<tree_name>

  Try to find the resource by searching for a tree with name <tree_name> in a file with stem <tree_file_stem> considering all packages.

• <package_name>::::<tree_name>

  Try to find a tree with name <tree_name> within the resources registered by <package_name>.

• ::::<tree_name>

  Try to find the resource by searching for a tree with name <tree_name> considering all packages.

• <package_name>::<tree_file_stem>::

  Try to find a file with stem <tree_file_stem> within the resources registered by <package_name>.

• ::<tree_file_stem>:: or <tree_file_stem>

  Try to find the resource by searching for a file with stem <tree_file_stem> considering all packages. Here you may conveniently omit the :: delimiter, since this is the most common way for searching for a resource.

Note

The delimiter :: must be kept when tokens are omitted, except when searching for resources using only the file stem.

Usage

Given the user has specified a behavior tree named MyBehaviorTree inside the XML file behavior/my_tree_file.xml, the CMake macro auto_apms_behavior_tree_register_trees must be called in the CMakeLists.txt of the parent package (for example my_package) like this:

auto_apms_behavior_tree_register_trees(
    "behavior/my_tree_file.xml"
)

The macro automatically parses the given files and detects the names of the trees inside. In the C++ source code, one may use this resource, after the parent package my_package has been installed, like this:

#include "auto_apms_behavior_tree_core/tree/tree_resource.hpp"
 
using namespace auto_apms_behavior_tree;
 
// For example, use the fully qualified tree resource identity signature
const std::string identity_string = "my_package::my_behavior_tree::MyTreeName";
 
// You may use the proxy class for a tree resource identity
core::TreeResourceIdentity identity(identity_string);
core::TreeResource resource(identity);
 
// Or instantiate the resource object directly from the corresponding identity string
core::TreeResource resource(identity_string);
 
// The resource object may for example be used with TreeDocument
core::TreeDocument doc;
doc.mergeResource(resource);  // Add "MyTreeName" to the document
 
// This also works, so creating a resource object is not strictly necessary
doc.mergeResource(identity_string)
 
// The simplest approach is this
doc.mergeResource("my_package::my_behavior_tree::MyTreeName");

See also

BehaviorResource

Definition at line 155 of file tree_resource.hpp.

Constructor & Destructor Documentation

TreeResource() [1/3]

TreeResource

(

const TreeResourceIdentity &

search_identity

)

Assemble a behavior tree resource using a TreeResourceIdentity.

Parameters

search_identity

Tree resource identity object used for searching the corresponding resource.

Exceptions

auto_apms_util::exceptions::ResourceError

if the resource cannot be found using the given identity.

Definition at line 55 of file tree_resource.cpp.

TreeResource() [2/3]

TreeResource

(

const std::string &

search_identity

)

Assemble a behavior tree resource identified by a string.

search_identity must be formatted like <package_name>::<tree_file_stem>::<tree_name>.

Parameters

search_identity

Tree resource identity string used for searching the corresponding resource.

Exceptions

auto_apms_util::exceptions::ResourceIdentityFormatError	if the identity string has wrong format.
auto_apms_util::exceptions::ResourceError	if the resource cannot be found using the given identity string.

Definition at line 96 of file tree_resource.cpp.

TreeResource() [3/3]

TreeResource

(

const char *

search_identity

)

Assemble a behavior tree resource identified by a string.

search_identity must be formatted like <package_name>::<tree_file_stem>::<tree_name>.

Parameters

search_identity

C-style tree resource identity string used for searching the corresponding resource.

Exceptions

auto_apms_util::exceptions::ResourceIdentityFormatError	if the identity string has wrong format.
auto_apms_util::exceptions::ResourceError	if the resource cannot be found using the given identity string.

Definition at line 98 of file tree_resource.cpp.

Member Function Documentation

findByTreeName()

TreeResource findByTreeName ( const std::string & tree_name, const std::string & package_name = "" )

static

Find an installed behavior tree resource using a specific behavior tree name.

This factory method acts equivalently to passing an identity string formatted like <package_name>::::<tree_name> to the constructor.

Parameters

tree_name	Name of the desired behavior tree.
package_name	Optional package name provided to narrow down the search. If empty, search in all installed packages.

Returns

Corresponding tree resource object.

Exceptions

auto_apms_util::exceptions::ResourceError

if the corresponding behavior tree cannot be found using the given arguments.

Definition at line 100 of file tree_resource.cpp.

findByFileStem()

TreeResource findByFileStem ( const std::string & file_stem, const std::string & package_name = "" )

static

Find an installed behavior tree resource using a specific behavior tree XML file stem.

This factory method acts equivalently to passing an identity string formatted like <package_name>::<tree_file_stem>:: to the constructor.

Parameters

file_stem	Stem of the desired behavior tree file (the stem of a file is the file name without the extension).
package_name	Optional package name provided to narrow down the search. If empty, search in all installed packages.

Returns

Corresponding tree resource object.

Exceptions

auto_apms_util::exceptions::ResourceError

if the corresponding behavior tree cannot be found using the given arguments.

Definition at line 107 of file tree_resource.cpp.

hasRootTreeName()

bool hasRootTreeName

(

)

const

Determine if this behavior tree resource specifies a root tree.

The name of the root tree is determined as follows:

• If the <tree_name> token was present in the resource identity when this instance was created, this is considered the root tree name.
• Otherwise, the XML of the associated tree document is parsed to determine the root tree.

Returns

true if the root tree of this resource can be determined, false otherwise.

Definition at line 114 of file tree_resource.cpp.

getRootTreeName()

std::string getRootTreeName

(

)

const

Get the name of the root tree of this behavior tree resource.

The name of the root tree is determined as follows:

• If the <tree_name> token was present in the resource identity when this instance was created, this is considered the root tree name.
• Otherwise, the XML of the associated tree document is parsed to determine the root tree.

Returns

Name of this resource's root tree.

Exceptions

auto_apms_util::exceptions::ResourceError

if the name of the root tree cannot be determined.

Definition at line 119 of file tree_resource.cpp.

createIdentityForTree()

TreeResourceIdentity createIdentityForTree

(

const std::string &

tree_name = ""

)

const

Create a valid identity string for a specific behavior tree of this resource.

Parameters

tree_name

Name of one of the trees inside this resource's tree document. If empty, do not refer to a specific behavior tree (identity won't be fully qualified).

Returns

Tree resource identity string.

Definition at line 133 of file tree_resource.cpp.

---

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

• auto_apms_behavior_tree_core/include/auto_apms_behavior_tree_core/tree/tree_resource.hpp
• auto_apms_behavior_tree_core/src/tree/tree_resource.cpp