tins 1.31.1 → 1.54.0

data/Rakefile

@@ -3,25 +3,42 @@
 require 'gem_hadar'
 
 GemHadar do
-  name        'tins'
-  author      'Florian Frank'
-  email       'flori@ping.de'
-  homepage    "https://github.com/flori/#{name}"
-  summary     'Useful stuff.'
-  description 'All the stuff that isn\'t good/big enough for a real library.'
-  test_dir    'tests'
+  name              'tins'
+  author            'Florian Frank'
+  email             'flori@ping.de'
+  homepage          "https://github.com/flori/#{name}"
+  summary           'Useful stuff.'
+  description       'All the stuff that isn\'t good/big enough for a real library.'
+  test_dir          'tests'
   test_files.concat Dir["#{test_dir}/*_test.rb"]
-  ignore      '.*.sw[pon]', 'pkg', 'Gemfile.lock', '.rvmrc', 'coverage', '.rbx',
-    '.AppleDouble', '.DS_Store', 'tags', '.bundle', '.byebug_history'
-  package_ignore '.all_images.yml', '.tool-versions', '.gitignore', 'VERSION',
-    'TODO', *Dir.glob('.github/**/*', File::FNM_DOTMATCH)
+  doc_code_files    files.grep(%r(\Alib/))
+  ignore            '.*.sw[pon]', 'pkg', 'Gemfile.lock', '.rvmrc', 'coverage',
+    '.rbx', '.AppleDouble', '.DS_Store', 'tags', 'cscope.out', '.bundle',
+    '.yardoc', 'doc', 'TODO.md'
+  package_ignore    '.all_images.yml', '.tool-versions', '.gitignore',
+    'VERSION', '.utilsrc', '.github', '.contexts'
 
-  readme      'README.md'
-  licenses << 'MIT'
+  readme            'README.md'
+  licenses <<       'MIT'
+  clean <<          'coverage'
+
+  changelog do
+    filename 'CHANGES.md'
+  end
+
+  github_workflows(
+    'static.yml' => {}
+  )
+
+  required_ruby_version  '>= 3.1'
 
-  required_ruby_version  '>= 2.0'
-  development_dependency 'utils'
-  development_dependency 'test-unit', '~>3.1'
-  development_dependency 'simplecov'
   dependency 'sync'
+  dependency 'bigdecimal'
+  dependency 'readline'
+  dependency 'mize',     '~> 0.6'
+  development_dependency 'all_images'
+  development_dependency 'debug'
+  development_dependency 'simplecov'
+  development_dependency 'term-ansicolor'
+  development_dependency 'test-unit', '~> 3.7'
 end

data/examples/let.rb

@@ -2,48 +2,16 @@
 
 require 'tins'
 
-LetScope = Tins::BlankSlate.with :instance_eval, :to_s, :inspect, :extend
-class LetScope
-  include Tins::MethodMissingDelegator::DelegatorModule
-  include Tins::BlockSelf
-
-  def initialize(my_self, bindings = {}, outer_scope = nil)
-    super(my_self)
-    @outer_scope = outer_scope
-    @bindings = bindings
-    extend Tins::Eigenclass
-    eigenclass_eval { extend Tins::Constant }
-    each_binding do |name, value|
-      eigenclass_eval {  constant name, value }
-    end
-  end
-
-  def each_binding(&block)
-    if @outer_scope
-      @outer_scope.each_binding(&block)
-    end
-    @bindings.each(&block)
-  end
-
-  def let(bindings = {}, &block)
-    ls = LetScope.new(block_self(&block), bindings, self)
-    ls.instance_eval(&block)
-  end
-
-  # Including this module into your current namespace defines the let method.
-  module Include
-    include Tins::BlockSelf
-
-    def let(bindings = {}, &block)
-      ls = LetScope.new(block_self(&block), bindings)
-      ls.instance_eval(&block)
-    end
-  end
-end
-
 if $0 == __FILE__
   class Foo
-    include LetScope::Include
+    include Tins::DynamicScope
+
+    def let(bindings = {})
+      dynamic_scope do
+        bindings.each { |name, value| send("#{name}=", value) }
+        yield
+      end
+    end
 
     def twice(x)
       2 * x

data/examples/mail.rb

@@ -1,10 +1,11 @@
+#!/usr/bin/env ruby
+
 require 'tins'
 require 'net/smtp'
 require 'time'
 
 class Mail
   extend Tins::DSLAccessor
