sevgi-function 0.94.0 → 0.98.2

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
@@ -24,29 +26,68 @@ module Sevgi
       # @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.
       def executable!(*args)
-        program = args.first.to_s.split.first
+        program = args.first.to_s
         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]
@@ -58,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]
@@ -68,11 +109,109 @@ 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) do
+          private_class_method :[]
+        end
+
+        WAKE = "."
+
+        private_constant :WAKE
+
+        class << self
+          def register(runner, pid)
+            mutex.synchronize do
+              install unless entries.any?
+              entries[runner] = Entry.new(runner, pid)
+            end
+          end
+
+          def unregister(runner)
+            worker = mutex.synchronize do
+              next unless entries.delete(runner)
+
+              restore unless entries.any?
+            end
+
+            worker.join if worker && worker != Thread.current
+          end
+
+          private
+
+          def dispatch
+            active = mutex.synchronize { entries.values.dup }
+            active.each { dispatch_entry(it) }
+          end
+
+          def dispatch_entry(entry)
+            entry.runner.send(:handle_sigint, entry.pid)
+          rescue ::StandardError => e
+            warn("SIGINT dispatch failed: #{e.message}")
+          end
+
+          def install
+            reader, writer = ::IO.pipe
+            worker = Thread.new { listen(reader) }
+            previous = Signal.trap("INT") { notify(writer) }
+
+            @previous = previous
+            @worker = worker
+            @writer = writer
+          rescue ::StandardError
+            Signal.trap("INT", previous) if previous
+            close_io(writer)
+            worker&.join
+            close_io(reader)
+            raise
+          end
+
+          def listen(reader)
+            dispatch while reader.read(1)
+          rescue ::IOError, ::SystemCallError
+            nil
+          ensure
+            close_io(reader)
+          end
+
+          def mutex = @mutex ||= Mutex.new
+
+          def entries = @entries ||= {}
+
+          def notify(writer)
+            writer.write_nonblock(WAKE, exception: false)
+          rescue ::IOError, ::SystemCallError
+            nil
+          end
+
+          def restore
+            Signal.trap("INT", @previous)
+            @previous = nil
+
+            writer = @writer
+            worker = @worker
+            @worker = nil
+            @writer = nil
+            close_io(writer)
+            worker
+          end
+
+          def close_io(io)
+            io&.close unless io&.closed?
+          rescue ::IOError
+            nil
+          end
+        end
+      end
+
+      private_constant :Signals
+
       # Runs shell commands and captures stdout, stderr, and exit status.
       # @api private
       class Runner
@@ -87,24 +226,26 @@ 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
 
         # rubocop:disable Lint/RescueException
         def capture(stdin, stdout, stderr, wait_thread, &input)
-          # Handle `^C`
-          previous = trap("INT") { handle_sigint(wait_thread.pid) }
+          registered = false
+          Signals.register(self, wait_thread.pid)
+          registered = true
           readers = start_readers(stdout, stderr)
 
           read_process(stdin, wait_thread, readers, &input)
@@ -113,7 +254,7 @@ module Sevgi
           raise
         ensure
           close_input(stdin)
-          trap("INT", previous) if previous
+          Signals.unregister(self) if registered
         end
         # rubocop:enable Lint/RescueException
 
@@ -189,16 +330,20 @@ 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
-      #     child process and the second SIGINT sends KILL; the previous SIGINT handler is restored before return.
+      #     child process and the second SIGINT as KILL to each active child outside trap context, then restores the
+      #     previous handler.
       def sh(...) = Runner.new.(...)
 
       # Runs a command, requiring both executable lookup and successful exit status.
@@ -206,11 +351,13 @@ 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
       # @note The child's stdin is closed after the input block. During execution, the first SIGINT sends TERM to the
-      #   child process and the second SIGINT sends KILL; the previous SIGINT handler is restored before return.
+      #   child process and the second SIGINT as KILL to each active child outside trap context, then restores the previous
+      #   handler.
       def sh!(*args, &block)
         executable!(*args) unless args.empty?
 

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.94.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.94.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.10
+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: []