sevgi-function 0.98.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f11073d7043461caa01968570217c218040207ff9a6abdcd5e56501946e35e1
-  data.tar.gz: 9992d6ae73303b55ead462ba6b599e965446dd7b0455621e4ad6aa029aa65376
+  metadata.gz: 16f640bb8dfbb97ac1ad5bb3ec38fd5fc15b3ef6c8bfdf2c28419449f87b2dbd
+  data.tar.gz: 545c92aba11d99154b251b14328db0752579374d9b1da6aaf441530dcb7b0ad2
 SHA512:
-  metadata.gz: 3cfb465db527caf1f1ba8e0305aebf3c3ba9164b6dc721122e4c5bb776f7843a05baf991fee72bff25a6c2d5be58c4625dfaac91c15d12e192fa1d12fc5ff2a3
-  data.tar.gz: cb6e493fa0ad5c0332b6424bf8e53d9d72a49fb0729f5f4b9dcd481e94fc492fd07e458d6405aeb44b676ec3927301dd72e33ca0da2bad256d3931955d5183dc
+  metadata.gz: 6807301c517b6eb9f74e8d15a0fe0d617638f801563eed933c54d2ff2fad59c22ac8cfeee36dadf8ae43a10c0508c86ebd68584c3c3825711df6fed95135570a
+  data.tar.gz: 07c3a9c39dfc2010d4a0ac86f15d6a69768d0f9f59226466fa2e5e3f18ff3309dd229e145702ccd6a349cb4a320ba897fa68cac42c32be4bd9d359c63a73a051

data/CHANGELOG.md

@@ -5,6 +5,120 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## Unreleased
 
