sevgi-function 0.95.0 → 0.98.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d64555b43d632235e9d1f1419294447fc5e63c0c2af0ba3b8c89fc1f82e7474
-  data.tar.gz: 6a15d7e54278e3d0cee74369616f60b6e43d70f8e2a7784c33a6737099fd9e4b
+  metadata.gz: 4f11073d7043461caa01968570217c218040207ff9a6abdcd5e56501946e35e1
+  data.tar.gz: 9992d6ae73303b55ead462ba6b599e965446dd7b0455621e4ad6aa029aa65376
 SHA512:
-  metadata.gz: 60083cb4298cad1644ec70bd490652b07bec34fe9498d8359653a82800fae41ac2d6128c527095af04f992a351bd260fb870761289537c3a5778dc71c214506a
-  data.tar.gz: bfc1aeaa49fb6a08cb7b78f14dc5e8b077e3d09de7bc52f92bc460692f5ec5831c2a30cae5ddde96b49b9ed0c494546f884b12af026557c0d8e676171d272130
+  metadata.gz: 3cfb465db527caf1f1ba8e0305aebf3c3ba9164b6dc721122e4c5bb776f7843a05baf991fee72bff25a6c2d5be58c4625dfaac91c15d12e192fa1d12fc5ff2a3
+  data.tar.gz: cb6e493fa0ad5c0332b6424bf8e53d9d72a49fb0729f5f4b9dcd481e94fc492fd07e458d6405aeb44b676ec3927301dd72e33ca0da2bad256d3931955d5183dc

data/CHANGELOG.md

@@ -5,6 +5,131 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## Unreleased
 
