Add sphinx documentation and an example for the ScriptReader

Author: urfeex

doc/architecture.rst

@@ -13,6 +13,7 @@ well as a couple of standalone modules to directly use subsets of the library's
    architecture/reverse_interface
    architecture/rtde_client
    architecture/script_command_interface
+   architecture/script_reader
    architecture/script_sender
    architecture/trajectory_point_interface
    architecture/ur_driver

doc/architecture/script_reader.rst

@@ -0,0 +1,132 @@
+:github_url: https://github.com/UniversalRobots/Universal_Robots_Client_Library/blob/master/doc/architecture/script_reader.rst
+
+.. _script_reader:
+
+ScriptReader
+============
+
+Script code used by the :ref:`script_sender` is read from a file. That script code might have to be
+dynamically modified based on some configuration input. For example, if the script code contains
+connections to a remote PC, that PC's IP address might be configured by the user. Another example
+would be to include certain parts of the script code only if the robot's software version supports
+that.
+
+For that purpose the ``ScriptReader`` class is provided. It reads the script code from a file and
+performs the following substitutions:
+
+- Replaces variables in the form of ``{{variable_name}}`` with the value of the variable
+  from a provided dictionary.
+- Includes other script files using the directive ``{% include file_name %}``. The included file is
+  read from the same directory as the main script file. Nested includes are also possible.
+- Use conditionals in order to add certain parts of the script code only if a condition matches.
+
+The supported substitutions use a basic implementation of the `Jinja2 templating engine` syntax.
+
+.. note::
+  One special literal is defined for **version information**. Use a software version prefixed with a
+  ``v`` character, e.g. ``v10.8.0`` to encode a software version. Version information entries can be
+  compared with each other.
+
+  **Do not** wrap version information into quotes, as this will be interpreted as a string.
+
+Example
+-------
+
+Given two script files:
+
+.. literalinclude:: ../../tests/resources/example_urscript_main.urscript
+   :caption: tests/resources/example_urscript_main.urscript
+   :linenos:
+   :lineno-match:
+
+.. literalinclude:: ../../tests/resources/example_urscript_feature.urscript
+   :language: python
+   :caption: tests/resources/example_urscript_feature.urscript
+   :linenos:
+   :lineno-match:
+
+The dictionary entry for ``feature_name`` is "torque control".
+
+Depending on the ``SOFTWARE_VERSION`` entry in the dictionary passed to the
+``ScriptReader``, the script code will be read as follows:
+
+Given ``SOFTWARE_VERSION = v5.21.0``, the script code will be:
+
+.. code-block:: python
+
+     popup("The cool new feature is not supported on Software version 5.23.0")
+
+
+Given ``SOFTWARE_VERSION = v5.23.0``, the script code will be:
+
+.. code-block:: python
+
+     textmsg("torque control is a very cool feature!")
+
+Supported Data
+--------------
+
+Data dictionary (C++ side)
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The data dictionary supports the following types
+
+- ``str``: A string value, e.g. "Hello World"
+- ``int``: An integer value, e.g. 42
+- ``double``: A floating point value, e.g. 3.14
+- ``bool``: A boolean value, e.g. ``true`` or ``false``
+- ``VersionInformation``: A version information value, e.g. ``VersionInformation::fromString("10.8.0")``
+
+Script code side
+~~~~~~~~~~~~~~~~
+
+Boolean expressions
+^^^^^^^^^^^^^^^^^^^
+
+Boolean expressions have to follow one of two possible syntax variations
+
+- Direct evaluation of a boolean variable from the data dictionary:
+
+  .. code-block::
+
+     boolean_variable_name
+
+- Comparison of a variable with a value using an operator.
+
+  .. code-block::
+
+     variable_name operator value
+
+  The operator has to be one of ``==``, ``!=``, ``<``, ``<=``, ``>``, ``>=``. On the lefthand side
+  of the operator there has to be a variable from the data dictionary. The right hand side can be
+  either a variable name or a value. If the right hand side is a variable name, it has to be
+  defined in the data dictionary as well. Values will be parsed as follows:
+
+  - Strings: Wrapped in quotes, e.g. ``"Hello World"`` or ``'Universal Robots'``.
+  - Numerical values such as ``42``, ``3.14``, ``-1``, ``1e-12``.
+  - Boolean values: See below.
+  - Version information: Prefixed with a ``v`` character, e.g. ``v10.8.0``, ``v5.23.0``.
+
+Boolean values parsing
+^^^^^^^^^^^^^^^^^^^^^^
+
+Boolean values can be parsed from the following strings:
+
+- ``true``, ``True``, ``TRUE``
+- ``on``, ``On``, ``ON``
+- ``yes``, ``Yes``, ``YES``
+- ``1``
+- ``false``, ``False``, ``FALSE``
+- ``off``, ``Off``, ``OFF``
+- ``no``, ``No``, ``NO``
+- ``0``
+
+Conditional blocks
+^^^^^^^^^^^^^^^^^^
+
+Conditional blocks have to be started with a ``{% if condition %}`` directive and closed with a
+``{% endif %}`` directive. The condition can be any boolean expression as described above.
+
+The ``{% elif condition %}`` and ``{% else %}`` directives can be used to add alternative paths.
+
+Conditional blocks can be nested.

tests/resources/example_urscript_feature.urscript

@@ -0,0 +1 @@
+textmsg("{{ feature_name }} is a very cool feature!")

tests/resources/example_urscript_main.urscript

@@ -0,0 +1,5 @@
+{% if SOFTWARE_VERSION >= v5.23.0 %}
+  {% include "example_urscript_feature.urscript" %}
+{% else %}
+  popup("The cool new feature is not supported on Software version 5.23.0")
+{% endif %}