+## 1.1.0 - 2026-10-29
+
+### Added
+
+- `Classes` returns an element's distinct CSS class names without changing the element; `Classify` shares its attribute normalization.
+- Generic document-local Style declarations with `Target`, `Param`, `Group`, and `Profiles`, and optional prepared PDF export through the native Mainz CLI.
+- Backend-independent `fallback: false` for export failures and `F.executable` for executable path lookup.
+- `F.path` for path validation and expansion, and `F.output_path` for default output names and directory targets.
+
+### Changed
+
+- Moved Graphics XML validation into auxiliary helpers and kept built-in paper dimensions in `Paper`.
+- Shared path validation between Graphics writers and Sundries exports while preserving output paths and error messages.
+
+### Fixed
+
+- Stamp code placeholders in nested and shared PDF Forms, with cycle-safe resource traversal.
+
+## 1.0.0 - 2026-09-16
+
+### Added
+
+- Added Hatch and Orb Showcase examples and displayed both arc lengths in the Arc example.
+
+### Changed
+
+- Matched documentation page widths to the homepage Showcase.
+- Aligned Derender user guidance with UTF-8 normalization and safe subtree selection rules.
+- Clarified the packaged skill's script invocation, subtree copying, and Derender selection and encoding rules.
+- Allowed Canvas and Paper values as the first `SVG` argument when using the default document profile.
+- Made element `dup` and `clone` own independent subtrees while retaining IDs and Ruby copy semantics.
+- Made Segment equality compare length and direction; ordering still compares length only.
+- Limited Tile cell, row, and column queries to the requested geometry and accelerated XML character validation.
+- Simplified the first-run guide and aligned library constructor examples.
+- Updated the packaged skill for canvas origins, alignment, Paper lookup, curved geometry, and export constraints.
+- Revised DSL catalog examples and packaged Sevgi skill guidance to use statement-style calls and show inspection results.
+- Refined Showcase example tabs, made Ruby and XML views fill their panels, and hid executable preambles from Ruby views.
+- Documented non-rendering element data and clarified the related DSL catalog examples.
+- Refined Showcase heading spacing, page-title colors, and DSL catalog cards across light and dark themes.
+- Removed an obsolete ruler example and unused site code.
+- Kept the Squared and Copperplate guidesheet examples together at the end of the Showcase.
+- Updated the packaged skill to avoid duplicate semantic shapes and unnecessary paint passes.
+
+### Fixed
+
+- Kept horizontal scrollbars visible in Showcase example code panels.
+- Read Derender input in its declared XML encoding and normalized generated source, XML declarations, and markup to UTF-8.
+- Preserved open-path endpoints and derived edges independently of display precision.
+- Kept near-axis and near-parallel line equations and intersections independent of angle and slope rounding.
+- Corrected the Showcase social image dimensions.
+- Added SVG namespaces to standalone drawing examples and regenerated their outputs.
+- Made failed Sevgi Rake tasks stop dependent tasks and captured required-library failures in executor results.
+- Removed executor signal-handler replacement so the host and shell retain SIGINT ownership.
+- Escaped late export CSS as XML text and inserted it only at a supported final root closing tag.
+- Preserved Derender processing instructions and rejected custom entity references and unsupported trailing document nodes before inclusion.
+- Included both box origins in `Align`, unified Tile index validation, and isolated custom numeric attribute snapshots.
+- Prevented avoidable overflow and underflow in point distances.
+- Corrected browser source-panel expectations and added executable documentation, YARD, and packaged-skill checks.
+- Rendered inline code in DSL catalog summaries and kept linked task themes visible below the sticky header.
+- Restored Showcase tab icons with embedded Font Awesome SVGs.
+
+## 0.100.0 - 2026-09-09
+
+### Added
+
+- Added `ArcTo` and `ArcBy` for SVG-native elliptical arc paths.
+- Added Geometry `Arc`, `Ellipse`, and `Circle` with bounds, length, predicates, affine transformations, and
+  linear/quadratic intersections. Closed ellipses and circles support sweeps and hatching.
+- Added Geometry `Point.midpoint`, `Element#closed?`, lined `vertices`, open-path traversal, and `Rect#center`.
+- Added Geometry aggregate bounding boxes through `Operation.box`, point collinearity through `Point.collinear?`, and
+  polygon `simple?`, `convex?`, and `concave?` predicates.
+- Added Protractor and Arc examples and documented the drawing and calculation APIs.
+
+### Changed
+
+- Removed redundant parent scans while duplicating element subtrees.
+- Reused source bounds across Tile cells to reduce repeated calculations and object allocations.
+
+### Fixed
+
+- Preserved Showcase card HTML through Markdown rendering so all examples and their tabs remain visible.
+- Preserved XML declarations, pre-root comments, CDATA sections, inline comments, and namespace-only leaves in
+  Derender output and evaluation.
+- Limited PDF stamp recoloring to replaced text and carried graphics state across a page's content streams.
+- Corrected decimal interval fitting and made Grid point queries honor the active numeric precision.
+- Prevented implicit shell interpretation of single executable arguments in `F.sh` and `F.sh!`, including paths with spaces or shell metacharacters.
+- Preserved inherited namespaces on detached Derender nodes in generated source and direct evaluation, including imports through `EvaluateChildren` and `IncludeChildren`.
+- Prevented sweep and Hatch lines from crossing the exterior between two tangent vertices of a concave polygon.
+- Aligned Tile cells with their declared bounds for circles, rotated shapes, and polygons whose first vertex differs from their bounding-box origin.
+- Limited `Load` chains to 128 active sources with `Executor::LoadDepthError`, preserving cycle detection and nested load diagnostics.
+- Rejected nil and false aggregate-box inputs with the documented geometry error.
+- Restored precision-aware rejection of zero-length Triangle sides.
+- Made point-set collinearity independent of input order and removed eager polygon edge-pair storage.
+- Applied the collinearity tolerance to every three-point subset, removing coordinate-axis-dependent baseline selection.
+
+## 0.99.0 - 2026-08-09
+
+### Added
+
+- Added `SVG.Module` for building anonymous callable drawing modules with their contract installed before definition.
+- Added responsive Mermaid diagrams for the Derender round trip and SVG validation lifecycle.
+
+### Changed
+
+- Reorganized the documentation around getting started, usage, composition, documents, layout, output, and examples.
+- Documented how the `igves` and `igsev` command names reflect their conversion directions.
+- Normalized DSL catalog provider labels to lowercase and simplified polyfill-backed editor entries to `inkscape`.
+
+### Fixed
+
+- Allowed A5-on-A4 pdfcpu conversion to replace an existing output file.
+- Pre-rendered Mermaid diagrams as inline SVG instead of parsing them in site visitors' browsers.
+- Removed duplicate provider and context labels from DSL catalog entries.
+
 ## 0.98.2 - 2026-07-25
 
 ### Fixed
