sevgi-function 0.94.0 → 0.98.2

data/README.md

@@ -1,6 +1,8 @@
 # Sevgi Function
 
-Shared helper functions used by Sevgi components.
+Sevgi Function contains the supported `Sevgi::F` toolbox shared by Sevgi components and advanced extensions. It is not
+intended as a general-purpose utility library; nested helper modules organize the facade implementation and are not
+consumer mixins.
 
 ## Install
 
@@ -22,15 +24,15 @@ 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`.
+Requires Ruby 3.4.0 or newer. CI verifies the current Ruby 3.4 release and the development Ruby from `.ruby-version`.
 
 ## Native prerequisites
 
-None beyond Ruby and this gem's Ruby dependencies.
+This gem needs only Ruby and its 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
+- 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

@@ -49,8 +49,6 @@ module Sevgi
   Undefined = Object
     .new
     .tap do |undefined|
-      const_set(:Self, -> { Undefined })
-
       # Returns the sentinel name.
       # @return [String]
       def undefined.to_s = "Undefined"
@@ -90,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/color.rb

@@ -2,7 +2,8 @@
 
 module Sevgi
   module Function
-    # ANSI color and style helpers for terminal output.
+    # ANSI color and style methods promoted to {Sevgi::F}. This module organizes the facade implementation; it is not a
+    # consumer mixin contract.
     module Color
       # Wraps a string in the blue terminal style.
       # @param string [Object] content to style

data/lib/sevgi/function/file.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require "digest"
 require "fileutils"
 
 module Sevgi
   module Function
-    # File-system helpers used by build scripts and DSL support code.
+    # File-system methods promoted to {Sevgi::F}. This module organizes the facade implementation; it is not a consumer
+    # mixin contract.
     module File
       # Checks whether a file would change if written with content.
       # @param file [String] file path to compare
@@ -14,14 +14,14 @@ module Sevgi
       # @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
+      # @raise [SystemCallError] when the file cannot be inspected or read
       def changed?(file, content, &filter)
         return true unless ::File.exist?(file)
 
         old_content = ::File.read(file)
         old_content, content = [old_content, content].map(&filter) if filter
 
-        Digest::SHA1.digest(old_content) != Digest::SHA1.digest(content)
+        old_content != content
       end
 
       # Finds an existing file by exact path or by trying default extensions.
@@ -29,11 +29,11 @@ module Sevgi
       # @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 file if ::File.file?(file)
         return nil unless ::File.extname(file).empty?
         return nil if extensions.empty?
 
-        extensions.map { |ext| "#{file}.#{ext}" }.detect { |file| ::File.exist?(file) }
+        extensions.map { |ext| "#{file}.#{ext}" }.detect { |file| ::File.file?(file) }
       end
 
       # Finds an existing file or raises.
@@ -79,8 +79,7 @@ module Sevgi
       # @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
+      # @raise [SystemCallError] when the destination cannot be inspected, read, or written
       def out(content, *paths, &filter)
         if paths.empty?
           ::Kernel.puts(content)
@@ -122,7 +121,7 @@ module Sevgi
       # 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
+      # @raise [SystemCallError] 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

@@ -10,28 +10,46 @@ module Sevgi
     #   @return [String] candidate path that matched
     # @!attribute [r] dir
     #   @return [String] directory where the match was found
-    Location = Data.define(:file, :slug, :dir)
+    Location = Data.define(:file, :slug, :dir) do
+      # Creates an owned immutable location snapshot.
+      # @param file [String] absolute matching file path
+      # @param slug [String] candidate path that matched
+      # @param dir [String] directory where the match was found
+      # @return [void]
+      def initialize(file:, slug:, dir:)
+        super(file: file.dup.freeze, slug: slug.dup.freeze, dir: dir.dup.freeze)
+      end
+
+      private_class_method :[]
+    end
 
-    # Locates one of several candidate files by walking upward from a start directory.
+    # Locates one of several candidate files by walking upward from an immutable configuration snapshot. Each call
+    # observes the filesystem again and returns an owned immutable {Location} snapshot.
     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
+      #   @yield optional matcher used instead of built-in file checks
       #   @yieldparam path [String] 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 self.call(*, **, &block) = new(*, **).call(&block)
 
-      # @!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
+      # Returns the frozen owned candidate paths.
+      # @return [Array<String>] frozen candidate path strings
+      attr_reader :paths
+
+      # Returns the frozen absolute start directory.
+      # @return [String] frozen absolute path
+      attr_reader :start
+
+      # Returns the frozen owned paths ignored during lookup.
+      # @return [Array<String>, nil] frozen absolute path strings, or nil
+      attr_reader :exclude
 
       # Builds an upward file locator.
       # @param paths [Array<String>, String] candidate file paths
@@ -39,15 +57,17 @@ module Sevgi
       # @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 = ::File.expand_path(start)
-        @exclude = [*exclude].map { ::File.expand_path(it) } unless exclude.nil?
+        @paths = Array(paths).map { it.dup.freeze }.freeze
+        @start = ::File.expand_path(start).freeze
+        @exclude = [*exclude].map { ::File.expand_path(it).freeze }.freeze unless exclude.nil?
+        freeze
       end
 
       # Runs the upward lookup.
-      # @yield optional matcher used instead of file existence checks
+      # @yield optional matcher used instead of built-in file checks
       # @yieldparam path [String] absolute candidate path
       # @yieldreturn [Boolean]
+      # @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
@@ -59,7 +79,7 @@ module Sevgi
 
           slug, file = found
 
-          return Location[file, slug, here]
+          return Location.new(file:, slug:, dir: here)
         end
       end
 
@@ -83,9 +103,10 @@ module Sevgi
       def match(here, &block)
         paths.each do |path|
           candidate = ::File.expand_path(path, here)
-          next if !block && excluded?(candidate)
+          next if excluded?(candidate)
 
-          return [path, candidate] if (block || proc { ::File.exist?(it) }).call(candidate)
+          matched = block ? block.call(candidate) : ::File.file?(candidate)
+          return [path, candidate] if matched
         end
 
         nil
@@ -104,6 +125,8 @@ module Sevgi
     # @param extension [String] default extension added before lookup
     # @return [Sevgi::Function::Location] found location
     # @raise [Sevgi::Error] when no matching file exists
+    # @raise [Errno::ENOENT] when the start directory does not exist
+    # @raise [Errno::ENOTDIR] when the start path is not a directory
     def self.locate(filename, start, exclude: nil, extension: EXTENSION)
       Locate.(F.qualify(filename, extension), start, exclude:).tap do |path|
         Error.("Cannot load a file matching: #{filename}") unless path

data/lib/sevgi/function/math.rb

@@ -2,14 +2,17 @@
 
 module Sevgi
   module Function
-    # Numeric and trigonometric helpers used by geometry and DSL code.
+    # Numeric and trigonometric methods promoted to {Sevgi::F}. This module owns the public thread-local
+    # {Math.precision} configuration but is not otherwise a consumer mixin contract.
     module Math
       # Default decimal precision used by approximate comparisons.
       PRECISION = 6
 
       PRECISION_KEY = :sevgi_function_math_precision
+      QUADRANT_COSINES = [1.0, 0.0, -1.0, 0.0].freeze
+      QUADRANT_SINES = [0.0, 1.0, 0.0, -1.0].freeze
 
-      private_constant :PRECISION_KEY
+      private_constant :PRECISION_KEY, :QUADRANT_COSINES, :QUADRANT_SINES
 
       # Returns the current thread's default numeric precision.
       # @return [Integer] current thread precision, or {PRECISION} when no override is set
@@ -22,64 +25,82 @@ module Sevgi
       # 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
+      # @raise [Sevgi::ArgumentError] when precision is not an Integer or nil
       def self.precision=(precision)
+        unless precision.nil? || precision.is_a?(::Integer)
+          ArgumentError.("Precision must be an Integer or nil: #{precision.inspect}")
+        end
+
         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))
+      # @raise [Sevgi::ArgumentError] when value is not a finite real number
+      # @raise [::Math::DomainError] when value is outside -1..1
+      def acos(value) = to_degrees(::Math.acos(finite_real(:value, value)))
 
       # Returns the inverse cotangent in degrees.
       # @param value [Numeric] cotangent value
       # @return [Float]
-      def acot(value) = 90.0 - to_degrees(::Math.atan(value))
+      # @raise [Sevgi::ArgumentError] when value is not a finite real number
+      def acot(value) = 90.0 - to_degrees(::Math.atan(finite_real(:value, value)))
 
       # 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
+      # @raise [Sevgi::ArgumentError] when value is not finite real or precision is not an Integer or nil
       def approx(float, precision = nil)
-        float.round(precision.nil? ? Function::Math.precision : precision)
+        precision = precision.nil? ? Function::Math.precision : valid_precision(precision)
+        valid_real(:value, float).round(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))
+      # @raise [Sevgi::ArgumentError] when value is not a finite real number
+      # @raise [::Math::DomainError] when value is outside -1..1
+      def asin(value) = to_degrees(::Math.asin(finite_real(:value, value)))
 
       # Returns the inverse tangent in degrees.
       # @param value [Numeric] tangent value
       # @return [Float]
-      def atan(value) = to_degrees(::Math.atan(value))
+      # @raise [Sevgi::ArgumentError] when value is not a finite real number
+      def atan(value) = to_degrees(::Math.atan(finite_real(:value, 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))
+      # @raise [Sevgi::ArgumentError] when an operand is not a finite real number
+      def atan2(y, x) = to_degrees(::Math.atan2(finite_real(:y, y), finite_real(:x, x)))
 
-      # Returns the cosine of an angle expressed in degrees.
+      # Returns the cosine of an angle expressed in degrees. Integer quarter turns return exact `-1.0`, `0.0`, or
+      # `1.0`; other angles use Ruby's floating-point Math implementation.
       # @param degrees [Numeric] angle in degrees
       # @return [Float]
-      def cos(degrees) = ::Math.cos(to_radians(degrees))
+      # @raise [Sevgi::ArgumentError] when degrees is not a finite real number
+      def cos(degrees)
+        degrees = finite_real(:degrees, degrees)
+        quadrant_value(degrees, QUADRANT_COSINES) { ::Math.cos(radians(degrees)) }
+      end
 
       # Returns the cotangent of an angle expressed in degrees.
       # @param degrees [Numeric] angle in degrees
       # @return [Float]
+      # @raise [Sevgi::ArgumentError] when degrees is not a finite real number
       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 real total length
+      # @param division [Numeric] finite real, non-zero division size
       # @return [Integer]
-      # @raise [Sevgi::ArgumentError] when division is zero
+      # @raise [Sevgi::ArgumentError] when an operand is not a finite Numeric or division is zero
       def count(length, division)
-        divisor = division.to_f
+        length = finite_real(:length, length)
+        divisor = finite_real(:division, division)
         ArgumentError.("Division must not be zero") if divisor.zero?
 
         (length / divisor).to_i
@@ -90,6 +111,7 @@ module Sevgi
       # @param right [Numeric] right operand
       # @param precision [Integer, nil] explicit precision, or nil to use {Math.precision}
       # @return [Boolean]
+      # @raise [Sevgi::ArgumentError] when an operand is not finite real or precision is invalid
       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.
@@ -97,6 +119,7 @@ module Sevgi
       # @param right [Numeric] right operand
       # @param precision [Integer, nil] explicit precision, or nil to use {Math.precision}
       # @return [Boolean]
+      # @raise [Sevgi::ArgumentError] when an operand is not finite real or precision is invalid
       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.
@@ -104,6 +127,7 @@ module Sevgi
       # @param right [Numeric] right operand
       # @param precision [Integer, nil] explicit precision, or nil to use {Math.precision}
       # @return [Boolean]
+      # @raise [Sevgi::ArgumentError] when an operand is not finite real or precision is invalid
       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.
@@ -111,6 +135,7 @@ module Sevgi
       # @param right [Numeric] right operand
       # @param precision [Integer, nil] explicit precision, or nil to use {Math.precision}
       # @return [Boolean]
+      # @raise [Sevgi::ArgumentError] when an operand is not finite real or precision is invalid
       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.
@@ -118,33 +143,46 @@ module Sevgi
       # @param right [Numeric] right operand
       # @param precision [Integer, nil] explicit precision, or nil to use {Math.precision}
       # @return [Boolean]
+      # @raise [Sevgi::ArgumentError] when an operand is not finite real or precision is invalid
       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
+      # @raise [Sevgi::ArgumentError] when value is not finite real or precision is not an Integer or nil
+      def round(float, precision)
+        number = valid_real(:value, float)
+        precision.nil? ? number : number.round(valid_precision(precision))
+      end
 
-      # Returns the sine of an angle expressed in degrees.
+      # Returns the sine of an angle expressed in degrees. Integer quarter turns return exact `-1.0`, `0.0`, or `1.0`;
+      # other angles use Ruby's floating-point Math implementation.
       # @param degrees [Numeric] angle in degrees
       # @return [Float]
-      def sin(degrees) = ::Math.sin(to_radians(degrees))
+      # @raise [Sevgi::ArgumentError] when degrees is not a finite real number
+      def sin(degrees)
+        degrees = finite_real(:degrees, degrees)
+        quadrant_value(degrees, QUADRANT_SINES) { ::Math.sin(radians(degrees)) }
+      end
 
       # Returns the tangent of an angle expressed in degrees.
       # @param degrees [Numeric] angle in degrees
       # @return [Float]
+      # @raise [Sevgi::ArgumentError] when degrees is not a finite real number
       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
+      # @raise [Sevgi::ArgumentError] when radians is not a finite real number
+      def to_degrees(radians) = finite_real(:radians, radians) * 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
+      # @raise [Sevgi::ArgumentError] when degrees is not a finite real number
+      def to_radians(degrees) = radians(finite_real(:degrees, degrees))
 
       # Runs a block with a current-thread precision override.
       # @param precision [Integer, nil] scoped precision, or nil to use {PRECISION}
@@ -152,6 +190,10 @@ module Sevgi
       # @yieldreturn [Object]
       # @return [Object] block return value
       # @raise [Sevgi::ArgumentError] when no block is given
+      # @raise [Sevgi::ArgumentError] when precision is not an Integer or nil
+      # @example Compare values under a temporary precision
+      #   Sevgi::F.with_precision(2) { Sevgi::F.eq?(1.001, 1.0) } # => true
+      #   Sevgi::Function::Math.precision # => 6
       def with_precision(precision, &block)
         ArgumentError.("Block required") unless block
 
@@ -166,7 +208,47 @@ module Sevgi
       # @param value [Numeric] value to check
       # @param precision [Integer, nil] explicit precision, or nil to use {Math.precision}
       # @return [Boolean]
+      # @raise [Sevgi::ArgumentError] when value is not finite real or precision is invalid
       def zero?(value, precision: nil) = eq?(value, 0.0, precision:)
+
+      private
+
+      def finite_real(field, value)
+        unless value.is_a?(::Numeric) && !value.is_a?(::Complex)
+          ArgumentError.("#{field} must be a finite real Numeric: #{value.inspect}")
+        end
+
+        number = begin
+          value.to_f
+        rescue ::StandardError => e
+          ArgumentError.("#{field} must be a finite real Numeric: #{value.inspect} (#{e.message})")
+        end
+
+        ArgumentError.("#{field} must be finite: #{value.inspect}") unless number.is_a?(::Float) && number.finite?
+
+        number
+      end
+
+      def quadrant_value(degrees, values)
+        turn = degrees % 360
+        return yield unless (turn % 90).zero?
+
+        values[(turn / 90).to_i]
+      end
+
+      def radians(degrees) = degrees / 180 * ::Math::PI
+
+      def valid_precision(precision)
+        return precision if precision.is_a?(::Integer)
+
+        ArgumentError.("Precision must be an Integer or nil: #{precision.inspect}")
+      end
+
+      def valid_real(field, value)
+        finite_real(field, value)
+        value
+      end
+
     end
 
     extend Math