sevgi 0.93.1 → 0.95.0

data/README.md

@@ -1,5 +1,61 @@
 # Sevgi
 
-Provides the top-level API and `.sevgi` script runner.
+Top-level API and `.sevgi` script runner.
 
-See the root [README](../README.md) and the documentation site for usage.
+## 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.0 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

@@ -5,17 +5,24 @@ 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

@@ -56,20 +56,14 @@ module Sevgi
       # Runs the `sevgi` 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::Executor::Error] when `--exception` or `SEVGI_VOMIT` requests raw errors
+      # @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
 
-        result = run(file = argv.shift, options)
-
-        if result.error?
-          raise result.error if options.vomit || ENV[ENVVOMIT]
-
-          die(result.error, file)
-        end
+        file = argv.shift
+        handle(run(file, options), file, options)
 
       rescue Binaries::Sevgi::Error => e
         abort(e.message)
@@ -85,6 +79,14 @@ module Sevgi
         exit(1)
       end
 
+      def handle(result, file, options)
+        return unless result&.error?
+
+        raise result.error if options.vomit || ENV[ENVVOMIT]
+
+        die(result.error, file)
+      end
+
       def help
         <<~HELP
           Usage: #{PROGNAME} [options...] <Sevgi file>

data/lib/sevgi/executor/error.rb

@@ -2,13 +2,19 @@
 
 module Sevgi
   class Executor
+    # Raised when a source attempts to load another source already active in the same scope.
+    class CycleError < ::Sevgi::Error
+    end
+
     # 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
+      # Returns the original script exception.
+      # @return [Exception]
+      attr_reader :error
+
+      # Returns the executor scope active when the error was captured.
+      # @return [Sevgi::Executor::Scope]
+      attr_reader :scope
 
       # Builds an executor error wrapper.
       # @param error [Exception] original exception
@@ -32,6 +38,10 @@ module Sevgi
           .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

data/lib/sevgi/executor/scope.rb

@@ -3,10 +3,11 @@
 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.
+    # @api private
     class Scope
-      # Error raised by low-level executor scope operations.
-      Error = Class.new(::Sevgi::Error)
-
       # @!attribute [r] scope
       #   @return [Module] isolated module where script source is evaluated
       # @!attribute [r] recent
@@ -18,11 +19,14 @@ module Sevgi
       # 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
         @error = nil
         @stack = {}
+        @active = {}
       end
 
       # Reports whether execution captured an error.
@@ -38,17 +42,20 @@ module Sevgi
       # @api private
       def call(source, receiver = nil, &boot)
         push(source)
+        execute(source, receiver, &boot)
 
-        tap do
-          @recent = run(source, receiver, &boot)
-
-          # rubocop:disable Lint/RescueException
-        rescue Exception => e
-          @error = Executor::Error.new(e, self)
+        self
+      end
 
-          throw(:result, self)
-          # rubocop:enable Lint/RescueException
-        end
+      # 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.
@@ -56,12 +63,18 @@ module Sevgi
       # @yield optional boot block that installs DSL methods before evaluation
       # @yieldreturn [void]
       # @return [Sevgi::Executor::Scope] self, with recent or error populated
-      # @raise [Errno::ENOENT] when the file cannot be read
+      # @note File-read failures are captured as {Sevgi::Executor::Error} on this scope.
       # @api private
-      def load(file, &block) = call(Source.load(file), &block)
+      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.
@@ -69,9 +82,6 @@ module Sevgi
       # @api private
       def peek = @stack[@stack.keys.last]
 
-      # Constant name used for the temporary script module under {Sevgi}.
-      MAIN_MODULE = :Main
-
       private
 
       def boot(receiver, &boot)
@@ -86,16 +96,40 @@ 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 enter(source)
+        if @active.key?(source.identity)
+          raise Executor::CycleError, "Recursive Sevgi load: #{source.file}"
+        end
+
+        @active[source.identity] = source
+        source
+      end
+
+      def leave(source)
+        return unless source
+
+        @active.delete(source.identity) if @active[source.identity].equal?(source)
+      end
+
+      def execute(source, receiver, &boot)
+        active = enter(source)
+        @recent = run(source, receiver, &boot)
+        # rubocop:disable Lint/RescueException
+      rescue Exception => e
+        @error = Executor::Error.new(e, self)
+        throw(:result, self)
+        # rubocop:enable Lint/RescueException
+      ensure
+        leave(active)
+      end
+
       def run(source, receiver, &boot)
         boot(receiver, &boot)
         evaluate(source)

data/lib/sevgi/executor/source.rb

@@ -29,6 +29,14 @@ module Sevgi
       # 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 [String] canonical source identity
+      def identity
+        ::File.realpath(file)
+      rescue ::SystemCallError
+        ::File.expand_path(file)
+      end
     end
   end
 end

data/lib/sevgi/executor.rb

@@ -11,14 +11,26 @@ module Sevgi
   #
   # 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.
+  # 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
 
+    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
+
     # 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
@@ -35,20 +47,11 @@ module Sevgi
     # @yield optional boot block that installs DSL methods before evaluation
     # @yieldreturn [void]
     # @return [Sevgi::Executor::Scope, nil] execution scope, or nil for empty source
