sevgi-function 0.93.1 → 0.95.0

data/README.md

@@ -1,5 +1,36 @@
 # Sevgi Function
 
-Provides shared helper functions used by Sevgi components.
+Shared helper functions used by Sevgi components.
 
-See the root [README](../README.md) and the documentation site for usage.
+## Install
+
+```sh
+gem install sevgi-function
+```
+
+## Require
+
+```ruby
+require "sevgi/function"
+```
+
+## Example
+
+```ruby
+Sevgi::F.eq?(0.1 + 0.2, 0.3, precision: 12)
+```
+
+## 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
+
+None beyond Ruby and this gem's Ruby dependencies.
+
+## Links
+
+- Documentation: https://sevgi.roktas.dev
+- API documentation: https://www.rubydoc.info/gems/sevgi-function
+- Source: https://github.com/roktas/sevgi/tree/main/function
+- Changelog: https://github.com/roktas/sevgi/blob/main/CHANGELOG.md

data/lib/sevgi/core.rb

@@ -45,27 +45,10 @@ module Sevgi
   # Error raised for invalid public API usage.
   ArgumentError = Class.new(Error) unless defined?(self::ArgumentError)
 
-  # Shared immutable empty array.
-  EMPTY_ARRAY = [].freeze
-
-  # Shared immutable empty hash.
-  EMPTY_HASH = {}.freeze
-
-  # Shared immutable empty options hash.
-  EMPTY_OPTS = {}.freeze
-
-  # Shared empty string.
-  EMPTY_STRING = ""
-
-  # Identity callable.
-  IDENTITY = -> (x) { x }.freeze
-
   # Sentinel object used to distinguish an omitted value from nil.
   Undefined = Object
     .new
     .tap do |undefined|
-      const_set(:Self, -> { Undefined })
-
       # Returns the sentinel name.
       # @return [String]
       def undefined.to_s = "Undefined"
@@ -105,7 +88,10 @@ module Sevgi
       # Returns the first argument that is not {Sevgi::Undefined}.
       # @param args [Array<Object>] candidate values
       # @return [Object, nil] first defined value, including nil, or nil when none exists
-      def undefined.coalesce(*args) = args.find(Self) { |x| !equal?(x) }
+      # @example Resolve an optional value
+      #   Sevgi::Undefined.coalesce(Sevgi::Undefined, nil) # => nil
+      # @see #default
+      def undefined.coalesce(*args) = args.find { |x| !equal?(x) }
     end
     .freeze
 end

data/lib/sevgi/function/locate.rb

@@ -2,6 +2,16 @@
 
 module Sevgi
   module Function
+    # Found file location returned by locate helpers.
+    #
+    # @!attribute [r] file
+    #   @return [String] absolute matching file path
+    # @!attribute [r] slug
+    #   @return [String] candidate path that matched
+    # @!attribute [r] dir
+    #   @return [String] directory where the match was found
+    Location = Data.define(:file, :slug, :dir)
+
     # Locates one of several candidate files by walking upward from a start directory.
     class Locate
       # @overload call(paths, start = Dir.pwd, exclude: nil, &block)
@@ -12,64 +22,83 @@ module Sevgi
       #   @yield optional matcher used instead of file existence checks
       #   @yieldparam path [String] candidate path
       #   @yieldreturn [Boolean]
-      #   @return [Sevgi::Function::Locate::Location, nil] found location, or nil
+      #   @return [Sevgi::Function::Location, nil] found location, or nil
       def self.call(*, **, &block) = new(*, **).call(&block)
 
-      Location = Data.define(:file, :slug, :dir)
+      # Returns candidate paths.
+      # @return [Array<String>]
+      attr_reader :paths
 
-      private_constant :Location
+      # Returns the absolute start directory.
+      # @return [String]
+      attr_reader :start
 
-      # @!attribute [r] paths
-      #   @return [Array<String>] candidate paths
-      # @!attribute [r] start
-      #   @return [String] start directory
-      # @!attribute [r] exclude
-      #   @return [Array<String>, nil] expanded paths ignored during lookup
-      attr_reader :paths, :start, :exclude
+      # Returns expanded paths ignored during lookup.
+      # @return [Array<String>, nil]
+      attr_reader :exclude
 
       # Builds an upward file locator.
       # @param paths [Array<String>, String] candidate file paths
