sevgi-derender 0.73.2 → 0.94.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f93d7904c06fa7f3f220a38fa776e1e6cf31e8dbe7c1dba45616dc06f045a47c
-  data.tar.gz: 959530f54e652a97025fa83ff7a5799f45640772357059b890742faaa83768e4
+  metadata.gz: 9f1b7265f14be33da5b43f634ac82059a6d438e723ecc2153a062452ea1610fc
+  data.tar.gz: 5c52f4aef783cd3b3c712f19883ebbcab9c28efce3802318fe1b1f55b2a7fd88
 SHA512:
-  metadata.gz: e8d3d5908c4c9fb6d729152a59ebbf644434ca5d19ffae80c2e94599f13048e42ef9f00377a982c584a5bd6bffb018c7666de46b5b1051245e9d274505d98513
-  data.tar.gz: b360cb383d3967c847553288ba376c994c602eff23b539abdec42bebb613c9e35c15ba2f2fe06f782a7ce41ad50aea01979fce62d3b712153e17e1fe9087ad03
+  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

@@ -0,0 +1,44 @@
+# Sevgi Derender
+
+Converts SVG/XML content back into Sevgi DSL source.
+
+## 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/binaries/igves.rb

@@ -4,14 +4,23 @@ require "sevgi"
 
 module Sevgi
   module Binaries
+    # Implements the `igves` executable that converts SVG files into Sevgi DSL source.
     module Igves
       extend self
 
+      # Executable name used in help output.
       PROGNAME = "igves"
 
+      # Error raised for invalid command-line usage.
       Error = Class.new(::Sevgi::Error)
 
+      # Parsed command-line options for the `igves` executable.
+      # @api private
       Options = Struct.new(: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::Igves::Options] parsed options
+        # @raise [Sevgi::Binaries::Igves::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?
@@ -23,6 +32,8 @@ module Sevgi
 
           def option(argv, options)
             case (arg = argv.shift)
+            when "-x", "--exception"
+              options.vomit = true
             when "-h", "--help"
               options.help = true
             when "-v", "--version"
@@ -36,25 +47,49 @@ module Sevgi
 
       private_constant :Options
 
+      # Runs the `igves` command-line interface.
+      # @param argv [Array<String>, String, nil] command-line arguments
+      # @return [nil]
+      # @raise [Sevgi::ArgumentError] when the SVG file cannot be found
+      # @raise [Sevgi::PanicError] when generated Ruby source cannot be formatted
+      # @raise [StandardError] when `--exception` or `SEVGI_VOMIT` requests raw errors
+      # @raise [SystemExit] when command-line usage aborts
       def call(argv)
-        return puts(help) if (options = Options.parse(argv = Array(argv))).help
-        return puts(::Sevgi::VERSION) if options.version
-
-        puts(run(argv.shift, options))
+        dispatch(Array(argv))
       rescue Binaries::Igves::Error => e
         abort(e.message)
       end
 
       private
 
+      def dispatch(argv)
+        options = Options.parse(argv)
+        return puts(help) if options.help
+        return puts(::Sevgi::VERSION) if options.version
+
+        print_file(argv.shift, options)
+      rescue Binaries::Igves::Error
+        raise
+      rescue ::StandardError => e
+        raise if raw_error?(options)
+
+        die(e, nil)
+      end
+
       def die(error, _file)
         warn(error.message)
         warn("")
-        error.backtrace!.each { warn("  #{it}") }
+        backtrace(error).each { warn("  #{it}") }
 
         exit(1)
       end
 
+      def backtrace(error)
+        return error.backtrace! if error.respond_to?(:backtrace!)
+
+        error.backtrace || []
+      end
+
       def help
         <<~HELP
           Usage: #{PROGNAME} [options...] <SVG file>
@@ -74,6 +109,20 @@ module Sevgi
 
         Derender.derender_file(file)
       end
+
+      def print_file(file, options)
+        puts(run(file, options))
+      rescue Binaries::Igves::Error
+        raise
+      rescue ::StandardError => e
+        raise if raw_error?(options)
+
+        die(e, file)
+      end
+
+      def raw_error?(options)
+        options&.vomit || ENV.fetch(ENVVOMIT, nil)
+      end
     end
   end
 end

