tins 1.43.0 → 1.44.0

data/lib/tins/limited.rb

@@ -1,8 +1,34 @@
 require 'thread'
 
 module Tins
+  # Tins::Limited provides a thread pool implementation that limits the number
+  # of concurrent threads running simultaneously.
+  #
+  # This class implements a producer-consumer pattern where you can submit
+  # tasks that will be executed by a fixed number of worker threads, preventing
+  # resource exhaustion from too many concurrent operations.
+  #
+  # @example Basic usage
+  #   limited = Tins::Limited.new(3)  # Limit to 3 concurrent threads
+  #
+  #   limited.process do |l|
+  #     10.times do
+  #       l.execute { puts "Task #{Thread.current.object_id}" }
+  #     end
+  #     l.stop  # Stop processing new tasks
+  #   end
+  #
+  # @example With named thread group
+  #   limited = Tins::Limited.new(5, name: 'worker_pool')
+  #   # Threads will be named 'worker_pool'
   class Limited
-    # Create a Limited instance, that runs _maximum_ threads at most.
+    # Create a Limited instance that runs at most _maximum_ threads
+    # simultaneously.
+    #
+    # @param maximum [Integer] The maximum number of concurrent worker threads
+    # @param name [String, nil] Optional name for the thread group
+    # @raise [ArgumentError] if maximum is less than 1
+    # @raise [TypeError] if maximum cannot be converted to Integer
     def initialize(maximum, name: nil)
       @maximum  = Integer(maximum)
       raise ArgumentError, "maximum < 1" if @maximum < 1
@@ -13,15 +39,28 @@ module Tins
       @tg       = ThreadGroup.new
     end
 
-    # The maximum number of worker threads.
+    # The maximum number of worker threads that can run concurrently.
+    #
+    # @return [Integer] The maximum concurrent thread limit
     attr_reader :maximum
 
-    # Execute _maximum_ number of threads in parallel.
+    # Submit a task to be executed by the thread pool.
+    #
+    # @yield [Thread] The block to execute as a task
+    # @raise [ArgumentError] if called before process has been started
     def execute(&block)
       @tasks or raise ArgumentError, "start processing first"
       @tasks << block
     end
 
+    # Start processing tasks with the configured thread pool.
+    #
+    # This method blocks until all tasks are completed and the processing is
+    # stopped. The provided block is called repeatedly to submit tasks via
+    # execute().
+    #
+    # @yield [Limited] The limited instance for submitting tasks
+    # @return [void]
     def process
       @tasks    = Queue.new
       @executor = create_executor
@@ -36,20 +75,32 @@ module Tins
       end
     end
 
+    # Stop processing new tasks and wait for existing tasks to complete.
+    #
+    # @return [void]
     def stop
       throw :stop
     end
 
     private
 
+    # Check if all tasks and threads have completed.
+    #
+    # @return [Boolean] true if no tasks remain and no threads are running
     def done?
       @tasks.empty? && @tg.list.empty?
     end
 
+    # Wait for all threads in the thread group to complete.
+    #
+    # @return [void]
     def wait
       @tg.list.each(&:join)
     end
 
+    # Create and start the executor thread that manages the worker pool.
+    #
+    # @return [Thread] The executor thread
     def create_executor
       Thread.new do
         @mutex.synchronize do
@@ -73,5 +124,3 @@ module Tins
     end
   end
 end
-
-require 'tins/alias'

data/lib/tins/lines_file.rb

@@ -1,29 +1,74 @@
 module Tins
+  # Tins::LinesFile provides enhanced file line processing capabilities.
+  #
+  # This class wraps file content in a way that allows for rich line-level
+  # operations, including tracking line numbers, filenames, and providing
+  # convenient navigation and matching methods. It's particularly useful for
+  # log processing, configuration files, or any scenario where you need to
+  # work with structured text data while maintaining context about line
+  # positions.
+  #
+  # @example Basic usage
+  #   lines_file = Tins::LinesFile.for_filename('example.txt')
+  #   lines_file.each do |line|
+  #     puts line.file_linenumber  # => "example.txt:1"
+  #     puts line.line_number      # => 1
+  #   end
+  #
+  # @example Line navigation and matching
+  #   lines_file = Tins::LinesFile.for_filename('example.txt')
+  #   lines_file.next!           # Move to next line
+  #   lines_file.match_forward(/pattern/)  # Match forward from current position
   class LinesFile
+    # Extension module that adds line metadata to individual lines.
+    #
+    # This module is automatically mixed into each line when a LinesFile is created,
+    # providing access to line number and filename information directly from the line objects.
     module LineExtension
+      # @return [Integer] The line number (1-based) of this line
       attr_reader :line_number
 