+## 0.98.2 - 2026-07-25
+
+### Fixed
+
+- Restored the `sevgi` CLI's main-object scope so bare toolkit calls remain available inside script helper classes.
+
+## 0.98.1 - 2026-07-20
+
+### Changed
+
+- Changed the `sevgi` CLI to use the executor's isolated scope by default.
+
+### Removed
+
+- Removed the redundant `-n` and `--nomain` CLI options; library consumers can still select `main: true` through
+  `Sevgi.execute` and `Sevgi.execute_file` when needed.
+
+## 0.98.0 - 2026-07-20
+
+### Added
+
+- Added standard-input support to `sevgi`, `igves`, and `igsev`; `sevgi --as NAME` and
+  `Sevgi.execute_file(..., as: NAME)` supply the logical source basename used by implicit SVG, PDF, and PNG
+  destinations without changing physical load identity.
+
+## 0.97.0 - 2026-07-19
+
+### Added
+
+- Added `sevgi-appendix`, containing the Sevgi agent skill and a RuboCop plugin for preserving readable `.sevgi` DSL
+  source alongside rubyfmt-formatted Ruby; the umbrella `sevgi` gem installs the matching Appendix version.
+- Added `sevgi --skill` to report the validated path of the matching packaged agent skill for product-neutral setup.
+- Added `igsev` to the umbrella gem for normalizing an SVG file through a complete SVG-to-Sevgi-to-SVG round trip.
+
+### Changed
+
+- Made Homebrew the recommended complete CLI installation while retaining Bundler and focused component gems for Ruby
+  application dependencies.
+
+## 0.96.0 - 2026-07-18
+
+### Added
+
+- Added exact, subtree-wide attribute omission to Derender content/file conversion, evaluation, and inclusion APIs;
+  `igves --omit` exposes the same behavior from the command line.
+- Added `Sevgi.SVG` as the explicit namespaced form of the top-level SVG document entrypoint.
+- Added the opt-in recursive `SVG::Modules` contract for callable drawing namespaces.
+- Added callable drawing-module `base` blocks, document and paper registry introspection, Canvas structural equality,
+  renderer options on `RenderChildren`, axis translation helpers, and a CC BY RDF helper.
+- Formalized non-rendering `-` metadata and `+` attribute updates as `Attributes::META_PREFIX` and
+  `Attributes::UPDATE_SUFFIX`; repeated Array updates now concatenate into a stable flat value.
+
+### Changed
+
+- Breaking: replaced the `SVG = Sevgi::Graphics` alias with an independent SVG facade. Facade operations now use
+  capitalized names such as `SVG.Canvas` and `SVG.Document`; lowercase component helpers remain on
+  `Sevgi::Graphics`, and the stuttering `SVG.SVG` form was removed.
+- Breaking: made low-level `Executor.execute` and `execute_file` runners private; consumers use
+  `Sevgi.execute` and `Sevgi.execute_file` while retaining the public result and error types.
+- Breaking: removed the abstract `Document::Base` layer from the selectable document-profile registry; `Minimal` and
+  `Default` are now sibling concrete profiles, and custom profile hierarchies should derive from `Base`.
+- Breaking: renamed Parallelogram segment and constraint arguments by geometric role: `base`, `side`, and
+  `constraint` replace axis-implying constructor names.
+- Made degree-based sine and cosine exact at integer quarter turns, eliminating cardinal Geometry residue.
+- Documented complete file-system failure families for file comparison, output, touch, and upward location helpers.
+- Formalized generated Tile ids, positional CSS classes, template placement, and per-use callback signatures.
+- Formalized String and Symbol ids across Derender selection APIs and documented file-read failures consistently.
+- Breaking: made top-level `Decompile`, `Derender`, `Evaluate`, and `EvaluateChildren` consume inline SVG/XML;
+  file inputs now use the corresponding `File`-suffixed entrypoints.
+- Breaking: replaced callable drawing module `call` block registration with argument-independent `base` blocks;
+  inherited bases run parent-first, and modules with one drawing method conventionally name it `call`.
+- Breaking: made bracket and call notation the canonical Geometry constructors. Among Data value types, bracket notation
+  is public only for Point, Segment, LengthAngle, Margin, and Paper; use `.new` for Location and result carriers, and
+  `Stay` for traversal stop tokens.
+- Breaking: aligned Point and Segment comparison with Ruby `Comparable`; malformed or unrelated comparison operands now
+  return nil from `<=>`.
+- Breaking: executor entrypoints now return immutable `Executor::Result` values and expose only `execute` and
+  `execute_file`; inspect `result.error`, `result.stack`, and `result.value` instead of executor scopes or lifecycle state.
+- Breaking: wrapper attributes and callable arguments use distinct channels, `With` rejects parentless receivers, and
+  unsupported direct constructors are private; use the documented factories for Content, concrete Geometry lined
+  elements, and Grid query values.
+- Breaking: Canvas uses `.new` for explicit fields, `.from_paper(paper, **overrides)` for paper conversion, and
+  `.call`/`Graphics.canvas` for dispatch; the misleading keyword-only `.from_paper(width:, height:)` form was removed.
+- Breaking: `Save`, `Write`, `PNG`, `PDF`, and Sundries native export normalize successful destinations to expanded
+  String paths and create missing parent directories; change-aware SVG writes still return nil when unchanged.
+- Breaking: renamed `Derender.evaluate_file_children` to `evaluate_children_file`; decompiled nodes now own immutable
+  public state while parser, strategy, and construction plumbing remain private.
+- Expanded runtime/YARD parity checks and exact contracts for inherited, extended, generated, and dynamic API surfaces,
+  forwarded options, error channels, path ownership, whitespace, namespaces, nil behavior, and return values.
+
+### Fixed
+
+- Rejected directories from default file discovery while preserving custom locator matchers.
+- Kept `Ancestral` context in non-rendering `-context` metadata instead of leaking it into SVG attributes.
+- Preserved source Canvas units and names when deriving fitted Grid canvases.
+- Prevented stale documentation assets from mixing old layouts with new HTML, and moved sidebar navigation into the
+  tablet menu at 1024px and below.
+- Normalized numeric slots owned by path, shape, transform, tile, and Inkscape page helpers to finite SVG number spelling;
+  arbitrary user-supplied attributes remain untouched.
+- Made named callable wrapper and symbol ids stable while omitting defaults for anonymous modules, and indexed every
+  rendered id value, including false and numeric values, through its serialized string.
+- Preserved signed Geometry constraint directions, rejected invalid sweep/export channels through Sevgi error families,
+  and validated raw output paths before expansion or rendering.
+- Made callable module configuration copy-owned and freeze-aware, document subclasses inherit their nearest profile, and
+  false executor boot receivers remain explicit rather than defaulting to an internal scope.
+- Made element trees, attributes, identifiers, locator results, document profiles, Derender nodes, shell results, and
+  executor results retain owned immutable snapshots where their public contracts promise value semantics.
+- Corrected Shell combined-output separators, nil export density errors, document render-option routing, executor source
+  snapshots, selected-node namespace/whitespace documentation, and Standard character-data validation.
+
+### Removed
+
+- Removed public access to pluralization tables and the internal SVG save extension; pluralization rules are now deeply
+  immutable.
+- Removed public documentation and constant access for command-line implementation modules; the `sevgi` and `igves`
+  executables remain unchanged.
+- Removed eager loading and public documentation of private Showcase build/test support; explicit support entrypoints
+  now keep the harness under the Showcase namespace.
+- Removed public access to document profile name normalizers; registry operations retain them as private plumbing.
+- Removed the redundant `Margin.margin` constructor; use canonical bracket notation.
+- Removed public executor orchestration, obsolete callable-module hooks, the old public attribute syntax constants, and
+  direct construction of abstract or internally wired Content, Element, and Grid query types.
+- Removed accidental public access to abstract Lined factories, internal element-name/export maps, result/location
+  bracket constructors, and direct Stop construction.
+
 ## 0.95.0 - 2026-07-11
 
 ### Security

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.0 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/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,31 +10,45 @@ 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)
 
