sevgi 0.73.2 → 0.94.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4696b409358c595a5196f8e4e037edf1cf6f2e171d3f083fa56438d36dd5750f
-  data.tar.gz: 857df564a95208647e8f3d5de0ae8f8289d4afcbe7433b74be05f2b433293256
+  metadata.gz: ceb2e9987cc3e1ee86f9a7e8961214a60b81685e89b2f2d9dc5986e3b2eed8f6
+  data.tar.gz: 50240698f875654431f4caf9681ddf8b163971c5f7d4ef9781849be17541e37d
 SHA512:
-  metadata.gz: a2687e5ec21afdc64e569a814a1ab0ff78436d93eb929bc661f5462f621da5305bdfada1fd256dd3960dbbc82bd4e64ea4f5d098a39870a83493b76b5a1844f2
-  data.tar.gz: 267238636b3ee84ada012dfd585889071aa0552abae6418922b423f6ee15bafe150ad721ae8d6718e45966f659669ac38972985c033dc77252d2ec2c8c14c627
+  metadata.gz: 9ddd81f3154b0bab5f2fa17890301f97fc960572874621bc42634f04caf826664c73a19082b9e8222a7155f2dcb5132f99a01afdb8ee841c6d6376bf162020b2
+  data.tar.gz: a8902dc527a3bcc3f26bce6f2eb8ecd442a26b4628db70c39011523bf409628f148c3288c7efc357b96b57fc67bc8aa640f7420d278494f8c32d2616bf9b615e

data/CHANGELOG.md

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

data/LICENSE

@@ -0,0 +1,5 @@
+Sevgi 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,61 @@
+# Sevgi
+
+Top-level API and `.sevgi` script runner.
+
+## Install
+
+```sh
+gem install sevgi
+```
+
+## Require
+
+```ruby
+require "sevgi"
+```
+
+## Example
+
+```ruby
+SVG(:minimal) do
+  rect(width: 3, height: 5)
+end.call
+```
+
+## Executable
+
+```sh
+sevgi drawing.sevgi
+```
+
+## Ruby compatibility
+
+Requires Ruby 3.4.0 or newer. CI verifies Ruby 3.4 and the current development Ruby from `.ruby-version`.
+
+## Native prerequisites
+
+The top-level gem installs Sevgi's standard components without native export gems. SVG-only scripts need no native
+packages beyond the standard Ruby dependencies.
+
+PDF/PNG export helpers come from `sevgi-sundries` and lazily load the optional Ruby gems `cairo`, `rsvg2`, and
+`hexapdf`. On Debian/Ubuntu:
+
+```sh
+sudo apt-get update
+sudo apt-get install -y libcairo2-dev libgdk-pixbuf-2.0-dev libgirepository1.0-dev libglib2.0-dev librsvg2-dev pkg-config
+gem install cairo rsvg2 hexapdf
+```
+
+On macOS with Homebrew:
+
+```sh
+brew install cairo gdk-pixbuf gobject-introspection librsvg pkg-config
+gem install cairo rsvg2 hexapdf
+```
+
+## Links
+
+- Documentation: https://sevgi.roktas.dev
+- API documentation: https://www.rubydoc.info/gems/sevgi
+- Source: https://github.com/roktas/sevgi/tree/main/toplevel
+- Changelog: https://github.com/roktas/sevgi/blob/main/CHANGELOG.md

data/lib/sevgi/binaries/rake.rb

@@ -2,14 +2,27 @@
 
 require "sevgi"
 
+# Extends FileUtils with Sevgi script helpers for Rake tasks.
 module FileUtils
   # Thin DSL wrapper to call a script without spawning a shell.
