sevgi-derender 0.93.1 → 0.94.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 126f64b403fbdff8cea203ad63c4857bf45254f2c513c9058db6803d8137414c
-  data.tar.gz: c531615d9b46226cf9bf35f1c828f18e678f6e148438b880337615b38da4301b
+  metadata.gz: 9f1b7265f14be33da5b43f634ac82059a6d438e723ecc2153a062452ea1610fc
+  data.tar.gz: 5c52f4aef783cd3b3c712f19883ebbcab9c28efce3802318fe1b1f55b2a7fd88
 SHA512:
-  metadata.gz: 8aea4ef742bba26cfd22a502fb1f761b476dd4dfb2bcd0573120e121c0853e9892abedd5f70d51203869b5052a5df2017fb285d448c8029dd1ab308a23b5ec67
-  data.tar.gz: 9447d2fc113a2eb97475ea2f2fe618e9e293573097908e7ea264fd95b10124ce8edce72ee5678e802d016fa26459e5bfea63ca6ea559b2522876f9e66ecd077f
+  metadata.gz: 98d494547c8854554dc9f791c4abd6ef1e99eb726face62c03b49756a0694be0267d311b103ac35a3797ad52dcc60cacf770c270569babcf5c4a6e9ee1bb0930
+  data.tar.gz: 3b127ab458de366d81b7efc0fb8b4ba94d6ce26cf2c9761389e4375aea02a079aaaa0c8447841416e45857674d9daee4494ffb1c28e2bca30b8944ba3addeeb3

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+Sevgi Derender follows the root Sevgi release notes:
+https://github.com/roktas/sevgi/blob/main/CHANGELOG.md

data/LICENSE

@@ -0,0 +1,5 @@
+Sevgi Derender is distributed under the GNU General Public License v3.0 or later.
+
+SPDX-License-Identifier: GPL-3.0-or-later
+
+Full project license: https://github.com/roktas/sevgi/blob/main/LICENSE

data/README.md

@@ -2,4 +2,43 @@
 
 Converts SVG/XML content back into Sevgi DSL source.
 
-See the root [README](../README.md) and the documentation site for usage.
+## Install
+
+```sh
+gem install sevgi-derender
+```
+
+## Require
+
+```ruby
+require "sevgi/derender"
+```
+
+## Example
+
+```ruby
+source = "<svg><rect width=\"3\" height=\"5\"/></svg>"
+Sevgi::Derender.derender(source)
+```
+
+## Executable
+
+```sh
+igves drawing.svg
+```
+
+## Ruby compatibility
+
+Requires Ruby 3.4.0 or newer. CI verifies Ruby 3.4 and the current development Ruby from `.ruby-version`.
+
+## Native prerequisites
+
+None beyond Ruby and this gem's Ruby dependencies. Nokogiri may use platform packages depending on the target Ruby
+platform.
+
+## Links
+
+- Documentation: https://sevgi.roktas.dev
+- API documentation: https://www.rubydoc.info/gems/sevgi-derender
+- Source: https://github.com/roktas/sevgi/tree/main/derender
+- Changelog: https://github.com/roktas/sevgi/blob/main/CHANGELOG.md

data/lib/sevgi/derender/attributes.rb

@@ -38,7 +38,8 @@ module Sevgi
             key = Css.to_key(key) if key.is_a?(::String)
 
             if key == "style"
-              "{ #{Attributes.decompile(Css.to_h!(value))} }"
+              style = Css.to_h!(value)
+              style.empty? ? "{}" : "{ #{Attributes.decompile(style)} }"
             elsif value.is_a?(::String)
               Css.to_value(value)
             elsif value.is_a?(::Hash)

data/lib/sevgi/derender/document.rb

@@ -6,17 +6,13 @@ module Sevgi
   module Derender
     # Parsed SVG/XML document wrapper used by the derender pipeline.
     class Document
