sevgi-function 0.73.2 → 0.94.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54d8ec739ffb09b6af47ed063c7f623eec4d53f460da37145dde187d66afb0bd
-  data.tar.gz: 73d6bcc926901e37b9cc5a34cab9ef36dc702e3465e04299fdd8a50ae98de2e9
+  metadata.gz: 7afe91e24bcfcbc6b2e398838f8cf9cce6fdb97b9c7b7cded831a6f892c75280
+  data.tar.gz: 505afa54ddc3e02573ed7169ca6aa01f14a90bd3c57d41bafe0cb87bb7b47e46
 SHA512:
-  metadata.gz: bb79282e9492163de25d534c4c00e69d5e6e2f12043cfba825dd1dbc5d81cf6a2ca8e45e294802956b45ed825a25e07319507e9815d1246bb1723ecd43d29fd4
-  data.tar.gz: 841d5ca22c243c504e5b64d50f16ba5ae9ff33e9cdf96300b517fe2c60e32b48fae7133cc2b248f81cc1d8c2b7ddf66f795439aa1c547155917608c8b6e1828d
+  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

@@ -0,0 +1,36 @@
+# Sevgi Function
+
+Shared helper functions used by Sevgi components.
+
+## 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

@@ -1,50 +1,95 @@
 # frozen_string_literal: true
 
 module Sevgi
-  # Constants
+  # Environment variable that asks command-line tools to re-raise captured errors.
   ENVVOMIT = "SEVGI_VOMIT"
+
+  # Default file extension for Sevgi scripts.
   EXTENSION = "sevgi"
 
-  # Errors
   unless defined?(Error)
+    # Base error class for Sevgi failures.
     class Error < StandardError
+      # @overload call(*args, **kwargs, &block)
+      #   Raises this error class.
+      #   @param args [Array] positional arguments forwarded to the exception constructor
+      #   @param kwargs [Hash] keyword arguments forwarded to the exception constructor
+      #   @yield optional block forwarded to the exception constructor
+      #   @yieldreturn [Object]
+      #   @return [void]
+      #   @raise [Sevgi::Error] always raises an instance of this class
       def self.call(*, **, &) = raise(self, *, **, &)
     end
   end
 
-  # for incorrect API usage
+  unless defined?(self::MissingComponentError)
+    # Error raised when an optional Sevgi component is required but unavailable.
+    class MissingComponentError < Error
+      # @return [String] missing component name
+      attr_reader :component
+
+      # Builds a missing component error.
+      # @param component [String, Symbol] missing component name
+      # @return [void]
+      def initialize(component)
+        @component = component.to_s
+
+        super("\"#{component}\" required")
+      end
+    end
+  end
+
+  # Error raised for internal invariants and implementation paths that should be unreachable.
   PanicError = Class.new(Error) unless defined?(self::PanicError)
-  ArgumentError = Class.new(Error) unless defined?(self::ArgumentError)
 
-  # Helpers
-  # Copied from https://github.com/dry-rb/dry-core. All kudos to the original authors.
-  EMPTY_ARRAY = [].freeze
-  EMPTY_HASH = {}.freeze
-  EMPTY_OPTS = {}.freeze
-  EMPTY_STRING = ""
-  IDENTITY = -> (x) { x }.freeze
+  # Error raised for invalid public API usage.
+  ArgumentError = Class.new(Error) unless defined?(self::ArgumentError)
 
+  # 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"
 
+      # Returns the sentinel inspection string.
+      # @return [String]
       def undefined.inspect = "Undefined"
 
+      # Resolves a value unless it is {Sevgi::Undefined}.
+      # @param x [Object] candidate value
+      # @param y [Object] fallback value
+      # @yield computes the fallback when both x and y are undefined
+      # @yieldreturn [Object]
+      # @return [Object] x, y, or the yielded fallback
       def undefined.default(x, y = self)
         return x unless equal?(x)
 
         equal?(y) ? yield : y
       end
 
