sevgi 0.94.0 → 0.98.2

data/lib/sevgi/executor/source.rb

@@ -4,31 +4,48 @@ module Sevgi
   class Executor
     # Describes Ruby source evaluated by the Sevgi executor.
     # @api private
-    Source = Data.define(:string, :file, :line) do
-      # @overload call(string:, file: nil, line: nil)
+    Source = Data.define(:string, :file, :line, :origin) do
+      # @overload call(string:, file: nil, line: nil, origin: nil)
       #   Builds a source object.
       #   @param string [String] Ruby source string
       #   @param file [String, nil] source file name for diagnostics
       #   @param line [Integer, nil] starting source line for diagnostics
+      #   @param origin [String, nil] physical source path used for load-cycle identity
       #   @return [Sevgi::Executor::Source] source object
       def self.call(...) = new(...)
 
       # Builds a source object from a file.
       # @param file [String] source file to read
+      # @param as [String, nil] logical source name used for evaluation and diagnostics
       # @return [Sevgi::Executor::Source] source object with file contents
       # @raise [Errno::ENOENT] when the file cannot be read
-      def self.load(file) = new(string: ::File.read(file), file: file, line: 1)
+      def self.load(file, as: nil) = new(string: ::File.read(file), file: as || file, line: 1, origin: file)
 
       # Creates a source object.
       # @param string [String] Ruby source string
       # @param file [String, nil] source file name for diagnostics
       # @param line [Integer, nil] starting source line for diagnostics
+      # @param origin [String, nil] physical source path used for load-cycle identity
       # @return [void]
-      def initialize(string:, file: nil, line: nil) = super(string:, file: file || "sevgi", line: line || 1)
+      def initialize(string:, file: nil, line: nil, origin: nil)
+        super(string:, file: file || "sevgi", line: line || 1, origin:)
+      end
+
+      private_class_method :[]
 
       # Returns the stack key used for this source.
       # @return [String] source file name
       def key = file
+
+      # Returns the canonical identity used for active-load cycle detection.
+      # @return [Integer, String] object identity for inline source, or canonical physical identity for loaded source
+      def identity
+        return object_id unless origin
+
+        ::File.realpath(origin)
+      rescue ::SystemCallError
+        ::File.expand_path(origin)
+      end
     end
   end
 end

data/lib/sevgi/executor.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
-require "singleton"
+require "sevgi/function"
 
 require_relative "executor/error"
+require_relative "executor/result"
 require_relative "executor/scope"
 require_relative "executor/source"
 
 module Sevgi
-  # Executes Sevgi script source inside an isolated module scope.
+  # Internal Sevgi script runtime and namespace for public execution result types.
   #
   # The executor is used by script mode and by the `Load` DSL word to preserve a
   # useful load stack while keeping DSL methods out of the caller's global object
@@ -16,156 +17,189 @@ module Sevgi
   # state. The process SIGINT handler is shared by Ruby, so executor runs guard it
   # with a reference-counted critical section and restore the previous handler
   # after the last active execution finishes.
+  #
+  # Consumers execute the full DSL through {Sevgi.execute} or {Sevgi.execute_file}, then inspect {Executor::Result},
+  # {Executor::Error}, and {Executor::CycleError}. The custom receiver and boot lifecycle is internal plumbing for the
+  # top-level API and Rake integration.
+  #
+  # @see https://sevgi.roktas.dev/execution/ Execution guide
   class Executor
-    include Singleton
+    private_class_method :new
+    private_constant :Scope
 
     # Thread-current key used for the fiber-local executor scope stack.
     # @api private
     SCOPE_KEY = :sevgi_executor_scopes
