sevgi-derender 0.73.2 → 0.93.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f93d7904c06fa7f3f220a38fa776e1e6cf31e8dbe7c1dba45616dc06f045a47c
-  data.tar.gz: 959530f54e652a97025fa83ff7a5799f45640772357059b890742faaa83768e4
+  metadata.gz: 126f64b403fbdff8cea203ad63c4857bf45254f2c513c9058db6803d8137414c
+  data.tar.gz: c531615d9b46226cf9bf35f1c828f18e678f6e148438b880337615b38da4301b
 SHA512:
-  metadata.gz: e8d3d5908c4c9fb6d729152a59ebbf644434ca5d19ffae80c2e94599f13048e42ef9f00377a982c584a5bd6bffb018c7666de46b5b1051245e9d274505d98513
-  data.tar.gz: b360cb383d3967c847553288ba376c994c602eff23b539abdec42bebb613c9e35c15ba2f2fe06f782a7ce41ad50aea01979fce62d3b712153e17e1fe9087ad03
+  metadata.gz: 8aea4ef742bba26cfd22a502fb1f761b476dd4dfb2bcd0573120e121c0853e9892abedd5f70d51203869b5052a5df2017fb285d448c8029dd1ab308a23b5ec67
+  data.tar.gz: 9447d2fc113a2eb97475ea2f2fe618e9e293573097908e7ea264fd95b10124ce8edce72ee5678e802d016fa26459e5bfea63ca6ea559b2522876f9e66ecd077f

data/README.md

@@ -0,0 +1,5 @@
+# Sevgi Derender
+
+Converts SVG/XML content back into Sevgi DSL source.
+
+See the root [README](../README.md) and the documentation site for usage.

data/lib/sevgi/binaries/igsev.rb

@@ -4,14 +4,23 @@ 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?
@@ -41,6 +50,14 @@ module Sevgi
 
       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

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) }
@@ -38,7 +47,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,73 @@ require "nokogiri"
 
 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.
+      # @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 [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
+        content = ::File.read(entry)
+        new(content) do
           @doc = self.class.cache[entry] ||
             begin
-              self.class.cache[entry] = self.class.parse(::File.read(entry))
+              self.class.cache[entry] = self.class.parse(content)
             end
         end
       end
 
+      # Parses SVG/XML content.
+      # @param content [String] SVG/XML source content
+      # @return [Nokogiri::XML::Document] parsed XML document
       def self.parse(content) = Nokogiri::XML(content)
 
+      # 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 ")
 
         content.split("\n").first
       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]
       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 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
 
@@ -55,12 +82,29 @@ module Sevgi
         Node.new(element, pres)
       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 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/internal.rb

@@ -4,37 +4,66 @@ 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
 
+      # 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} }")["*"]
 
+      # 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,31 @@
 
 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
 
+      # Builds a derender node.
+      # @param node [Nokogiri::XML::Node] source XML node
+      # @param pres [Array<String>] preamble XML lines carried by the root node
+      # @return [void]
       def initialize(node, pres = [])
         @node = node
         @pres = pres
         @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,6 +37,8 @@ module Sevgi
 
       alias meta _
 
+      # 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
@@ -37,28 +53,53 @@ module Sevgi
         end
       end
 
+      # Returns source XML attributes.
+      # @return [Hash{String => String}] XML attributes
       def attributes! = attributes
 
+      # 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, preserving or stripping whitespace according to xml:space.
+      # @return [String]
+      def content = @content ||= preserve_space? ? node.content : node.content.strip
 
+      # 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] target graphics element
+      # @raise [Sevgi::PanicError] when generated Ruby source cannot be formatted
       def evaluate(element, include_current = true)
         return element.instance_eval(derender) if include_current
 
         children.each { element.instance_eval(it.derender) }
       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)
 
+      # 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
 
@@ -71,10 +112,16 @@ module Sevgi
         nil
       end
 
+      # Returns the source XML node name.
+      # @return [String]
       def name = @name ||= node.name
 
+      # Returns source XML namespaces.
+      # @return [Hash{String => String}] namespace declarations
       def namespaces = (@namespaces ||= node.namespaces.to_h { |namespace, uri| [namespace, uri] })
 
+      # Reports whether this node is the SVG root strategy.
+      # @return [Boolean]
       def root? = type == :Root
 
       private
@@ -93,6 +140,44 @@ module Sevgi
         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?)
+      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
+
+      private
+
+      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.93.1"
   end
 end

data/lib/sevgi/derender.rb

@@ -10,21 +10,72 @@ require_relative "derender/node"
 require_relative "derender/version"
 
 module Sevgi
+  # Converts SVG/XML content into Sevgi DSL source or evaluates it into graphics elements.
   module Derender
-    # Takes SVG (XML content) and returns a Derender::Node object.
+    # 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
     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
     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 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 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] 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)
+
+    # 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 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)
 
-    # Takes SVG (XML content), evaluates the inner node under the given Graphics element and returns the element.
+    # Evaluates SVG/XML content under a graphics element, excluding the selected node itself.
+    # @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
     def evaluate!(content, element, id: nil) = Document.new(content).decompile(id).evaluate!(element)
+
+    # Evaluates an SVG/XML file under a graphics element, excluding the selected node itself.
+    # @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)
 
     extend self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sevgi-derender
 version: !ruby/object:Gem::Version
-  version: 0.73.2
+  version: 0.93.1
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.73.2
+        version: 0.93.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.73.2
+        version: 0.93.1
 - !ruby/object:Gem::Dependency
   name: sevgi-graphics
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.73.2
+        version: 0.93.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.73.2
+        version: 0.93.1
 - !ruby/object:Gem::Dependency
   name: css_parser
   requirement: !ruby/object:Gem::Requirement