data/lib/sevgi/derender/attributes.rb

@@ -2,7 +2,10 @@
 
 module Sevgi
   module Derender
+    # Converts SVG/XML attribute hashes into Sevgi DSL keyword source.
+    # @api private
     module Attributes
+      # Attribute keys rendered before ordinary attributes.
       ATTRIBUTES_SHOULD_COME_FIRST = %w[
         id
         inkscape:label
@@ -14,11 +17,17 @@ module Sevgi
         xmlns:_
       ]
         .freeze
+
+      # Attribute keys rendered after ordinary attributes.
       ATTRIBUTES_SHOULD_COME_LAST = %w[
         style
       ].freeze
 
+      # Converts an attribute hash into Sevgi DSL keyword source.
+      # @param hash [Hash{String, Symbol => Object}] attributes to render
+      # @return [String] Ruby keyword or hash source
       def decompile(hash)
+        hash = hash.dup
         pre, post = {}, {}
 
         ATTRIBUTES_SHOULD_COME_FIRST.each { |key| pre[key] = hash.delete(key) if hash.key?(key) }
@@ -29,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)
@@ -38,7 +48,7 @@ module Sevgi
               value
             end => value
 
-            key.match?(/\W/) ? "\"#{key}\": #{value}" : "#{key}: #{value}"
+            key.match?(/\W/) ? "#{Ruby.literal(key)}: #{value}" : "#{key}: #{value}"
           end
           .join(", ")
       end

data/lib/sevgi/derender/document.rb

@@ -4,46 +4,74 @@ require "nokogiri"
 
 module Sevgi
   module Derender
+    # Parsed SVG/XML document wrapper used by the derender pipeline.
     class Document
-      @cache = {}
-
-      class << self
-        attr_reader :cache
-      end
-
+      # 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 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"))
 
         ArgumentError.("File not found: #{path}") unless ::File.exist?(entry)
 
-        new(::File.read(entry)) do
-          @doc = self.class.cache[entry] ||
-            begin
-              self.class.cache[entry] = self.class.parse(::File.read(entry))
-            end
-        end
+        content = ::File.read(entry)
+        new(content)
       end
 
-      def self.parse(content) = Nokogiri::XML(content)
+      # Parses SVG/XML content in strict XML mode.
+      # @param content [String] SVG/XML source content
+      # @return [Nokogiri::XML::Document] parsed XML document
+      # @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
+      #   @return [Nokogiri::XML::Document] parsed XML document
+      # @!attribute [r] decl
+      #   @return [String, nil] XML declaration line, if present
       attr_reader :doc, :decl
 
+      # Builds a parsed document wrapper from SVG/XML content.
+      # @param content [String] SVG/XML source content
+      # @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
 
-        @doc = self.class.parse(content)
+        @doc ||= self.class.parse(content)
         @decl = self.class.declaration(content)
       end
 
+      # 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 document has no root element or the id is absent
       def decompile(id = nil)
         if id
-          if (found = doc.xpath("//*[@id='#{id}']") || []).empty?
+          if (found = doc.xpath("//*[@id=#{xpath_literal(id)}]") || []).empty?
             ArgumentError.("No such element with id '#{id}' in document")
           end
 
@@ -52,15 +80,46 @@ 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.
+      # @return [Array<String>] preamble XML lines
       def pres
         @pres ||= [].tap do |lines|
           lines.append(*doc.children.take_while { |node| node != doc.root }.map(&:to_xml))
           lines.unshift(decl) unless lines.first == decl
         end
       end
+
+      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
+
+        return "'#{value}'" unless value.include?("'")
+        return "\"#{value}\"" unless value.include?("\"")
+
+        parts = value.split("'", -1).flat_map.with_index do |part, index|
+          index.zero? ? [part] : ["'", part]
+        end
+
+        "concat(#{parts.map { |part| part == "'" ? "\"'\"" : "'#{part}'" }.join(", ")})"
+      end
     end
   end
 end

data/lib/sevgi/derender/elements/any.rb

@@ -3,7 +3,11 @@
 module Sevgi
   module Derender
     module Elements
+      # Default element strategy for ordinary SVG/XML elements.
+      # @api private
       module Any