-    private_constant :SCOPE_KEY, :Source
+    SOURCE_LINE_MAX = (2 ** 31) - 1
+    private_constant :SCOPE_KEY, :SOURCE_LINE_MAX, :Source
+
+    # Owns mutable execution and process-signal state outside the public executor surface.
+    # @api private
+    class State
+      def initialize
+        @signal_count = 0
+        @signal_mutex = Mutex.new
+        @signal_previous = nil
+      end
+
+      def create(scope = nil) = Scope.new(scope).tap { scopes << it }
+      def current = scopes.last
+
+      def restore
+        @signal_mutex.synchronize do
+          next if @signal_count.zero?
+
+          @signal_count -= 1
+          next unless @signal_count.zero?
+
+          Signal.trap("INT", @signal_previous)
+          @signal_previous = nil
+        end
+      end
+
+      def shutdown(scope = nil)
+        return scopes.pop unless scope
+        return scopes.pop if scopes.last.equal?(scope)
+
+        scopes.delete(scope)
+      end
+
+      def trap
+        @signal_mutex.synchronize do
+          @signal_previous = Signal.trap("INT") { Kernel.abort("") } if @signal_count.zero?
+          @signal_count += 1
+        end
+      end
+
+      private
+
+      def scopes = Thread.current[SCOPE_KEY] ||= []
+    end
+
+    STATE = State.new
+    private_constant :STATE, :State
 
     # Loads a script file inside the current executor scope.
     # @param file [String] path to a Sevgi script file
-    # @return [Sevgi::Executor::Scope] current execution scope
+    # @return [Sevgi::Executor::Scope] current internal execution scope
     # @raise [Sevgi::PanicError] when there is no active executor scope
     # @note Uses the active executor scope from the current fiber.
     # @api private
     def self.load(file, ...)
-      PanicError.("box stack empty; create a box first") unless instance.current
+      PanicError.("box stack empty; create a box first") unless STATE.current
 
-      instance.current.load(file, ...)
+      STATE.current.load(file, ...)
     end
 
+    private_class_method :load
+
     # Executes Ruby source inside a managed Sevgi script scope.
     # @param string [String] source to evaluate
     # @param file [String, nil] source file name used for errors and backtraces
     # @param line [Integer, nil] starting source line used for errors and backtraces
     # @param require [String, nil] optional Ruby library to require before execution
-    # @param receiver [Object, nil] receiver used while booting the DSL
+    # @param receiver [Object, nil] receiver used verbatim while booting the DSL; nil selects the isolated execution
+    #   module, while false and other executable objects remain explicit receivers
     # @yield optional boot block that installs DSL methods before evaluation
     # @yieldreturn [void]
-    # @return [Sevgi::Executor::Scope, nil] execution scope, or nil for empty source
-    # @note Required-library load failures are captured as {Sevgi::Executor::Error} on the returned scope.
+    # @return [Sevgi::Executor::Result] immutable execution result
+    # @raise [Sevgi::ArgumentError] when source, file, line, required library, or receiver is invalid
+    # @note Script and required-library failures are captured in {Sevgi::Executor::Result#error}; inspect
+    #   {Sevgi::Executor::Error#cause} for the original exception.
+    # @note Empty source without `require:` is a strict no-op: no scope is created, the receiver and boot block are
+    #   unused, and the result stack is empty. Supplying `require:` uses the normal boot and evaluation lifecycle.
     # @note Reentrant and concurrent calls keep independent scope stacks per fiber. The temporary SIGINT handler remains
     #   process-global while any execution is active.
+    # @api private
     def self.execute(string, file: nil, line: nil, require: nil, receiver: nil, &block)
+      validate_source!(string, file, line)
+      validate_context!(require, receiver)
+
       execute_source(Source.new(string:, file:, line:), require:, receiver:, &block)
     end
 
     # Executes a file inside a managed Sevgi script scope.
     # @param file [String] source file to read and execute
+    # @param as [String, nil] logical source name used for evaluation and diagnostics
     # @param require [String, nil] optional Ruby library to require before execution
-    # @param receiver [Object, nil] receiver used while booting the DSL
+    # @param receiver [Object, nil] receiver used verbatim while booting the DSL; nil selects the isolated execution
+    #   module, while false and other executable objects remain explicit receivers
     # @yield optional boot block that installs DSL methods before evaluation
     # @yieldreturn [void]