-      # @param start [String] directory where lookup starts
-      # @param exclude [Array<String>, String, nil] paths ignored during lookup
+      # @param start [String] directory where lookup starts, expanded without changing process cwd
+      # @param exclude [Array<String>, String, nil] paths ignored during lookup after absolute expansion
       # @return [void]
       def initialize(paths, start = ::Dir.pwd, exclude: nil)
         @paths = Array(paths)
-        @start = start
+        @start = ::File.expand_path(start)
         @exclude = [*exclude].map { ::File.expand_path(it) } unless exclude.nil?
       end
 
       # Runs the upward lookup.
       # @yield optional matcher used instead of file existence checks
-      # @yieldparam path [String] candidate path
+      # @yieldparam path [String] absolute candidate path
       # @yieldreturn [Boolean]
-      # @return [Sevgi::Function::Locate::Location, nil] found location, or nil
-      # @raise [Errno::ENOENT] when the start directory cannot be entered
+      # @note Absolute exclusions are applied before the default or custom matcher.
+      # @return [Sevgi::Function::Location, nil] found location, or nil
+      # @raise [Errno::ENOENT] when the start directory does not exist
+      # @raise [Errno::ENOTDIR] when the start path is not a directory
       def call(&block)
-        origin = ::Dir.pwd
-        ::Dir.chdir(start)
+        validate_start!
 
-        here = ::Dir.pwd
-        until (found = match(&block))
-          ::Dir.chdir("..")
-          ::Dir.pwd == here ? return : here = ::Dir.pwd
-        end
+        each_parent(start) do |here|
+          next unless (found = match(here, &block))
 
-        Location[::File.expand_path(found, here), found, here]
-      ensure
-        ::Dir.chdir(origin)
+          slug, file = found
+
+          return Location[file, slug, here]
+        end
       end
 
       private
 
-      def match(&block)
-        finder = block ||
-          if exclude.nil?
-            proc { |path| ::File.exist?(path) }
-          else
-            proc { |path| !exclude.include?(::File.expand_path(path)) && ::File.exist?(path) }
-          end
+      def each_parent(here)
+        loop do
+          yield here
+
+          parent = ::File.dirname(here)
+          break if parent == here
+
+          here = parent
+        end
+      end
+
+      def excluded?(candidate)
+        exclude&.include?(candidate)
+      end
+
+      def match(here, &block)
+        paths.each do |path|
+          candidate = ::File.expand_path(path, here)
+          next if excluded?(candidate)
+
+          return [path, candidate] if (block || proc { ::File.exist?(it) }).call(candidate)
+        end
+
+        nil
+      end
 
-        paths.find { finder.call(it) }
+      def validate_start!
+        raise ::Errno::ENOENT, start unless ::File.exist?(start)
+        raise ::Errno::ENOTDIR, start unless ::File.directory?(start)
       end
     end
 
@@ -78,7 +107,7 @@ module Sevgi
     # @param start [String] directory where lookup starts
     # @param exclude [Array<String>, String, nil] paths ignored during lookup
     # @param extension [String] default extension added before lookup
-    # @return [Sevgi::Function::Locate::Location] found location
+    # @return [Sevgi::Function::Location] found location
     # @raise [Sevgi::Error] when no matching file exists
     def self.locate(filename, start, exclude: nil, extension: EXTENSION)
       Locate.(F.qualify(filename, extension), start, exclude:).tap do |path|

data/lib/sevgi/function/math.rb

@@ -74,11 +74,17 @@ module Sevgi
       def cot(degrees) = 1.0 / ::Math.tan(to_radians(degrees))
 
       # Counts complete divisions in a length.
-      # @param length [Numeric] total length
-      # @param division [Numeric] division size
+      # @param length [Numeric] finite total length
+      # @param division [Numeric] finite, non-zero division size
       # @return [Integer]
-      # @raise [ZeroDivisionError] when division is zero
-      def count(length, division) = (length / division.to_f).to_i
+      # @raise [Sevgi::ArgumentError] when an operand is not a finite Numeric or division is zero
+      def count(length, division)
+        length = finite_real(:length, length)
+        divisor = finite_real(:division, division)
+        ArgumentError.("Division must not be zero") if divisor.zero?
+
+        (length / divisor).to_i
+      end
 
       # Compares two numeric values after approximate rounding.
       # @param left [Numeric] left operand