+        # Converts this node into unformatted Sevgi DSL lines.
+        # @return [Array<String>] unformatted Ruby source lines
         def decompile(*)
           if children.any?
             children.one? && children.first.node.text? ? Array(leaf(has_attributes: attributes.any?)) : tree
@@ -16,11 +20,11 @@ module Sevgi
 
         def leaf(has_content: true, has_attributes: true)
           attributes = attributes!
-          [
-            element,
-            *("'#{content}', " if has_content),
-            *(Attributes.decompile(attributes) if has_attributes)
-          ].join(" ")
+          args = []
+          args << Ruby.literal(content) if has_content
+          args << Attributes.decompile(attributes) if has_attributes && attributes.any?
+
+          args.empty? ? element : "#{element} #{args.join(", ")}"
         end
 
         def tree

data/lib/sevgi/derender/elements/css.rb

@@ -1,10 +1,13 @@
-#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 module Sevgi
   module Derender
     module Elements
+      # Element strategy for SVG style elements.
+      # @api private
       module CSS
+        # Converts a style node into unformatted Sevgi DSL lines.
+        # @return [Array<String>] unformatted Ruby source lines
         def decompile(*)
           return [] unless (lines = css_lines)
 
@@ -24,7 +27,7 @@ module Sevgi
           hash
             .map do |selector, declarations|
               [
-                "\"#{selector}\": {",
+                "#{Ruby.literal(selector)}: {",
                 *declarations.map { |key, value| "#{Css.to_key_value(key, value)}," },
                 "},"
               ]

data/lib/sevgi/derender/elements/junk.rb

@@ -1,10 +1,13 @@
-#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 module Sevgi
   module Derender
     module Elements
+      # Element strategy for comments and ignored XML nodes.
+      # @api private
       module Junk
+        # Drops ignored nodes from generated source.
+        # @return [Array<String>] empty source lines
         def decompile(*) = []
       end
     end

data/lib/sevgi/derender/elements/root.rb

@@ -3,9 +3,14 @@
 module Sevgi
   module Derender
     module Elements
+      # Element strategy for the SVG root element.
+      # @api private
       module Root
         include Any
 
+        # Converts the SVG root into unformatted Sevgi DSL lines.
+        # @param pres [Array<String>] preamble XML lines
+        # @return [Array<String>] unformatted Ruby source lines
         def decompile(pres = [])
           lines = super
           return lines unless pres&.any?
@@ -13,15 +18,19 @@ module Sevgi
           lines.unshift(
             [
               "SVG.document preambles: [",
-              *pres.map { "'#{it}'," },
+              *pres.map { "#{Ruby.literal(it)}," },
               "]",
               ""
             ]
           )
         end
 
+        # Returns the root DSL word.
+        # @return [String]
         def element = "SVG"
 
+        # Returns root attributes merged with namespace declarations.
+        # @return [Hash{String => String}] attributes and namespaces
         def attributes! = {**attributes, **namespaces}
       end
     end

data/lib/sevgi/derender/elements/text.rb

@@ -1,11 +1,14 @@
-#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 module Sevgi
   module Derender
     module Elements
+      # Element strategy for text nodes.
+      # @api private
       module Text
-        def decompile(*) = ["_ #{content}"]
+        # Converts a text node into unformatted Sevgi DSL lines.
+        # @return [Array<String>] unformatted Ruby source lines
+        def decompile(*) = ["_ #{Ruby.literal(content)}"]
       end
     end
   end

data/lib/sevgi/derender/elements.rb

@@ -1,5 +1,14 @@
 # frozen_string_literal: true
 
+module Sevgi
+  module Derender
+    # Element strategy modules mixed into derender nodes according to XML node type.
+    # @api private
+    module Elements
+    end
+  end
+end
+
 require_relative "elements/any"
 require_relative "elements/css"
 require_relative "elements/junk"

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

@@ -4,37 +4,70 @@ require "sevgi/function"
 
 module Sevgi
   module Derender
+    # CSS parser and formatter helpers used while derendering attributes and style nodes.
+    # @api private
     module Css
       require "css_parser"
 
+      # Parses CSS rules into a selector/declaration hash.
+      # @param css_string [String] CSS rule source
+      # @return [Hash, nil] parsed CSS declarations grouped by selector
       def to_h(css_string)
         parser = ::CssParser::Parser.new
         parser.load_string!(css_string)
         parser.to_h["all"]
       end
 