-    # @return [Sevgi::Executor::Scope, nil] execution scope, or nil for an empty file
-    # @note File-read and required-library load failures are captured as {Sevgi::Executor::Error} on the returned scope.
+    # @return [Sevgi::Executor::Result] immutable execution result
+    # @raise [Sevgi::ArgumentError] when file, logical source name, required library, or receiver is invalid
+    # @note File-read, script, and required-library failures are captured in {Sevgi::Executor::Result#error}; inspect
+    #   {Sevgi::Executor::Result#stack} for nested loads.
+    # @note An empty file without `require:` is a strict no-op: no scope is created, the receiver and boot block are
+    #   unused, and the result stack is empty. Supplying `require:` uses the normal boot and evaluation lifecycle.
     # @note Reentrant and concurrent calls keep independent scope stacks per fiber. The temporary SIGINT handler remains
     #   process-global while any execution is active.
-    def self.execute_file(file, require: nil, receiver: nil, &block)
+    # @api private
+    def self.execute_file(file, as: nil, require: nil, receiver: nil, &block)
+      ArgumentError.("Executor file must be a String") unless file.is_a?(::String)
+      ArgumentError.("Executor logical file must be a String or nil") unless as.nil? || as.is_a?(::String)
+      validate_context!(require, receiver)
+
       source = nil
       begin
-        source = Source.load(file)
+        source = Source.load(file, as:)
       rescue ::SystemCallError => e
-        return capture_error(Source.new(string: "", file:, line: 1), e)
+        return capture_error(Source.new(string: "", file: as || file, line: 1, origin: file), e)
       end
 
       execute_source(source, require:, receiver:, &block)
     end
 
-    # Removes the current executor scope.
-    # @return [Sevgi::Executor::Scope, nil] removed scope
-    # @api private
-    def self.shutdown
-      instance.shutdown
-    end
-
-    def initialize
-      @signal_count = 0
-      @signal_mutex = Mutex.new
-      @signal_previous = nil
-    end
+    private_class_method :execute, :execute_file
 
-    # Creates and pushes a new executor scope.
-    # @param scope [Module, nil] existing module scope to reuse
-    # @return [Sevgi::Executor::Scope] created scope
-    # @api private
-    def create(scope = nil) = Scope.new(scope).tap { scopes << it }
+    class << self
+      private
 
-    # Returns the active executor scope.
-    # @return [Sevgi::Executor::Scope, nil] active scope, if any
-    # @api private
-    def current = scopes.last
-
-    # Restores the process SIGINT handler when the last active execution ends.
-    # @return [void]
-    # @api private
-    def restore
-      @signal_mutex.synchronize do
-        next if @signal_count.zero?
-
-        @signal_count -= 1
-        next unless @signal_count.zero?
-
-        Signal.trap("INT", @signal_previous)
-        @signal_previous = nil
+      def capture_error(source, error)
+        acquired = STATE.trap
+        scope = STATE.create
+        scope.capture(source, error).result
+      ensure
+        STATE.restore if acquired
+        STATE.shutdown(scope) if scope
       end
-    end
 
-    # Removes the active executor scope.
-    # @param scope [Sevgi::Executor::Scope, nil] exact scope to remove, or nil to pop the current scope
-    # @return [Sevgi::Executor::Scope, nil] removed scope
-    # @api private
-    def shutdown(scope = nil)
-      return scopes.pop unless scope
-      return scopes.pop if scopes.last.equal?(scope)
+      def execute_source(source, require:, receiver:, &block)
+        acquired = false
+        return Result.new(value: nil, error: nil, stack: []) if source.string.empty? && require.nil?
 
-      scopes.delete(scope)
-    end
+        acquired = STATE.trap
+        scope = STATE.create
+        catch(:result) { run_source(scope, source, require, receiver, &block) }
+        scope.result
 
-    # Installs the process SIGINT handler while one or more executions are active.
-    # @return [void]
-    # @api private
-    def trap
-      @signal_mutex.synchronize do
-        @signal_previous = Signal.trap("INT") { Kernel.abort("") } if @signal_count.zero?
-
-        @signal_count += 1
+      ensure
+        STATE.restore if acquired
+        STATE.shutdown(scope) if scope
       end