-  include Tins::InstanceExec
   include Tins::MethodMissingDelegator::DelegatorModule
   include Tins::BlockSelf
 

data/examples/null_pattern.rb

@@ -1,3 +1,5 @@
+#!/usr/bin/env ruby
+
 require 'tins'
 $:.unshift 'examples'
 

data/examples/ones_difference.stm

@@ -22,4 +22,3 @@
 18. right goto: 19
 19. cond  if: '1', then: 18, else: 21
 20. halt
-21. halt

data/examples/turing.rb

@@ -1,3 +1,5 @@
+#!/usr/bin/env ruby
+
 require 'term/ansicolor'
 require 'tins'
 
@@ -305,6 +307,8 @@ if $0 == __FILE__ and ARGV.any?
     else
       raise "unknown turing machine suffix: #{ext}, use .stm or .mtm"
     end
-  tm = machine_type.new(File.read(filename))
+  tm = File.open(filename) do |file|
+    machine_type.new(file)
+  end
   $DEBUG ? tm.step(*tapes) : tm.run(*tapes)
 end

data/lib/tins/alias.rb

@@ -1 +1,2 @@
+# This Is Not Spruz
 Spruz = Tins

data/lib/tins/annotate.rb

@@ -1,38 +1,48 @@
-module Tins::Annotate
-  def annotate(name)
-    singleton_class.class_eval do
-      define_method(name) do |annotation = :annotated|
-        instance_variable_set "@__annotation_#{name}__", annotation
-      end
+module Tins
+  # A module for adding annotations to classes and methods
+  #
+  # This module provides functionality to add metadata annotations to classes and
+  # methods, allowing for enhanced documentation and introspection capabilities
+  module Annotate
+    # The annotate method sets up annotation functionality for a given name
+    # by defining methods to set and retrieve annotations on class methods
+    #
+    # @param name [ Symbol ] the name of the annotation to define
+    def annotate(name)
+      singleton_class.class_eval do
+        define_method(name) do |annotation = :annotated|
+          instance_variable_set "@__annotation_#{name}__", annotation
+        end
 
-      define_method("#{name}_of") do |method_name|
-        __send__("#{name}_annotations")[method_name]
-      end
+        define_method("#{name}_of") do |method_name|
+          __send__("#{name}_annotations")[method_name]
+        end
 
-      define_method("#{name}_annotations") do
-        if instance_variable_defined?("@__annotation_#{name}_annotations__")
-          instance_variable_get "@__annotation_#{name}_annotations__"
-        else
-          instance_variable_set "@__annotation_#{name}_annotations__", {}
+        define_method("#{name}_annotations") do
+          if instance_variable_defined?("@__annotation_#{name}_annotations__")
+            instance_variable_get "@__annotation_#{name}_annotations__"
+          else
+            instance_variable_set "@__annotation_#{name}_annotations__", {}
+          end
         end
-      end
 
-      old_method_added = instance_method(:method_added)
-      define_method(:method_added) do |method_name|
-        old_method_added.bind(self).call method_name
-        if annotation = instance_variable_get("@__annotation_#{name}__")
-          __send__("#{name}_annotations")[method_name] = annotation
+        old_method_added = instance_method(:method_added)
+        define_method(:method_added) do |method_name|
+          old_method_added.bind(self).call method_name
+          if annotation = instance_variable_get("@__annotation_#{name}__")
+            __send__("#{name}_annotations")[method_name] = annotation
+          end
+          instance_variable_set "@__annotation_#{name}__", nil
         end
-        instance_variable_set "@__annotation_#{name}__", nil
       end
-    end
 
-    define_method("#{name}_annotations") do
-      self.class.__send__("#{name}_annotations")
-    end
+      define_method("#{name}_annotations") do
+        self.class.__send__("#{name}_annotations")
+      end
 
-    define_method("#{name}_of") do |method_name|
-      self.class.__send__("#{name}_of", method_name)
+      define_method("#{name}_of") do |method_name|
+        self.class.__send__("#{name}_of", method_name)
+      end
     end
   end
 end

data/lib/tins/ask_and_send.rb

@@ -1,17 +1,47 @@
 module Tins
+  # A module that provides methods to call private and protected methods on
+  # objects.
   module AskAndSend