-      @cache = {}
-
-      class << self
-        # @return [Hash{String => Nokogiri::XML::Document}] parsed document cache keyed by expanded file path
-        attr_reader :cache
-      end
-
-      # Loads and parses an SVG/XML file, using the parse cache when possible.
+      # Loads and parses an SVG/XML file.
+      #
+      # Each call reads the current file content and returns an isolated parsed document. Caller mutation of one loaded
+      # document does not affect later loads of the same path.
       # @param path [String] path to the source file, with or without `.svg` extension
       # @return [Sevgi::Derender::Document] document wrapper
-      # @raise [Sevgi::ArgumentError] when the file cannot be found
+      # @raise [Sevgi::ArgumentError] when the file cannot be found or file content is malformed XML
       # @raise [Errno::EACCES] when the file cannot be read
       def self.load_file(path)
         entry = ::File.expand_path(F.qualify(path, "svg"))
@@ -24,26 +20,30 @@ module Sevgi
         ArgumentError.("File not found: #{path}") unless ::File.exist?(entry)
 
         content = ::File.read(entry)
-        new(content) do
-          @doc = self.class.cache[entry] ||
-            begin
-              self.class.cache[entry] = self.class.parse(content)
-            end
-        end
+        new(content)
       end
 
-      # Parses SVG/XML content.
+      # Parses SVG/XML content in strict XML mode.
       # @param content [String] SVG/XML source content
       # @return [Nokogiri::XML::Document] parsed XML document
-      def self.parse(content) = Nokogiri::XML(content)
+      # @raise [Sevgi::ArgumentError] when content is not well-formed XML
+      # @raise [Sevgi::ArgumentError] when content has no root element
+      def self.parse(content)
+        Nokogiri::XML(content.to_s.lstrip, &:strict).tap do |doc|
+          ArgumentError.("XML document has no root element") unless doc.root
+        end
+
+      rescue Nokogiri::XML::SyntaxError => e
+        raise ArgumentError, "Malformed XML: #{e.message.lines.first.strip}", cause: e
+      end
 
       # Extracts the XML declaration from SVG/XML content.
       # @param content [String] SVG/XML source content
       # @return [String, nil] XML declaration line, if present
       def self.declaration(content)
-        return unless (content = content.lstrip).start_with?("<?xml ")
+        return unless (content = content.to_s.lstrip).start_with?("<?xml ")
 
-        content.split("\n").first
+        content[/\A<\?xml\b.*?\?>/m]
       end
 
       # @!attribute [r] doc
@@ -57,6 +57,7 @@ module Sevgi
       # @yield optional initializer used by {load_file} to install cached parse state
       # @yieldreturn [void]
       # @return [void]
+      # @raise [Sevgi::ArgumentError] when content is malformed XML
       def initialize(content, &block)
         instance_exec(&block) if block
 
@@ -67,7 +68,7 @@ module Sevgi
       # Converts the root or selected node into a derender node.
       # @param id [String, nil] optional SVG id selecting a node inside the document
       # @return [Sevgi::Derender::Node] selected node in the derender tree
-      # @raise [Sevgi::ArgumentError] when the id is absent
+      # @raise [Sevgi::ArgumentError] when the document has no root element or the id is absent
       def decompile(id = nil)
         if id
           if (found = doc.xpath("//*[@id=#{xpath_literal(id)}]") || []).empty?
@@ -79,7 +80,9 @@ module Sevgi
           doc.root
         end => element
 
-        Node.new(element, pres)
+        ArgumentError.("XML document has no root element") unless element
+
+        Node.new(element, pres, namespaces: namespace_scope(element))
       end
 
       # Returns XML declaration and pre-root nodes preserved for root decompilation.
@@ -93,6 +96,18 @@ module Sevgi
 
       private
 
+      def namespace_scope(element)
+        element == doc.root ? local_namespaces(element) : element.namespaces
+      end
+
+      def local_namespaces(element)
+        return {} unless element.respond_to?(:namespace_definitions)
+
+        element.namespace_definitions.to_h do |namespace|
+          [namespace.prefix ? "xmlns:#{namespace.prefix}" : "xmlns", namespace.href]
+        end
+      end
+
       def xpath_literal(value)
         value = value.to_s
 

