tins 1.43.0 → 1.44.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb6123d834dff1c32f3797c66fe9caf261b6f8463d29bf388f1d180da05e7157
-  data.tar.gz: 05b4687013b1842153c9dc96974bd000e59523cc2fefb26ed31e09d855971235
+  metadata.gz: 85b86d026f46e89213c6a4716ccd6296b4a8990b2fcd20ac8aa12a227c2f7a9a
+  data.tar.gz: b85c6e3f69fa911e10bb801fca3197949877bc6908bd565167c5dbb67c6d8248
 SHA512:
-  metadata.gz: 0eac79c5130dd92ddb9de65604b447eb6a271d0d94aecdebea60a78f163a073fc88161e0f43b0971c8e0e12f704e58ceae924c6b623e5eca714089a27de51041
-  data.tar.gz: 6c951446395225c9b03785f8aa8e44f5bfc6cf20cadd01346b02cfbc1c8e88a44aae997245c992df8867878f3d9ed8962d4109bb74479b227ce656f958eea840
+  metadata.gz: cb41548efe7a7c5628c225c89fe81417081a7aff6f5760a7ac21d5490731468488a25d0d795b4a932ebe516caf3d0d4722f2f645b674454b8b014791b44ecf88
+  data.tar.gz: 50eb96f4b5a54a4e38d0282ac926752c792acf8a7d09e61bb12eaad725e7f17bcd7195043f69a9c5d59a23b77d99a0461012474dbb6564c7e4b87ad40e0d4c0c

data/.contexts/code_comment.rb

@@ -5,22 +5,19 @@ context do
     end
   end
 
-  namespace "tests" do
-    Dir['tests/**/*.rb'].each do |filename|
-      file filename, tags: 'test'
-    end
-  end
-
 
   file 'README.md', tags: 'documentation'
 
   file '.contexts/yard.md', tags: [ 'yard', 'cheatsheet' ]
 
-  meta guidelins: <<~EOT
+  meta guidelines: <<~EOT
     # Guidelines for creating YARD documentation
 
     - Look into the file, with tags yard and cheatsheet for how comment ruby
       constructs.
-    - In comments above initialize methods never omit @return
+    - In comments above initialize methods **ALWAYS** omit @return.
+    - **NEVER** output @return [ void ] in comments of any method, because
+      in Ruby every method returns something. If you don't know or if the
+      method is just called because its side effect just omit the @return.
   EOT
 end

data/.contexts/lib.rb

@@ -20,7 +20,5 @@ context do
   file 'README.md', tags: 'documentation'
 
   meta ruby: RUBY_DESCRIPTION
-
-  meta code_coverage: json('coverage/coverage_context.json')
 end
 

data/CHANGES.md

@@ -1,5 +1,17 @@
 # Changes
 
+## 2025-09-12 v1.44.0
+
+### Major Changes
+
+- **Ruby Version Requirement**: Updated minimum Ruby version requirement to 3.1
+- **Dependency Modernization**: Replaced deprecated `Tins::Memoize` module
+  implementation with `mize` gem for memoization functionality
+- **Documentation Overhaul**: Comprehensive YARD documentation added across all
+  modules with examples and parameter descriptions
+- **README Enhancement**: Improved README.md with better documentation,
+  examples, and usage instructions
+
 ## 2025-09-05 v1.43.0
 
 - Added new `dsl_lazy_accessor` method that creates lazy-loaded accessors with

data/README.md

@@ -2,18 +2,170 @@
 
 ## Description
 
-Non yet.
+A collection of useful Ruby utilities that extend the standard library with
+practical conveniences. Tins provides lightweight, dependency-free tools for
+common programming tasks.
 
-## Badges
+## Documentation
 