@@ -212,7 +326,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Changed
 
-- Added the checker board example to the documentation showcase flow.
+- Added the checkerboard example to the documentation showcase flow.
 - Consolidated Victor Book attribution for adapted showcase examples into a single documentation note.
 
 ### Fixed

data/README.md

@@ -1,8 +1,8 @@
 # Sevgi Function
 
 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.
+a general-purpose utility library. Nested helper modules organize the facade implementation and are not consumer
+mixins.
 
 ## Install
 
@@ -19,9 +19,14 @@ require "sevgi/function"
 ## Example
 
 ```ruby
-Sevgi::F.eq?(0.1 + 0.2, 0.3, precision: 12)
+Sevgi::F.with_precision(12) do
+  Sevgi::F.eq?(0.1 + 0.2, 0.3) # => true
+end
 ```
 
+The facade also provides `.sevgi` file discovery, generated-file output, argv-safe child processes, naming helpers,
+and terminal status output. Use the linked API documentation for exact results and failure contracts.
+
 ## Ruby compatibility
 
 Requires Ruby 3.4.0 or newer. CI verifies the current Ruby 3.4 release and the development Ruby from `.ruby-version`.

data/lib/sevgi/core.rb

@@ -39,7 +39,7 @@ module Sevgi
     end
   end
 
-  # Error raised for internal invariants and implementation paths that should be unreachable.
+  # Error raised for broken internal invariants and unreachable implementation paths.
   PanicError = Class.new(Error) unless defined?(self::PanicError)
 
   # Error raised for invalid public API usage.

data/lib/sevgi/function/color.rb

@@ -2,7 +2,7 @@
 
 module Sevgi
   module Function
-    # ANSI color and style methods promoted to {Sevgi::F}. This module organizes the facade implementation; it is not a
+    # 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.

data/lib/sevgi/function/file.rb

@@ -4,10 +4,10 @@ require "fileutils"
 
 module Sevgi
   module Function
-    # File-system methods promoted to {Sevgi::F}. This module organizes the facade implementation; it is not a consumer
+    # 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.
+      # Checks whether a file differs from the supplied 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
@@ -93,6 +93,40 @@ module Sevgi
         end
       end
 
+      # Resolves an output path, using the default when value is nil or an existing directory.
+      # The default is validated only when used. This method does not create files or directories.
+      # @param value [String, #to_path, nil] explicit output path or directory
+      # @param default [String, #to_path] default output path; its basename is used for a directory target
+      # @param context [String] public operation named in errors
+      # @return [String] expanded output path
+      # @raise [Sevgi::ArgumentError] when a selected path/default is blank, invalid, or cannot be converted
+      def output_path(value, default:, context: "Output")
+        return path(default, context: "#{context} default") if value.nil?
+
+        output = path(value, context: "#{context} path")
+        return output unless ::File.directory?(output)
+
+        default = path(default, context: "#{context} default")
+        ::File.join(output, ::File.basename(default))
+      end
+
+      # Converts a non-blank path to an expanded String without requiring it to exist.
+      # @param value [String, #to_path] raw path value
+      # @param context [String] error-message subject
+      # @return [String] expanded path
+      # @raise [Sevgi::ArgumentError] when value is blank, has an invalid type, or path conversion fails
+      def path(value, context: "Path")
+        path = value.respond_to?(:to_path) ? value.to_path : value
+        ArgumentError.("#{context} must be a String or path-like object") unless path.is_a?(::String)
+        ArgumentError.("#{context} must be provided") if path.strip.empty?
+
+        ::File.expand_path(path)
+      rescue ::Sevgi::ArgumentError
+        raise
+      rescue ::StandardError => e
+        ArgumentError.("#{context} must be a String or path-like object: #{e.message}")
+      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