-      def to_h!(style_string) = to_h("* { #{style_string} }")["*"]
+      # 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)
+        hash = to_h("* { #{style_string} }")
 
+        hash ? hash.fetch("*", {}) : {}
+      end
+
+      # Converts a CSS key into a Ruby hash key.
+      # @param arg [String] CSS key
+      # @return [String] Ruby hash key source
       def to_key(arg) = arg
 
-      def to_key_value(key, value) = "\"#{to_key(key)}\": #{to_value(value)}"
+      # Converts a CSS key/value pair into Ruby hash source.
+      # @param key [String] CSS declaration key
+      # @param value [String] CSS declaration value
+      # @return [String] Ruby hash pair source
+      def to_key_value(key, value) = "#{Ruby.literal(to_key(key))}: #{to_value(value)}"
 
-      def to_value(arg) = (arg.to_f.to_s == arg) || (arg.to_i.to_s == arg) ? arg : "\"#{arg}\""
+      # Converts a CSS value into Ruby source.
+      # @param arg [String] CSS value
+      # @return [String] Ruby literal or numeric source
+      def to_value(arg) = (arg.to_f.to_s == arg) || (arg.to_i.to_s == arg) ? arg : arg.inspect
 
       extend self
     end
 
     private_constant :Css
 
+    # Ruby source formatting helpers used by the derender pipeline.
+    # @api private
     module Ruby
       require "rufo"
 
+      # Formats generated Ruby source.
+      # @param unformatted_ruby [String] unformatted Ruby source
+      # @return [String] formatted Ruby source
+      # @raise [Sevgi::PanicError] when source cannot be parsed by the formatter
       def format(unformatted_ruby)
         Rufo::Formatter.format(unformatted_ruby)
       rescue Rufo::SyntaxError
-        raise unformatted_ruby
+        PanicError.(unformatted_ruby)
       end
 
+      # Converts a value into a Ruby string literal.
+      # @param value [Object] value to stringify
+      # @return [String] Ruby string literal source
+      def literal(value) = value.to_s.inspect
+
       extend self
     end
 

data/lib/sevgi/derender/node.rb

@@ -2,17 +2,34 @@
 
 module Sevgi
   module Derender
+    # Node in a derender tree produced from an SVG/XML node.
     class Node
+      # @!attribute [r] node
+      #   @return [Nokogiri::XML::Node] source XML node
+      # @!attribute [r] pres
+      #   @return [Array<String>] preamble XML lines carried by the root node
+      # @!attribute [r] type
+      #   @return [Symbol] dispatch type used by derender element strategies
       attr_reader :node, :pres, :type
 
-      def initialize(node, pres = [])
+      # 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 = [], namespaces: nil)
         @node = node
         @pres = pres
+        @namespaces = namespaces
         @type = dispatch
       end
 
+      # Attribute namespace prefix used for Sevgi metadata.
       META_NAMESPACE = "_:"
 