data/lib/sevgi/derender/evaluator.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Sevgi
+  module Derender
+    # Builds graphics element trees from derender nodes without evaluating Ruby source.
+    # @api private
+    class Evaluator
+      # Builds an evaluator.
+      # @param parent [Sevgi::Graphics::Element] target graphics parent
+      # @return [void]
+      def initialize(parent) = @parent = parent
+
+      # Appends a derender node to the target parent.
+      # @param node [Sevgi::Derender::Node] derender node
+      # @return [Sevgi::Graphics::Element, nil] included element, or nil when the node does not produce graphics output
+      def append(node)
+        case node.type
+        when :CSS
+          append_css(node)
+        when :Text
+          parent.Element(:_, node.content)
+        else
+          append_element(node)
+        end
+      end
+
+      private
+
+      attr_reader :parent
+
+      def append_css(node)
+        return unless (hash = Css.to_h(node.node.content))
+
+        parent.Element(:style, Graphics::Content.css(hash), type: "text/css", **node.attributes)
+      end
+
+      def append_element(node)
+        parent.Element(node.name, *content(node), **attributes(node)).tap do |element|
+          node.children.each { self.class.new(element).append(it) } unless content(node).any?
+        end
+      end
+
+      def attributes(node) = node.attributes!
+
+      def content(node)
+        node.children.one? && node.children.first.node.text? ? [node.content] : []
+      end
+    end
+
+    private_constant :Evaluator
+  end
+end

data/lib/sevgi/derender/internal.rb

@@ -21,7 +21,11 @@ module Sevgi
       # Parses an inline style declaration string.
       # @param style_string [String] CSS declaration source
       # @return [Hash] parsed declarations for the synthetic universal selector
-      def to_h!(style_string) = to_h("* { #{style_string} }")["*"]
+      def to_h!(style_string)
+        hash = to_h("* { #{style_string} }")
+
+        hash ? hash.fetch("*", {}) : {}
+      end
 
       # Converts a CSS key into a Ruby hash key.
       # @param arg [String] CSS key

data/lib/sevgi/derender/node.rb

@@ -15,10 +15,13 @@ module Sevgi
       # Builds a derender node.
       # @param node [Nokogiri::XML::Node] source XML node
       # @param pres [Array<String>] preamble XML lines carried by the root node
+      # @param namespaces [Hash{String => String}, nil] namespace declarations to emit on this node; selected roots use
+      #   their full inherited namespace scope, while ordinary children use only declarations from their own element
       # @return [void]
-      def initialize(node, pres = [])
+      def initialize(node, pres = [], namespaces: nil)
         @node = node
         @pres = pres
+        @namespaces = namespaces
         @type = dispatch
       end
 
@@ -39,23 +42,11 @@ module Sevgi
 
       # Returns source XML attributes keyed with namespace prefixes when present.
       # @return [Hash{String => String}] XML attributes
-      def attributes
-        @attributes ||= node.attribute_nodes.to_h do |attr|
-          name, value = attr.name, attr.value
+      def attributes = @attributes ||= node.attribute_nodes.to_h { [attribute_key(it), it.value] }
 
-          if attr.respond_to?(:namespace) && (namespace = attr.namespace) && (prefix = namespace.prefix)
-            "#{prefix}:#{name}"
-          else
-            name
-          end => key
-
-          [key, value]
-        end
-      end
-
-      # Returns source XML attributes.
+      # Returns source XML attributes and namespace declarations emitted on this node.
       # @return [Hash{String => String}] XML attributes
-      def attributes! = attributes
+      def attributes! = {**attributes, **namespaces}
 
       # Returns non-ignorable child derender nodes.
       # @return [Array<Sevgi::Derender::Node>] child nodes
@@ -66,9 +57,12 @@ module Sevgi
           .reject { |child| ignorable_child?(child) }
       end
 