+    # The ask_and_send method attempts to invoke a given method on the object
+    # if that method is available.
+    #
+    # @param method_name [ Symbol ] the name of the method to invoke
+    # @param args [ Array ] arguments to pass to the method
+    # @yield [ block ] optional block to pass to the method
+    # @return [ Object, nil ] the result of the method call or nil if the
+    # method doesn't exist
     def ask_and_send(method_name, *args, &block)
       if respond_to?(method_name)
         __send__(method_name, *args, &block)
       end
     end
 
+    # The ask_and_send! method attempts to invoke a private or protected method
+    # on the object.
+    #
+    # @param method_name [ Symbol ] the name of the method to call
+    # @param args [ Array ] arguments to pass to the method
+    # @param block [ Proc ] optional block to pass to the method
+    #
+    # @return [ Object, nil ] the result of the method call or nil if the
+    # method doesn't exist
     def ask_and_send!(method_name, *args, &block)
       if respond_to?(method_name, true)
         __send__(method_name, *args, &block)
       end
     end
 
+    # The ask_and_send_or_self method attempts to invoke the specified method
+    # on the object If the method exists, it calls the method with the provided
+    # arguments and block If the method does not exist, it returns the object
+    # itself
+    #
+    # @param method_name [ Symbol ] the name of the method to call
+    # @param args [ Array ] the arguments to pass to the method
+    # @param block [ Proc ] the block to pass to the method
+    #
+    # @return [ Object ] the result of the method call or self if the method
+    # doesn't exist
     def ask_and_send_or_self(method_name, *args, &block)
       if respond_to?(method_name)
         __send__(method_name, *args, &block)
@@ -20,6 +50,17 @@ module Tins
       end
     end
 
+    # The ask_and_send_or_self! method attempts to send a message to the object
+    # with the given method name and arguments. If the object responds to the
+    # method, it executes the method and returns the result. If the object does
+    # not respond to the method, it returns the object itself.
+    #
+    # @param method_name [ Symbol ] the name of the method to send
+    # @param args [ Array ] the arguments to pass to the method
+    # @param block [ Proc ] the block to pass to the method
+    #
+    # @return [ Object ] the result of the method call or the object itself if
+    # the method is not found
     def ask_and_send_or_self!(method_name, *args, &block)
       if respond_to?(method_name, true)
         __send__(method_name, *args, &block)

data/lib/tins/attempt.rb

@@ -1,4 +1,6 @@
 module Tins
+  # A module that provides functionality for attempting operations with error
+  # handling and retry logic.
   module Attempt
     # Attempts code in block *attempts* times, sleeping according to *sleep*
     # between attempts and catching the exception(s) in *exception_class*.
@@ -14,6 +16,7 @@ module Tins
     def attempt(opts = {}, &block)
       sleep           = nil
       exception_class = StandardError
+      prev_exception  = nil
       if Numeric === opts
         attempts = opts
       else
@@ -28,7 +31,7 @@ module Tins
       if exception_class.nil?
         begin
           count += 1
-          if block.call(count)
+          if block.call(count, prev_exception)
             return true
           elsif count < attempts
             sleep_duration(sleep, count)
@@ -38,10 +41,11 @@ module Tins
       else
         begin
           count += 1
-          block.call(count)
+          block.call(count, prev_exception)
           true
         rescue *exception_class
           if count < attempts
+            prev_exception = $!
             sleep_duration(sleep, count)
             retry
           end
@@ -61,6 +65,11 @@ module Tins
 
     private
 
+    # The sleep_duration method handles sleeping for a specified duration or
+    # based on a proc call.
+    #
+    # @param duration [ Numeric, Proc ] the duration to sleep or a proc that
+    # returns the duration
     def sleep_duration(duration, count)
       case duration
       when Numeric
@@ -70,6 +79,26 @@ module Tins
       end
     end
 
+    # Computes the base for exponential backoff that results in a specific
+    # total sleep duration.
+    #
+    # This method solves for the base `x` in the geometric series:
+    #   x^0 + x^1 + x^2 + ... + x^(attempts-1) = sleep
+    #
+    # The solution ensures that when using exponential delays with base `x`,
+    # the total time spent across all attempts equals approximately the
+    # specified sleep duration. This method of computation is used if a
+    # negative number of secondes was requested in the attempt method.
+    #
+    # @param sleep [Numeric] The total number of seconds to distribute across
+    # all attempts
+    # @param attempts [Integer] The number of attempts (must be > 2)
+    #
+    # @return [Float] The base for exponential backoff delays
+    # @raise [ArgumentError] If attempts <= 2, or if the sleep parameters are
+    # invalid
+    # @raise [ArgumentError] If the algorithm fails to converge after maximum
+    # iterations
     def compute_duration_base(sleep, attempts)
       x1, x2  = 1, sleep
       attempts <= sleep or raise ArgumentError,