-    end
 
-    def self.capture_error(source, error)
-      instance.trap
-      scope = instance.create
-      scope.capture(source, error)
-    ensure
-      instance.restore
-      instance.shutdown(scope) if scope
-    end
+      def run_source(scope, source, library, receiver, &block)
+        ::Kernel.require(library) if library
+        scope.call(source, receiver, &block)
+      rescue ::LoadError => e
+        scope.capture(source, e)
+      end
 
-    def self.execute_source(source, require:, receiver:, &block)
-      return if source.string.empty?
+      def validate_context!(library, receiver)
+        ArgumentError.("Executor library must be a String or nil") unless library.nil? || library.is_a?(::String)
 
-      instance.trap
-      scope = instance.create
-      catch(:result) { run_source(scope, source, require, receiver, &block) }
+        valid = (receiver in ::Object) && receiver.respond_to?(:public_send) && receiver.respond_to?(:instance_exec)
+        ArgumentError.("Executor receiver must be an executable Object or nil") unless valid
+      end
 
-    ensure
-      instance.restore
-      instance.shutdown(scope) if scope
-    end
+      def validate_source!(string, file, line)
+        ArgumentError.("Executor source must be a String") unless string.is_a?(::String)
+        ArgumentError.("Executor file must be a String or nil") unless file.nil? || file.is_a?(::String)
 
-    def self.run_source(scope, source, library, receiver, &block)
-      ::Kernel.require(library) if library
-      scope.call(source, receiver, &block)
-    rescue ::LoadError => e
-      scope.capture(source, e)
+        valid = line.nil? || (line.is_a?(::Integer) && line.between?(1, SOURCE_LINE_MAX))
+        ArgumentError.("Executor line must be between 1 and #{SOURCE_LINE_MAX}") unless valid
+      end
     end
-
-    private_class_method :capture_error, :execute_source, :run_source
-
-    private
-
-    def scopes = Thread.current[SCOPE_KEY] ||= []
   end
+
 end

data/lib/sevgi/skill.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "rubygems"
+require "sevgi"
+
+module Sevgi
+  # Locates the agent skill packaged for the installed Sevgi version.
+  # @api private
+  module Skill
+    extend self
+
+    Error = Class.new(::Sevgi::Error)
+
+    def path
+      spec = ::Gem::Specification.find_by_name("sevgi-appendix", "= #{::Sevgi::VERSION}")
+      packaged = packaged_path(spec)
+      # Package managers may replace a versioned gem path with their stable prefix.
+      path = ::File.expand_path(ENV.fetch("SEVGI_SKILL", packaged))
+
+      Error.("Sevgi skill is unavailable at #{path}.") unless ::File.file?(::File.join(path, "SKILL.md"))
+
+      path
+    rescue ::Gem::MissingSpecError
+      Error.("sevgi-appendix #{::Sevgi::VERSION} is not installed.")
+    end
+
+    private
+
+    def packaged_path(spec)
+      relative = spec.metadata["sevgi_skill_path"]
+      root = ::File.expand_path(spec.full_gem_path)
+      path = ::File.expand_path(relative, root) if relative.is_a?(String) && !relative.empty?
+      inside = path&.start_with?("#{root}#{::File::SEPARATOR}")
+
+      Error.("sevgi-appendix #{::Sevgi::VERSION} does not declare a valid skill path.") unless inside
+
+      path
+    end
+  end
+
+  private_constant :Skill
+end