-      # Returns node text content, preserving or stripping whitespace according to xml:space.
+      # Returns node text content.
+      #
+      # `xml:space="preserve"` keeps content verbatim. Default-space text nodes are stripped for ordinary pretty-printed
+      # content, but inline text boundary spaces next to element siblings are kept because they affect rendered SVG text.
       # @return [String]
-      def content = @content ||= preserve_space? ? node.content : node.content.strip
+      def content = @content ||= preserve_space? ? node.content : normalized_content
 
       # Converts this node into formatted Sevgi DSL Ruby source.
       # @return [String] formatted Sevgi DSL source
@@ -82,19 +76,18 @@ module Sevgi
       # Evaluates this node under a graphics element.
       # @param element [Sevgi::Graphics::Element] target graphics element
       # @param include_current [Boolean] true to evaluate this node, false to evaluate only children
-      # @return [Sevgi::Graphics::Element] target graphics element
-      # @raise [Sevgi::PanicError] when generated Ruby source cannot be formatted
+      # @return [Sevgi::Graphics::Element, Array<Sevgi::Graphics::Element>, nil] included current element, included child
+      #   elements when include_current is false, or nil when the node does not produce graphics output
       def evaluate(element, include_current = true)
-        return element.instance_eval(derender) if include_current
+        return Evaluator.new(element).append(self) if include_current
 
-        children.each { element.instance_eval(it.derender) }
+        evaluate_children(element)
       end
 
       # Evaluates only this node's children under a graphics element.
       # @param element [Sevgi::Graphics::Element] target graphics element
-      # @return [Sevgi::Graphics::Element] target graphics element
-      # @raise [Sevgi::PanicError] when generated Ruby source cannot be formatted
-      def evaluate!(element) = evaluate(element, false)
+      # @return [Array<Sevgi::Graphics::Element>] included child elements
+      def evaluate_children(element) = children.map { it.evaluate(element) }.compact
 
       # Finds the first descendant whose attribute matches a value.
       # @param arg [String] attribute value to find
@@ -103,22 +96,16 @@ module Sevgi
       def find(arg, by: "id")
         return self if attributes[by] == arg
 
-        children&.each do |child|
-          found = child.find(arg, by:)
-
-          return found if found
-        end
-
-        nil
+        children.lazy.map { it.find(arg, by:) }.find(&:itself)
       end
 
       # Returns the source XML node name.
       # @return [String]
       def name = @name ||= node.name
 
-      # Returns source XML namespaces.
+      # Returns source XML namespace declarations emitted on this node.
       # @return [Hash{String => String}] namespace declarations
-      def namespaces = (@namespaces ||= node.namespaces.to_h { |namespace, uri| [namespace, uri] })
+      def namespaces = (@namespaces ||= local_namespaces)
 
       # Reports whether this node is the SVG root strategy.
       # @return [Boolean]
@@ -126,14 +113,17 @@ module Sevgi
 
       private
 
+      def attribute_key(attribute) = [attribute.namespace&.prefix, attribute.name].compact.join(":")
+
       def dispatch
-        if node.text?
+        case
+        when node.text?
           :Text
-        elsif node.comment?
+        when node.comment?
           :Junk
-        elsif node.name == "style"
+        when node.name == "style"
           :CSS
-        elsif node.name == "svg"
+        when node.name == "svg"
           :Root
         else
           :Any
@@ -142,7 +132,8 @@ module Sevgi
       end
 
       def ignorable_child?(child)
-        child.type == :Junk || (child.node.text? && child.node.text.strip.empty? && !child.preserve_space?)
+        child.type == :Junk ||
+          (child.node.text? && child.node.text.strip.empty? && !child.preserve_space? && !child.inline_text?)
       end
 
       protected
@@ -160,8 +151,20 @@ module Sevgi
         false
       end
 
+      def inline_text? = node.text? && !node.content.match?(/[\r\n]/) && node.parent&.children&.any?(&:element?)
+
       private
 
