tins 1.32.0 → 1.44.0

data/lib/tins/implement.rb

@@ -1,5 +1,32 @@
 module Tins
+  # Provides methods for defining abstract method implementations that raise
+  # NotImplementedError. Useful for creating interface-like modules or base
+  # classes where certain methods must be implemented by subclasses.
+  #
+  # @example Basic usage
+  #   module MyInterface
+  #     include Tins::Implement
+  #     implement :process
+  #   end
+  #
+  #   class MyClass
+  #     include MyInterface
+  #     # Must implement process method or it will raise NotImplementedError
+  #   end
+  #
+  # @example With custom messages
+  #   module ApiInterface
+  #     include Tins::Implement
+  #     implement :get_data, :subclass
+  #     implement :post_data, :submodule
+  #   end
+  #
+  # @see Tins::MethodDescription For method description integration
   module Implement
+    # Predefined error message templates for different implementation contexts.
+    #
+    # These templates provide context-specific error messages that help
+    # developers understand where and how methods should be implemented.
     MESSAGES = {
       default:   'method %{method_name} not implemented in module %{module}',
       subclass:  'method %{method_name} has to be implemented in '\
@@ -8,6 +35,21 @@ module Tins
         'submodules of %{module}',
     }
 
+    # Defines an implementation for a method that raises NotImplementedError.
+    #
+    # @param method_name [Symbol, String] The name of the method to implement
+    # @param msg [Symbol, String, Hash] The error message template or options
+    #   @option msg [Symbol] :in When msg is a Hash, specifies which message key to use
+    #
+    # @example Basic usage
+    #   implement :process
+    #   # => Defines process method that raises NotImplementedError
+    #
+    # @example Custom message
+    #   implement :calculate, 'Custom error message'
+    #
+    # @example Using predefined message template
+    #   implement :validate, :subclass
     def implement(method_name, msg = :default)
       method_name.nil? and return
       case msg
@@ -30,6 +72,14 @@ module Tins
       end
     end
 
+    # Defines an implementation for a method that raises NotImplementedError
+    # specifically for submodule implementations.
+    #
+    # @param method_name [Symbol, String] The name of the method to implement
+    #
+    # @example Usage
+    #   implement_in_submodule :render
+    #   # => Defines render method with submodule-specific error message
     def implement_in_submodule(method_name)
       implement method_name,
         'method %{method_name} has to be implemented in submodules of'\

data/lib/tins/limited.rb

@@ -1,50 +1,126 @@
 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.
-    def initialize(maximum)
-      @mutex =  Mutex.new
-      @continue = ConditionVariable.new
-      @maximum = Integer(maximum)
+    # 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
-      @count = 0
-      @tg = ThreadGroup.new
+      @mutex    = Mutex.new
+      @continue = ConditionVariable.new
+      @name     = name
+      @count    = 0
+      @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.
-    def execute
-      @mutex.synchronize do
+    # 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
+      @executor.name = @name if @name
+      catch :stop do
         loop do
-          if @count < @maximum
-            @count += 1
-            Thread.new do
-              @tg.add Thread.current
-              yield
-              @mutex.synchronize { @count -= 1 }
-              @continue.signal
-            end
-            return
-          else
-            @continue.wait(@mutex)
-          end
+          yield self
         end
+      ensure
+        wait until done?
+        @executor.kill
       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
 
-    def process
-      yield self
-    ensure
-      wait
+    # 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
+          loop do
+            if @count < @maximum
+              task = @tasks.pop
+              @count += 1
+              Thread.new do
+                @tg.add Thread.current
+                task.(Thread.current)
+              ensure
+                @count -= 1
+                @continue.signal
+              end
+            else
+              @continue.wait(@mutex)
+            end
+          end
+        end
+      end
     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