+  #
+  # The script receives positional arguments through `ARGA` and keyword arguments through `ARGH`.
+  #
+  # @example Run a Sevgi script from a Rake task
+  #   sevgi "drawings/card", "front", theme: :dark
+  #
+  # @param file [String] Sevgi script file, with or without `.sevgi` extension
+  # @param args [Array] positional arguments exposed to the script as `ARGA`
+  # @param kwargs [Hash] keyword arguments exposed to the script as `ARGH`
+  # @return [Sevgi::Executor::Scope, nil] execution scope, or nil for an empty file
+  # @raise [Sevgi::ArgumentError] when the script file cannot be found
+  # @see Sevgi::Executor.execute_file
   def sevgi(file, *args, **kwargs)
-    Sevgi.execute_file(F.existing!(file, [EXTENSION])) do |mod|
-      include(Sevgi)
+    Sevgi::Executor.execute_file(Sevgi::F.existing!(file, [Sevgi::EXTENSION])) do
+      extend(Sevgi)
 
-      mod.const_set(:ARGA, args).freeze
-      mod.const_set(:ARGH, kwargs).freeze
+      const_set(:ARGA, args).freeze
+      const_set(:ARGH, kwargs).freeze
     end
   end
 end

data/lib/sevgi/binaries/sevgi.rb

@@ -3,15 +3,25 @@
 require "sevgi"
 
 module Sevgi
+  # Command-line entrypoint implementations shipped with Sevgi.
   module Binaries
+    # Implements the `sevgi` executable.
     module Sevgi
       extend self
 
+      # Executable name used in help output.
       PROGNAME = "sevgi"
 
+      # Error raised for invalid command-line usage.
       Error = Class.new(::Sevgi::Error)
 
+      # Parsed command-line options for the `sevgi` executable.
+      # @api private
       Options = Struct.new(:require, :nomain, :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::Sevgi::Options] parsed options
+        # @raise [Sevgi::Binaries::Sevgi::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?
@@ -25,7 +35,7 @@ module Sevgi
             case (arg = argv.shift)
             when "-r", "--require"
               options.require = argv.shift
-            when "-m", "--nomain"
+            when "-n", "--nomain"
               options.nomain = true
             when "-x", "--exception"
               options.vomit = true
@@ -43,6 +53,11 @@ module Sevgi
 
       private_constant :Options
 
+      # Runs the `sevgi` command-line interface.
+      # @param argv [Array<String>, String, nil] command-line arguments
+      # @return [nil]
+      # @raise [Sevgi::Executor::Error] when `--exception` or `SEVGI_VOMIT` requests raw executor errors
+      # @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/executor/error.rb

@@ -2,9 +2,18 @@
 
 module Sevgi
   class Executor
+    # Wraps an exception raised while executing Sevgi script source.
     class Error < ::Sevgi::Error
+      # @!attribute [r] error
+      #   @return [Exception] original exception raised by script execution
+      # @!attribute [r] scope
+      #   @return [Sevgi::Executor::Scope] executor scope active when the error was captured
       attr_reader :error, :scope
 
+      # Builds an executor error wrapper.
+      # @param error [Exception] original exception
+      # @param scope [Sevgi::Executor::Scope] executor scope active at failure time
+      # @return [void]
       def initialize(error, scope)
         @error = error
         @scope = scope
@@ -12,13 +21,23 @@ module Sevgi
         super(error.message)
       end
 
+      # Returns backtrace entries that belong to the Sevgi load stack.
+      # @return [Array<String>] filtered backtrace lines relative to the current directory
       def backtrace!
+        sources = stack.map { ::File.expand_path(it) }
+
         error
           .backtrace
-          .select { |line| stack.any? { line.start_with?(::File.expand_path(it)) } }
+          .select { sources.include?(::File.expand_path(it.split(":", 2).first)) }
           .map { |line| line.delete_prefix("#{::Dir.pwd}/") }
       end
 
+      # Returns the original exception as the wrapped cause.
+      # @return [Exception]
+      def cause = error
+
+      # Returns the script load stack active at failure time.
+      # @return [Array<String>] script file names in load order
       def stack = scope.stack
     end
   end

