tins 1.38.0 → 1.51.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26f2a6faf004d28bc511820eb58835ba4b555481d38b12839b264fde8664b321
-  data.tar.gz: 394319369bf23b6afee56aebfe70ebdebe9d4d05ff77181338a754f667921266
+  metadata.gz: '0842c03ef937e88e3983fe986604f369f741c783d5aeb1f73a27d50f98512265'
+  data.tar.gz: aeaf30f783e232586deb4b60017623539d37973a035331050c5d4c75c9af1f72
 SHA512:
-  metadata.gz: 6491996c174a13ec0a4b1cbd8c2437e7f7becca98965962a0aa446e7a7bd50f87ef8ebef4ba61dc0c48b38a97a0009ee1b6411a414c42ca53903f97a9e025861
-  data.tar.gz: cc785591e2c3efe72b0b70585dd30001bf5d4e6d7ff6b8b1b88c023c7be85bc6cb1ca7262e9b3ace3a009f4eac39ca2b9cf62dea73858bd0dd570292b583c62d
+  metadata.gz: fc76519aa6e09ff9a9e8094712070f71be2f34540a4001af2f6f07c5de357ac8642230828d543ffa53219936bf877db88e02e6dfb3a6f713e312b236b45e3d2a
+  data.tar.gz: 9e65ecc2199824d5efafb4502c9c5bef6322c5e9cad8f9f72504bb0571d09b15251e539db7b6336cad0af161e382bb2bf473fcaf720d2f146a6dba3b2757f84f

data/CHANGES.md

@@ -1,5 +1,164 @@
 # Changes
 