data/lib/sevgi/svg.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Sevgi
+  # Public SVG facade installed by `require "sevgi"`.
+  #
+  # Capitalized methods are SVG DSL operations: {SVG.Canvas} creates a canvas,
+  # {SVG.Document} defines a document profile, and {SVG.Paper} registers a
+  # paper size. Double-colon names are Ruby constants and types, such as
+  # {SVG::Canvas} and {SVG::Document}. The global `SVG(...)` method builds a
+  # drawing; there is intentionally no stuttering `SVG.SVG(...)` form.
+  #
+  # Lowercase constructors remain on {Sevgi::Graphics} for focused component
+  # use. Script execution belongs to {Sevgi.execute} and is not part of this
+  # SVG-domain facade.
+  #
+  # @example Compose a drawing through the facade
+  #   SVG.Paper 85, 55, :card
+  #   canvas = SVG.Canvas :card, margins: 4
+  #   profile = SVG.Document attributes: {viewBox: "0 0 85 55"}
+  #
+  #   drawing = SVG profile, canvas do
+  #     rect width: 85, height: 55, rx: 3
+  #   end
+  #
+  #   drawing.Render
+  # @example Distinguish an operation from its result type
+  #   canvas = SVG.Canvas width: 24, height: 24, unit: :px
+  #   canvas.is_a?(SVG::Canvas) #=> true
+  # @see https://sevgi.roktas.dev/getting-started/ Getting started
+  # @see https://sevgi.roktas.dev/library-mode/ Library mode guide
+  module SVG
+    # SVG attribute collection and normalization API.
+    Attributes = Graphics::Attributes
+    # Canvas value type returned by {SVG.Canvas}.
+    Canvas = Graphics::Canvas
+    # Explicit SVG content serialization types.
+    Content = Graphics::Content
+    # Document profiles and document classes.
+    Document = Graphics::Document
+    # Base SVG/XML element type.
+    Element = Graphics::Element
+    # Duplicate-id and structural lint failure.
+    LintError = Graphics::LintError
+    # CSS-like canvas margin value.
+    Margin = Graphics::Margin
+    # Graphics mixtures available for document composition.
+    Mixtures = Graphics::Mixtures
+    # Contract for one callable drawing module.
+    Module = Graphics::Module
+    # Recursive contract for namespaces of callable drawing modules.
+    Modules = Graphics::Modules
+    # Immutable paper-size value and profile registry.
+    Paper = Graphics::Paper
+    # Current Sevgi toolkit version.
+    VERSION = Sevgi::VERSION
+
+    # Builds a canvas from a paper profile or explicit dimensions.
+    # @return [Sevgi::Graphics::Canvas] canvas value
+    # @see Sevgi::Toplevel#Canvas
+    def self.Canvas(...) = Sevgi.Canvas(...)
+
+    # Converts inline SVG/XML into an immutable Derender node.
+    # @return [Sevgi::Derender::Node] selected node
+    # @see Sevgi::Toplevel#Decompile
+    def self.Decompile(...) = Sevgi.Decompile(...)
+
+    # Converts an SVG/XML file into an immutable Derender node.
+    # @return [Sevgi::Derender::Node] selected node
+    # @see Sevgi::Toplevel#DecompileFile
+    def self.DecompileFile(...) = Sevgi.DecompileFile(...)
+
+    # Converts inline SVG/XML into formatted Sevgi DSL source.
+    # @return [String] formatted Sevgi DSL source
+    # @see Sevgi::Toplevel#Derender
+    def self.Derender(...) = Sevgi.Derender(...)
+
+    # Converts an SVG/XML file into formatted Sevgi DSL source.
+    # @return [String] formatted Sevgi DSL source
+    # @see Sevgi::Toplevel#DerenderFile
+    def self.DerenderFile(...) = Sevgi.DerenderFile(...)
+
+    # Defines, validates, or looks up a document profile.
+    # @return [Class] document class
+    # @see Sevgi::Toplevel#Document
+    def self.Document(...) = Sevgi.Document(...)
+
+    # Defines or replaces a document profile.
+    # @return [Class] document class
+    # @see Sevgi::Toplevel#Document!
+    def self.Document!(...) = Sevgi.Document!(...)
+
+    # Includes an inline SVG/XML node under a graphics element.
+    # @return [Sevgi::Graphics::Element, nil] included element, or nil when no output is produced
+    # @see Sevgi::Toplevel#Evaluate
+    def self.Evaluate(...) = Sevgi.Evaluate(...)
+
+    # Includes only an inline SVG/XML node's children under a graphics element.
+    # @return [Array<Sevgi::Graphics::Element>] immutable included-child snapshot
+    # @see Sevgi::Toplevel#EvaluateChildren
+    def self.EvaluateChildren(...) = Sevgi.EvaluateChildren(...)
+
+    # Includes only an SVG/XML file node's children under a graphics element.
+    # @return [Array<Sevgi::Graphics::Element>] immutable included-child snapshot
+    # @see Sevgi::Toplevel#EvaluateChildrenFile
+    def self.EvaluateChildrenFile(...) = Sevgi.EvaluateChildrenFile(...)
+
+    # Includes an SVG/XML file node under a graphics element.
+    # @return [Sevgi::Graphics::Element, nil] included element, or nil when no output is produced
+    # @see Sevgi::Toplevel#EvaluateFile
+    def self.EvaluateFile(...) = Sevgi.EvaluateFile(...)
+
+    # Fits a drawable grid to a graphics canvas.
+    # @return [Sevgi::Sundries::Grid] fitted grid
+    # @see Sevgi::Toplevel#Grid
+    def self.Grid(...) = Sevgi.Grid(...)
+
+    # Loads nested `.sevgi` files through the active executor scope.
+    # @return [Array<String>] requested file names
+    # @see Sevgi::Toplevel#Load
+    def self.Load(...) = Sevgi.Load(...)
+
+    # Extends a document profile with a named or anonymous graphics mixture.
+    # @return [Module, nil] anonymous mixture when supplied, otherwise nil
+    # @see Sevgi::Toplevel#Mixin
+    def self.Mixin(...) = Sevgi.Mixin(...)
+
+    # Defines or validates a named paper profile.
+    # @return [Symbol, String] original paper profile name
+    # @see Sevgi::Toplevel#Paper
+    def self.Paper(...) = Sevgi.Paper(...)
+
+    # Defines or overwrites a named paper profile.
+    # @return [Symbol, String] original paper profile name
+    # @see Sevgi::Toplevel#Paper!
+    def self.Paper!(...) = Sevgi.Paper!(...)
+  end
+end