-      # Returns candidate paths.
-      # @return [Array<String>]
+      # Returns the frozen owned candidate paths.
+      # @return [Array<String>] frozen candidate path strings
       attr_reader :paths
 
-      # Returns the absolute start directory.
-      # @return [String]
+      # Returns the frozen absolute start directory.
+      # @return [String] frozen absolute path
       attr_reader :start
 
-      # Returns expanded paths ignored during lookup.
-      # @return [Array<String>, nil]
+      # 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.
@@ -43,13 +57,14 @@ 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.
@@ -64,7 +79,7 @@ module Sevgi
 
           slug, file = found
 
-          return Location[file, slug, here]
+          return Location.new(file:, slug:, dir: here)
         end
       end
 
@@ -90,7 +105,8 @@ module Sevgi
           candidate = ::File.expand_path(path, here)
           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
@@ -109,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,60 +25,77 @@ 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] finite total length
-      # @param division [Numeric] finite, non-zero division size
+      # @param length [Numeric] finite real total length
+      # @param division [Numeric] finite real, non-zero division size
       # @return [Integer]
       # @raise [Sevgi::ArgumentError] when an operand is not a finite Numeric or division is zero
       def count(length, division)
@@ -91,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.
@@ -98,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.
@@ -105,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.
@@ -112,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.
@@ -119,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}
@@ -153,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
 
@@ -167,19 +208,20 @@ 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)
-          ArgumentError.("#{field} must be a finite Numeric: #{value.inspect}")
+        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 Numeric: #{value.inspect} (#{e.message})")
+          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?
@@ -187,6 +229,26 @@ module Sevgi
         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

data/lib/sevgi/function/shell.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 require "open3"
+require "shellwords"
 
 module Sevgi
   module Function
-    # Shell execution helpers and executable lookup utilities.
+    # Command methods promoted to {Sevgi::F}. This module owns the public immutable {Shell::Result} value but is not
+    # otherwise a consumer mixin contract.
     module Shell
       # Checks whether a program exists and is executable.
       # @param program [Object] program name, absolute path, or relative slash-containing path
@@ -30,24 +32,62 @@ module Sevgi
         Error.("Missing executable: #{program}") unless executable?(program)
       end
 
-      # Result object returned by shell commands.
-      Result = Struct.new(:args, :outs, :errs, :exit_code) do
+      # Immutable result returned by shell commands.
+      #
+      # @example Inspect a command result
+      #   require "rbconfig"
+      #   result = Sevgi::F.sh(RbConfig.ruby, "-e", "puts 42")
+      #   result.ok?     # => true
+      #   result.outline # => "42"
+      Result = Data.define(:args, :outs, :errs, :exit_code, :signal) do
         # @!attribute [r] args
-        #   @return [Array<String>] command arguments
+        #   @return [Array<String>] frozen command arguments
         # @!attribute [r] outs
-        #   @return [Array<String>] captured stdout lines
+        #   @return [Array<String>] frozen captured stdout lines
         # @!attribute [r] errs