+## 2025-12-20 v1.51.0
+
+- Added `readline` as a runtime dependency in both `Rakefile` and
+  `tins.gemspec`
+- The `readline` dependency version is set to `>= 0` in `tins.gemspec`
+- The `readline` dependency is added to the `GemHadar` block in `Rakefile`
+
+## 2025-12-19 v1.50.0
+
+- Updated `gem_hadar` development dependency version to **2.10**
+- Added `ruby:4.0-rc-alpine` image to the `images` section in `.all_images.yml`
+
+## 2025-12-18 v1.49.0
+
+- Updated `bundle update` command to `bundle update --all` in `.all_images.yml`
+  to ensure all dependencies are updated recursively
+- Added support for IEC binary prefixes with new `PREFIX_IEC_UC` constant and
+  updated `prefixes` method to handle `:iec_uc` and `:iec_uppercase`
+  identifiers
+- Added corresponding test cases for IEC prefix mapping
+- Added `:si_greek` alias for fractional prefixes (`m`, `µ`, `n`, etc.) in `PREFIX_F`
+- Added `:si_uppercase` alias for SI uppercase prefixes (`K`, `M`, `G`, etc.) in `PREFIX_SI_UC`
+- Updated `PREFIX_SI_UC` comment to clarify these are based on **1000**-step increments, not 1024
+- Enhanced `prefixes` method to support new aliases while maintaining backward compatibility
+- Added comprehensive tests for new aliases in `Tins::UnitTest`
+- Updated `s.rubygems_version` from **3.7.2** to **4.0.2** in gemspec
+
+## 2025-12-05 v1.48.0
+
+- Added `Tins::Token.analyze` class method to calculate bit strength
+- Moved bit calculation logic from `initialize` to `analyze` method for reuse
+- Implemented bit strength calculation using formula: `length ×
+  log₂(alphabet_size)`
+- Added comprehensive tests for the `analyze` method with various alphabets
+- Support both token string and length-based analysis
+- Implemented proper error handling for required parameters
+- Updated `initialize` method to use the new `analyze` method
+- Test cases verify bit strength for **BASE16**, **BASE64**, and **BASE32**
+  alphabets
+- Method returns integer bit strength for cryptographic token analysis
+
+## 2025-11-14 v1.47.0
+
+- Tins::GO
+    - Renamed `EnumerableExtension` module to `ArrayExtension` throughout the
+      codebase
+    - Updated method calls from `<<` to `push` for consistency with
+      `ArrayExtension`
+    - Modified `to_a` method implementation to return `@arguments` directly
+    - Updated test assertions to expect `ArrayExtension` instead of
+      `EnumerableExtension`
+    - Changed documentation comments to reflect the new `ArrayExtension` name
+    - Updated type checking from `EnumerableExtension` to `ArrayExtension` in
+      conditional logic
+
+## 2025-11-10 v1.46.0
+
+- Updated `s.rubygems_version` from **3.6.9** to **3.7.2** in gemspec
+- In Tins::GO
+    - Extended string defaults with `EnumerableExtension` transformation
+    - Modified `v.transform_values!` to check and extend strings that aren't already `EnumerableExtension`
+    - Applied `w << w` to properly initialize the extension on default strings
+    - Updated tests to verify `EnumerableExtension` instances for both `v` and `w` options
+    - Set default value for `?w` option to **'baz'** in test cases
+    - Maintained backward compatibility while normalizing string handling
+    - Ensured consistent behavior between ARGV strings and default strings
+
+## 2025-10-16 v1.45.0
+
+- Added `patch` alias for `build` and `build=` methods to align with SemVer terminology
+- Updated `LEVELS` mapping to support `:patch` as alias for `:build` index
+- Added `patch` and `patch=` aliases using the `alias` method
+- Added tests for `patch` getter and setter functionality
+- Updated `gem_hadar` development dependency from version **2.5** to **2.8**
+- Added `openssl-dev` to Docker build dependencies
+- Added `github_workflows` configuration to `Rakefile` for `static.yml` workflow
+- Removed `.byebug_history` from `.gitignore` file
+- Removed `.byebug_history` from ignore list in `Rakefile`
+- Removed duplicate `mize` entry from code indexer configuration
+
+## 2025-09-13 v1.44.1
+
+- Updated documentation link in README.md to point to GitHub.io instead of
+  RubyDoc.info
+- Added graceful handling for missing `gem_hadar/simplecov` gem by wrapping
+  require and start in begin/rescue block to catch `LoadError`
+- Modified gem packaging to include all files in `.github` and `.contexts` directories using `FileList` for dynamic inclusion
+- Created `static.yml` file
+
+## 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
+  support for default blocks and dynamic block assignment
+- Removed support for Ruby versions **3.1** and **3.0** from image definitions
+
+## 2025-08-19 v1.42.0
+
+- Improved core class extension safety by using `respond_to?` checks to avoid
+  overriding existing methods such as `deep_dup`, `camelize`, and `underscore`
+- Simplified GitHub directory ignore patterns in `Rakefile` by removing
+  recursive glob pattern for `.github` directory and directly specifying it as
+  a single entry
+- Added documentation context files and YARD cheatsheet, including `.contexts/`
+  directory with code comment examples and updated `Rakefile` and
+  `tins.gemspec` to include context files and `context_spook` dependency
+
+## 2025-08-18 v1.41.0
+
+- Added new `named_placeholders_interpolate` method for template substitution
+- Method supports both static and dynamic default values via Proc
+- Maintains backward compatibility with existing `named_placeholders_assign` method
+- Includes comprehensive tests for all functionality and error handling
+- Uses `named_placeholders_assign` internally for consistent implementation
+
+## 2025-08-18 v1.40.0
+
+- Added `Tins::StringNamedPlaceholders` module with `named_placeholders` and
+  `named_placeholders_assign` methods for string template substitution
+- Implemented support for both static and dynamic default values using Proc
+  objects
+- Extended `String` class with `tins/xt/string` to include the new named
+  placeholders functionality
+- Enhanced test coverage with comprehensive tests for all named placeholders
+  functionality including error handling and duplicate placeholder management
+- Replaced manual SimpleCov setup with `GemHadar::SimpleCov.start` in test
+  helper
+
+## 2025-07-30 v1.39.1
+
+- Updated `gem_hadar` development dependency to version **1.22**
+- Bumped version from '1.39.0' to '1.39.1' in lib/tins/version.rb
+- Updated `s.version` in tins.gemspec from "1.39.0" to "1.39.1"
+- Updated stub version in tins.gemspec from **1.39.0** to **1.39.1**
+
+## 2025-07-30 v1.39.0
+
+- Updated `VERSION` constant in `lib/tins/version.rb` from **1.38.0** to **1.39.0**
+- Updated gem stub and version in `tins.gemspec`
+- Updated `s.rubygems_version` from **3.6.2** to **3.6.9**
+- Updated `s.add_development_dependency :gem_hadar` from ~> **1.19** to ~> **1.21**
+- Added support for thread naming in `Limited` class
+  - Added `name` parameter to `Limited#initialize`
+  - Set `@name` attribute when provided
+  - Set executor name with `@name` if available
+  - Updated tests to use named threads
+- Removed `binary` option from discover block in `.utilsrc`
+
 ## 2025-01-04 v1.38.0
 
 * Improved Tins::Limited concurrency handling:

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: [GitHub.io](https://flori.github.io/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,28 +3,38 @@
 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',
-    '.utilsrc', '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'
 
-  required_ruby_version  '>= 2.0'
+  github_workflows(
+    'static.yml' => {}
+  )
+
+  required_ruby_version  '>= 3.1'
+
+  dependency 'sync'
+  dependency 'bigdecimal'
+  dependency 'readline'
+  dependency 'mize',     '~> 0.6'
   development_dependency 'all_images'
   development_dependency 'debug'
-  development_dependency 'term-ansicolor'
-  development_dependency 'test-unit', '~>3.1'
   development_dependency 'simplecov'
-  dependency 'sync'
-  dependency 'bigdecimal'
+  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

@@ -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)