+      # Maps a value unless it is {Sevgi::Undefined}.
+      # @param value [Object] candidate value
+      # @yield maps a defined value
+      # @yieldparam value [Object] the defined value
+      # @yieldreturn [Object]
+      # @return [Object] the sentinel or the mapped value
       def undefined.map(value) = equal?(value) ? self : yield(value)
 
+      # Returns the sentinel itself.
+      # @return [Sevgi::Undefined]
       def undefined.dup = self
 
+      # Returns the sentinel itself.
+      # @return [Sevgi::Undefined]
       def undefined.clone = self
 
+      # 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) }
     end
     .freeze

data/lib/sevgi/function/color.rb

@@ -2,15 +2,46 @@
 
 module Sevgi
   module Function
+    # ANSI color and style helpers for terminal output.
     module Color
+      # Wraps a string in the blue terminal style.
+      # @param string [Object] content to style
+      # @return [String]
       def blue(string) = "\e[1m\e[38;5;81m#{string}\e[0m"
+
+      # Wraps a string in the cyan terminal style.
+      # @param string [Object] content to style
+      # @return [String]
       def cyan(string) = "\e[1m\e[38;5;51m#{string}\e[0m"
+
+      # Wraps a string in the green terminal style.
+      # @param string [Object] content to style
+      # @return [String]
       def green(string) = "\e[1m\e[38;5;35m#{string}\e[0m"
+
+      # Wraps a string in the magenta terminal style.
+      # @param string [Object] content to style
+      # @return [String]
       def magenta(string) = "\e[1m\e[38;5;200m#{string}\e[0m"
+
+      # Wraps a string in the red terminal style.
+      # @param string [Object] content to style
+      # @return [String]
       def red(string) = "\e[1m\e[38;5;197m#{string}\e[0m"
+
+      # Wraps a string in the yellow terminal style.
+      # @param string [Object] content to style
+      # @return [String]
       def yellow(string) = "\e[1m\e[38;5;227m#{string}\e[0m"
 
+      # Wraps a string in the bold terminal style.
+      # @param string [Object] content to style
+      # @return [String]
       def bold(string) = "\e[1m#{string}\e[0m"
+
+      # Wraps a string in the dim terminal style.
+      # @param string [Object] content to style
+      # @return [String]
       def dim(string) = "\e[1m\e[2m#{string}\e[0m"
     end
 

data/lib/sevgi/function/file.rb

@@ -5,7 +5,16 @@ require "fileutils"
 
 module Sevgi
   module Function
+    # File-system helpers used by build scripts and DSL support code.
     module File
+      # Checks whether a file would change if written with content.
+      # @param file [String] file path to compare
+      # @param content [String] proposed file content
+      # @yield optional normalization filter applied to both old and new content
+      # @yieldparam content [String] content to normalize
+      # @yieldreturn [String]
+      # @return [Boolean] true when the file is missing or content differs
+      # @raise [Errno::EACCES] when the file cannot be read
       def changed?(file, content, &filter)
         return true unless ::File.exist?(file)
 
@@ -15,6 +24,10 @@ module Sevgi
         Digest::SHA1.digest(old_content) != Digest::SHA1.digest(content)
       end
 
+      # Finds an existing file by exact path or by trying default extensions.
+      # @param file [String] file path or extensionless basename
+      # @param extensions [Array<String>] extensions to try when file has no extension
+      # @return [String, nil] matching file path, or nil when no file is found
       def existing(file, extensions)
         return file if ::File.exist?(file)
         return nil unless ::File.extname(file).empty?
@@ -23,27 +36,51 @@ module Sevgi
         extensions.map { |ext| "#{file}.#{ext}" }.detect { |file| ::File.exist?(file) }
       end
 
+      # Finds an existing file or raises.
+      # @param file [String] file path or extensionless basename
+      # @param extensions [Array<String>] extensions to try when file has no extension
+      # @return [String] matching file path
+      # @raise [Sevgi::ArgumentError] when no matching file exists
       def existing!(file, extensions)
         existing(file, extensions).tap do |found|