+      def normalized_content = inline_text? ? node.content : node.content.strip
+
+      def local_namespaces
+        return {} unless node.respond_to?(:namespace_definitions)
+
+        node.namespace_definitions.to_h do |namespace|
+          [namespace.prefix ? "xmlns:#{namespace.prefix}" : "xmlns", namespace.href]
+        end
+      end
+
       def each_node
         current = node
 

data/lib/sevgi/derender/version.rb

@@ -3,6 +3,6 @@
 module Sevgi
   module Derender
     # Current version of the Sevgi derender gem.
-    VERSION = "0.93.1"
+    VERSION = "0.94.0"
   end
 end

data/lib/sevgi/derender.rb

@@ -5,32 +5,98 @@ require_relative "derender/internal"
 require_relative "derender/attributes"
 require_relative "derender/document"
 require_relative "derender/elements"
+require_relative "derender/evaluator"
 require_relative "derender/node"
 
 require_relative "derender/version"
 
 module Sevgi
   # Converts SVG/XML content into Sevgi DSL source or evaluates it into graphics elements.
+  #
+  # Evaluation APIs treat SVG/XML as data: they build graphics element trees directly and do not execute generated Ruby
+  # source. Malformed, rootless, or unmatched input is rejected with {Sevgi::ArgumentError}.
   module Derender
+    # @!method self.decompile(content, id: nil)
+    #   Converts SVG/XML content into a derender node.
+    #   @param content [String] SVG/XML source content
+    #   @param id [String, nil] optional SVG id selecting a node inside the source
+    #   @return [Sevgi::Derender::Node] selected node in the derender tree
+    #   @raise [Sevgi::ArgumentError] when content is malformed or rootless, or when the id is absent
+    # @!method self.decompile_file(file, id: nil)
+    #   Converts an SVG/XML file into a derender node.
+    #   @param file [String] path to the source SVG/XML file
+    #   @param id [String, nil] optional SVG id selecting a node inside the source
+    #   @return [Sevgi::Derender::Node] selected node in the derender tree
+    #   @raise [Sevgi::ArgumentError] when the file cannot be found, file content is malformed or rootless, or the id is
+    #     absent
+    # @!method self.derender(content, id: nil)
+    #   Converts SVG/XML content into Sevgi DSL Ruby source.
+    #   @param content [String] SVG/XML source content
+    #   @param id [String, nil] optional SVG id selecting a node inside the source
+    #   @return [String] formatted Sevgi DSL source
+    #   @raise [Sevgi::ArgumentError] when content is malformed or rootless, or when the id is absent
+    #   @raise [Sevgi::PanicError] when generated Ruby source cannot be formatted
+    # @!method self.derender_file(file, id: nil)
+    #   Converts an SVG/XML file into Sevgi DSL Ruby source.
+    #   @param file [String] path to the source SVG/XML file
+    #   @param id [String, nil] optional SVG id selecting a node inside the source
+    #   @return [String] formatted Sevgi DSL source
+    #   @raise [Sevgi::ArgumentError] when the file cannot be found, file content is malformed or rootless, or the id is
+    #     absent
+    #   @raise [Sevgi::PanicError] when generated Ruby source cannot be formatted
+    # @!method self.evaluate(content, element, id: nil)
+    #   Evaluates SVG/XML content under a graphics element, including the selected node.
+    #   @param content [String] SVG/XML source content
+    #   @param element [Sevgi::Graphics::Element] target graphics element
+    #   @param id [String, nil] optional SVG id selecting a node inside the source
+    #   @return [Sevgi::Graphics::Element, nil] included selected/root graphics element, or nil when the selected node
+    #     produces no graphics output
+    #   @raise [Sevgi::ArgumentError] when content is malformed or rootless, or when the id is absent
+    # @!method self.evaluate_children(content, element, id: nil)
+    #   Evaluates only the selected node's children under a graphics element.
+    #   @param content [String] SVG/XML source content
+    #   @param element [Sevgi::Graphics::Element] target graphics element
+    #   @param id [String, nil] optional SVG id selecting a node inside the source
+    #   @return [Array<Sevgi::Graphics::Element>] included child graphics elements
+    #   @raise [Sevgi::ArgumentError] when content is malformed or rootless, or when the id is absent
+    # @!method self.evaluate_file(file, element, id: nil)
+    #   Evaluates an SVG/XML file under a graphics element, including the selected node.
+    #   @param file [String] path to the source SVG/XML file
+    #   @param element [Sevgi::Graphics::Element] target graphics element
+    #   @param id [String, nil] optional SVG id selecting a node inside the source
+    #   @return [Sevgi::Graphics::Element, nil] included selected/root graphics element, or nil when the selected node
+    #     produces no graphics output
+    #   @raise [Sevgi::ArgumentError] when the file cannot be found, file content is malformed or rootless, or the id is
+    #     absent
+    # @!method self.evaluate_file_children(file, element, id: nil)
+    #   Evaluates only the selected node's children from an SVG/XML file under a graphics element.
+    #   @param file [String] path to the source SVG/XML file
+    #   @param element [Sevgi::Graphics::Element] target graphics element
+    #   @param id [String, nil] optional SVG id selecting a node inside the source
+    #   @return [Array<Sevgi::Graphics::Element>] included child graphics elements
+    #   @raise [Sevgi::ArgumentError] when the file cannot be found, file content is malformed or rootless, or the id is
+    #     absent
+
     # Converts SVG/XML content into a derender node.
     # @param content [String] SVG/XML source content
     # @param id [String, nil] optional SVG id selecting a node inside the source
     # @return [Sevgi::Derender::Node] selected node in the derender tree