data/lib/sevgi/toplevel/derender.rb

@@ -4,20 +4,106 @@ require "sevgi/derender"
 
 module Sevgi
   module Toplevel
+    # Converts inline SVG/XML content into a derender node.
+    # @param content [String] SVG/XML source content
+    # @param id [String, Symbol, nil] optional SVG id selecting a node inside the source
+    # @param omit [String, Symbol, Array<String, Symbol>, nil] exact attribute name or names omitted from the selected
+    #   subtree after id selection
+    # @return [Sevgi::Derender::Node] selected node in the derender tree
+    # @raise [Sevgi::ArgumentError] when content is malformed or rootless, or the id is absent
+    # @see Sevgi.Decompile
+    # @see Sevgi::Derender.decompile
+    def Decompile(content, id: nil, omit: nil) = Derender.decompile(content, id:, omit:)
+
     # 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
+    # @param id [String, Symbol, nil] optional SVG id selecting a node inside the source
+    # @param omit [String, Symbol, Array<String, Symbol>, nil] exact attribute name or names omitted from the selected
+    #   subtree after id selection
     # @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 is absent, malformed, or rootless, or the id is absent
+    # @raise [SystemCallError] when the file cannot be read
+    # @see Sevgi.DecompileFile
     # @see Sevgi::Derender.decompile_file
-    def Decompile(file, id = nil) = Derender.decompile_file(file, id:)
+    def DecompileFile(file, id: nil, omit: nil) = Derender.decompile_file(file, id:, omit:)
+
+    # Converts inline SVG/XML content into Sevgi DSL Ruby source.
+    # @param content [String] SVG/XML source content
+    # @param id [String, Symbol, nil] optional SVG id selecting a node inside the source
+    # @param omit [String, Symbol, Array<String, Symbol>, nil] exact attribute name or names omitted from the selected
+    #   subtree after id selection
+    # @return [String] formatted Sevgi DSL source
+    # @raise [Sevgi::ArgumentError] when content is malformed or rootless, or the id is absent
+    # @raise [Sevgi::PanicError] when generated Ruby source cannot be formatted
+    # @see Sevgi.Derender
+    # @see Sevgi::Derender.derender
+    def Derender(content, id: nil, omit: nil) = Derender.derender(content, id:, omit:)
 
     # 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