-          raise ArgumentError, "No matching file(s) found: #{file}" unless found
+          ArgumentError.("No matching file(s) found: #{file}") unless found
         end
       end
 
-      def existings(*files, extensions: [])
-        {}.tap do |existings|
-          files.compact.each { |file| existings[file] = existing(file, extensions) }
+      # Maps each non-nil input file to an existing path lookup result.
+      # @param files [Array<String, nil>] file paths or extensionless basenames
+      # @param extensions [Array<String>] extensions to try when a file has no extension
+      # @return [Hash{String => String, nil}] original file names mapped to found paths
+      def existing_map(*files, extensions: [])
+        {}.tap do |found|
+          files.compact.each { |file| found[file] = existing(file, extensions) }
         end
       end
 
-      def existings!(...)
-        existings = F.existings(...)
-        missings = existings.select { |_, match| match.nil? }.keys
+      # @overload existing_map!(*files, extensions: [])
+      #   Maps each non-nil input file to an existing path lookup result or raises.
+      #   @param files [Array<String, nil>] file paths or extensionless basenames
+      #   @param extensions [Array<String>] extensions to try when a file has no extension
+      #   @return [Hash{String => String}] original file names mapped to found paths
+      #   @raise [Sevgi::ArgumentError] when any requested file is missing
+      def existing_map!(...)
+        found = F.existing_map(...)
+        missings = found.select { |_, match| match.nil? }.keys
 
-        raise ArgumentError, "No matching file(s) found: #{missings.join(", ")}" unless missings.empty?
+        ArgumentError.("No matching file(s) found: #{missings.join(", ")}") unless missings.empty?
 
-        existings
+        found
       end
 
+      # Writes content to a file when it changed, or prints to stdout without a path.
+      # @param content [String] output content
+      # @param paths [Array<String>] path components for the output file
+      # @yield optional normalization filter used for change detection
+      # @yieldparam content [String] old or new content
+      # @yieldreturn [String]
+      # @return [String, nil] expanded file path when written, otherwise nil
+      # @raise [Errno::EACCES] when the file cannot be read or written
+      # @raise [Errno::ENOENT] when the parent directory does not exist
       def out(content, *paths, &filter)
         if paths.empty?
           ::Kernel.puts(content)
@@ -57,13 +94,20 @@ module Sevgi
         end
       end
 
+      # Adds a default extension when a path has no extension.
+      # @param file [String] file path
+      # @param default_extension [String] extension to append without a leading dot
+      # @return [String] qualified file path
       def qualify(file, default_extension)
         return file unless ::File.extname(file).empty?
 
         "#{file}.#{default_extension}"
       end
 
-      # Adapted from ActiveSupport
+      # Replaces or removes the extension on a path.
+      # @param ext [String, nil] replacement extension, without or with a leading dot
+      # @param paths [Array<String>] path components
+      # @return [String] path with the replacement extension
       def subext(ext, *paths)
         path = ::File.join(*paths)
 
@@ -75,6 +119,10 @@ module Sevgi
         Pathname.new(path).sub_ext(ext).to_s
       end
 
+      # Creates a file and any missing parent directories.
+      # @param paths [Array<String>] path components for the file
+      # @return [String] touched file path
+      # @raise [Errno::EACCES] when the file or parent directory cannot be created
       def touch(*paths)
         ::File.join(*paths).tap do |path|
           ::FileUtils.mkdir_p(::File.dirname(path))

data/lib/sevgi/function/locate.rb

@@ -2,53 +2,111 @@
 
 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)
+      #   Builds a locator and runs it.
+      #   @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
+      #   @yield optional matcher used instead of file existence checks
+      #   @yieldparam path [String] candidate path
+      #   @yieldreturn [Boolean]
+      #   @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] 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, 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] absolute candidate path
+      # @yieldreturn [Boolean]
+      # @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
 
+    # Locates a Sevgi-related file by walking upward from a start directory.
+    # @param filename [String] file name or extensionless basename
+    # @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::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|
-        raise Error, "Cannot load a file matching: #{filename}" unless path
+        Error.("Cannot load a file matching: #{filename}") unless path
       end
     end
   end