-    # @raise [Sevgi::ArgumentError] when the id is absent
+    # @raise [Sevgi::ArgumentError] when content is malformed or rootless, or when the id is absent
     def decompile(content, id: nil) = Document.new(content).decompile(id)
 
     # Converts an SVG/XML file into a derender node.
     # @param file [String] path to the source SVG/XML file
     # @param id [String, nil] optional SVG id selecting a node inside the source
     # @return [Sevgi::Derender::Node] selected node in the derender tree
-    # @raise [Sevgi::ArgumentError] when the file cannot be found or the id is absent
+    # @raise [Sevgi::ArgumentError] when the file cannot be found, file content is malformed or rootless, or the id is
+    #   absent
     def decompile_file(file, id: nil) = Document.load_file(file).decompile(id)
 
     # Converts SVG/XML content into Sevgi DSL Ruby source.
     # @param content [String] SVG/XML source content
     # @param id [String, nil] optional SVG id selecting a node inside the source
     # @return [String] formatted Sevgi DSL source
-    # @raise [Sevgi::ArgumentError] when the id is absent
+    # @raise [Sevgi::ArgumentError] when content is malformed or rootless, or when the id is absent
     # @raise [Sevgi::PanicError] when generated Ruby source cannot be formatted
     def derender(content, id: nil) = Document.new(content).decompile(id).derender
 
@@ -38,7 +104,8 @@ module Sevgi
     # @param file [String] path to the source SVG/XML file
     # @param id [String, nil] optional SVG id selecting a node inside the source
     # @return [String] formatted Sevgi DSL source
-    # @raise [Sevgi::ArgumentError] when the file cannot be found or the id is absent
+    # @raise [Sevgi::ArgumentError] when the file cannot be found, file content is malformed or rootless, or the id is
+    #   absent
     # @raise [Sevgi::PanicError] when generated Ruby source cannot be formatted
     def derender_file(file, id: nil) = Document.load_file(file).decompile(id).derender
 
@@ -46,37 +113,39 @@ module Sevgi
     # @param content [String] SVG/XML source content
     # @param element [Sevgi::Graphics::Element] target graphics element
     # @param id [String, nil] optional SVG id selecting a node inside the source
-    # @return [Sevgi::Graphics::Element] target graphics element
-    # @raise [Sevgi::ArgumentError] when the id is absent
-    # @raise [Sevgi::PanicError] when generated Ruby source cannot be formatted
+    # @return [Sevgi::Graphics::Element, nil] included selected/root graphics element, or nil when the selected node
+    #   produces no graphics output
+    # @raise [Sevgi::ArgumentError] when content is malformed or rootless, or when the id is absent
     def evaluate(content, element, id: nil) = Document.new(content).decompile(id).evaluate(element)
 