-[![Code Climate](https://codeclimate.com/github/flori/tins.png)](https://codeclimate.com/github/flori/tins)
+Complete API documentation is available at: [RubyDoc.info](https://rubydoc.info/gems/tins)
 
-[![Code Coverage](https://codeclimate.com/github/flori/tins/coverage.png)](https://codeclimate.com/github/flori/tins)
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'tins'
+```
+
+Or:
+
+```ruby
+gem 'tins', require 'tins/xt'
+```
+
+to automatically extend some core classes with useful methods.
+
+And then execute:
+
+ $ bundle install
+
+Or install it yourself as:
+
+ $ gem install tins
+
+## Usage
+
+```ruby
+# Load all utilities
+
+require 'tins'
+
+# Load all utilities and extends core classes with useful methods
+require 'tins/xt'
+```
+## Some Usage Examples
+
+### Duration Handling
+
+```ruby
+require 'tins/duration'
+
+duration = Tins::Duration.new(9000)
+puts duration.to_s # "02:30:00"
+puts duration.to_i # 9000 (seconds)
+
+# Parse durations from strings
+Tins::Duration.parse('2h 30m', template: '%hh %mm') # 9000 (seconds)
+```
+
+### Unit Conversion
+
+```ruby
+require 'tins/unit'
+
+bytes = Tins::Unit.parse('1.5 GB', unit: ?B).to_i # => 1610612736
+puts Tins::Unit.format(bytes, unit: 'B') # "1.500000 GB"
+```
+
+### Secure File Writing
+
+```ruby
+require 'tins/xt/secure_write'
+
+# Write files safely (atomic operation)
+File.secure_write('config.json', '{"key": "value"}')
+```
+
+### Time Freezing for Testing
+
+```ruby
+require 'tins/xt/time_freezer'
+
+# Freeze time during testing
+Tins::TimeFreezer.freeze(Time.new('2011-12-13 14:15:16')) do
+  puts Time.now # Always returns the frozen time
+end
+```
+
+### Building blocks for DSLs
+
+```ruby
+class Foo
+  include Tins::DynamicScope
+
+  def let(bindings = {})
+    dynamic_scope do
+      bindings.each { |name, value| send("#{name}=", value) }
+      yield
+    end
+  end
+
+  def twice(x)
+    2 * x
+  end
+
+  def test
+    let x: 1, y: twice(1) do
+      let z: twice(x) do
+        "#{x} * #{y} == #{z} # => #{x * y == twice(x)}"
+      end
+    end
+  end
+end
+
+Foo.new.test # "1 * 2 == 2 # => true"
+```
+
+### Core Class Extensions (xt)
+
+When you require `tins/xt`, some useful methods are added to core classes:
+
+```ruby
+default_options = {
+  format: :json,
+  timeout: 30,
+  retries: 3
+}
+
+user_options = { timeout: 60 }
+options = user_options | default_options
+# => { format: :json, timeout: 60, retries: 3 }
+
+'1.10.3'.version < '1.9.2'.version # => false
+
+add_one         = -> x { x + 1 }
+multiply_by_two = -> x { x * 2 }
+composed        = multiply_by_two * add_one
+composed.(5) # => 12
+
+# For Testing
+>> o = Object.new
+>> o.puts # => private method, NoMethodError
+>> o = o.expose
+>> o.puts "hello"
+hello
+```
+
+### Hash Symbolization
+
+```ruby
+require 'tins/hash_symbolize_keys_recursive'
+
+hash = {
+  'name' => 'John',
+  'age' => 30,
+  'address' => {
+    'street' => '123 Main St'
+  }
+}
+hash.symbolize_keys_recursive! # Converts all keys to symbols recursively
+```
 
 ## Author
 
-Florian Frank mailto:flori@ping.de
+[Florian Frank](mailto:flori@ping.de)
 
 ## License
 
-This software is licensed under the MIT (Expat) license.
+[MIT License](./LICENSE)

data/Rakefile

@@ -3,30 +3,33 @@
 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', '.yardoc'
-  package_ignore '.all_images.yml', '.tool-versions', '.gitignore', 'VERSION',
-    '.utilsrc', 'TODO', '.github', '.contexts'
+  doc_code_files    files.grep(%r(\Alib/))
+  ignore            '.*.sw[pon]', 'pkg', 'Gemfile.lock', '.rvmrc', 'coverage',
+    '.rbx', '.AppleDouble', '.DS_Store', 'tags', 'cscope.out', '.bundle',
+    '.byebug_history', '.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'
 
-  required_ruby_version  '>= 2.0'
+  required_ruby_version  '>= 3.1'
 
   dependency 'sync'
   dependency 'bigdecimal'
+  dependency 'mize',     '~> 0.6'
   development_dependency 'all_images'
-  development_dependency 'context_spook', '~> 0.2'
   development_dependency 'debug'
   development_dependency 'simplecov'
   development_dependency 'term-ansicolor'
-  development_dependency 'test-unit', '~> 3.1'
+  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

@@ -6,7 +6,6 @@ require 'time'
 
 class Mail
   extend Tins::DSLAccessor
-  include Tins::InstanceExec
   include Tins::MethodMissingDelegator::DelegatorModule
   include Tins::BlockSelf
 

data/examples/turing.rb

@@ -307,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*.
@@ -63,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
@@ -72,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,
@@ -98,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