@@ -162,6 +168,25 @@ module Sevgi
       # @param precision [Integer, nil] explicit precision, or nil to use {Math.precision}
       # @return [Boolean]
       def zero?(value, precision: nil) = eq?(value, 0.0, precision:)
+
+      private
+
+      def finite_real(field, value)
+        unless value.is_a?(::Numeric)
+          ArgumentError.("#{field} must be a finite Numeric: #{value.inspect}")
+        end
+
+        number = begin
+          value.to_f
+        rescue ::StandardError => e
+          ArgumentError.("#{field} must be a finite Numeric: #{value.inspect} (#{e.message})")
+        end
+
+        ArgumentError.("#{field} must be finite: #{value.inspect}") unless number.is_a?(::Float) && number.finite?
+
+        number
+      end
+
     end
 
     extend Math

data/lib/sevgi/function/shell.rb

@@ -6,17 +6,17 @@ module Sevgi
   module Function
     # Shell execution helpers and executable lookup utilities.
     module Shell
-      # Checks whether a program exists in PATH.
-      # @param program [Object] program name
-      # @return [Boolean] true when an executable with this name is found
+      # Checks whether a program exists and is executable.
+      # @param program [Object] program name, absolute path, or relative slash-containing path
+      # @return [Boolean] true when an executable regular file is found
+      # @note PATH is evaluated on every call; empty PATH segments mean the current directory.
       def executable?(program)
         program = program.to_s
         return false if program.empty?
+        return executable_file?(program) if slash_path?(program)
 
-        executable_cache.fetch(program) do
-          executable_cache[program] = ENV.fetch("PATH", "").split(::File::PATH_SEPARATOR).any? do |dir|
-            ::File.executable?(::File.join(dir, program))
-          end
+        ENV.fetch("PATH", "").split(::File::PATH_SEPARATOR, -1).any? do |dir|
+          executable_file?(::File.join(dir.empty? ? "." : dir, program))
         end
       end
 
@@ -24,8 +24,9 @@ module Sevgi
       # @param args [Array<Object>] command arguments
       # @return [nil]
       # @raise [Sevgi::Error] when the program cannot be found in PATH
+      # @note The first argument is checked as one exact argv entry; it is never shell-split.
       def executable!(*args)
-        program = args.first.to_s.split.first
+        program = args.first.to_s
         Error.("Missing executable: #{program}") unless executable?(program)
       end
 
@@ -73,6 +74,101 @@ module Sevgi
         def self.dummy = new([], [], [], 0)
       end
 
+      # Shared process-global SIGINT state for overlapping shell runners.
+      # @api private
+      module Signals
+        Entry = Data.define(:runner, :pid)
+        WAKE = "."
+
+        private_constant :WAKE
+
+        class << self
+          def register(runner, pid)
+            mutex.synchronize do
+              install unless entries.any?
+              entries[runner] = Entry.new(runner, pid)
+            end
+          end
+
+          def unregister(runner)
+            worker = mutex.synchronize do
+              next unless entries.delete(runner)
+
+              restore unless entries.any?
+            end
+
+            worker.join if worker && worker != Thread.current
+          end
+
+          private
+
+          def dispatch
+            active = mutex.synchronize { entries.values.dup }
+            active.each { dispatch_entry(it) }
+          end
+
+          def dispatch_entry(entry)
+            entry.runner.send(:handle_sigint, entry.pid)
+          rescue ::StandardError => e
+            warn("SIGINT dispatch failed: #{e.message}")
+          end
+
+          def install
+            reader, writer = ::IO.pipe
+            worker = Thread.new { listen(reader) }
+            previous = Signal.trap("INT") { notify(writer) }
+
+            @previous = previous
+            @worker = worker
+            @writer = writer
+          rescue ::StandardError
+            Signal.trap("INT", previous) if previous
+            close_io(writer)
+            worker&.join
+            close_io(reader)
+            raise
+          end
+
+          def listen(reader)
+            dispatch while reader.read(1)
+          rescue ::IOError, ::SystemCallError
+            nil
+          ensure
+            close_io(reader)
+          end
+
+          def mutex = @mutex ||= Mutex.new
+
+          def entries = @entries ||= {}
+
+          def notify(writer)
+            writer.write_nonblock(WAKE, exception: false)
+          rescue ::IOError, ::SystemCallError
+            nil
+          end
+
+          def restore
+            Signal.trap("INT", @previous)
+            @previous = nil
+
+            writer = @writer
+            worker = @worker
+            @worker = nil
+            @writer = nil
+            close_io(writer)
+            worker
+          end
+
+          def close_io(io)
+            io&.close unless io&.closed?
+          rescue ::IOError
+            nil
+          end
+        end
+      end
+
+      private_constant :Signals
+
       # Runs shell commands and captures stdout, stderr, and exit status.
       # @api private
       class Runner