-    # Evaluates an SVG/XML file under a graphics element, including the selected node.
-    # @param file [String] path to the source SVG/XML file
+    # Evaluates only the selected node's children under a graphics element.
+    # @param content [String] SVG/XML source content
     # @param element [Sevgi::Graphics::Element] target graphics element
     # @param id [String, nil] optional SVG id selecting a node inside the source
-    # @return [Sevgi::Graphics::Element] target graphics element
-    # @raise [Sevgi::ArgumentError] when the file cannot be found or the id is absent
-    # @raise [Sevgi::PanicError] when generated Ruby source cannot be formatted
-    def evaluate_file(file, element, id: nil) = Document.load_file(file).decompile(id).evaluate(element)
+    # @return [Array<Sevgi::Graphics::Element>] included child graphics elements
+    # @raise [Sevgi::ArgumentError] when content is malformed or rootless, or when the id is absent
+    def evaluate_children(content, element, id: nil) = Document.new(content).decompile(id).evaluate_children(element)
 
-    # Evaluates SVG/XML content under a graphics element, excluding the selected node itself.
-    # @param content [String] SVG/XML source content
+    # Evaluates an SVG/XML file under a graphics element, including the selected node.
+    # @param file [String] path to the source SVG/XML file
     # @param element [Sevgi::Graphics::Element] target graphics element
     # @param id [String, nil] optional SVG id selecting a node inside the source
-    # @return [Sevgi::Graphics::Element] target graphics element
-    # @raise [Sevgi::ArgumentError] when the id is absent
-    # @raise [Sevgi::PanicError] when generated Ruby source cannot be formatted
-    def evaluate!(content, element, id: nil) = Document.new(content).decompile(id).evaluate!(element)
+    # @return [Sevgi::Graphics::Element, nil] included selected/root graphics element, or nil when the selected node
+    #   produces no graphics output
+    # @raise [Sevgi::ArgumentError] when the file cannot be found, file content is malformed or rootless, or the id is
+    #   absent
+    def evaluate_file(file, element, id: nil) = Document.load_file(file).decompile(id).evaluate(element)
 
-    # Evaluates an SVG/XML file under a graphics element, excluding the selected node itself.
+    # Evaluates only the selected node's children from an SVG/XML file under a graphics element.
     # @param file [String] path to the source SVG/XML file
     # @param element [Sevgi::Graphics::Element] target graphics element
     # @param id [String, nil] optional SVG id selecting a node inside the source
-    # @return [Sevgi::Graphics::Element] target graphics element
-    # @raise [Sevgi::ArgumentError] when the file cannot be found or the id is absent
-    # @raise [Sevgi::PanicError] when generated Ruby source cannot be formatted
-    def evaluate_file!(file, element, id: nil) = Document.load_file(file).decompile(id).evaluate!(element)
+    # @return [Array<Sevgi::Graphics::Element>] included child graphics elements
+    # @raise [Sevgi::ArgumentError] when the file cannot be found, file content is malformed or rootless, or the id is
+    #   absent
+    def evaluate_file_children(file, element, id: nil)
+      Document.load_file(file).decompile(id).evaluate_children(element)
+    end
 
     extend self
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sevgi-derender
 version: !ruby/object:Gem::Version
-  version: 0.93.1
+  version: 0.94.0
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.93.1
+        version: 0.94.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.93.1
+        version: 0.94.0
 - !ruby/object:Gem::Dependency
   name: sevgi-graphics
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.93.1
+        version: 0.94.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.93.1
+        version: 0.94.0
 - !ruby/object:Gem::Dependency
   name: css_parser
   requirement: !ruby/object:Gem::Requirement
@@ -86,9 +86,10 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE
 - README.md
 - bin/igves
