better tutorial

Author: Davide Faconti

docs/tutorial_08_additional_args.md

@@ -1,4 +1,4 @@
-# Custom initialization and/or construction
+# Pass additional arguments during initialization and/or construction
 
 In every single example we explored so far we were "forced" to provide a
 constructor with the following signature
@@ -11,21 +11,25 @@ constructor with the following signature
 In same cases, it is desirable to pass to the constructor of our class 
 additional arguments, parameters, pointers, references, etc.
 
-We will just use the word _"parameter"_ for the rest of the tutorial.
+**Many people use blackboards to do that: this is not recomendable.**
 
-Even if, theoretically, these parameters can be passed using Input Ports, 
+We will just use the word _"arguments"_ for the rest of the tutorial.
+
+Even if, theoretically, these arguments **could** be passed using Input Ports,
 that would be the wrong way to do it if:
 
-- The parameters are known at _deployment-time_.
-- The parameters don't change at _run-time_.
-- The parameters don't need to be from the _XML_.
+- The arguments are known at _deployment-time_.
+- The arguments don't change at _run-time_.
+- The arguments don't need to be set from the _XML_.
+
+If all these conditions are met, using ports or the blackboard is cumbersome and highly discouraged.
 
-If all these conditions are met, using ports is just cumbersome and highly discouraged.
+## Method 1: register a custom builder
 
-## The C++ example
+Consider the following custom node called **Action_A**.
 
-Next, we can see two alternative ways to pass parameters to a class: 
-either as arguments of the constructor of the class or in an `init()` method.
+We want to pass three additional arguments; they can be arbitrarily complex objects,
+you are not limited to built-in types.
 
 ```C++
 // Action_A has a different constructor than the default one.
@@ -41,114 +45,106 @@ public:
         _arg2(arg2),
         _arg3(arg3) {}
 
-    NodeStatus tick() override
-    {
-        std::cout << "Action_A: " << _arg1 << " / " << _arg2 << " / " 
-                  << _arg3 << std::endl;
-        return NodeStatus::SUCCESS;
-    }
     // this example doesn't require any port
     static PortsList providedPorts() { return {}; }
 
+    // tick() can access the private members
+    NodeStatus tick() override;
+
 private:
     int _arg1;
     double _arg2;
     std::string _arg3;
 };
+```
+
+This node should be registered as shown further:
+
+```C++
+BehaviorTreeFactory factory;
+
+// A node builder is a functor that creates a std::unique_ptr<TreeNode>.
+// Using lambdas or std::bind, we can easily "inject" additional arguments.
+NodeBuilder builder_A =
+   [](const std::string& name, const NodeConfiguration& config)
+{
+    return std::make_unique<Action_A>( name, config, 42, 3.14, "hello world" );
+};
+
+// BehaviorTreeFactory::registerBuilder is a more general way to
+// register a custom node.
+factory.registerBuilder<Action_A>( "Action_A", builder_A);
+
+// Register more custom nodes, if needed.
+// ....
+
+// The rest of your code, where you create and tick the tree, goes here.
+// ....
+```
+
+## Method 2: use an init method
+
+Alternatively, you may call an init method before ticking the tree.
+
+```C++
 
-// Action_B implements an init(...) method that must be called once
-// before the first tick()
 class Action_B: public SyncActionNode
 {
 
 public:
+    // The constructor looks as usual.
     Action_B(const std::string& name, const NodeConfiguration& config):
         SyncActionNode(name, config) {}
 
-    // we want this method to be called ONCE and BEFORE the first tick()
-    void init( int arg1, double arg2, std::string arg3 )
+    // We want this method to be called ONCE and BEFORE the first tick()
+    void init( int arg1, double arg2, const std::string& arg3 )
     {
         _arg1 = (arg1);
         _arg2 = (arg2);
         _arg3 = (arg3);
     }
 
-    NodeStatus tick() override
-    {
-        std::cout << "Action_B: " << _arg1 << " / " << _arg2 << " / " 
-                  << _arg3 << std::endl;
-        return NodeStatus::SUCCESS;
-    }
     // this example doesn't require any port
     static PortsList providedPorts() { return {}; }
 
+    // tick() can access the private members
+    NodeStatus tick() override;
+
 private:
     int _arg1;
     double _arg2;
     std::string _arg3;
 };
 ```
 
-The way we register and initialize them in our `main` is slightly different.
-
+The way we register and initialize Action_B is slightly different:
 
 ```C++
-static const char* xml_text = R"(
-
- <root >
-     <BehaviorTree>
-        <Sequence>
-            <Action_A/>
-            <Action_B/>
-        </Sequence>
-     </BehaviorTree>
- </root>
- )";
-
-int main()
-{
-    BehaviorTreeFactory factory;
 
-    // A node builder is nothing more than a function pointer to create a 
-    // std::unique_ptr<TreeNode>.
-    // Using lambdas or std::bind, we can easily "inject" additional arguments.
-    NodeBuilder builder_A = 
-       [](const std::string& name, const NodeConfiguration& config)
-    {
-        return std::make_unique<Action_A>( name, config, 42, 3.14, "hello world" );
-    };
+BehaviorTreeFactory factory;
 
-    // BehaviorTreeFactory::registerBuilder is a more general way to
-    // register a custom node. 
-    factory.registerBuilder<Action_A>( "Action_A", builder_A);
+// The regitration of  Action_B is done as usual, but remember
+// that we still need to call Action_B::init()
+factory.registerNodeType<Action_B>( "Action_B" );
 
-    // The regitration of  Action_B is done as usual, but remember 
-    // that we still need to call Action_B::init()
-    factory.registerNodeType<Action_B>( "Action_B" );
+// Register more custom nodes, if needed.
+// ....
 
-    auto tree = factory.createTreeFromText(xml_text);
+// Create the whole tree
+auto tree = factory.createTreeFromText(xml_text);
 
-    // Iterate through all the nodes and call init() if it is an Action_B
-    for( auto& node: tree.nodes )
+// Iterate through all the nodes and call init() if it is an Action_B
+for( auto& node: tree.nodes )
+{
+    // Not a typo: it is "=", not "=="
+    if( auto action_B = dynamic_cast<Action_B*>( node.get() ))
     {
-        if( auto action_B_node = dynamic_cast<Action_B*>( node.get() ))
-        {
-            action_B_node->init( 69, 9.99, "interesting_value" );
-        }
+        action_B->init( 42, 3.14, "hello world");
     }
-
-    tree.tickRoot();
-
-    return 0;
 }
 
-   
-/* Expected output:
-
-    Action_A: 42 / 3.14 / hello world
-    Action_B: 69 / 9.99 / interesting_value
-*/
-
+// The rest of your code, where you tick the tree, goes here.
+// ....
 ```
 
 

mkdocs.yml

@@ -49,7 +49,7 @@ nav:
        - "Tutorial 5: Subtrees and Loggers":  tutorial_05_subtrees.md
        - "Tutorial 6: Ports remapping":       tutorial_06_subtree_ports.md
        - "Tutorial 7: Wrap legacy code":      tutorial_07_legacy.md
-       - "Tutorial 8: Class parameters":      tutorial_08_additional_args.md
+       - "Tutorial 8: Additional arguments":  tutorial_08_additional_args.md
        - "Tutorial 9: Coroutines":            tutorial_09_coroutines.md
 
     - Migration Guide: