Erb template

lib/sdf/erb.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module SDF
+    # Module for handling ERB files
+    module ERB
+        module_function
+
+        # Parses an ERB string and returns the raw rendered string
+        #
+        # @param [String] erb_content ERB template file content as string
+        # @param [Hash] erb_args the configuration arguments to evaluate
+        # @return [String] the raw rendered XML string representing the model
+        def parse_erb_as_str(erb_content, **erb_args)
+            erb_engine = ::ERB.new(erb_content, trim_mode: "-")
+
+            # Render the ERB template with the passed hash arguments
+            erb_engine.result_with_hash(erb_args)
+        end
+
+        # Renders an ERB template and returns it as a REXML::Document
+        #
+        # @return [REXML::Document] the rendered sdf model
+        def render_erb_sdf_model(path, **erb_args)
+            erb_content = File.read(path)
+            solved_erb_as_sdf_str = parse_erb_as_str(erb_content, **erb_args)
+
+            REXML::Document.new(solved_erb_as_sdf_str)
+        end
+    end
+end

lib/sdf/erb_loader.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "erb"
+require_relative "sdf_loader"
+
+module SDF
+    # class to load SDF and ERB templated SDF files
+    class ERBLoader < Loader
+        def initialize(erb_args: {})
+            super()
+            @erb_args = erb_args
+        end
+
+        def parse_sdf_document(sdf_file)
+            SDF::ERB.render_erb_sdf_model(sdf_file, **@erb_args)
+        end
+    end
+end

lib/sdf/exceptions.rb

@@ -1,3 +1,24 @@
 module SDF
     class InternalError < RuntimeError; end
+
+    module XML
+        # Exception raised when trying to load a model URI, but the model does
+        # not contain a SDF entry for the required SDF version
+        class UnavailableSDFVersionInModel < ArgumentError; end
+        # Exception raised when trying to load a file that is not a SDF file
+        class NotSDF < ArgumentError; end
+        # Exception raised when trying to load a malformed XML file
+        class InvalidXML < ArgumentError; end
+
+        # Exception raised when trying to resolve a model that cannot be found
+        # in {model_path}
+        class NoSuchModel < ArgumentError
+            attr_reader :model_name
+
+            def initialize(model_name)
+                super
+                @model_name = model_name
+            end
+        end
+    end
 end

lib/sdf/root.rb

@@ -28,12 +28,12 @@ def initialize(xml, metadata = {})
         # @raise [XML::NotSDF] if the file is not a SDF file
         # @raise [XML::InvalidXML] if the file is not a valid XML file
         # @return [Root]
-        def self.load(sdf_file, expected_sdf_version = nil, flatten: true)
+        def self.load(sdf_file, expected_sdf_version = nil, flatten: true, loader: SDF::Loader.new)
             if sdf_file =~ %r{^model://(.*)}
                 load_from_model_name(::Regexp.last_match(1), expected_sdf_version,
-                                     flatten: flatten)
+                                     flatten: flatten, loader: loader)
             else
-                xml, metadata = XML.load_sdf(sdf_file, flatten: flatten, metadata: true)
+                xml, metadata = XML.load_sdf(sdf_file, flatten: flatten, metadata: true, loader: loader)
                 new(xml.root, metadata)
             end
         end
@@ -48,9 +48,9 @@ def self.load(sdf_file, expected_sdf_version = nil, flatten: true)
         #   (as version * 100, i.e. version 1.5 is represented by 150). Leave to
         #   nil to always read the latest.
         # @return [Root]
-        def self.load_from_model_name(model_name, sdf_version = nil, flatten: true)
+        def self.load_from_model_name(model_name, sdf_version = nil, flatten: true, loader: SDF::Loader.new)
             xml, metadata = XML.model_from_name(model_name, sdf_version,
-                                                flatten: flatten, metadata: true)
+                                                flatten: flatten, metadata: true, loader: loader)
             new(xml.root, metadata)
         end
 

lib/sdf/sdf_loader.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "erb"
+require_relative "exceptions"
+
+module SDF
+    # class to load SDF and ERB templated SDF files
+    class Loader
+        # Open a SDF file SDF file and returns its XML representation.
+        #
+        # @param [String] sdf_file the path to the SDF file
+        # @raise [Errno::ENOENT] if the files does not exist
+        # @raise [NotSDF] if the file is not a SDF file
+        # @raise [InvalidXML] if the file is not a valid XML file
+        # @return [REXML::Element] sdf_file's content as a REXML::Element instance
+        def load_sdf_raw(sdf_file)
+            find_or_raise_file_not_found(sdf_file)
+
+            sdf = begin
+                parse_sdf_document(sdf_file)
+            rescue REXML::ParseException => e
+                unless e.message.include?("No root")
+                    raise SDF::XML::InvalidXML,
+                          "Cannot load #{sdf_file}: #{e.message}"
+                end
+
+                REXML::Document.new
+            end
+            validate_sdf_root(sdf, sdf_file)
+
+            sdf
+        end
+
+        private
+
+        def find_or_raise_file_not_found(sdf_file)
+            return if File.exist?(sdf_file)
+
+            file_name = File.basename(sdf_file)
+            dir_path  = File.dirname(sdf_file)
+            raise Errno::ENOENT,
+                  "Cannot find '#{file_name}' in '#{dir_path}'." \
+                  "You probably want to update the GAZEBO_MODEL_PATH " \
+                  "environment variable, or set SDF.model_path explicitly."
+        end
+
+        def parse_sdf_document(sdf_file)
+            File.open(sdf_file) do |io|
+                REXML::Document.new(io)
+            end
+        end
+
+        def validate_sdf_root(sdf, sdf_file)
+            unless sdf.root
+                raise SDF::XML::NotSDF,
+                      "#{sdf_file} can be parsed as an XML file, but it " \
+                      "does not have a root"
+            end
+            return if %w[sdf gazebo].include?(sdf.root.name)
+
+            raise SDF::XML::NotSDF, "#{sdf_file} is not a SDF file"
+        end
+    end
+end

lib/sdf/xml.rb

@@ -1,4 +1,7 @@
 require "rexml/document"
+require_relative "exceptions"
+require_relative "sdf_loader"
+require_relative "erb_loader"
 
 module SDF
     module XML
@@ -7,24 +10,6 @@ module XML
         #     (as version * 100, i.e. version 1.5 is represented by 150). Leave to
         #     nil to always read the latest.
 
-        # Exception raised when trying to load a model URI, but the model does
-        # not contain a SDF entry for the required SDF version
-        class UnavailableSDFVersionInModel < ArgumentError; end
-        # Exception raised when trying to load a file that is not a SDF file
-        class NotSDF < ArgumentError; end
-        # Exception raised when trying to load a malformed XML file
-        class InvalidXML < ArgumentError; end
-
-        # Exception raised when trying to resolve a model that cannot be found
-        # in {model_path}
-        class NoSuchModel < ArgumentError
-            attr_reader :model_name
-
-            def initialize(model_name)
-                @model_name = model_name
-            end
-        end
-
         # The search path for models
         #
         # It defaults to GAZEBO_MODEL_PATH
@@ -83,9 +68,9 @@ def self.clear_cache
         #   SDF file for the required SDF version
         #
         # @return [REXML::Element]
-        def self.load_gazebo_model(dir, sdf_version = nil, metadata: false, flatten: true)
+        def self.load_gazebo_model(dir, sdf_version = nil, metadata: false, flatten: true, loader: SDF::Loader.new)
             load_sdf(model_path_of(dir, sdf_version), metadata: metadata,
-                                                      flatten: flatten)
+                                                      flatten: flatten, loader: loader)
         end
 
         # Find model string into model.config path
@@ -128,7 +113,7 @@ def self.model_path_of(dir, sdf_version = nil)
         #
         # @!macro sdf_version
         # @return [Hash<String,REXML::Element>]
-        def self.gazebo_models(sdf_version = nil)
+        def self.gazebo_models(sdf_version = nil, loader: SDF::ERBLoader.new)
             @gazebo_models[sdf_version] ||= {}
             @model_path.each do |p|
                 Dir.glob(File.join(p, "*")) do |subdir|
@@ -140,7 +125,7 @@ def self.gazebo_models(sdf_version = nil)
                         begin
                             sdf_file_path = model_path_of(subdir, sdf_version)
                             sdf, metadata = load_sdf(sdf_file_path, metadata: true,
-                                                                    flatten: false)
+                                                                    flatten: false, loader: loader)
                             @gazebo_models[sdf_version][File.basename(subdir)] =
                                 ModelCacheEntry.new(sdf_file_path, sdf, metadata)
                         rescue UnavailableSDFVersionInModel
@@ -165,7 +150,7 @@ def self.gazebo_models(sdf_version = nil)
         # @raise (see model_path_of)
         # @raise [NoSuchModel] if the provided model name does not resolve to a
         #   model in {model_path}
-        # @return [REXML::Element]
+        # @return [String] the path to the SDF file for the model
         def self.model_path_from_name(model_name, model_path: @model_path, sdf_version: nil)
             @gazebo_models[sdf_version] ||= {}
             cache = (@gazebo_models[sdf_version][model_name] ||= ModelCacheEntry.new)
@@ -193,12 +178,12 @@ def self.model_path_from_name(model_name, model_path: @model_path, sdf_version:
         #   model in {model_path}
         # @return [REXML::Element]
         def self.model_from_name(
-            model_name, sdf_version = nil, metadata: false, flatten: true
+            model_name, sdf_version = nil, metadata: false, flatten: true, loader: SDF::Loader.new
         )
             path = model_path_from_name(model_name, sdf_version: sdf_version)
             cache = @gazebo_models[sdf_version][model_name]
             unless cache.xml
-                cache.xml, cache.metadata = load_sdf(path, metadata: true, flatten: false)
+                cache.xml, cache.metadata = load_sdf(path, metadata: true, flatten: false, loader: loader)
             end
             xml = cache.xml
             if flatten
@@ -213,6 +198,23 @@ def self.model_from_name(
             end
         end
 
+        # Resolves relative paths and model:// URIs in the XML tree in-place
+        #
+        # This method traverses the XML tree starting from the given node, and
+        # expands any relative paths or `model://` URIs inside `<uri>` tags to
+        # absolute paths on the local filesystem.
+        #
+        # It skips `<include>` tags because those are resolved separately during
+        # {.add_include_tags}.
+        #
+        # @example Replaces a model:// mesh path:
+        #   # Before: <uri>model://robot_model/hull.dae</uri>
+        #   # After:  <uri>/path/to/workspace/robot_models/models/sdf/robot_model/hull.dae</uri>
+        #
+        # @param [REXML::Element] node the XML element to traverse
+        # @!macro sdf_version
+        # @param [String] base_path the base directory path used to resolve relative paths
+        # @return [void]
         def self.resolve_relative_uris(node, sdf_version, base_path)
             nodes = [node]
             until nodes.empty?
@@ -264,16 +266,34 @@ def self.deep_copy_xml(node)
         # This method modifies the XML tree by replacing the include tags found
         # as direct children of the provided element by the included content.
         #
+        # @example
+        #   # Before calling add_include_tags:
+        #   # <world name="my_world">
+        #   #   <include>
+        #   #     <uri>model://my_sensor</uri>
+        #   #     <name>custom_sensor</name>
+        #   #     <pose>1 0 0 0 0 0</pose>
+        #   #   </include>
+        #   # </world>
+        #   #
+        #   # After calling add_include_tags:
+        #   # <world name="my_world">
+        #   #   <model name="custom_sensor">
+        #   #     <pose>1 0 0 0 0 0</pose>
+        #   #     <link name="sensor_link">...</link>
+        #   #   </model>
+        #   # </world>
+        #
         # @param [REXML::Element] elem element to find include tags
         # @!macro sdf_version
         # @return [void]
-        def self.add_include_tags(elem, sdf_version, base_path)
+        def self.add_include_tags(elem, sdf_version, base_path, loader: SDF::Loader.new)
             includes = {}
 
             replacements = []
             elem.elements.each do |inc|
                 if inc.name == "world" || inc.name == "model" # model-within-model
-                    added_includes = add_include_tags(inc, sdf_version, base_path)
+                    added_includes = add_include_tags(inc, sdf_version, base_path, loader: loader)
                     includes.merge! added_includes do |_, old, new|
                         old + new
                     end
@@ -309,11 +329,11 @@ def self.add_include_tags(elem, sdf_version, base_path)
 
                     included_sdf, included_metadata =
                         model_from_name(model_name, sdf_version, metadata: true,
-                                                                 flatten: false)
+                                                                 flatten: false, loader: loader)
                 elsif File.directory?(uri_path = File.expand_path(uri, base_path))
                     included_sdf, included_metadata =
                         load_gazebo_model(uri_path, sdf_version, metadata: true,
-                                                                 flatten: false)
+                                                                 flatten: false, loader: loader)
                 else
                     raise ArgumentError,
                           "URI #{uri} is neither a model:// URI nor an existing directory"