data/lib/sevgi/function/math.rb

@@ -2,51 +2,170 @@
 
 module Sevgi
   module Function
+    # Numeric and trigonometric helpers used by geometry and DSL code.
     module Math
-      @precision = PRECISION = 6
+      # Default decimal precision used by approximate comparisons.
+      PRECISION = 6
 
-      class << self
-        attr_accessor :precision
+      PRECISION_KEY = :sevgi_function_math_precision
+
+      private_constant :PRECISION_KEY
+
+      # Returns the current thread's default numeric precision.
+      # @return [Integer] current thread precision, or {PRECISION} when no override is set
+      def self.precision
+        precision = Thread.current.thread_variable_get(PRECISION_KEY)
+
+        precision.nil? ? PRECISION : precision
+      end
+
+      # Sets or clears the current thread's default numeric precision.
+      # @param precision [Integer, nil] precision override, or nil to return to {PRECISION}
+      # @return [Integer, nil] assigned precision
+      def self.precision=(precision)
+        Thread.current.thread_variable_set(PRECISION_KEY, precision)
       end
 
+      # Returns the inverse cosine in degrees.
+      # @param value [Numeric] cosine value
+      # @return [Float]
+      # @raise [Math::DomainError] when value is outside -1..1
       def acos(value) = to_degrees(::Math.acos(value))
 
+      # Returns the inverse cotangent in degrees.
+      # @param value [Numeric] cotangent value
+      # @return [Float]
       def acot(value) = 90.0 - to_degrees(::Math.atan(value))
 
-      def approx(float, precision = nil) = float.round(precision || Function::Math.precision)
+      # Rounds a float with an explicit or thread-local precision.
+      # @param float [Numeric] value to round
+      # @param precision [Integer, nil] explicit precision, or nil to use {Math.precision}
+      # @return [Numeric] rounded value
+      # @raise [TypeError] when float cannot be rounded
+      def approx(float, precision = nil)
+        float.round(precision.nil? ? Function::Math.precision : precision)
+      end
 
+      # Returns the inverse sine in degrees.
+      # @param value [Numeric] sine value
+      # @return [Float]
+      # @raise [Math::DomainError] when value is outside -1..1
       def asin(value) = to_degrees(::Math.asin(value))
 
+      # Returns the inverse tangent in degrees.
+      # @param value [Numeric] tangent value
+      # @return [Float]
       def atan(value) = to_degrees(::Math.atan(value))
 
+      # Returns the quadrant-aware inverse tangent in degrees.
+      # @param y [Numeric] y component
+      # @param x [Numeric] x component
+      # @return [Float]
       def atan2(y, x) = to_degrees(::Math.atan2(y, x))
 
+      # Returns the cosine of an angle expressed in degrees.
+      # @param degrees [Numeric] angle in degrees
+      # @return [Float]
       def cos(degrees) = ::Math.cos(to_radians(degrees))
 
+      # Returns the cotangent of an angle expressed in degrees.
+      # @param degrees [Numeric] angle in degrees
+      # @return [Float]
       def cot(degrees) = 1.0 / ::Math.tan(to_radians(degrees))
 
-      def count(length, division) = (length / division.to_f).to_i
+      # Counts complete divisions in a length.
+      # @param length [Numeric] total length
+      # @param division [Numeric] division size
+      # @return [Integer]
+      # @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
+      # @param right [Numeric] right operand
+      # @param precision [Integer, nil] explicit precision, or nil to use {Math.precision}
+      # @return [Boolean]
       def eq?(left, right, precision: nil) = approx(left, precision) == approx(right, precision)
 
+      # Checks whether the rounded left operand is greater than or equal to the rounded right operand.
+      # @param left [Numeric] left operand
+      # @param right [Numeric] right operand
+      # @param precision [Integer, nil] explicit precision, or nil to use {Math.precision}
+      # @return [Boolean]
       def ge?(left, right, precision: nil) = approx(left, precision) >= approx(right, precision)
 