-        #   @return [Array<String>] captured stderr lines
+        #   @return [Array<String>] frozen captured stderr lines
         # @!attribute [r] exit_code
         #   @return [Integer, nil] process exit code
+        # @!attribute [r] signal
+        #   @return [Integer, nil] terminating signal number
+
+        # Creates an owned result snapshot.
+        # @param args [Array<Object>] command arguments
+        # @param outs [Array<String>] captured stdout lines
+        # @param errs [Array<String>] captured stderr lines
+        # @param exit_code [Integer, nil] process exit code
+        # @param signal [Integer, nil] terminating signal number
+        # @return [void]
+        def initialize(args:, outs:, errs:, exit_code:, signal:)
+          super(
+            args: args.map { it.to_s.dup.freeze }.freeze,
+            outs: outs.map { it.dup.freeze }.freeze,
+            errs: errs.map { it.dup.freeze }.freeze,
+            exit_code:,
+            signal:
+          )
+        end
 
-        # Returns stdout, a separator, and stderr as one string.
-        # @return [String]
-        def all = [*outs, "\n\n", *errs].join("\n").strip
+        private_class_method :[]
+
+        # Returns captured output with one blank line between non-empty streams.
+        # Captured lines are joined with one newline and are not otherwise trimmed.
+        # @example Combine standard output and standard error
+        #   result = Sevgi::Function::Shell::Result.new(
+        #     args: ["tool"], outs: ["output"], errs: ["warning"], exit_code: 0, signal: nil
+        #   )
+        #   result.all # => "output\n\nwarning"
+        # @return [String] combined output, or an empty string when neither stream contains lines
+        def all
+          return err if outs.empty?
+          return out if errs.empty?
+
+          "#{out}\n\n#{err}"
+        end
 
         # Returns the command as a shell-like display string.
         # @return [String]
-        def cmd = args.join(" ")
+        def cmd = ::Shellwords.join(args)
 
         # Returns captured stderr as a string.
         # @return [String]
@@ -59,7 +99,7 @@ module Sevgi
 
         # Reports whether the command exited successfully.
         # @return [Boolean]
-        def ok? = exit_code&.zero?
+        def ok? = !exit_code.nil? && exit_code.zero?
 
         # Returns captured stdout as a string.
         # @return [String]
@@ -69,15 +109,18 @@ module Sevgi
         # @return [String, nil]
         def outline = outs.first
 
-        # Builds a successful empty result.
-        # @return [Sevgi::Function::Shell::Result]
-        def self.dummy = new([], [], [], 0)
+        # Reports whether the command was terminated by a signal.
+        # @return [Boolean]
+        def signaled? = !signal.nil?
       end
 
       # Shared process-global SIGINT state for overlapping shell runners.
       # @api private
       module Signals
-        Entry = Data.define(:runner, :pid)
+        Entry = Data.define(:runner, :pid) do
+          private_class_method :[]
+        end
+
         WAKE = "."
 
         private_constant :WAKE
@@ -183,16 +226,17 @@ module Sevgi
         # @yield optional content writer for stdin
         # @yieldreturn [String, nil]
         # @return [Sevgi::Function::Shell::Result]
+        # @raise [Sevgi::ArgumentError] when no command is given
         # @raise [Errno::ENOENT] when the executable cannot be spawned
         def call(*args, &input)
-          return Result.dummy if args.empty?
+          ArgumentError.("Shell command required") if args.empty?
 
           @coathooks = 0
           outs, errs, status = Open3.popen3(*args) do |stdin, stdout, stderr, wait_thread|
             capture(stdin, stdout, stderr, wait_thread, &input)
           end
 
-          Result.new(args, outs, errs, status.exitstatus)
+          Result.new(args:, outs:, errs:, exit_code: status.exitstatus, signal: status.termsig)
         end
 
         private
@@ -286,12 +330,15 @@ module Sevgi
         end
       end
 
+      private_constant :Runner
+
       # @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 [Sevgi::ArgumentError] when no command is given
       #   @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
@@ -304,6 +351,7 @@ module Sevgi
       # @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::ArgumentError] when no command is given
       # @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

data/lib/sevgi/function/string.rb

@@ -2,7 +2,8 @@
 
 module Sevgi
   module Function
