TreeResource Class Reference

Class containing behavior tree resource data. More...

#include <auto_apms_behavior_tree_core/tree/tree_resource.hpp>

Public Member Functions
	TreeResource (const Identity &identity)
	Assemble a behavior tree resource using a TreeResourceIdentity.
	TreeResource (const std::string &identity)
	Assemble a behavior tree resource identified by a string.
	TreeResource (const char *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.
NodeManifest	getNodeManifest () const
	Get the node manifest associated with this resource.
std::string	getPackageName () const
	Get the name of the package this resource was registered by.
std::string	getFileStem () const
	Get the file stem of the XML file containing the tree document associated with this resource.
Identity	createIdentity (const std::string &tree_name="") const
	Create a valid tree resource identity string representing this resource.

Static Public Member Functions
static TreeResource	selectByTreeName (const std::string &tree_name, const std::string &package_name="")
	Find an installed behavior tree resource using a specific behavior tree name.
static TreeResource	selectByFileStem (const std::string &file_stem, const std::string &package_name="")
	Find an installed behavior tree resource using a specific behavior tree XML file stem.

Detailed Description

Class containing behavior tree resource data.

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

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 config/my_tree_file.xml, the CMake macro auto_apms_behavior_tree_declare_trees must be called in the CMakeLists.txt of the parent package (for example my_package_name) like this:

auto_apms_behavior_tree_declare_trees(
    "config/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_name 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_name::my_tree_file::MyBehaviorTree";
 
// 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 "MyBehaviorTree" 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_name::my_tree_file::MyBehaviorTree");

Definition at line 168 of file tree_resource.hpp.

Constructor & Destructor Documentation

TreeResource() [1/3]

TreeResource

(

const Identity &

identity

)

Assemble a behavior tree resource using a TreeResourceIdentity.

Parameters

identity

Tree resource identity object.

Exceptions

auto_apms_util::exceptions::ResourceError

if the resource cannot be found using the given identity.

Definition at line 62 of file tree_resource.cpp.

TreeResource() [2/3]

TreeResource

(

const std::string &

identity

)

Assemble a behavior tree resource identified by a string.

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

Parameters

identity

Identity string for a specific behavior tree 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 159 of file tree_resource.cpp.

TreeResource() [3/3]

TreeResource

(

const char *

identity

)

Assemble a behavior tree resource identified by a string.

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

Parameters

identity

C-style identity string for a specific behavior tree 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 161 of file tree_resource.cpp.

Member Function Documentation

selectByTreeName()

TreeResource selectByTreeName ( 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 163 of file tree_resource.cpp.

selectByFileStem()

TreeResource selectByFileStem ( 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 168 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 173 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 175 of file tree_resource.cpp.

getNodeManifest()

NodeManifest getNodeManifest

(

)

const

Get the node manifest associated with this resource.

Returns

Node manifest object.

Definition at line 189 of file tree_resource.cpp.

getPackageName()

std::string getPackageName

(

)

const

Get the name of the package this resource was registered by.

Returns

Package name.

Definition at line 191 of file tree_resource.cpp.

getFileStem()

std::string getFileStem

(

)

const

Get the file stem of the XML file containing the tree document associated with this resource.

Returns

File stem of the associated XML file.

Definition at line 193 of file tree_resource.cpp.

createIdentity()

TreeResourceIdentity createIdentity

(

const std::string &

tree_name = ""

)

const

Create a valid tree resource identity string representing this resource.

Parameters

tree_name

Name of one of the trees inside this resource's tree document the returned identity string should refer to. If empty, do not refer to a specific behavior tree.

Returns

Tree resource identity string.

Definition at line 195 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