@@ -96,6 +125,18 @@ module Tins
       result
     end
 
+    # The interpret_sleep method determines the sleep behavior for retry attempts.
+    #
+    # @param sleep [Numeric, Proc, nil] the sleep duration or proc to use
+    # between retries, nil if no sleep was requested
+    # @param attempts [Integer] the number of retry attempts
+    #
+    # @return [Proc, nil] a proc that calculates the sleep duration or nil if
+    # no sleep is needed
+    #
+    # @raise [ArgumentError] if a negative sleep value is provided with less
+    # than 3 attempts
+    # @raise [TypeError] if the sleep argument is not Numeric, Proc, or nil
     def interpret_sleep(sleep, attempts)
       case sleep
       when nil

data/lib/tins/bijection.rb

@@ -1,5 +1,12 @@
 module Tins
+  # A hash subclass that ensures bijection between keys and values
   class Bijection < Hash
+    # Creates a new Bijection instance with key-value pairs.
+    #
+    # @param pairs [Array] an array of key-value pairs to populate the
+    # bijection
+    #
+    # @return [Bijection] a new bijection populated with the provided pairs
     def self.[](*pairs)
       pairs.size % 2 == 0 or
         raise ArgumentError, "odd number of arguments for #{self}"
@@ -15,10 +22,20 @@ module Tins
       end
     end
 
+    # The initialize method sets up a new instance with an inverted bijection.
+    #
+    # @param inverted [ Bijection ] the inverted bijection object, defaults to
+    # a new Bijection instance
     def initialize(inverted = Bijection.new(self))
       @inverted = inverted
     end
 
+    # The fill method populates the object with content from a block if it is
+    # empty.
+    #
+    # @return [ self ] returns the object itself after filling or if it was not
+    # empty
+    # @yield [ self ] yields self to the block for population
     def fill
       if empty?
         yield self
@@ -27,6 +44,9 @@ module Tins
       self
     end
 
+    # The freeze method freezes the current object and its inverted attribute.
+    #
+    # @return [Object] the frozen object
     def freeze
       r = super
       unless @inverted.frozen?
@@ -35,12 +55,26 @@ module Tins
       r
     end
 
+    # The []= method assigns a value to a key in the hash and maintains an
+    # inverted index.
+    #
+    # @param key [ Object ] the key to assign
+    # @param value [ Object ] the value to assign
+    #
+    # @return [ Object ] the assigned value
+    #
+    # @note This method will not overwrite existing keys, it will return early
+    # if the key already exists.
     def []=(key, value)
       key?(key) and return
       super
       @inverted[value] = key
     end
 
+    # The inverted attribute returns the inverted state of the object.
+    # Creates a new Bijection instance filled with key-value pairs.
+    #
+    # @return [Bijection] a new bijection instance with the specified key-value pairs
     attr_reader :inverted
   end
 end

data/lib/tins/case_predicate.rb

@@ -1,5 +1,26 @@
 module Tins
+  # A module that provides a predicate method for checking if a value matches
+  # any of the given cases.
   module CasePredicate
+    # Checks if the object matches any of the given arguments using the ===
+    # operator.
+    #
+    # This method provides pattern matching functionality similar to Ruby's
+    # case/when statements, using the === operator for semantic equality
+    # checking.
+    #
+    # @example Basic type matching
+    #   "hello".case?(String, Integer)     # => String (matches first argument)
+    #   42.case?(String, Integer)          # => Integer (matches first argument)
+    #   nil.case?(String, Integer)         # => nil (no matches)
+    #
+    # @example Range and pattern matching
+    #   15.case?(1..10, 11..20, 21..30)    # => 11..20 (matches range)
+    #   "hello world".case?(/foo/, /hello/) # => /hello/ (matches regex)
+    #
+    # @param args [Array] the arguments to check against using === operator
+    # @return [Object, nil] the first matching argument, or nil if no match is
+    # found
     def case?(*args)
       args.find { |a| a === self }
     end

data/lib/tins/complete.rb

@@ -1,11 +1,27 @@
 require 'readline'
 
 module Tins
+  # A module that provides completion functionality for objects.
   module Complete
     module_function
 
     @@sync = Sync.new
 