+      # Checks whether the rounded left operand is greater than the rounded right operand.
+      # @param left [Numeric] left operand
+      # @param right [Numeric] right operand
+      # @param precision [Integer, nil] explicit precision, or nil to use {Math.precision}
+      # @return [Boolean]
       def gt?(left, right, precision: nil) = approx(left, precision) > approx(right, precision)
 
+      # Checks whether the rounded left operand is less than or equal to the rounded right operand.
+      # @param left [Numeric] left operand
+      # @param right [Numeric] right operand
+      # @param precision [Integer, nil] explicit precision, or nil to use {Math.precision}
+      # @return [Boolean]
       def le?(left, right, precision: nil) = approx(left, precision) <= approx(right, precision)
 
+      # Checks whether the rounded left operand is less than the rounded right operand.
+      # @param left [Numeric] left operand
+      # @param right [Numeric] right operand
+      # @param precision [Integer, nil] explicit precision, or nil to use {Math.precision}
+      # @return [Boolean]
       def lt?(left, right, precision: nil) = approx(left, precision) < approx(right, precision)
 
+      # Rounds a value only when precision is present.
+      # @param float [Numeric] value to round
+      # @param precision [Integer, nil] explicit precision, or nil to return float unchanged
+      # @return [Numeric]
       def round(float, precision) = precision ? float.round(precision) : float
 
+      # Returns the sine of an angle expressed in degrees.
+      # @param degrees [Numeric] angle in degrees
+      # @return [Float]
       def sin(degrees) = ::Math.sin(to_radians(degrees))
 
+      # Returns the tangent of an angle expressed in degrees.
+      # @param degrees [Numeric] angle in degrees
+      # @return [Float]
       def tan(degrees) = ::Math.tan(to_radians(degrees))
 
+      # Converts radians to degrees.
+      # @param radians [Numeric] angle in radians
+      # @return [Float]
       def to_degrees(radians) = radians.to_f * 180 / ::Math::PI
 
+      # Converts degrees to radians.
+      # @param degrees [Numeric] angle in degrees
+      # @return [Float]
       def to_radians(degrees) = degrees.to_f / 180 * ::Math::PI
 
+      # Runs a block with a current-thread precision override.
+      # @param precision [Integer, nil] scoped precision, or nil to use {PRECISION}
+      # @yield block executed with the scoped precision
+      # @yieldreturn [Object]
+      # @return [Object] block return value
+      # @raise [Sevgi::ArgumentError] when no block is given
+      def with_precision(precision, &block)
+        ArgumentError.("Block required") unless block
+
+        previous = Thread.current.thread_variable_get(PRECISION_KEY)
+        Function::Math.precision = precision
+        block.call
+      ensure
+        Function::Math.precision = previous if block
+      end
+
+      # Checks whether a value is approximately zero.
+      # @param value [Numeric] value to check
+      # @param precision [Integer, nil] explicit precision, or nil to use {Math.precision}
+      # @return [Boolean]
       def zero?(value, precision: nil) = eq?(value, 0.0, precision:)
     end
 

data/lib/sevgi/function/shell.rb

@@ -4,49 +4,96 @@ require "open3"
 
 module Sevgi
   module Function
+    # Shell execution helpers and executable lookup utilities.
     module Shell
+      # 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)
-        executable_cache.fetch(program) do
-          executable_cache[program] = ENV["PATH"].split(::File::PATH_SEPARATOR).any? do |dir|
-            ::File.executable?(::File.join(dir, program))
-          end
+        program = program.to_s
+        return false if program.empty?
+        return executable_file?(program) if slash_path?(program)
+
+        ENV.fetch("PATH", "").split(::File::PATH_SEPARATOR, -1).any? do |dir|
+          executable_file?(::File.join(dir.empty? ? "." : dir, program))
         end
       end
 