-- lib/sevgi/binaries/igsev.rb
 - lib/sevgi/binaries/igves.rb
 - lib/sevgi/derender.rb
 - lib/sevgi/derender/attributes.rb
@@ -99,6 +100,7 @@ files:
 - lib/sevgi/derender/elements/junk.rb
 - lib/sevgi/derender/elements/root.rb
 - lib/sevgi/derender/elements/text.rb
+- lib/sevgi/derender/evaluator.rb
 - lib/sevgi/derender/internal.rb
 - lib/sevgi/derender/node.rb
 - lib/sevgi/derender/version.rb
@@ -117,7 +119,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.4.0.pre.preview1
+      version: 3.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/lib/sevgi/binaries/igsev.rb

@@ -1,114 +0,0 @@
-# frozen_string_literal: true
-
-require "sevgi"
-
-module Sevgi
-  module Binaries
-    # Implements the `igsev` executable that derenders SVG and executes the generated Sevgi DSL.
-    module Igsev
-      extend self
-
-      # Executable name used in help output.
-      PROGNAME = "igsev"
-
-      # Error raised for invalid command-line usage.
-      Error = Class.new(::Sevgi::Error)
-
-      # Parsed command-line options for the `igsev` executable.
-      # @api private
-      Options = Struct.new(:require, :vomit, :help, :version) do
-        # Parses command-line options and removes them from the argv array.
-        # @param argv [Array<String>] mutable command-line argument array
-        # @return [Sevgi::Binaries::Igsev::Options] parsed options
-        # @raise [Sevgi::Binaries::Igsev::Error] when an option is not recognized
-        def self.parse(argv)
-          new.tap do |options|
-            argv.first.start_with?("-") ? option(argv, options) : break until argv.empty?
-          end
-        end
-
-        class << self
-          private
-
-          def option(argv, options)
-            case (arg = argv.shift)
-            when "-r", "--require"
-              options.require = argv.shift
-            when "-x", "--exception"
-              options.vomit = true
-
-            when "-h", "--help"
-              options.help = true
-            when "-v", "--version"
-              options.version = true
-            else
-              Error.("Not a valid option: #{arg}")
-            end
-          end
-        end
-      end
-
-      private_constant :Options
-
-      # Runs the `igsev` command-line interface.
-      # @param argv [Array<String>, String, nil] command-line arguments
-      # @return [nil]
-      # @raise [LoadError] when a required Ruby library cannot be loaded
-      # @raise [Sevgi::ArgumentError] when the SVG file cannot be found
-      # @raise [Sevgi::Executor::Error] when `--exception` or `SEVGI_VOMIT` requests raw errors
-      # @raise [Sevgi::PanicError] when generated Ruby source cannot be formatted
-      # @raise [SystemExit] when command-line usage or script execution aborts
-      def call(argv)
-        return puts(help) if (options = Options.parse(argv = Array(argv))).help
-        return puts(::Sevgi::VERSION) if options.version
-
-        result = run(file = argv.shift, options)
-
-        if result.error?
-          raise result.error if options.vomit || ENV[ENVVOMIT]
-
-          die(result.error, file)
-        else
-          result.recent.Out()
-        end
-
-      rescue Binaries::Igsev::Error => e
-        abort(e.message)
-      end
-
-      private
-
-      def die(error, _file)
-        warn(error.message)
-        warn("")
-        error.backtrace!.each { warn("  #{it}") }
-
-        exit(1)
-      end
-
-      def help
-        <<~HELP
-          Usage: #{PROGNAME} [options...] <SVG file>
-
-          See documentation for detailed help.
-
-          Options:
-
-          -r, --require LIB     Require Ruby LIB
-          -x, --exception       Raise exception instead of abort
-
-          -h, --help            Show this help
-          -v, --version         Display version
-        HELP
-      end
-
-      def run(file, options)
-        Error.("No SVG file given.") unless file
-
-        sevgi = Derender.derender_file(file)
-
-        ::Sevgi.execute(sevgi, require: options.require)
-      end
-    end
-  end
-end