sevgi-function 0.93.1 → 0.94.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 060b3cdf233db4debfb3429c2d8663d94840ae00de70980124089f2d5d04c675
-  data.tar.gz: 2f80215534863a248171055a829ddcfa36ccf73013fbd430064b04fade3eeb5f
+  metadata.gz: 7afe91e24bcfcbc6b2e398838f8cf9cce6fdb97b9c7b7cded831a6f892c75280
+  data.tar.gz: 505afa54ddc3e02573ed7169ca6aa01f14a90bd3c57d41bafe0cb87bb7b47e46
 SHA512:
-  metadata.gz: e4de61331c47e0007652e6c7548adf6de50e8d4ded0e1bc95c05dc9d7a0fc9929ee4ffdd3af3b3cd73eddc777495691c4952186e3f0f34390edcee062f0e907b
-  data.tar.gz: a36e58998da54d4c687e9266e1c58290af919ab3e4229627ab2d4c5a9b0ec4bd7a04a053ef8e8779ea3ef51268c1add54c75328475904562267d7073e683fa3f
+  metadata.gz: dd9066dc9cc025ff15122265b66ace4861a62b150a10ac72addd1255bf3223337cd1ad3c6e0259423abc184a98db97cb0f5c0e0769224240e20db8ae8654ee41
+  data.tar.gz: 0d47888b1cce2c39fba38c09ead6044401908ae48d789ff596ee0cb7055c2225cab69b094803c84a8a8d1737d4d2a3268e1f769154e9770c55c01e9813f6160e

data/CHANGELOG.md

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

data/LICENSE

@@ -0,0 +1,5 @@
+Sevgi Function 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

@@ -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 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,21 +45,6 @@ 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

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,78 @@ 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)
-
-      private_constant :Location
-
       # @!attribute [r] paths
       #   @return [Array<String>] candidate paths
       # @!attribute [r] start
-      #   @return [String] start directory
+      #   @return [String] absolute start directory
       # @!attribute [r] exclude
       #   @return [Array<String>, nil] expanded paths ignored during lookup
       attr_reader :paths, :start, :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
+      # @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))
+
+          slug, file = found
 
-        Location[::File.expand_path(found, here), found, here]
-      ensure
-        ::Dir.chdir(origin)
+          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 !block && 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 +102,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

@@ -77,8 +77,13 @@ module Sevgi
       # @param length [Numeric] total length
       # @param division [Numeric] division size
       # @return [Integer]
-      # @raise [ZeroDivisionError] when division is zero
-      def count(length, division) = (length / division.to_f).to_i
+      # @raise [Sevgi::ArgumentError] when division is zero
+      def count(length, division)
+        divisor = division.to_f
+        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

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
 
@@ -91,12 +91,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 +101,47 @@ module Sevgi
 
         private
 
-        def capture(stdout, stderr, wait_thread)
+        # rubocop:disable Lint/RescueException
+        def capture(stdin, stdout, stderr, wait_thread, &input)
           # Handle `^C`
           previous = trap("INT") { handle_sigint(wait_thread.pid) }
+          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
+          close_input(stdin)
           trap("INT", previous) if previous
         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 +151,66 @@ 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 sends KILL; the previous SIGINT handler is restored before return.
       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 sends KILL; the previous SIGINT handler is restored before return.
       def sh!(*args, &block)
         executable!(*args) unless args.empty?
 
@@ -163,7 +226,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.94.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.94.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,7 +43,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:
   - - ">="