+      # @return [String] The filename associated with this line's source
       def filename
         lines_file.filename.dup
       end
     end
 
+    # Create a LinesFile instance from a filename.
+    #
+    # @param filename [String] Path to the file to read
+    # @param line_number [Integer] Starting line number (default: 1)
+    # @return [LinesFile] A new LinesFile instance
     def self.for_filename(filename, line_number = nil)
       obj = new(File.readlines(filename), line_number)
       obj.filename = filename
       obj
     end
 
+    # Create a LinesFile instance from an already opened file.
+    #
+    # @param file [File] An open File object to read from
+    # @param line_number [Integer] Starting line number (default: 1)
+    # @return [LinesFile] A new LinesFile instance
     def self.for_file(file, line_number = nil)
       obj = new(file.readlines, line_number)
       obj.filename = file.path
       obj
     end
 
+    # Create a LinesFile instance from an array of lines.
+    #
+    # @param lines [Array<String>] Array of line strings
+    # @param line_number [Integer] Starting line number (default: 1)
+    # @return [LinesFile] A new LinesFile instance
     def self.for_lines(lines, line_number = nil)
       new(lines, line_number)
     end
 
+    # Initialize a LinesFile with lines and optional starting line number.
+    #
+    # @param lines [Array<String>] Array of line strings to process
+    # @param line_number [Integer] Starting line number (default: 1)
     def initialize(lines, line_number = nil)
       @lines = lines
       @lines.each_with_index do |line, i|
@@ -34,27 +79,42 @@ module Tins
       instance_variable_set :@line_number, line_number || (@lines.empty? ? 0 : 1)
     end
 
+    # @return [String] The filename associated with this LinesFile
     attr_accessor :filename
 
+    # @return [Integer] The current line number (1-based)
     attr_reader :line_number
 
+    # Reset the current line number to the beginning.
+    #
+    # @return [LinesFile] Returns self for chaining
     def rewind
       self.line_number = 1
       self
     end
 
+    # Move to the next line.
+    #
+    # @return [LinesFile, nil] Returns self if successful, nil if at end of file
     def next!
       old = line_number
       self.line_number += 1
       line_number > old ? self : nil
     end
 
+    # Move to the previous line.
+    #
+    # @return [LinesFile, nil] Returns self if successful, nil if at beginning
     def previous!
       old = line_number
       self.line_number -= 1
       line_number < old ? self : nil
     end
 
+    # Set the current line number.
+    #
+    # @param number [Integer] The new line number to set
+    # @return [void]
     def line_number=(number)
       number = number.to_i
       if number > 0 && number <= last_line_number
@@ -62,14 +122,21 @@ module Tins
       end
     end
 
+    # @return [Integer] The total number of lines in this file
     def last_line_number
       @lines.size
     end
 
+    # @return [Boolean] True if the file has no lines
     def empty?
       @lines.empty?
     end
 
+    # Iterate through all lines, setting the current line number for each.
+    #
+    # @yield [line] Each line in the file
+    # @yieldparam line [String] The current line object with line metadata
+    # @return [LinesFile] Returns self for chaining
     def each(&block)
       empty? and return self
       old_line_number = line_number
@@ -83,15 +150,22 @@ module Tins
     end
     include Enumerable
 
+    # @return [String, nil] The current line content or nil if out of bounds
     def line
       index = line_number - 1
       @lines[index] if index >= 0
     end
 
+    # @return [String] Formatted filename and line number (e.g., "file.txt:5")
     def file_linenumber
       "#{filename}:#{line_number}"
     end
 
+    # Match a regular expression backward from current position.
+    #
+    # @param regexp [Regexp] The regular expression to match
+    # @param previous_after_match [Boolean] Whether to move back one line after match
+    # @return [Array<String>, nil] Captured groups or nil if no match
     def match_backward(regexp, previous_after_match = false)
       begin
         if line =~ regexp
@@ -101,6 +175,11 @@ module Tins
       end while previous!
     end
 
+    # Match a regular expression forward from current position.
+    #
+    # @param regexp [Regexp] The regular expression to match
+    # @param next_after_match [Boolean] Whether to move forward one line after match
+    # @return [Array<String>, nil] Captured groups or nil if no match
     def match_forward(regexp, next_after_match = false)
       begin
         if line =~ regexp
@@ -110,14 +189,14 @@ module Tins
       end while next!
     end
 
+    # @return [String] String representation including line number and content
     def to_s
       "#{line_number} #{line.chomp}"
     end
 
+    # @return [String] Detailed inspection string
     def inspect
       "#<#{self.class}: #{to_s.inspect}>"
     end
   end
 end
-
-require 'tins/alias'