@@ -91,12 +187,9 @@ module Sevgi
         def call(*args, &input)
           return Result.dummy if args.empty?
 
+          @coathooks = 0
           outs, errs, status = Open3.popen3(*args) do |stdin, stdout, stderr, wait_thread|
-            content = input.call if input
-            stdin.write(content) if content
-            stdin.close
-
-            capture(stdout, stderr, wait_thread)
+            capture(stdin, stdout, stderr, wait_thread, &input)
           end
 
           Result.new(args, outs, errs, status.exitstatus)
@@ -104,19 +197,48 @@ module Sevgi
 
         private
 
-        def capture(stdout, stderr, wait_thread)
-          # Handle `^C`
-          previous = trap("INT") { handle_sigint(wait_thread.pid) }
+        # rubocop:disable Lint/RescueException
+        def capture(stdin, stdout, stderr, wait_thread, &input)
+          registered = false
+          Signals.register(self, wait_thread.pid)
+          registered = true
+          readers = start_readers(stdout, stderr)
 
-          outs = Thread.new { stdout.readlines.map(&:chomp) }
-          errs = Thread.new { stderr.readlines.map(&:chomp) }
-
-          [outs.value, errs.value, wait_thread.value]
+          read_process(stdin, wait_thread, readers, &input)
+        rescue Exception
+          cleanup_failed_capture(stdin, wait_thread, readers)
+          raise
         ensure
-          trap("INT", previous) if previous
+          close_input(stdin)
+          Signals.unregister(self) if registered
+        end
+        # rubocop:enable Lint/RescueException
+
+        def start_readers(stdout, stderr)
+          [
+            Thread.new { stdout.readlines.map(&:chomp) },
+            Thread.new { stderr.readlines.map(&:chomp) }
+          ]
+        end
+
+        def read_process(stdin, wait_thread, readers, &input)
+          write_input(stdin, &input)
+          close_input(stdin)
+
+          status = wait_thread.value
+
+          [readers[0].value, readers[1].value, status]
+        end
+
+        def cleanup_failed_capture(stdin, wait_thread, readers)
+          close_input(stdin)
+          stop_process(wait_thread)
+          join_readers(readers)
         end
 
         def handle_sigint(pid)
+          @coathooks += 1
+
           message, signal = if @coathooks > 1
             ["SIGINT received again. Force quitting...", "KILL"]
           else
@@ -126,28 +248,68 @@ module Sevgi
           warn
           warn(message)
           ::Process.kill(signal, pid)
-          @coathooks += 1
         rescue Errno::ESRCH
           warn("No process to kill.")
         end
+
+        def write_input(stdin)
+          return unless block_given?
+
+          content = yield
+          stdin.write(content) if content
+        end
+
+        def close_input(stdin)
+          stdin.close unless stdin.closed?
+        rescue IOError
+          nil
+        end
+
+        def stop_process(wait_thread)
+          return unless wait_thread&.alive?
+
+          kill_process("TERM", wait_thread.pid)
+          return if wait_thread.join(1)
+
+          kill_process("KILL", wait_thread.pid)
+          wait_thread.join
+        end
+
+        def kill_process(signal, pid)
+          ::Process.kill(signal, pid)
+        rescue Errno::ESRCH
+          nil
+        end
+
+        def join_readers(readers)
+          Array(readers).each(&:join)
+        end
       end
 
       # @overload sh(*args, &block)
       #   Runs a command and captures stdout, stderr, and exit status.
       #   @param args [Array<String>] command and arguments