data/lib/sevgi/executor/scope.rb

@@ -2,11 +2,24 @@
 
 module Sevgi
   class Executor
+    # Holds one isolated Sevgi script execution scope and its result.
+    #
+    # Scope objects belong to one executor run and are pushed onto the current
+    # fiber's executor stack. They are not shared between concurrent executions.
     class Scope
-      Error = Class.new(::Sevgi::Error)
-
+      # @!attribute [r] scope
+      #   @return [Module] isolated module where script source is evaluated
+      # @!attribute [r] recent
+      #   @return [Object, nil] last expression result from the executed source
+      # @!attribute [r] error
+      #   @return [Sevgi::Executor::Error, nil] captured execution error
       attr_reader :scope, :recent, :error
 
+      # Creates a script execution scope.
+      # @param scope [Module, nil] existing module to evaluate source in
+      # @return [void]
+      # @note When no module is supplied, the internal module reports its name as `Sevgi::Main` for readable Ruby error
+      #   messages without publishing a process-global `Sevgi::Main` constant.
       def initialize(scope = nil)
         @scope = scope || main
         @recent = nil
@@ -14,16 +27,22 @@ module Sevgi
         @stack = {}
       end
 
+      # Reports whether execution captured an error.
+      # @return [Boolean] true when execution failed
       def error? = !error.nil?
 
+      # Executes one source object in this scope.
+      # @param source [Sevgi::Executor::Source] source to evaluate
+      # @param receiver [Object, nil] receiver used while booting the DSL
+      # @yield optional boot block that installs DSL methods before evaluation
+      # @yieldreturn [void]
+      # @return [Sevgi::Executor::Scope] self, with recent or error populated
+      # @api private
       def call(source, receiver = nil, &boot)
         push(source)
 
         tap do
-          @recent = begin
-            boot(receiver, &boot)
-            evaluate(source)
-          end
+          @recent = run(source, receiver, &boot)
 
           # rubocop:disable Lint/RescueException
         rescue Exception => e
@@ -34,14 +53,41 @@ module Sevgi
         end
       end
 
-      def load(file, &block) = call(Source.load(file), &block)
+      # Captures a preprocessing failure for this scope.
+      # @param source [Sevgi::Executor::Source] source active when preprocessing failed
+      # @param error [Exception] original preprocessing exception
+      # @return [Sevgi::Executor::Scope] self, with error populated
+      # @api private
+      def capture(source, error)
+        push(source)
+        @error = Executor::Error.new(error, self)
+        self
+      end
+
+      # Loads a file into this existing execution scope.
+      # @param file [String] source file to read and evaluate
+      # @yield optional boot block that installs DSL methods before evaluation
+      # @yieldreturn [void]
+      # @return [Sevgi::Executor::Scope] self, with recent or error populated
+      # @note File-read failures are captured as {Sevgi::Executor::Error} on this scope.
+      # @api private
+      def load(file, &block)
+        call(Source.load(file), &block)
+      rescue ::SystemCallError => e
+        capture(Source.new(string: "", file:, line: 1), e)
+        throw(:result, self)
+      end
 
+      # Returns the unique source stack for this execution.
+      # @return [Array<String>] source file keys in load order
+      # @note The stack is owned by this scope and is not shared with concurrent executions.
       def stack = @stack.keys
 
+      # Returns the most recently pushed source.
+      # @return [Sevgi::Executor::Source, nil] most recent source object
+      # @api private
       def peek = @stack[@stack.keys.last]
 
-      MAIN_MODULE = :Main
-
       private
 
       def boot(receiver, &boot)
@@ -56,15 +102,17 @@ module Sevgi
       end
 
       def main
-        Module.new.tap do |mod|
-          Sevgi.send(:remove_const, MAIN_MODULE) if Sevgi.const_defined?(MAIN_MODULE)
-          Sevgi.const_set(MAIN_MODULE, mod)
-        end
+        Module.new.tap { |mod| mod.define_singleton_method(:name) { "Sevgi::Main" } }
       end
 
       def push(source)
         tap { @stack[source.key] = source }
       end