data/lib/sevgi/function/math.rb

@@ -78,7 +78,7 @@ module Sevgi
       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. Integer quarter turns return exact `-1.0`, `0.0`, or
-      # `1.0`; other angles use Ruby's floating-point Math implementation.
+      # `1.0`. Other angles use Ruby's floating-point Math implementation.
       # @param degrees [Numeric] angle in degrees
       # @return [Float]
       # @raise [Sevgi::ArgumentError] when degrees is not a finite real number
@@ -94,6 +94,7 @@ module Sevgi
       def cot(degrees) = 1.0 / ::Math.tan(to_radians(degrees))
 
       # Counts complete divisions in a length.
+      # A positive quotient one floating-point step below the next integer counts as that integer.
       # @param length [Numeric] finite real total length
       # @param division [Numeric] finite real, non-zero division size
       # @return [Integer]
@@ -103,7 +104,11 @@ module Sevgi
         divisor = finite_real(:division, division)
         ArgumentError.("Division must not be zero") if divisor.zero?
 
-        (length / divisor).to_i
+        quotient = length / divisor
+        whole = quotient.to_i
+        candidate = whole + 1
+
+        quotient > whole && quotient.next_float == candidate ? candidate : whole
       end
 
       # Compares two numeric values after approximate rounding.
@@ -156,7 +161,7 @@ module Sevgi
         precision.nil? ? number : number.round(valid_precision(precision))
       end
 
-      # Returns the sine of an angle expressed in degrees. Integer quarter turns return exact `-1.0`, `0.0`, or `1.0`;
+      # 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]

data/lib/sevgi/function/shell.rb

@@ -8,25 +8,35 @@ module Sevgi
     # 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.
+      # Returns the absolute path of the first executable regular file, or nil.
       # @param program [Object] program name, absolute path, or relative slash-containing path
-      # @return [Boolean] true when an executable regular file is found
-      # @note PATH is evaluated on every call; empty PATH segments mean the current directory.
-      def executable?(program)
+      # @return [String, nil] absolute executable path, preserving a selected symlink
+      # @note PATH is evaluated on every call. Empty PATH segments mean the current directory.
+      def executable(program)
         program = program.to_s
-        return false if program.empty?
-        return executable_file?(program) if slash_path?(program)
+        return if program.empty?
+        if slash_path?(program)
+          return executable_file?(program) ? ::File.expand_path(program) : nil
+        end
 
-        ENV.fetch("PATH", "").split(::File::PATH_SEPARATOR, -1).any? do |dir|
-          executable_file?(::File.join(dir.empty? ? "." : dir, program))
+        ENV.fetch("PATH", "").split(::File::PATH_SEPARATOR, -1).each do |dir|
+          path = ::File.expand_path(program, dir.empty? ? "." : dir)
+          return path if executable_file?(path)
         end
+        nil
       end
 
+      # Checks whether a program exists and is executable.
+      # @param program [Object] program name, absolute path, or relative slash-containing path
+      # @return [Boolean] true when an executable regular file is found
+      # @see #executable
+      def executable?(program) = !executable(program).nil?
+
       # 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
-      # @note The first argument is checked as one exact argv entry; it is never shell-split.
+      # @note The first argument is checked as one exact argv entry. It is never shell-split.
       def executable!(*args)
         program = args.first.to_s
         Error.("Missing executable: #{program}") unless executable?(program)