+      # Returns Sevgi metadata attributes without the metadata namespace prefix.
+      # @return [Hash{String => String}] metadata attributes
       def _
         @_ ||= attributes
           .slice(
@@ -23,76 +40,147 @@ module Sevgi
 
       alias meta _
 
-      def attributes
-        @attributes ||= node.attribute_nodes.to_h do |attr|
-          name, value = attr.name, attr.value
+      # Returns source XML attributes keyed with namespace prefixes when present.
+      # @return [Hash{String => String}] XML attributes
+      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
-
-      def attributes! = attributes
+      # Returns source XML attributes and namespace declarations emitted on this node.
+      # @return [Hash{String => String}] XML attributes
+      def attributes! = {**attributes, **namespaces}
 
+      # Returns non-ignorable child derender nodes.
+      # @return [Array<Sevgi::Derender::Node>] child nodes
       def children
-        @children ||= node.children.map { |child| self.class.new(child) }.reject do |child|
-          (child.node.text? and child.node.text.strip.empty?) or child.type == :Junk
-        end
+        @children ||= node
+          .children
+          .map { |child| self.class.new(child) }
+          .reject { |child| ignorable_child?(child) }
       end
 
-      def content = @content ||= node.content.strip
+      # 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 : normalized_content
 
+      # Converts this node into formatted Sevgi DSL Ruby source.
+      # @return [String] formatted Sevgi DSL source
+      # @raise [Sevgi::PanicError] when generated Ruby source cannot be formatted
       def derender = Ruby.format(decompile(pres).join("\n"))
 
+      # Returns the Sevgi DSL element name for this node.
+      # @return [String]
       def element = name
 
+      # 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, 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
 
-      def evaluate!(element) = evaluate(element, false)
+      # Evaluates only this node's children under a graphics element.
+      # @param element [Sevgi::Graphics::Element] target graphics element
+      # @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
+      # @param by [String] attribute name used for lookup
+      # @return [Sevgi::Derender::Node, nil] matching node, or nil
       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
 
-      def namespaces = (@namespaces ||= node.namespaces.to_h { |namespace, uri| [namespace, uri] })
+      # Returns source XML namespace declarations emitted on this node.
+      # @return [Hash{String => String}] namespace declarations
+      def namespaces = (@namespaces ||= local_namespaces)
 
+      # Reports whether this node is the SVG root strategy.
+      # @return [Boolean]
       def root? = type == :Root
 
       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
         end
           .tap { extend(Elements.const_get(it)) }
       end
+
+      def ignorable_child?(child)
+        child.type == :Junk ||
+          (child.node.text? && child.node.text.strip.empty? && !child.preserve_space? && !child.inline_text?)
+      end
+
+      protected
+
+      def preserve_space?
+        each_node do |current|
+          case xml_space(current)
+          when "preserve"
+            return true
+          when "default"
+            return false
+          end
+        end
+
+        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
+
+        while current
+          yield current
+          current = current.respond_to?(:parent) ? current.parent : nil
+        end
+      end
+
+      def xml_space(current)
+        return unless current.respond_to?(:attribute_nodes)
+
+        current.attribute_nodes.find { xml_space_attribute?(it) }&.value
+      end
+
+      def xml_space_attribute?(attribute) = attribute.name == "space" && attribute.namespace&.prefix == "xml"
     end
   end
 end

data/lib/sevgi/derender/version.rb

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

data/lib/sevgi/derender.rb

@@ -5,27 +5,147 @@ 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
-    # Takes SVG (XML content) and returns a Derender::Node object.
+    # @!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 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, file content is malformed or rootless, or the id is
+    #   absent
     def decompile_file(file, id: nil) = Document.load_file(file).decompile(id)
 
-    # Takes SVG (XML content) and returns Sevgi DSL string (formatted Ruby content).
+    # 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
     def derender(content, id: nil) = Document.new(content).decompile(id).derender
+
+    # 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
     def derender_file(file, id: nil) = Document.load_file(file).decompile(id).derender
 
-    # Takes SVG (XML content), evaluates it under the given Graphics element and returns the element.
+    # 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
     def evaluate(content, element, id: nil) = Document.new(content).decompile(id).evaluate(element)
+
+    # 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
+    def evaluate_children(content, element, id: nil) = Document.new(content).decompile(id).evaluate_children(element)
+
+    # 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
     def evaluate_file(file, element, id: nil) = Document.load_file(file).decompile(id).evaluate(element)
 
-    # Takes SVG (XML content), evaluates the inner node under the given Graphics element and returns the element.
-    def evaluate!(content, element, id: nil) = Document.new(content).decompile(id).evaluate!(element)
-    def evaluate_file!(file, element, id: nil) = Document.load_file(file).decompile(id).evaluate!(element)
+    # 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
+    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.73.2
+  version: 0.94.0
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.73.2
+        version: 0.94.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.73.2
+        version: 0.94.0
 - !ruby/object:Gem::Dependency
   name: sevgi-graphics
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.73.2
+        version: 0.94.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.73.2
+        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,97 +0,0 @@
-# frozen_string_literal: true
-
-require "sevgi"
-
-module Sevgi
-  module Binaries
-    module Igsev
-      extend self
-
-      PROGNAME = "igsev"
-
-      Error = Class.new(::Sevgi::Error)
-
-      Options = Struct.new(:require, :vomit, :help, :version) do
-        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
-
-      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