sevgi-function 0.73.2 → 0.93.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54d8ec739ffb09b6af47ed063c7f623eec4d53f460da37145dde187d66afb0bd
-  data.tar.gz: 73d6bcc926901e37b9cc5a34cab9ef36dc702e3465e04299fdd8a50ae98de2e9
+  metadata.gz: 060b3cdf233db4debfb3429c2d8663d94840ae00de70980124089f2d5d04c675
+  data.tar.gz: 2f80215534863a248171055a829ddcfa36ccf73013fbd430064b04fade3eeb5f
 SHA512:
-  metadata.gz: bb79282e9492163de25d534c4c00e69d5e6e2f12043cfba825dd1dbc5d81cf6a2ca8e45e294802956b45ed825a25e07319507e9815d1246bb1723ecd43d29fd4
-  data.tar.gz: 841d5ca22c243c504e5b64d50f16ba5ae9ff33e9cdf96300b517fe2c60e32b48fae7133cc2b248f81cc1d8c2b7ddf66f795439aa1c547155917608c8b6e1828d
+  metadata.gz: e4de61331c47e0007652e6c7548adf6de50e8d4ded0e1bc95c05dc9d7a0fc9929ee4ffdd3af3b3cd73eddc777495691c4952186e3f0f34390edcee062f0e907b
+  data.tar.gz: a36e58998da54d4c687e9266e1c58290af919ab3e4229627ab2d4c5a9b0ec4bd7a04a053ef8e8779ea3ef51268c1add54c75328475904562267d7073e683fa3f

data/README.md

@@ -0,0 +1,5 @@
+# Sevgi Function
+
+Provides shared helper functions used by Sevgi components.
+
+See the root [README](../README.md) and the documentation site for usage.

data/lib/sevgi/core.rb

@@ -1,50 +1,110 @@
 # 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)
+
+  # Error raised for invalid public API usage.
   ArgumentError = Class.new(Error) unless defined?(self::ArgumentError)
 
-  # Helpers
-  # Copied from https://github.com/dry-rb/dry-core. All kudos to the original authors.
+  # 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"
 
+      # 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,21 +2,48 @@
 
 module Sevgi
   module Function
+    # 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::Locate::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
+      # @!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
+      # @return [void]
       def initialize(paths, start = ::Dir.pwd, exclude: nil)
         @paths = Array(paths)
         @start = 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
+      # @yieldreturn [Boolean]
+      # @return [Sevgi::Function::Locate::Location, nil] found location, or nil
+      # @raise [Errno::ENOENT] when the start directory cannot be entered
       def call(&block)
         origin = ::Dir.pwd
         ::Dir.chdir(start)
@@ -46,9 +73,16 @@ module Sevgi
       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::Locate::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,165 @@
 
 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))
 
+      # Counts complete divisions in a length.
+      # @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
 
+      # 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,99 @@ require "open3"
 
 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
       def executable?(program)
+        program = program.to_s
+        return false if program.empty?
+
         executable_cache.fetch(program) do
-          executable_cache[program] = ENV["PATH"].split(::File::PATH_SEPARATOR).any? do |dir|
+          executable_cache[program] = ENV.fetch("PATH", "").split(::File::PATH_SEPARATOR).any? do |dir|
             ::File.executable?(::File.join(dir, program))
           end
         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?
 
           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
+            content = input.call if input
+            stdin.write(content) if content
+            stdin.close
 
-            block(stdout, stderr, wait_thread)
+            capture(stdout, stderr, wait_thread)
           end
 
           Result.new(args, outs, errs, status.exitstatus)
@@ -54,14 +104,16 @@ module Sevgi
 
         private
 
-        def block(stdout, stderr, wait_thread)
+        def capture(stdout, stderr, wait_thread)
           # Handle `^C`
-          trap("INT") { handle_sigint(wait_thread.pid) }
+          previous = trap("INT") { handle_sigint(wait_thread.pid) }
 
-          outs = stdout.readlines.map(&:chomp)
-          errs = stderr.readlines.map(&:chomp)
+          outs = Thread.new { stdout.readlines.map(&:chomp) }
+          errs = Thread.new { stderr.readlines.map(&:chomp) }
 
-          [outs, errs, wait_thread.value]
+          [outs.value, errs.value, wait_thread.value]
+        ensure
+          trap("INT", previous) if previous
         end
 
         def handle_sigint(pid)
@@ -80,8 +132,22 @@ module Sevgi
         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]
+      #   @return [Sevgi::Function::Shell::Result]
+      #   @raise [Errno::ENOENT] when the executable cannot be spawned
       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]
+      # @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
       def sh!(*args, &block)
         executable!(*args) unless args.empty?
 
@@ -90,7 +156,7 @@ module Sevgi
             warn(result.err)
             warn("")
 
-            raise "Command failed: #{result.cmd}"
+            Error.("Command failed: #{result.cmd}")
           end
         end
       end

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,8 +19,9 @@ 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
+      # Words that should not be pluralized.
       UNCOUNTABLES = Hash[
         *%w[
           sheep
@@ -32,6 +37,7 @@ module Sevgi
       ]
         .freeze
 
+      # Singular-to-plural forms that do not follow suffix rules.
       IRREGULARS = Hash[
         *%w[
           child
@@ -54,8 +60,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,11 +88,14 @@ 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
 

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.93.1"
   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.93.1
 platform: ruby
 authors:
 - Recai Oktaş