+      # Requires the first command argument to name an executable program.
+      # @param args [Array<Object>] command arguments
+      # @return [nil]
+      # @raise [Sevgi::Error] when the program cannot be found in PATH
       def executable!(*args)
-        program = args.first.split.first
-        raise "Missing executable: #{program}" unless executable?(program)
+        program = args.first.to_s.split.first
+        Error.("Missing executable: #{program}") unless executable?(program)
       end
 
+      # Result object returned by shell commands.
       Result = Struct.new(:args, :outs, :errs, :exit_code) do
+        # @!attribute [r] args
+        #   @return [Array<String>] command arguments
+        # @!attribute [r] outs
+        #   @return [Array<String>] captured stdout lines
+        # @!attribute [r] errs
+        #   @return [Array<String>] captured stderr lines
+        # @!attribute [r] exit_code
+        #   @return [Integer, nil] process exit code
+
+        # Returns stdout, a separator, and stderr as one string.
+        # @return [String]
         def all = [*outs, "\n\n", *errs].join("\n").strip
+
+        # Returns the command as a shell-like display string.
+        # @return [String]
         def cmd = args.join(" ")
+
+        # Returns captured stderr as a string.
+        # @return [String]
         def err = errs.join("\n")
+
+        # Reports whether the command failed.
+        # @return [Boolean]
         def notok? = !ok?
+
+        # Reports whether the command exited successfully.
+        # @return [Boolean]
         def ok? = exit_code&.zero?
+
+        # Returns captured stdout as a string.
+        # @return [String]
         def out = outs.join("\n")
+
+        # Returns the first stdout line.
+        # @return [String, nil]
         def outline = outs.first
 
+        # Builds a successful empty result.
+        # @return [Sevgi::Function::Shell::Result]
         def self.dummy = new([], [], [], 0)
       end
 
-      # Adapted to popen3 from github.com/mina-deploy/mina
+      # Runs shell commands and captures stdout, stderr, and exit status.
+      # @api private
       class Runner
+        # Creates a shell runner.
+        # @return [void]
         def initialize
           @coathooks = 0
         end
 
-        def call(*args, &block)
+        # Runs a command and captures its output.
+        # @param args [Array<String>] command and arguments
+        # @yield optional content writer for stdin
+        # @yieldreturn [String, nil]
+        # @return [Sevgi::Function::Shell::Result]
+        # @raise [Errno::ENOENT] when the executable cannot be spawned
+        def call(*args, &input)
           return Result.dummy if args.empty?
 
+          @coathooks = 0
           outs, errs, status = Open3.popen3(*args) do |stdin, stdout, stderr, wait_thread|
-            if block
-              input = block.call
-              stdin.write(block.call) if input
-              stdin.close
-            end
-
-            block(stdout, stderr, wait_thread)
+            capture(stdin, stdout, stderr, wait_thread, &input)
           end
 
           Result.new(args, outs, errs, status.exitstatus)
@@ -54,17 +101,47 @@ module Sevgi
 
         private
 
-        def block(stdout, stderr, wait_thread)
+        # rubocop:disable Lint/RescueException
+        def capture(stdin, stdout, stderr, wait_thread, &input)
           # Handle `^C`
-          trap("INT") { handle_sigint(wait_thread.pid) }
+          previous = trap("INT") { handle_sigint(wait_thread.pid) }
+          readers = start_readers(stdout, stderr)
+
+          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
 
-          outs = stdout.readlines.map(&:chomp)
-          errs = stderr.readlines.map(&:chomp)
+        def read_process(stdin, wait_thread, readers, &input)
+          write_input(stdin, &input)
+          close_input(stdin)
 
