Add ScriptReader for script template parsing (#343)

This PR adds a script parser that extends the templating capabilities
when loading script code.

In particular that allows
- Variable substitution (exists already, but this was refactored)
- Conditionals
- Includes

With this we can add script code that only compiles on later software
versions only if the required version is used. This way, older software
versions can still be used, the new feature will simply not be present
there. So far, when using new script code functions, the code would not
have compiled on newer versions effectively increasing the minimal
required software version.

---------

Co-authored-by: Mads Holm Peters <[email protected]>

Author: urfeex

CMakeLists.txt

@@ -18,6 +18,7 @@ add_library(urcl
     src/comm/tcp_socket.cpp
     src/comm/tcp_server.cpp
     src/control/reverse_interface.cpp
+    src/control/script_reader.cpp
     src/control/script_sender.cpp
     src/control/trajectory_point_interface.cpp
     src/control/script_command_interface.cpp

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,156 @@
+: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
+~~~~~~~~~~~~~~~~
+
+Variable replacements
+^^^^^^^^^^^^^^^^^^^^^
+
+Variable replacements in the script code are done using the syntax ``{{ variable_name }}``. For
+this to work, the variable ``variable_name`` has to be defined in the data dictionary passed to the
+``ScriptReader``.
+
+The expression ``{{ variable_name }}`` will be replaced with the string representation of the
+variable's content.
+
+- If the variable is a string, it has to be wrapped into quotes in the script
+  code. e.g.
+
+  .. code-block:: python
+
+     textmsg("{{ log_message }}")
+
+
+- Boolean variables will be replaced with the string ``True`` or ``False``.
+- Numeric variables (integer and floating point) will be replaced with the string representation generated by
+  `std::to_string() <https://en.cppreference.com/w/cpp/string/basic_string/to_string>`_.
+- Version information variables will be replaced with the string representation similar to
+  ``10.7.0.0``
+
+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.

include/ur_client_library/control/script_reader.h

@@ -0,0 +1,128 @@
+// -- BEGIN LICENSE BLOCK ----------------------------------------------
+// Copyright 2025 Universal Robots A/S
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are met:
+//
+//    * Redistributions of source code must retain the above copyright
+//      notice, this list of conditions and the following disclaimer.
+//
+//    * Redistributions in binary form must reproduce the above copyright
+//      notice, this list of conditions and the following disclaimer in the
+//      documentation and/or other materials provided with the distribution.
+//
+//    * Neither the name of the {copyright_holder} nor the names of its
+//      contributors may be used to endorse or promote products derived from
+//      this software without specific prior written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+// POSSIBILITY OF SUCH DAMAGE.
+// -- END LICENSE BLOCK ------------------------------------------------
+
+#pragma once
+#include <filesystem>
+#include <string>
+#include <unordered_map>
+#include <variant>
+
+#include <ur_client_library/ur/datatypes.h>
+#include <ur_client_library/ur/version_information.h>
+
+namespace urcl
+{
+namespace control
+{
+/*!
+ * \brief This class handles reading script files parsing special instructions that will get replaced.
+ *
+ * When parsing the script code, it is supported to have
+ *   - Variable replacements using `{{ VARIABLE_NAME }}`
+ *   - Including other files using `{% include <filename> %}`.
+ *     The filename has to be relative to the root script file's folder
+ *   - Conditionals using
+ *
+ *         {% if <condition %}
+ *           ...
+ *         {% elif <condition> %}
+ *           ...
+ *         {% else %}
+ *           ...
+ *         {% endif %}
+ *
+ *
+ * Those directives use Jinja2 notation.
+ */
+class ScriptReader
+{
+public:
+  using DataVariant = std::variant<std::string, double, int, bool, VersionInformation>;
+  using DataDict = std::unordered_map<std::string, DataVariant>;
+
+  ScriptReader() = default;
+
+  /*!
+   * \brief Reads a script file and applies variable replacements, includes, and conditionals.
+   * \param file_path Path of the script file to be loaded.
+   * \param data Data dictionary used for variable replacements and expression evaluation.
+   * \return The Script code with all replacements, includes and conditionals applied.
+   */
+  std::string readScriptFile(const std::string& file_path, const DataDict& data = DataDict());
+
+  /*!
+   * \brief Evaluate a boolean expression
+   * \param expression The boolean expression to be evaluated.
+   * \param data A data dictionary that will be used when evaluating the expressions
+   * \return The result of evaluating the boolean expression
+   */
+  static bool evaluateExpression(const std::string& expression, const DataDict& data);
+
+private:
+  enum BlockType
+  {
+    IF,
+    ELIF,
+    ELSE
+  };
+  struct BlockState
+  {
+    BlockType type;
+    bool condition_matched;  // Has any previous condition in this block matched?
+    bool should_render;      // Should this block render?
+    bool parent_render;      // Is the parent block rendering?
+  };
+
+  std::filesystem::path script_path_;
+
+  static std::string readFileContent(const std::string& file_path);
+  void replaceIncludes(std::string& script_code, const DataDict& data);
+  static void replaceVariables(std::string& script_code, const DataDict& data);
+  static void replaceConditionals(std::string& script_code, const DataDict& data);
+};
+
+bool operator<(const ScriptReader::DataVariant& lhs, const ScriptReader::DataVariant& rhs);
+bool operator>(const ScriptReader::DataVariant& lhs, const ScriptReader::DataVariant& rhs);
+bool operator==(const ScriptReader::DataVariant& lhs, const ScriptReader::DataVariant& rhs);
+
+inline bool operator!=(const ScriptReader::DataVariant& lhs, const ScriptReader::DataVariant& rhs)
+{
+  return !(lhs == rhs);
+}
+inline bool operator<=(const ScriptReader::DataVariant& lhs, const ScriptReader::DataVariant& rhs)
+{
+  return (lhs < rhs || lhs == rhs);
+}
+inline bool operator>=(const ScriptReader::DataVariant& lhs, const ScriptReader::DataVariant& rhs)
+{
+  return (lhs > rhs || lhs == rhs);
+}
+}  // namespace control
+}  // namespace urcl

include/ur_client_library/exceptions.h

@@ -213,5 +213,17 @@ class UnsupportedMotionType : public UrException
   {
   }
 };
+
+class UnknownVariable : public UrException
+{
+private:
+  std::string text_;
+
+public:
+  explicit UnknownVariable() = delete;
+  explicit UnknownVariable(const std::string& variable_name) : std::runtime_error("Unknown variable: " + variable_name)
+  {
+  }
+};
 }  // namespace urcl