data/lib/tins/lru_cache.rb

@@ -1,33 +1,57 @@
 module Tins
+  # An LRU (Least Recently Used) cache implementation.
+  #
+  # This cache maintains a fixed-size collection of key-value pairs,
+  # automatically removing the least recently accessed item when the capacity
+  # is exceeded.
   class LRUCache
     include Enumerable
 
-    class << self
-      private
+    # Our "nil" value if it wasn' set by clients
+    NOT_EXIST = Object.new.freeze
 
-      my_nil = Object.new.freeze
-
-      define_method(:not_exist) do
-        my_nil
-      end
-    end
+    private_constant :NOT_EXIST
 
+    # Initializes a new LRU cache with the specified capacity.
+    #
+    # @param capacity [Integer] maximum number of items the cache can hold
     def initialize(capacity)
-      @capacity = capacity
+      @capacity = Integer(capacity)
+      @capacity >= 1 or
+        raise ArgumentError, "capacity should be >= 1, was #@capacity"
       @data     = {}
     end
 
+    # Returns the maximum capacity of the cache.
+    #
+    # @return [Integer] the cache capacity
     attr_reader :capacity
 
+    # Retrieves the value associated with the given key.
+    #
+    # If the key exists, it is moved to the most recently used position.
+    # Returns nil if the key does not exist.
+    #
+    # @param key [Object] the key to look up
+    # @return [Object, nil] the value for the key or nil if not found
     def [](key)
-      case value = @data.delete(key){ not_exist }
-      when not_exist
+      case value = @data.delete(key) { NOT_EXIST }
+      when NOT_EXIST
         nil
       else
         @data[key] = value
       end
     end
 
+    # Associates a value with a key in the cache.
+    #
+    # If the key already exists, its position is updated to most recently used.
+    # If adding this item exceeds the capacity, the least recently used item is
+    # removed.
+    #
+    # @param key [Object] the key to set
+    # @param value [Object] the value to associate with the key
+    # @return [Object] the assigned value
     def []=(key, value)
       @data.delete(key)
       @data[key] = value
@@ -37,26 +61,39 @@ module Tins
       value
     end
 
+    # Iterates over all key-value pairs in the cache.
+    #
+    # Items are yielded in order from most recently used to least recently used.
+    #
+    # @yield [key, value] yields each key-value pair
+    # @yieldparam key [Object] the key
+    # @yieldparam value [Object] the value
+    # @return [Enumerator] if no block is given
     def each(&block)
       @data.reverse_each(&block)
     end
 
+    # Removes and returns the value associated with the given key.
+    #
+    # @param key [Object] the key to delete
+    # @return [Object, nil] the removed value or nil if not found
     def delete(key)
       @data.delete(key)
     end
 
+    # Removes all items from the cache.
+    #
+    # @return [Tins::LRUCache] self
     def clear
       @data.clear
+      self
     end
 
+    # Returns the number of items currently in the cache.
+    #
+    # @return [Integer] the current size of the cache
     def size
       @data.size
     end
-
-    private
-
-    def not_exist
-      self.class.send(:not_exist)
-    end
   end
 end

data/lib/tins/memoize.rb

@@ -1,91 +1,119 @@
 require 'tins/extract_last_argument_options'
+require 'mize'
 
 module Tins
+  # Provides memoization functionality for methods and functions with support
+  # for instance-level and class-level caching respectively.
+  #
+  # @example Basic method memoization
+  #   class Calculator
+  #     def expensive_calculation(x, y)
+  #       # Some expensive computation
+  #       x * y
+  #     end
+  #     memoize_method :expensive_calculation
+  #   end
+  #
+  # @example Function memoization (shared across instances)
+  #   class MathUtils
+  #     def self.factorial(n)
+  #       n <= 1 ? 1 : n * factorial(n - 1)
+  #     end
+  #     memoize_function :factorial
+  #   end
+  #
+  # @example With freezing results
+  #   class DataProcessor
+  #     def process_data(input)
+  #       # Process data and return result
+  #       input.dup
+  #     end
+  #     memoize_method :process_data, freeze: true
+  #   end
+  #
+  # @note This module is deprecated in favor of the {https://github.com/flori/mize mize} gem.
+  #       Use `memoize method:` or `memoize function:` from the mize gem directly.
   module Memoize
+    # Provides cache management methods for memoized functions and methods.
+    # This module is included in classes that use memoization functionality.
+    #
+    # @example Using cache methods directly
+    #   class Example
+    #     include Tins::Memoize::CacheMethods
+    #
+    #     def expensive_method
+    #       # Some expensive computation
+    #     end
+    #     memoize_method :expensive_method
+    #   end
+    #
+    #   obj = Example.new
+    #   obj.memoize_cache_clear  # Clear all cached values
+    #   obj.__memoize_cache__    # Access the internal cache object
     module CacheMethods