tests/test_script_reader.cpp

@@ -32,6 +32,7 @@
 
 #include <gtest/gtest.h>
 #include "ur_client_library/control/script_reader.h"
+#include "ur_client_library/ur/version_information.h"
 
 #include <fstream>
 
@@ -165,6 +166,7 @@ TEST_F(ScriptReaderTest, ReplaceVariables)
   // By default std::to_string will convert double to 6 decimal places
   EXPECT_EQ(script, "movej([value1, 42, 6.280000, 0, 0, 0])\nlocal is_true = True\nlocal is_false = False\nThis is "
                     "just a line without any replacement");
+  std::remove(existing_script_file);
 }
 
 TEST_F(ScriptReaderTest, VariableNotInDictThrowsError)
@@ -186,6 +188,7 @@ TEST_F(ScriptReaderTest, VariableNotInDictThrowsError)
   ofs.close();
 
   EXPECT_THROW(reader.readScriptFile(existing_script_file, data), urcl::UnknownVariable);
+  std::remove(existing_script_file);
 }
 
 TEST_F(ScriptReaderTest, ReplaceConditionals)
@@ -235,6 +238,7 @@ Please log in.
   data["is_guest"] = false;
   script = reader.readScriptFile(existing_script_file, data);
   EXPECT_EQ(script, "Please log in.");
+  std::remove(existing_script_file);
 }
 
 TEST_F(ScriptReaderTest, CheckCondition)
@@ -323,25 +327,6 @@ TEST_F(ScriptReaderTest, CheckCondition)
   EXPECT_THROW(reader.evaluateExpression("X >= True", data), std::invalid_argument);
 }
 
-TEST_F(ScriptReaderTest, ParseBoolean)
-{
-  EXPECT_TRUE(ScriptReader::parseBoolean("true"));
-  EXPECT_TRUE(ScriptReader::parseBoolean("True"));
-  EXPECT_TRUE(ScriptReader::parseBoolean("TRUE"));
-  EXPECT_TRUE(ScriptReader::parseBoolean("on"));
-  EXPECT_TRUE(ScriptReader::parseBoolean("On"));
-  EXPECT_TRUE(ScriptReader::parseBoolean("ON"));
-  EXPECT_TRUE(ScriptReader::parseBoolean("1"));
-  EXPECT_FALSE(ScriptReader::parseBoolean("false"));
-  EXPECT_FALSE(ScriptReader::parseBoolean("False"));
-  EXPECT_FALSE(ScriptReader::parseBoolean("FALSE"));
-  EXPECT_FALSE(ScriptReader::parseBoolean("off"));
-  EXPECT_FALSE(ScriptReader::parseBoolean("Off"));
-  EXPECT_FALSE(ScriptReader::parseBoolean("OFF"));
-  EXPECT_FALSE(ScriptReader::parseBoolean("0"));
-  EXPECT_THROW(ScriptReader::parseBoolean("notabool"), urcl::UrException);
-}
-
 TEST_F(ScriptReaderTest, DataVariantOperators)
 {
   ScriptReader::DataDict data;
@@ -403,49 +388,21 @@ TEST_F(ScriptReaderTest, DataVariantOperators)
   EXPECT_THROW(data["double1"] == data["str1"], std::invalid_argument);
 }
 
-TEST_F(ScriptReaderTest, ConditionalInclude)
+TEST_F(ScriptReaderTest, Example)
 {
   ScriptReader reader;
-
-  char existing_script_file[] = "main_script.XXXXXX";
-  std::ignore = mkstemp(existing_script_file);
-  char existing_include_file[] = "included_script.XXXXXX";
-  std::ignore = mkstemp(existing_include_file);
-  std::ofstream ofs(existing_script_file);
-  if (ofs.bad())
-  {
-    std::cout << "Failed to create temporary files" << std::endl;
-    GTEST_FAIL();
-  }
-  ofs << "textmsg(\"This is a test script\")" << std::endl;
-  ofs << "{% if ROBOT_VERSION > 10.7 %}" << std::endl;
-  ofs << "{% include '" << std::string(existing_include_file) << "' %}" << std::endl;
-  ofs << "{% endif %}" << std::endl;
-  ofs.close();
-
-  // Create a temporary included script
-  std::ofstream ofs_included(existing_include_file);
-  if (ofs_included.bad())
-  {
-    std::cout << "Failed to create temporary files" << std::endl;
-    GTEST_FAIL();
-  }
-  ofs_included << "movej([1,2,3,4,5,6])";
-  ofs_included.close();
+  std::string existing_script_file = "resources/example_urscript_main.urscript";
 
   ScriptReader::DataDict data;
-  data["ROBOT_VERSION"] = 10.8;  // Set a version greater than 10.7 to include the script
+  data["SOFTWARE_VERSION"] = urcl::VersionInformation::fromString("5.9");
+  data["feature_name"] = "torque control";
 
   std::string processed_script = reader.readScriptFile(existing_script_file, data);
-  std::string expected_script = "textmsg(\"This is a test script\")\n"
-                                "movej([1,2,3,4,5,6])";
+  std::string expected_script = "  popup(\"The cool new feature is not supported on Software version 5.23.0\")";
   EXPECT_EQ(processed_script, expected_script);
 
-  data["ROBOT_VERSION"] = 10.6;
+  data["SOFTWARE_VERSION"] = urcl::VersionInformation::fromString("5.23.0");
   processed_script = reader.readScriptFile(existing_script_file, data);
-  expected_script = "textmsg(\"This is a test script\")";
+  expected_script = "  textmsg(\"torque control is a very cool feature!\")";
   EXPECT_EQ(processed_script, expected_script);
-
-  std::remove(existing_script_file);
-  std::remove(existing_include_file);
 }