-#endif  // ifndef UR_CLIENT_LIBRARY_EXCEPTIONS_H_INCLUDED
+#endif  // ifndef UR_CLIENT_LIBRARY_EXCEPTIONS_H_INCLUDED

include/ur_client_library/helpers.h

@@ -29,6 +29,7 @@
 #ifndef UR_CLIENT_LIBRARY_HELPERS_H_INCLUDED
 #define UR_CLIENT_LIBRARY_HELPERS_H_INCLUDED
 
+#include <string>
 #include <chrono>
 #include <functional>
 #ifdef _WIN32
@@ -78,5 +79,25 @@ bool setFiFoScheduling(pthread_t& thread, const int priority);
  */
 void waitFor(std::function<bool()> condition, const std::chrono::milliseconds timeout,
              const std::chrono::milliseconds check_interval = std::chrono::milliseconds(50));
+
+/*!
+ * \brief Parses a boolean value from a string.
+ *
+ * The string can be one of
+ *  - true, True, TRUE
+ *  - on, On, ON
+ *  - yes, Yes, YES
+ *  - 1
+ *  - false, False, FALSE
+ *  - off, Off, OFF
+ *  - no, No, NO
+ *  - 0
+ *
+ * \param str string to be parsed
+ * \throws urcl::UrException If the string doesn't match one of the options
+ * \return The boolean representation of the string
+ */
+bool parseBoolean(const std::string& str);
+
 }  // namespace urcl
 #endif  // ifndef UR_CLIENT_LIBRARY_HELPERS_H_INCLUDED

include/ur_client_library/ur/datatypes.h

@@ -30,6 +30,7 @@
 
 #include <ur_client_library/types.h>
 #include "ur_client_library/log.h"
+#include <sstream>
 
 namespace urcl
 {