+    # @param id [String, Symbol, nil] optional SVG id selecting a node inside the source
+    # @param omit [String, Symbol, Array<String, Symbol>, nil] exact attribute name or names omitted from the selected
+    #   subtree after id selection
     # @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 is absent, malformed, or rootless, or the id is absent
+    # @raise [Sevgi::PanicError] when generated Ruby source cannot be formatted
+    # @raise [SystemCallError] when the file cannot be read
+    # @see Sevgi.DerenderFile
     # @see Sevgi::Derender.derender_file
-    def Derender(file, id = nil) = Derender.derender_file(file, id:)
+    def DerenderFile(file, id: nil, omit: nil) = Derender.derender_file(file, id:, omit:)
+
+    # Evaluates inline 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, Symbol, nil] optional SVG id selecting a node inside the source
+    # @param omit [String, Symbol, Array<String, Symbol>, nil] exact attribute name or names omitted from the selected
+    #   subtree after id selection
+    # @return [Sevgi::Graphics::Element, nil] included selected/root element, or nil when it produces no output
+    # @raise [Sevgi::ArgumentError] when content is malformed or rootless, or the id is absent
+    # @see Sevgi.Evaluate
+    # @see Sevgi::Derender.evaluate
+    def Evaluate(content, element, id: nil, omit: nil) = Derender.evaluate(content, element, id:, omit:)
+
+    # Evaluates only the selected node's children from inline SVG/XML content under a graphics element.
+    # @param content [String] SVG/XML source content
+    # @param element [Sevgi::Graphics::Element] target graphics element
+    # @param id [String, Symbol, nil] optional SVG id selecting a node inside the source
+    # @param omit [String, Symbol, Array<String, Symbol>, nil] exact attribute name or names omitted from the selected
+    #   subtree after id selection
+    # @return [Array<Sevgi::Graphics::Element>] immutable included-child snapshot
+    # @raise [Sevgi::ArgumentError] when content is malformed or rootless, or the id is absent
+    # @see Sevgi.EvaluateChildren
+    # @see Sevgi::Derender.evaluate_children
+    def EvaluateChildren(content, element, id: nil, omit: nil)
+      Derender.evaluate_children(content, element, id:, omit:)
+    end
+
+    # 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, Symbol, nil] optional SVG id selecting a node inside the source
+    # @param omit [String, Symbol, Array<String, Symbol>, nil] exact attribute name or names omitted from the selected
+    #   subtree after id selection
+    # @return [Array<Sevgi::Graphics::Element>] immutable included-child snapshot
+    # @raise [Sevgi::ArgumentError] when the file is absent, malformed, or rootless, or the id is absent
+    # @raise [SystemCallError] when the file cannot be read
+    # @see Sevgi.EvaluateChildrenFile
+    # @see Sevgi::Derender.evaluate_children_file
+    def EvaluateChildrenFile(file, element, id: nil, omit: nil)
+      Derender.evaluate_children_file(file, element, id:, omit:)
+    end
+
+    # 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, Symbol, nil] optional SVG id selecting a node inside the source
+    # @param omit [String, Symbol, Array<String, Symbol>, nil] exact attribute name or names omitted from the selected
+    #   subtree after id selection
+    # @return [Sevgi::Graphics::Element, nil] included selected/root element, or nil when it produces no output
+    # @raise [Sevgi::ArgumentError] when the file is absent, malformed, or rootless, or the id is absent
+    # @raise [SystemCallError] when the file cannot be read
+    # @see Sevgi.EvaluateFile
+    # @see Sevgi::Derender.evaluate_file
+    def EvaluateFile(file, element, id: nil, omit: nil) = Derender.evaluate_file(file, element, id:, omit:)
   end
 end