-          [outs, errs, wait_thread.value]
+          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
@@ -74,14 +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 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 [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 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 [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?
 
@@ -90,14 +219,20 @@ module Sevgi
             warn(result.err)
             warn("")
 
-            raise "Command failed: #{result.cmd}"
+            Error.("Command failed: #{result.cmd}")
           end
         end
       end
 
       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

@@ -2,7 +2,11 @@
 
 module Sevgi
   module Function
+    # String helpers used by generated names and user-facing text.
     module String
+      # Returns the final constant name segment from a module path.
+      # @param path [Object] module, class, or string-like path
+      # @return [String]
       def demodulize(path)
         path = path.to_s
         if (i = path.rindex("::"))
@@ -15,23 +19,23 @@ module Sevgi
 
     extend String
 
-    # Simplified from https://github.com/rails/rails/blob/main/activesupport/lib/active_support/inflector/inflections.rb
+    # Lightweight English pluralization helper.
     module Pluralize
-      UNCOUNTABLES = Hash[
-        *%w[
-          sheep
-          fish
-          sheep
-          series
-          species
-          money
-          rice
-          information
-          equipment
-        ].map { [it, true] }.flatten
+      # Words that should not be pluralized.
+      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.
       IRREGULARS = Hash[
         *%w[
           child
@@ -54,8 +58,10 @@ module Sevgi
       ]
         .freeze
 
+      # Plural forms already accepted as plural.
       PLURALS = IRREGULARS.invert.freeze
 
+      # Ordered suffix replacement rules.
       RULES = [
         [/(quiz)$/i, "\\1zes"],
         [/^(oxen)$/i, "\\1"],
@@ -80,15 +86,18 @@ module Sevgi
         [/$/, "s"]
       ].freeze
 
-      # Pluralize.('post')             # => "posts"
-      # Pluralize.('octopus')          # => "octopi"
-      # Pluralize.('sheep')            # => "sheep"
-      # Pluralize.('words')            # => "words"
-      # Pluralize.('CamelOctopus')     # => "CamelOctopi"
+      # Pluralizes an English word using a small built-in rule set.
+      # @param word [Object] word to pluralize
+      # @return [String]
+      # @example
+      #   F.pluralize("post")         # => "posts"
+      #   F.pluralize("octopus")      # => "octopi"
+      #   F.pluralize("sheep")        # => "sheep"
+      #   F.pluralize("CamelOctopus") # => "CamelOctopi"
       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/ui.rb

@@ -2,11 +2,33 @@
 
 module Sevgi
   module Function
+    # Small terminal status helpers used by build and release tasks.
     module UI
+      # Reports an in-progress status message.
+      # @param message [Object] status message
+      # @return [nil]
       def do(message) = warn("#{cyan("···")} #{bold(message)}")
+
+      # Reports an optional neutral status message unless SILENT is set.
+      # @param message [Object] status message
+      # @return [nil]
       def mayok(message) = (warn("  #{dim("·")} #{dim(message)}") unless ENV["SILENT"])
+
+      # Reports a failure status message.
+      # @param message [Object] status message
+      # @return [nil]
       def notok(message) = warn("  #{red("✗")} #{bold(message)}")
+
+      # Reports a success status message.
+      # @param message [Object] status message
+      # @return [nil]
       def ok(message) = warn("  #{cyan("✓")} #{bold(message)}")
+
+      # Reports a status message according to the yielded value.
+      # @param message [Object] status message
+      # @yield computes the status value
+      # @yieldreturn [Object]
+      # @return [Object] yielded value
       def ui(message) = yield.tap { it ? ok(message) : notok(message) }
     end
 

data/lib/sevgi/function/version.rb

@@ -2,6 +2,7 @@
 
 module Sevgi
   module Function
-    VERSION = "0.73.2"
+    # Current version of the Sevgi function gem.
+    VERSION = "0.94.0"
   end
 end

data/lib/sevgi/function.rb

@@ -13,5 +13,13 @@ require_relative "function/ui"
 require_relative "function/version"
 
 module Sevgi
+  # Shared helper namespace used directly as `Sevgi::Function` and through {Sevgi::F}.
+  #
+  # @example Use helper methods through the public alias
+  #   F.pluralize("axis")
+  module Function
+  end
+
+  # Public alias for the shared function helper namespace.
   F = Function unless defined?(F)
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sevgi-function
 version: !ruby/object:Gem::Version
-  version: 0.73.2
+  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:
   - - ">="