@@ -362,39 +382,6 @@ def self.add_include_tags(elem, sdf_version, base_path)
             includes
         end
 
-        # Open a SDF file and returns the XML representation
-        #
-        # Unlike {.load_sdf}, this really only loads the XML information, not
-        # resolving the include tags.
-        #
-        # @param [String] sdf_file the path to the SDF file
-        # @raise [Errno::ENOENT] if the files does not exist
-        # @raise [NotSDF] if the file is not a SDF file
-        # @raise [InvalidXML] if the file is not a valid XML file
-        # @return [REXML::Element]
-        def self.load_sdf_raw(sdf_file)
-            sdf = File.open(sdf_file) do |io|
-                REXML::Document.new(io)
-            rescue REXML::ParseException => e
-                unless e.message.match?(/No root/)
-                    raise InvalidXML, "cannot load #{sdf_file}: #{e.message}"
-                end
-
-                REXML::Document.new
-            end
-
-            unless sdf.root
-                raise NotSDF,
-                      "#{sdf_file} can be parsed as an XML file, but it does not have a root"
-            end
-
-            if sdf.root.name != "sdf" && sdf.root.name != "gazebo"
-                raise NotSDF, "#{sdf_file} is not a SDF file"
-            end
-
-            sdf
-        end
-
         # Get sdf_version
         #
         # @param [REXML::Element] sdf element
@@ -441,19 +428,22 @@ def self.sdf_version_of(sdf)
         # @param [Boolean] metadata whether the method should return a metadata hash
         #   about the various inclusions that have been performed. See above for
         #   the hash format
+        # @param [#load_sdf_raw] loader object that acts as a loader.Takes a file path as input
+        # and returns a REXML::Element with its content. Must respond to
+        # `load_sdf_raw(path: String) -> REXML::Element`
         # @return [REXML::Element,(REXML::Element,Hash)] either the XML tree by itself
         #   if `metadata` is false, or the pair of the tree and the metadata hash
         #   otherwise.
         # @raise [Errno::ENOENT] if the files does not exist
         # @raise [NotSDF] if the file is not a SDF file
         # @raise [InvalidXML] if the file is not a valid XML file
         # @return [REXML::Element]
-        def self.load_sdf(sdf_file, flatten: true, metadata: false)
-            sdf = load_sdf_raw(sdf_file)
+        def self.load_sdf(sdf_file, flatten: true, metadata: false, loader: SDF::Loader.new)
+            sdf = loader.load_sdf_raw(sdf_file)
             sdf_version = sdf_version_of(sdf)
 
             sdf_metadata = Hash["includes" => {}, "path" => sdf_file]
-            includes = add_include_tags(sdf.root, sdf_version, File.dirname(sdf_file))
+            includes = add_include_tags(sdf.root, sdf_version, File.dirname(sdf_file), loader: loader)
             sdf_metadata["includes"].merge!(includes) do |_, old, new|
                 old + new
             end