+
+      def run(source, receiver, &boot)
+        boot(receiver, &boot)
+        evaluate(source)
+      end
     end
   end
 end

data/lib/sevgi/executor/source.rb

@@ -2,13 +2,32 @@
 
 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)
+      #   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
+      #   @return [Sevgi::Executor::Source] source object
       def self.call(...) = new(...)
 
+      # Builds a source object from a file.
+      # @param file [String] source file to read
+      # @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)
 
+      # 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
+      # @return [void]
       def initialize(string:, file: nil, line: nil) = super(string:, file: file || "sevgi", line: line || 1)
 
+      # Returns the stack key used for this source.
+      # @return [String] source file name
       def key = file
     end
   end

data/lib/sevgi/executor.rb

@@ -7,44 +7,165 @@ require_relative "executor/scope"
 require_relative "executor/source"
 
 module Sevgi
+  # Executes Sevgi script source inside an isolated module scope.
+  #
+  # 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
+  # whenever possible. Active scope stacks are isolated per Ruby fiber, so
+  # concurrent executions can perform nested `Load` calls without sharing scope
+  # 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.
   class Executor
     include Singleton
 
+    # Thread-current key used for the fiber-local executor scope stack.
+    # @api private
+    SCOPE_KEY = :sevgi_executor_scopes
+    private_constant :SCOPE_KEY, :Source
+
+    # 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
+    # @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
 
       instance.current.load(file, ...)
     end
 
+    # 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
+    # @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.
+    # @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(string, file: nil, line: nil, require: nil, receiver: nil, &block)
-      return if string.empty?
+      execute_source(Source.new(string:, file:, line:), require:, receiver:, &block)
+    end
 
-      Signal.trap("INT") { Kernel.abort("") }
+    # Executes a file inside a managed Sevgi script scope.
+    # @param file [String] source file to read and execute
+    # @param require [String, nil] optional Ruby library to require before execution
+    # @param receiver [Object, nil] receiver used while booting the DSL
+    # @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.
+    # @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)
+      source = nil
+      begin
+        source = Source.load(file)
+      rescue ::SystemCallError => e
+        return capture_error(Source.new(string: "", file:, line: 1), e)
+      end
 
-      ::Kernel.require(require) if require
+      execute_source(source, require:, receiver:, &block)
+    end
 
-      catch(:result) do
-        instance.create.call(Source.new(string:, file:, line:), receiver, &block)
+    # 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
+
+    # 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 }
+
+    # 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
       end
+    end
 
-    ensure
-      instance.shutdown
+    # 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)
+
+      scopes.delete(scope)
     end
 
-    def self.execute_file(file, require: nil, receiver: nil, &block)
-      execute(::File.read(file), file: file, line: 1, require:, receiver:, &block)
+    # 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
+      end
     end
 
-    def self.shutdown
-      instance.shutdown
+    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 initialize = @scopes = []
+    def self.execute_source(source, require:, receiver:, &block)
+      return if source.string.empty?
+
+      instance.trap
+      scope = instance.create
+      catch(:result) { run_source(scope, source, require, receiver, &block) }
+
+    ensure
+      instance.restore
+      instance.shutdown(scope) if scope
+    end
+
+    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)
+    end
 
-    def create(scope = nil) = Scope.new(scope).tap { @scopes << it }
+    private_class_method :capture_error, :execute_source, :run_source
 
-    def current = @scopes.last
+    private
 
-    def shutdown = @scopes.pop
+    def scopes = Thread.current[SCOPE_KEY] ||= []
   end
 end

data/lib/sevgi/toplevel/derender.rb

@@ -4,12 +4,20 @@ require "sevgi/derender"
 
 module Sevgi
   module Toplevel