-      # Return the cache object.
+      # Return the cache object used for memoization.
+      #
+      # @return [Object] The cache instance
       def __memoize_cache__
-        @__memoize_cache__ ||= {}
+        if @__memoize_cache__
+          @__memoize_cache__
+        else
+          @__memoize_cache__ = __mize_cache__
+          def @__memoize_cache__.empty?
+            @data.empty?
+          end
+          @__memoize_cache__
+        end
       end
 
-      # Clear cached values for all methods/functions.
+      # Clear cached values for all methods/functions of this object.
+      #
+      # @return [self] For chaining
       def memoize_cache_clear
          __memoize_cache__.clear
         self
       end
-
-      def memoize_apply_visibility(id)
-        visibility = instance_eval do
-          case
-          when private_method_defined?(id)
-            :private
-          when protected_method_defined?(id)
-            :protected
-          end
-        end
-        yield
-      ensure
-        visibility and __send__(visibility, id)
-      end
     end
 
     class ::Module
-      # Automatically memoize calls of the the methods +method_ids+. The
-      # memoized results do NOT ONLY depend on the arguments, but ALSO on the
-      # object the method is called on.
+      # Memoize a method so that its return value is cached based on the arguments
+      # and the object instance. Each instance maintains its own cache.
+      #
+      # @param method_ids [Array<Symbol>] One or more method names to memoize
+      # @option opts [Boolean] :freeze (false) Whether to freeze results
+      # @return [Symbol, Array<Symbol>] The memoized method name(s)
+      #
+      # @deprecated Use `memoize method:` from the mize gem instead.
       def memoize_method(*method_ids)
+        warn "[DEPRECATION] `memoize_method` is deprecated. Please use `memoize method:` from mize gem."
         method_ids.extend(ExtractLastArgumentOptions)
         method_ids, opts = method_ids.extract_last_argument_options
-        include CacheMethods
-        method_ids.each do |method_id|
-          method_id = method_id.to_s.to_sym
-          memoize_apply_visibility method_id do
-            orig_method = instance_method(method_id)
-            __send__(:define_method, method_id) do |*args|
-              mc = __memoize_cache__
-              if mc.key?(method_id) and result = mc[method_id][args]
-                result
-              else
-                (mc[method_id] ||= {})[args] = result = orig_method.bind(self).call(*args)
-                $DEBUG and warn "#{self.class} cached method #{method_id}(#{args.inspect unless args.empty?}) = #{result.inspect} [#{__id__}]"
-                opts[:freeze] and result.freeze
-              end
-              result
-            end
-          end
+        method_ids.each do |method|
+          memoize method:, **opts.slice(:freeze)
         end
+        include CacheMethods
         method_ids.size == 1 ? method_ids.first : method_ids
       end
 
       include CacheMethods
 
-      # Automatically memoize calls of the functions +function_ids+. The
-      # memoized result does ONLY depend on the arguments given to the
-      # function.
+      # Memoize a function (class method) so that its return value is cached
+      # based only on the arguments, shared across all instances of the class.
+      #
+      # @param function_ids [Array<Symbol>] One or more function names to memoize
+      # @option opts [Boolean] :freeze (false) Whether to freeze results
+      # @return [Symbol, Array<Symbol>] The memoized function name(s)
+      #
+      # @deprecated Use `memoize function:` from the mize gem instead.
       def memoize_function(*function_ids)
+        warn "[DEPRECATION] `memoize_function` is deprecated. Please use `memoize function:` from mize gem."
         function_ids.extend(ExtractLastArgumentOptions)
         function_ids, opts = function_ids.extract_last_argument_options
-        mc = __memoize_cache__
-        function_ids.each do |function_id|
-          function_id = function_id.to_s.to_sym
-          memoize_apply_visibility function_id do
-            orig_function = instance_method(function_id)
-            __send__(:define_method, function_id) do |*args|
-              if mc.key?(function_id) and result = mc[function_id][args]
-                result
-              else
-                (mc[function_id] ||= {})[args] = result = orig_function.bind(self).call(*args)
-                opts[:freeze] and result.freeze
-                $DEBUG and warn "#{self.class} cached function #{function_id}(#{args.inspect unless args.empty?}) = #{result.inspect}"
-              end
-              result
-            end
-          end
+        function_ids.each do |function|
+          memoize function:, **opts.slice(:freeze)
         end
         function_ids.size == 1 ? function_ids.first : function_ids
       end
     end
   end
 end
-
-require 'tins/alias'