-      #   @yield optional content writer for stdin
-      #   @yieldreturn [String, nil]
+      #   @yield optional stdin producer, evaluated once after output readers start
+      #   @yieldreturn [String, nil] content to write to stdin; nil writes nothing
       #   @return [Sevgi::Function::Shell::Result]
-      #   @raise [Errno::ENOENT] when the executable cannot be spawned
+      #   @raise [SystemCallError] when the executable cannot be spawned or process pipes cannot be opened
+      #   @raise [StandardError] when the input block raises; the child is terminated and reaped before propagation
+      #   @note The child's stdin is closed after the input block. During execution, the first SIGINT sends TERM to the
+      #     child process and the second SIGINT as KILL to each active child outside trap context, then restores the
+      #     previous handler.
       def sh(...) = Runner.new.(...)
 
       # Runs a command, requiring both executable lookup and successful exit status.
       # @param args [Array<String>] command and arguments
-      # @yield optional content writer for stdin
-      # @yieldreturn [String, nil]
+      # @yield optional stdin producer, evaluated once after output readers start
+      # @yieldreturn [String, nil] content to write to stdin; nil writes nothing
       # @return [Sevgi::Function::Shell::Result]
       # @raise [Sevgi::Error] when the executable is missing or the command fails
-      # @raise [Errno::ENOENT] when the executable cannot be spawned
+      # @raise [SystemCallError] when the executable cannot be spawned or process pipes cannot be opened
+      # @raise [StandardError] when the input block raises; the child is terminated and reaped before propagation
+      # @note The child's stdin is closed after the input block. During execution, the first SIGINT sends TERM to the
+      #   child process and the second SIGINT as KILL to each active child outside trap context, then restores the previous
+      #   handler.
       def sh!(*args, &block)
         executable!(*args) unless args.empty?
 
@@ -163,7 +325,13 @@ module Sevgi
 
       private
 
-      def executable_cache = @executable_cache ||= {}
+      def executable_file?(path)
+        ::File.file?(path) && ::File.executable?(path)
+      end
+
+      def slash_path?(program)
+        program.include?(::File::SEPARATOR) || (::File::ALT_SEPARATOR && program.include?(::File::ALT_SEPARATOR))
+      end
     end
 
     extend Shell

data/lib/sevgi/function/string.rb

@@ -22,19 +22,17 @@ module Sevgi
     # Lightweight English pluralization helper.
     module Pluralize
       # Words that should not be pluralized.
-      UNCOUNTABLES = Hash[
-        *%w[
-          sheep
-          fish
-          sheep
-          series
-          species
-          money
-          rice
-          information
-          equipment
-        ].map { [it, true] }.flatten
+      UNCOUNTABLES = %w[
+        equipment
+        fish
+        information
+        money
+        rice
+        series
+        sheep
+        species
       ]
+        .to_h { [it, true] }
         .freeze
 
       # Singular-to-plural forms that do not follow suffix rules.
@@ -99,7 +97,7 @@ module Sevgi
       def pluralize(word)
         result = word.to_s.dup
 
-        return result if word.empty? || UNCOUNTABLES.key?(result) || PLURALS.key?(result)
+        return result if result.empty? || UNCOUNTABLES.key?(result) || PLURALS.key?(result)
         return IRREGULARS[result] if IRREGULARS.key?(result)
 
         RULES.each { |(rule, replacement)| break if result.sub!(rule, replacement) }

data/lib/sevgi/function/version.rb

@@ -3,6 +3,6 @@
 module Sevgi
   module Function
     # Current version of the Sevgi function gem.
-    VERSION = "0.93.1"
+    VERSION = "0.95.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sevgi-function
 version: !ruby/object:Gem::Version
-  version: 0.93.1
+  version: 0.95.0
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,6 +15,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE
 - README.md
 - lib/sevgi/core.rb
 - lib/sevgi/function.rb
@@ -41,14 +43,14 @@ 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:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.11
 specification_version: 4
 summary: Various utility functions for the Sevgi toolkit.
 test_files: []