-    def Decompile(file, id) = Derender.decompile_file(file, 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
+    # @see Sevgi::Derender.decompile_file
+    def Decompile(file, id = nil) = Derender.decompile_file(file, id:)
 
-    def Decompile!(file, id) = Derender.decompile_file!(file, id:)
-
-    def Derender(file, id) = Derender.derender_file(file, id:)
-
-    def Derender!(file, id) = Derender.derender_file!(file, id:)
+    # 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
+    # @see Sevgi::Derender.derender_file
+    def Derender(file, id = nil) = Derender.derender_file(file, id:)
   end
 end

data/lib/sevgi/toplevel/executor.rb

@@ -7,11 +7,31 @@ module Sevgi
 
   private_constant :BootBlock
 
+  # Executes Sevgi script source with the full top-level DSL installed.
+  # @param args [Array] arguments forwarded to {Sevgi::Executor.execute}
+  # @param kwargs [Hash] keyword arguments forwarded to {Sevgi::Executor.execute}
+  # @return [Sevgi::Executor::Scope, nil] execution result, or nil for empty source
+  # @note Required-library load failures are captured as {Sevgi::Executor::Error} on the returned scope.
+  # @note Reentrant and concurrent calls keep independent executor scope stacks per fiber.
+  # @see Sevgi::Executor.execute
   def self.execute(*args, **kwargs) = Executor.execute(*args, **kwargs, &BootBlock)
 
+  # Executes a Sevgi script file with the full top-level DSL installed.
+  # @param args [Array] arguments forwarded to {Sevgi::Executor.execute_file}
+  # @param kwargs [Hash] keyword arguments forwarded to {Sevgi::Executor.execute_file}
+  # @return [Sevgi::Executor::Scope, nil] execution result, or nil for an empty file
+  # @note File-read and required-library load failures are captured as {Sevgi::Executor::Error} on the returned scope.
+  # @note Reentrant and concurrent calls keep independent executor scope stacks per fiber.
+  # @see Sevgi::Executor.execute_file
   def self.execute_file(*args, **kwargs) = Executor.execute_file(*args, **kwargs, &BootBlock)
 
   module Toplevel
+    # Loads one or more Sevgi files relative to the caller's source file.
+    # @param files [Array<String>] Sevgi script files to locate and execute
+    # @return [Array<String>] the input file list
+    # @raise [Sevgi::PanicError] when called without an active executor scope
+    # @raise [Sevgi::Error] when a file cannot be located
+    # @note `Load` resolves against the active executor scope in the current fiber.
     def Load(*files)
       start = ::File.dirname(caller_locations(1..1).first.path)
 

data/lib/sevgi/toplevel/function.rb

@@ -4,14 +4,13 @@ require "sevgi/function"
 
 module Sevgi
   module Toplevel
-    module Function
-      extend Sevgi::Function::Color
-      extend Sevgi::Function::Math
-      extend Sevgi::Function::Pluralize
-      extend Sevgi::Function::Shell
-      extend Sevgi::Function::UI
-    end
-
-    promote Function, :F
+    # Promotes the canonical function helper namespace as `F` in the full top-level DSL.
+    #
+    # @example Use helper functions inside script mode
+    #   SVG do
+    #     text F.pluralize("axis")
+    #   end
+    # @see Sevgi::Function
+    promote Sevgi::Function, :F
   end
 end

data/lib/sevgi/toplevel/graphics.rb

@@ -4,14 +4,45 @@ require "sevgi/graphics"
 
 module Sevgi
   module Toplevel
+    # @overload Mixin(mod, document = Sevgi::Graphics::Document::Base, &block)
+    #   Adds graphics mixture methods to a document class.
+    #   @param mod [Symbol, String] named mixture to mix into the document
+    #   @param document [Class] document class receiving the mixture
+    #   @yield optional anonymous mixture module body
+    #   @yieldreturn [void]
+    #   @return [void]
+    #   @raise [NameError] when a named mixture cannot be resolved
+    #   @see Sevgi::Graphics::Mixtures.mixin
+    # @overload Mixin(document = Sevgi::Graphics::Document::Base, &block)
+    #   Adds an anonymous graphics mixture to a document class.
+    #   @param document [Class] document class receiving the mixture
+    #   @yield anonymous mixture module body
+    #   @yieldreturn [void]
+    #   @return [Module] anonymous mixture
+    #   @raise [Sevgi::ArgumentError] when no named mixture or block is given
+    #   @see Sevgi::Graphics::Mixtures.mixin
     def Mixin(...) = Graphics::Mixtures.mixin(...)
 
-    def Paper(width, height, name = :custom, unit: "mm")
-      name.tap { Graphics::Paper.define(name, width:, height:, unit:) unless Graphics::Paper.exist?(name) }
-    end
+    # @overload Paper(width, height, name = :custom, unit: "mm")
+    #   Defines or validates a named paper profile for DSL use.
+    #   @param width [Numeric] paper width
+    #   @param height [Numeric] paper height
+    #   @param name [Symbol] paper profile name
+    #   @param unit [String, Symbol] size unit
+    #   @return [Symbol] the paper profile name
+    #   @raise [Sevgi::ArgumentError] when the profile is invalid or an existing profile differs
+    #   @see Sevgi::Graphics#paper
+    def Paper(...) = Graphics.paper(...)
 
-    def Paper!(width, height, name = :custom, unit: "mm")
-      name.tap { Graphics::Paper.define(name, width:, height:, unit:) }
-    end
+    # @overload Paper!(width, height, name = :custom, unit: "mm")
+    #   Defines or overwrites a named paper profile for DSL use.
+    #   @param width [Numeric] paper width
+    #   @param height [Numeric] paper height
+    #   @param name [Symbol] paper profile name
+    #   @param unit [String, Symbol] size unit
+    #   @return [Symbol] the paper profile name
+    #   @raise [Sevgi::ArgumentError] when the profile is invalid or the paper name is reserved
+    #   @see Sevgi::Graphics#paper!
+    def Paper!(...) = Graphics.paper!(...)
   end
 end

data/lib/sevgi/toplevel/sundries.rb

@@ -4,6 +4,15 @@ require "sevgi/sundries"
 
 module Sevgi
   module Toplevel
+    # Builds a drawable grid from a graphics canvas.
+    # @param canvas [Sevgi::Graphics::Canvas] canvas defining page size and margins
+    # @param unit [Numeric] minor grid unit
+    # @param multiple [Integer] number of minor units in each major interval
+    # @return [Sevgi::Sundries::Grid] grid fitted to the canvas
+    # @raise [Sevgi::ArgumentError] when canvas is not a graphics canvas
+    # @raise [Sevgi::ArgumentError] when unit is not a finite positive number
+    # @raise [Sevgi::ArgumentError] when multiple is not a positive integer
+    # @raise [Sevgi::ArgumentError] when canvas dimensions, margins, and grid intervals cannot fit
     def Grid(canvas, unit:, multiple:)
       ArgumentError.("Must be a Canvas: #{canvas}") unless canvas.is_a?(Graphics::Canvas)
 

data/lib/sevgi/toplevel.rb

@@ -1,6 +1,12 @@
 # frozen_string_literal: true
 
 module Sevgi
+  # Shared implementation for the full Sevgi top-level DSL.
+  #
+  # This module is installed by `include Sevgi` or `extend Sevgi`; it should not
+  # normally be included directly.
+  #
+  # @see Sevgi
   module Toplevel
     @constants = {}
 
@@ -12,7 +18,12 @@ module Sevgi
       def inject(base)
         return if base.instance_variable_defined?("@_toplevel_injected_")
 
-        @constants.each { |args| (base.is_a?(::Module) ? base : base.class).const_set(*args) }
+        if base.is_a?(::Module)
+          @constants.each do |name, constant|
+            base.const_set(name, constant) unless base.const_defined?(name, false)
+          end
+        end
+
         base.instance_variable_set("@_toplevel_injected_", true)
       end
 
@@ -21,11 +32,21 @@ module Sevgi
       end
     end
 
+    # Injects promoted constants when the DSL is included in a module or class.
+    # @param base [Module] the class or module receiving promoted constants
+    # @return [void]
+    # @api private
     def self.included(base)
       super
       inject(base)
     end
 
+    # Injects promoted constants when the DSL is extended by a module.
+    # @param base [Object] the object or module receiving the DSL methods
+    # @return [void]
+    # @note Constants are promoted only to modules/classes. Extending an ordinary object installs methods without
+    #   writing constants to `Object`.
+    # @api private
     def self.extended(base)
       super
       inject(base)

data/lib/sevgi/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Sevgi
-  VERSION = "0.73.2"
+  # Current version of the Sevgi top-level gem.
+  VERSION = "0.94.0"
 end

data/lib/sevgi.rb

@@ -9,20 +9,51 @@ require "sevgi/sundries"
 
 require "sevgi/version"
 
-# Minimal Toplevel Interface (activated with 'require "sevgi"')
+# Minimal top-level SVG interface installed by `require "sevgi"`.
+# @return [Module] the graphics module used as the SVG DSL namespace
 SVG = Sevgi::Graphics
+
+# @overload SVG(document = :default, canvas = Undefined, **attributes, &block)
+#   Builds an SVG document through the default top-level DSL entrypoint.
+#   @param document [Symbol, Class] document profile name or document class
+#   @param canvas [Object] optional canvas or paper profile argument
+#   @param attributes [Hash] root SVG attributes
+#   @yield the document block evaluated in the SVG document context
+#   @yieldreturn [void]
+#   @return [Sevgi::Graphics::Document::Proto] a rendered SVG document object
+#   @raise [Sevgi::ArgumentError] when the document, paper, or canvas arguments are invalid
 def SVG(...) = Sevgi::Graphics.SVG(...)
 
-# Maximal Toplevel Interface (activated with 'include Sevgi')
+# Full top-level API for Sevgi library and script consumers.
+#
+# Including this module in a class or module installs DSL methods such as
+# `Paper`, `Load`, and `Grid`, plus convenience constants such as `F`,
+# `Geometry`, `Origin`, and `Export`. Extending a module does the same.
+# Extending an ordinary object installs the methods only and does not write
+# promoted constants to `Object`.
+#
+# @example Include the DSL in an object
+#   class Drawing
+#     include Sevgi
+#   end
 module Sevgi
   # See sevgi/toplevel/*.rb files for details
   require_relative "sevgi/toplevel"
 
+  # Installs the full toplevel DSL into an including class or module.
+  # @param base [Module] the class or module receiving the DSL methods
+  # @return [void]
+  # @api private
   def self.included(base)
     super
     base.include(Toplevel)
   end
 
+  # Installs the full toplevel DSL into an extending object or module.
+  # @param base [Object] the receiver extended with the DSL methods
+  # @return [void]
+  # @note Promoted constants are written only when base is a module or class.
+  # @api private
   def self.extended(base)
     super
     base.extend(Toplevel)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sevgi
 version: !ruby/object:Gem::Version
-  version: 0.73.2
+  version: 0.94.0
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,84 +15,84 @@ 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-function
   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: sevgi-geometry
   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: 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: sevgi-standard
   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: sevgi-sundries
   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
 description: Provides a scriptable DSL with utilities for creating SVG content with
   Ruby.
 email: roktas@gmail.com
@@ -101,6 +101,8 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE
 - README.md
 - bin/sevgi
 - lib/sevgi.rb
@@ -133,7 +135,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:
   - - ">="