-    # String helpers used by generated names and user-facing text.
+    # String methods promoted to {Sevgi::F}. This module organizes the facade implementation; it is not a consumer mixin
+    # contract.
     module String
       # Returns the final constant name segment from a module path.
       # @param path [Object] module, class, or string-like path
@@ -19,9 +20,11 @@ module Sevgi
 
     extend String
 
-    # Lightweight English pluralization helper.
+    # English pluralization promoted to {Sevgi::F}. This module organizes the facade implementation; it is not a
+    # consumer mixin contract.
     module Pluralize
       # Words that should not be pluralized.
+      # @api private
       UNCOUNTABLES = %w[
         equipment
         fish
@@ -36,6 +39,7 @@ module Sevgi
         .freeze
 
       # Singular-to-plural forms that do not follow suffix rules.
+      # @api private
       IRREGULARS = Hash[
         *%w[
           child
@@ -59,9 +63,11 @@ module Sevgi
         .freeze
 
       # Plural forms already accepted as plural.
+      # @api private
       PLURALS = IRREGULARS.invert.freeze
 
       # Ordered suffix replacement rules.
+      # @api private
       RULES = [
         [/(quiz)$/i, "\\1zes"],
         [/^(oxen)$/i, "\\1"],
@@ -84,16 +90,20 @@ module Sevgi
         [/^(ax|test)is$/i, "\\1es"],
         [/s$/i, "s"],
         [/$/, "s"]
-      ].freeze
+      ]
+        .each(&:freeze)
+        .freeze
+
+      private_constant :IRREGULARS, :PLURALS, :RULES, :UNCOUNTABLES
 
       # 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"
+      # @example Pluralize through the library facade
+      #   Sevgi::F.pluralize("post")         # => "posts"
+      #   Sevgi::F.pluralize("octopus")      # => "octopi"
+      #   Sevgi::F.pluralize("sheep")        # => "sheep"
+      #   Sevgi::F.pluralize("CamelOctopus") # => "CamelOctopi"
       def pluralize(word)
         result = word.to_s.dup
 

data/lib/sevgi/function/ui.rb

@@ -2,7 +2,8 @@
 
 module Sevgi
   module Function
-    # Small terminal status helpers used by build and release tasks.
+    # Terminal status methods promoted to {Sevgi::F}. This module organizes the facade implementation; it is not a
+    # consumer mixin contract.
     module UI
       # Reports an in-progress status message.
       # @param message [Object] status message

data/lib/sevgi/function/version.rb

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

data/lib/sevgi/function.rb

@@ -13,13 +13,23 @@ require_relative "function/ui"
 require_relative "function/version"
 
 module Sevgi
-  # Shared helper namespace used directly as `Sevgi::Function` and through {Sevgi::F}.
+  # Support toolbox for Sevgi components and advanced extensions. The supported helper facade is {Sevgi::F}; it
+  # provides degree-based trigonometry and precision, file discovery and output, argv-safe commands, naming helpers,
+  # and small terminal status tools. It is not intended as a general-purpose utility library.
   #
-  # @example Use helper methods through the public alias
-  #   F.pluralize("axis")
+  # {Function::Location}, {Function::Locate}, and {Function::Shell::Result} are public supporting values. The
+  # thread-local precision accessors remain on {Function::Math.precision}. Other nested helper modules organize the
+  # facade implementation and its method documentation; consumers should not include or extend them.
+  #
+  # @example Use the supported facade in library code
+  #   Sevgi::F.with_precision(3) do
+  #     Sevgi::F.cos(60)
+  #     Sevgi::F.approx(1.0 / 3)
+  #   end
+  # @see https://sevgi.roktas.dev/functions/ Function toolbox guide
   module Function
   end
 
-  # Public alias for the shared function helper namespace.
+  # Supported helper facade for Sevgi extensions and advanced consumers.
   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.95.0
+  version: 0.98.2
 platform: ruby
 authors:
 - Recai Oktaş
@@ -9,7 +9,7 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Enhances the Sevgi toolkit with utility methods.
+description: Collects numeric, string, file, shell, and terminal helpers.
 email: roktas@gmail.com
 executables: []
 extensions: []
@@ -50,7 +50,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.11
+rubygems_version: 4.0.16
 specification_version: 4
-summary: Various utility functions for the Sevgi toolkit.
+summary: Shared utility functions for Sevgi components.
 test_files: []