+    # The complete method reads a line of input from the user with optional
+    # prompt and history support.
+    #
+    # @param prompt [ String ] the prompt string to display to the user
+    # @param add_hist [ Boolean ] whether to add the input to the command
+    # history
+    #
+    # @yield [ String ] the completion procedure to use for tab completion
+    #
+    # @return [ String ] the line of input entered by the user
+    #
+    # @example Prompt with easy tab completion
+    #   complete(prompt: 'Pick a ruby file! ') {
+    #     Dir['**/*.rb'].grep(/#{it}/)
+    #   }.then { '%u lines' % File.new(it).each_line.count }
     def complete(prompt: '', add_hist: false, &block)
       @@sync.synchronize do
         Readline.completion_proc = block

data/lib/tins/concern.rb

@@ -1,9 +1,49 @@
 module Tins
+  # A module concern implementation that supports dependency tracking, class
+  # method inclusion, and block execution hooks.
+  #
+  # This module provides a way to define reusable module functionality with
+  # automatic dependency management, class method injection, and lifecycle
+  # callbacks similar to ActiveSupport::Concern but with more control.
+  #
+  # @example Basic usage
+  #   module MyConcern
+  #     extend Tins::Concern
+  #
+  #     included do
+  #       attr_accessor :logger
+  #     end
+  #
+  #     def log(message)
+  #       logger&.info message
+  #     end
+  #
+  #     class_methods do
+  #       def my_class_method
+  #         # ...
+  #       end
+  #     end
+  #   end
+  #
+  #   class MyClass
+  #     include MyConcern
+  #   end
   module Concern
+    # Extends the base object with dependency tracking capabilities.
+    #
+    # This method initializes an instance variable on the base object to store
+    # dependency information.
+    #
+    # @param base [ Object ] the object being extended
     def self.extended(base)
       base.instance_variable_set("@_dependencies", [])
     end
 
+    # The append_features method includes dependencies and class methods in the
+    # base class.
+    #
+    # @param base [ Object ] the base class to include features in
+    # @return [ Boolean ] true if features were appended, false otherwise
     def append_features(base)
       if base.instance_variable_defined?("@_dependencies")
         base.instance_variable_get("@_dependencies") << self
@@ -19,12 +59,72 @@ module Tins
       end
     end
 
+    # Prepends the features of this module to the base class.
+    #
+    # This method handles the inclusion of dependencies and class methods when
+    # a module is included in a class. It manages dependency tracking and
+    # ensures proper extension of the base class with ClassMethods.
+    #
+    # @param base [Class] the class that includes this module
+    # @return [Boolean] true if the module was successfully prepended, false otherwise
+    def prepend_features(base)
+      if base.instance_variable_defined?("@_dependencies")
+        base.instance_variable_get("@_dependencies") << self
+        false
+      else
+        return false if base < self
+        @_dependencies.each { |dep| base.send(:include, dep) }
+        super
+        base.extend const_get("ClassMethods") if const_defined?("ClassMethods")
+        base.class_eval(&@_prepended_block) if instance_variable_defined?("@_prepended_block")
+        Thread.current[:tin_concern_args] = nil
+        true
+      end
+    end
+
+    # The included method is called when the module is included in a class or
+    # module.
+    #
+    # @param base [ Object ] the class or module that includes this module
+    # @param block [ Proc ] optional block to be executed when included
     def included(base = nil, &block)
       if base.nil?
+        instance_variable_defined?(:@_included_block) and
+          raise StandardError, "included block already defined"
         @_included_block = block
       else
         super
       end
     end
+
+    # The prepended method handles the setup of a block for prepend
+    # functionality or delegates to the superclass implementation
+    #
+    # @param base [ Object ] the base object to prepend to, or nil to set up a block
+    # @param block [ Proc ] the block to be used for prepend functionality
+    def prepended(base = nil, &block)
+      if base.nil?
+        instance_variable_defined?(:@_prepended_block) and
+          raise StandardError, "prepended block already defined"
+        @_prepended_block = block
+      else
+        super
+      end
+    end
+
+    # Defines a ClassMethods module for the current class and evaluates the
+    # given block within it.
+    #
+    # @param block [Proc] The block to be evaluated in the context of the
+    # ClassMethods module
+    # @return [Module] The ClassMethods module that was defined or retrieved
+    def class_methods(&block)
+      modul = const_get(:ClassMethods) if const_defined?(:ClassMethods, false)
+      unless modul
+        modul = Module.new
+        const_set(:ClassMethods, modul)
+      end
+      modul.module_eval(&block)
+    end
   end
 end