@@ -232,7 +242,7 @@ module Sevgi
           ArgumentError.("Shell command required") if args.empty?
 
           @coathooks = 0
-          outs, errs, status = Open3.popen3(*args) do |stdin, stdout, stderr, wait_thread|
+          outs, errs, status = Open3.popen3(*command(args)) do |stdin, stdout, stderr, wait_thread|
             capture(stdin, stdout, stderr, wait_thread, &input)
           end
 
@@ -241,7 +251,14 @@ module Sevgi
 
         private
 
-        # rubocop:disable Lint/RescueException
+        def command(args)
+          args = args.dup
+          index = args.first.is_a?(::Hash) ? 1 : 0
+          args[index] = [args[index], args[index]] unless args[index].is_a?(::Array)
+          args
+        end
+
+        # rubocop:disable-next Lint/RescueException
         def capture(stdin, stdout, stderr, wait_thread, &input)
           registered = false
           Signals.register(self, wait_thread.pid)
@@ -256,7 +273,6 @@ module Sevgi
           close_input(stdin)
           Signals.unregister(self) if registered
         end
-        # rubocop:enable Lint/RescueException
 
         def start_readers(stdout, stderr)
           [
@@ -336,11 +352,11 @@ module Sevgi
       #   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
+      #   @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
+      #   @raise [StandardError] when the input block raises. The child is terminated and reaped before propagation
       #   @note The child's stdin is closed after the input block. During execution, the first SIGINT sends TERM to the
       #     child process and the second SIGINT as KILL to each active child outside trap context, then restores the
       #     previous handler.
@@ -349,12 +365,12 @@ module Sevgi
       # Runs a command, requiring both executable lookup and successful exit status.
       # @param args [Array<String>] command and arguments
       # @yield optional stdin producer, evaluated once after output readers start
-      # @yieldreturn [String, nil] content to write to stdin; nil writes nothing
+      # @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
+      # @raise [StandardError] when the input block raises. The child is terminated and reaped before propagation
       # @note The child's stdin is closed after the input block. During execution, the first SIGINT sends TERM to the
       #   child process and the second SIGINT as KILL to each active child outside trap context, then restores the previous
       #   handler.

data/lib/sevgi/function/string.rb

@@ -2,7 +2,7 @@
 
 module Sevgi
   module Function
-    # String methods promoted to {Sevgi::F}. This module organizes the facade implementation; it is not a consumer mixin
+    # 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.
@@ -20,10 +20,10 @@ module Sevgi
 
     extend String
 
-    # English pluralization promoted to {Sevgi::F}. This module organizes the facade implementation; it is not a
+    # 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.
+      # Words excluded from pluralization.
       # @api private
       UNCOUNTABLES = %w[
         equipment

data/lib/sevgi/function/ui.rb

@@ -2,7 +2,7 @@
 
 module Sevgi
   module Function
-    # Terminal status methods promoted to {Sevgi::F}. This module organizes the facade implementation; it is not a
+    # 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.

data/lib/sevgi/function/version.rb

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

data/lib/sevgi/function.rb

@@ -13,13 +13,13 @@ require_relative "function/ui"
 require_relative "function/version"
 
 module Sevgi
-  # Support toolbox for Sevgi components and advanced extensions. The supported helper facade is {Sevgi::F}; it
+  # 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.
   #
   # {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.
+  # facade implementation and its method documentation. Consumers do not include or extend them.
   #
   # @example Use the supported facade in library code
   #   Sevgi::F.with_precision(3) do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sevgi-function
 version: !ruby/object:Gem::Version
-  version: 0.98.2
+  version: 1.1.0
 platform: ruby
 authors:
 - Recai Oktaş
@@ -50,7 +50,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Shared utility functions for Sevgi components.
 test_files: []