-    # @raise [LoadError] when the optional required library cannot be loaded
+    # @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?
-
-      interrupt = Signal.trap("INT") { Kernel.abort("") }
-
-      ::Kernel.require(require) if require
-
-      scope = instance.create
-      catch(:result) { scope.call(Source.new(string:, file:, line:), receiver, &block) }
-
-    ensure
-      Signal.trap("INT", interrupt) if interrupt
-      instance.shutdown if scope
+      execute_source(Source.new(string:, file:, line:), require:, receiver:, &block)
     end
 
     # Executes a file inside a managed Sevgi script scope.
@@ -58,10 +61,18 @@ module Sevgi
     # @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
-    # @raise [Errno::ENOENT] when the file cannot be read
-    # @raise [LoadError] when the optional required library cannot be loaded
+    # @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)
-      execute(::File.read(file), file: file, line: 1, require:, receiver:, &block)
+      source = nil
+      begin
+        source = Source.load(file)
+      rescue ::SystemCallError => e
+        return capture_error(Source.new(string: "", file:, line: 1), e)
+      end
+
+      execute_source(source, require:, receiver:, &block)
     end
 
     # Removes the current executor scope.
@@ -71,22 +82,94 @@ module Sevgi
       instance.shutdown
     end
 
-    def initialize = @scopes = []
+    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 }
+    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
+    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
 
     # 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 = @scopes.pop
+    def shutdown(scope = nil)
+      return scopes.pop unless scope
+      return scopes.pop if scopes.last.equal?(scope)
+
+      scopes.delete(scope)
+    end
+
+    # 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.capture_error(source, error)
+      acquired = instance.trap
+      scope = instance.create
+      scope.capture(source, error)
+    ensure
+      instance.restore if acquired
+      instance.shutdown(scope) if scope
+    end
+
+    def self.execute_source(source, require:, receiver:, &block)
+      acquired = false
+      return if source.string.empty? && require.nil?
+
+      acquired = instance.trap
+      scope = instance.create
+      catch(:result) { run_source(scope, source, require, receiver, &block) }
+
+    ensure
+      instance.restore if acquired
+      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
+
+    private_class_method :capture_error, :execute_source, :run_source
+
+    private
+
+    def scopes = Thread.current[SCOPE_KEY] ||= []
   end
+
 end

data/lib/sevgi/toplevel/executor.rb

@@ -11,7 +11,8 @@ module Sevgi
   # @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
-  # @raise [LoadError] when the optional `require:` library cannot be loaded
+  # @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)
 
@@ -19,8 +20,8 @@ module Sevgi
   # @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
-  # @raise [Errno::ENOENT] when the file cannot be read
-  # @raise [LoadError] when the optional `require:` library cannot be loaded
+  # @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)
 
@@ -30,11 +31,12 @@ module Sevgi
     # @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)
 
       files.each do |file|
-        location = F.locate(file, start, exclude: start)
+        location = F.locate(file, start)
 
         ::Sevgi::Executor.load(location.file)
       end

data/lib/sevgi/toplevel/function.rb

@@ -4,20 +4,13 @@ require "sevgi/function"
 
 module Sevgi
   module Toplevel
-    # Function helper namespace promoted as `F` by the full top-level DSL.
+    # 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
-    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
+    # @see Sevgi::Function
+    promote Sevgi::Function, :F
   end
 end

data/lib/sevgi/toplevel/sundries.rb

@@ -7,9 +7,12 @@ module Sevgi
     # 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 [Numeric] number of minor units in each major interval
+    # @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, unit, multiple, or fitting span is invalid
+    # @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

@@ -11,16 +11,19 @@ module Sevgi
     @constants = {}
 
     class << self
-      attr_reader :constants
+      # Returns an immutable snapshot of promoted constants.
+      # @return [Hash<Symbol, Object>]
+      def constants = @constants.dup.freeze
 
       private
 
       def inject(base)
         return if base.instance_variable_defined?("@_toplevel_injected_")
 
-        target = base.is_a?(::Module) ? base : base.class
-        @constants.each do |name, constant|
-          target.const_set(name, constant) unless target.const_defined?(name, false)
+        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)
@@ -31,7 +34,7 @@ module Sevgi
       end
     end
 
-    # Injects promoted constants when the DSL is included.
+    # 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
@@ -40,9 +43,11 @@ module Sevgi
       inject(base)
     end
 
-    # Injects promoted constants when the DSL is extended.
-    # @param base [Object] the object or module receiving promoted constants
+    # 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

data/lib/sevgi/version.rb

@@ -2,5 +2,5 @@
 
 module Sevgi
   # Current version of the Sevgi top-level gem.
-  VERSION = "0.93.1"
+  VERSION = "0.95.0"
 end

data/lib/sevgi.rb

@@ -26,9 +26,11 @@ def SVG(...) = Sevgi::Graphics.SVG(...)
 
 # Full top-level API for Sevgi library and script consumers.
 #
-# Including or extending this module installs DSL methods such as `Paper`, `Load`,
-# and `Grid`, plus convenience constants such as `F`, `Geometry`, `Origin`, and
-# `Export`.
+# 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
@@ -50,6 +52,7 @@ module Sevgi
   # 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