tins 1.61.0 → 1.62.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ba81a48e00f9a9ae7eaadaeeebc69b0b0eb6820308cf3540d4c6158f8f86f93
-  data.tar.gz: 40fc9c05a472b234c0601ddd0ba22c091bab1ae655a2fe4f73cdb1c88daa5042
+  metadata.gz: 10b0d776e1885f0202af59a976790f05b95819127acc39a51440ca3234922787
+  data.tar.gz: 756e1c2582fb33347ab1abf0e2db0964170e23de4ebfe1d4853aae45a2594195
 SHA512:
-  metadata.gz: 9f35bd33d3d9bce8952a18c2aa9852a936fb0dfa1e18c7bfc8942da63435fea10da153079817991cd333ab67099349763037d7f1ff1b34faf269cad95bc2d856
-  data.tar.gz: 1c6f77c57ceda3dc375a50d988418ea55c63048ee4f47adf8432ad1262f03d63664de5b8546b199761bbbaf4e0d0a56ae53b2e40280ec1653a2577388b9b2e0d
+  metadata.gz: d83cac4e43f7920378533ded76f233b1fae4f90d263ee1eb8e8d9d0aac200b1f48bced843eb78f0e711a40eea18cc6b3b41a016b157e461d21fa54f45e1c8620
+  data.tar.gz: 6abcf2a734c6f57f9c954c71a87c7031b20230971525f3a4f92284ab3b1c00f59fe69ed36fb3c239b7a503f19615700d9788e5264864cc4d2d6cdbe90645b293

data/CHANGES.md

@@ -1,5 +1,72 @@
 # Changes
 
+## 2026-11-06 v1.62.0
+
+### Features
+
+- Added `Tins::EnumJoined` module providing `#joined` for human-friendly
+  sentence-style joining of `Enumerable` objects.
+- Added `Tins::Duration#to_human` for generating human-readable duration
+  strings with configurable styles and connectors.
+- Added `Tins::Duration.parse_human` class method to parse human-readable
+  duration strings (inverse of `#to_human`).
+- Added `Tins::Duration.from_string` class method to create a `Duration`
+  instance from a parsed string.
+- `Tins::Duration.parse` now accepts an `Array` of template strings, trying
+  them in order until a match is found.
+- Added `Tins::Duration::HUMAN_CONNECTORS` constant with `:none`, `:spaces`,
+  and `:prose` presets.
+- Added `Tins::Duration::STYLE_DEFAULT_CONNECTOR` constant mapping styles to
+  default connector presets.
+
+### Fixes
+
+- `Tins::Duration.parse`: Fixed a bug where a literal mismatch raised a
+  `RuntimeError` instead of `Tins::Duration::ParserError`.
+- `Tins::Null`: Fixed documentation example to correctly show `user.name.to_s`
+  instead of `user.name`.
+
+### Improvements
+
+- `Tins::Duration`: Refactored parsing logic to extract `parse_template` as a
+  private method.
+- `Tins::Duration`: Updated `to_f` documentation to clarify that it returns the
+  magnitude (always non-negative) and that sign is tracked via `negative?`.
+- `Tins::Duration`: Changed `template:` default in `parse` to `nil` to support
+  multi-template detection.
+- `Tins::Duration`: Extracted connector resolution logic into a private
+  `ConnectorResolver` module.
+
+### Build & CI
+
+- Bumped development dependency `gem_hadar` to require version **2.21.0** or
+  later.
+
+### Testing
+
+- Added tests for `Tins::EnumJoined#joined` covering empty, single, multiple
+  elements, custom connectors, and type coercion.
+- Added tests for `Tins::Duration#to_human` covering styles, connectors, max
+  units, and negative durations.
+- Added tests for `Tins::Duration.parse_human` covering roundtrips, custom
+  connectors, and error cases.
+- Added tests for `Tins::Duration.from_string` covering default and custom
+  templates.
+- Added tests for `Tins::Duration.parse` with template arrays, including order
+  sensitivity and error handling.
+- Added tests for `Tins::Duration::ParserError` inheritance and specific
+  mismatch scenarios.
+
+### Documentation
+
+- `Tins::Attempt`: Rewrote documentation using YARD tags and added examples for
+  fixed sleep, exponential backoff, and return-value mode.
+- `Tins::EnumSqueeze`: Added module-level documentation explaining
+  `squeeze`/`squeeze!` semantics and usage examples.
+- `Tins::DslKit`: Fixed documentation examples for `Eigenclass`, `ClassMethod`,
+  `ThreadGlobal`, `Delegate`, `Scope`, `DynamicScope`, and `Deflect` to
+  accurately reflect API usage.
+
 ## 2026-10-11 v1.61.0
 
 *   `only_once`/`try_only_once` now accept a `touch:` option to automatically

data/lib/tins/attempt.rb

@@ -2,17 +2,55 @@ 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*.
+    # Executes the block up to a configured number of attempts, with
+    # optional sleeping between retries and exception-based success
+    # detection.
     #
-    # *sleep* is either a Proc returning a floating point number for duration
-    # as seconds or a Numeric >= 0 or < 0. In the former case this is the
-    # duration directly, in the latter case -*sleep* is the total number of
-    # seconds that is slept before giving up, and every attempt is retried
-    # after a exponentially increasing duration of seconds.
+    # When +:exception_class+ is set (default +StandardError+), the block
+    # succeeds if it returns without raising. When it is +nil+, the block's
+    # truthy return value determines success instead.
     #
-    # Iff *reraise* is true the caught exception is reraised after running out
-    # of attempts.
+    # @param opts [Hash, Numeric] Configuration hash, or a legacy
+    #   attempt count.
+    # @option opts [Integer] :attempts (1) Number of tries.
+    # @option opts [Class, Array<Class>, nil] :exception_class
+    #   (StandardError) Exception(s) to rescue. Pass +nil+ to use
+    #   return-value mode instead.
+    # @option opts [Numeric, Proc, nil] :sleep (nil) Sleep between
+    #   attempts. A non-negative Numeric is a fixed duration in seconds.
+    #   A negative Numeric is a total budget — each retry sleeps an
+    #   exponentially increasing fraction of that budget. Think of
+    #   `sleep: -10` as "retry for at most 10 seconds total".
+    #   A Proc receives the 1-based attempt count and returns the
+    #   duration in seconds.
+    # @option opts [true, Proc, Class] :reraise (nil) Behaviour when all
+    #   attempts are exhausted. +true+ re-raises the last exception.
+    #   A +Proc+ is called with the exception (does not re-raise).
+    #   A +Class+ raises that class with the original message.
+    #
+    # @yield [count, prev_exception]
+    # @yieldparam count [Integer] 1-based attempt number
+    # @yieldparam prev_exception [Exception, nil] Exception from the
+    #   previous attempt, or +nil+ on the first try
+    # @return [Boolean, nil] +true+ on success, +false+ on exhaustion,
+    #   +nil+ when attempts <= 0
+    # @raise [ArgumentError] If +:attempts+ is less than 1
+    # @raise [TypeError] If +:sleep+ is not Numeric, Proc, or nil
+    #
+    # @example Fixed sleep, re-raise on failure
+    #   attempt(attempts: 3, sleep: 0.5, reraise: true) do |n, prev|
+    #     flaky_api.call
+    #   end
+    #
+    # @example Exponential backoff within a 5-second budget
+    #   attempt(attempts: 5, sleep: -5) do |n, prev|
+    #     unstable_socket.read
+    #   end
+    #
+    # @example Return-value mode (no exception catching)
+    #   attempt(attempts: 10, exception_class: nil) do |n, _|
+    #     parse_line(buffer)
+    #   end
     def attempt(opts = {}, &block)
       sleep           = nil
       exception_class = StandardError

data/lib/tins/dslkit.rb

@@ -13,7 +13,7 @@ module Tins
   #
   # @example Using eigenclass alias
   #   class MyClass
-  #     include Tins::Eigenclass
+  #     extend Tins::Eigenclass
   #   end
   #
   #   puts MyClass.eigenclass  # => MyClass singleton class
@@ -33,7 +33,7 @@ module Tins
     # @return [Object] The result of the last expression in the block
     # @example Defining class methods using attr_accessor on a class
     #   class MyClass
-    #     include Tins::Eigenclass
+    #     extend Tins::Eigenclass
     #   end
     #
     #   MyClass.eigenclass_eval { attr_accessor :foo }
@@ -71,7 +71,7 @@ module Tins
   #
   # @example Using ClassMethod module to define class methods dynamically
   #   class MyClass
-  #     include Tins::ClassMethod
+  #     extend Tins::ClassMethod
   #   end
   #
   #   # Define class methods using the ClassMethod helpers
@@ -125,9 +125,10 @@ module Tins
 
   # Provides thread-safe global variable functionality for modules and classes.
   #
-  # This module enables the definition of thread-global variables that maintain
-  # their state per thread within a given module or class scope. These variables
-  # are initialized lazily and provide thread safety through mutex synchronization.
+  # This module enables the definition of global variables within a given
+  # module or class scope. Values are shared across all threads, and access
+  # is synchronized through a mutex for thread safety. Variables are
+  # initialized lazily on first access.
   #
   # @example Basic usage with module-level thread globals
   #   class MyClass
@@ -161,9 +162,10 @@ module Tins
     # Define a thread global variable named _name_ in this module/class. If the
     # value _value_ is given, it is used to initialize the variable.
     #
-    # Thread global variables maintain their state per thread within the scope
-    # of the module or class where they are defined. The initialization is lazy,
-    # meaning the default value or block is only executed when first accessed.
+    # The value is shared across all threads within the scope of the module
+    # or class where it is defined. Access is synchronized via a mutex. The
+    # initialization is lazy, meaning the default value or block is only
+    # executed when first accessed.
     #
     # @param name [Symbol, String] The name of the thread global variable to define
     # @param default_value [Object] The default value for the variable (optional)
@@ -731,19 +733,35 @@ module Tins
 
     private_constant :UNSET
 
-    # A method to easily delegate methods to an object, stored in an
-    # instance variable or returned by a method call.
+    # A method to easily delegate methods to an object stored in an
+    # instance variable, class variable, constant, or returned by a
+    # method call.
+    #
+    # @param method_name [Symbol] The method to delegate
+    # @param opts [Hash] Configuration options
+    # @option opts [String] :to The delegation target: an instance
+    #   variable ("@var"), class variable ("@@var"), constant
+    #   ("SomeClass"), or method name
+    # @option opts [Symbol] :as Alias for the delegated method
+    #   (defaults to +method_name+)
     #
-    # It's used like this:
+    # @example Delegate to an instance variable
     #   class A
-    #     delegate :method_here, :@obj, :method_there
+    #     extend Tins::Delegate
+    #     delegate :method_here, to: :@obj
     #   end
-    # or:
+    #
+    # @example Delegate with an alias
     #   class A
-    #     delegate :method_here, :method_call, :method_there
+    #     extend Tins::Delegate
+    #     delegate :method_here, to: :@obj, as: :method_there
     #   end
     #
-    # _other_method_name_ defaults to method_name, if it wasn't given.
+    # @example Delegate to a method call result
+    #   class A
+    #     extend Tins::Delegate
+    #     delegate :method_here, to: :current_target
+    #   end
     def delegate(method_name, opts = {})
       to = opts[:to] || UNSET
       as = opts[:as] || method_name
@@ -837,7 +855,7 @@ module Tins
   #
   # @example Basic usage with a custom parameterizable module
   #   module MyModule
-  #     include Tins::ParameterizedModule
+  #     extend Tins::ParameterizedModule
   #
   #     def self.parameterize(options = {})
   #       # Custom parameterization logic
@@ -933,31 +951,36 @@ module Tins
   # tracking nested contexts in multi-threaded applications.
   #
   # @example Basic stack operations
-  #   Scope.scope_push("context1")
-  #   Scope.scope_push("context2")
-  #   Scope.scope_top  # => "context2"
-  #   Scope.scope_pop  # => "context2"
-  #   Scope.scope_top  # => "context1"
+  #   class MyCtx
+  #     include Tins::Scope
+  #   end
+  #
+  #   ctx = MyCtx.new
+  #   ctx.scope_push("context1")
+  #   ctx.scope_push("context2")
+  #   ctx.scope_top  # => "context2"
+  #   ctx.scope_pop
+  #   ctx.scope_top  # => "context1"
   #
   # @example Block-based context management
-  #   Scope.scope_block("request_context") do
+  #   ctx.scope_block("request_context") do
   #     # Within this block, "request_context" is active
   #   end
   #   # Automatically cleaned up when block exits
   #
   # @example Nested scope blocks
-  #   Scope.scope_block("outer_context") do
-  #     Scope.scope_block("inner_context") do
-  #       Scope.scope_top  # => "inner_context"
+  #   ctx.scope_block("outer_context") do
+  #     ctx.scope_block("inner_context") do
+  #       ctx.scope_top  # => "inner_context"
   #     end
-  #     Scope.scope_top  # => "outer_context"
+  #     ctx.scope_top  # => "outer_context"
   #   end
-  #   Scope.scope_top  # => nil (empty stack)
+  #   ctx.scope_top  # => nil (empty stack)
   #
   # @example Multiple named scopes
-  #   Scope.scope_push("frame1", :database)
-  #   Scope.scope_push("frame2", :database)
-  #   Scope.scope_get(:database)  # => ["frame1", "frame2"]
+  #   ctx.scope_push("frame1", :database)
+  #   ctx.scope_push("frame2", :database)
+  #   ctx.scope_get(:database)  # => ["frame1", "frame2"]
   module Scope
     # Pushes a scope frame onto the top of the specified scope stack.
     #
@@ -1041,32 +1064,44 @@ module Tins
   # template engines, and context-sensitive applications.
   #
   # @example Basic dynamic scoping
-  #   include Tins::DynamicScope
+  #   class MyDsl
+  #     include Tins::DynamicScope
   #
-  #   dynamic_scope do
-  #     self.foo = "value"  # Sets variable in current scope
-  #     puts foo           # => "value" (reads from current scope)
+  #     def run
+  #       dynamic_scope do
+  #         self.foo = "value"  # Sets variable in current scope
+  #         puts foo           # => "value" (reads from current scope)
+  #       end
+  #     end
   #   end
   #
   # @example Nested scopes with variable shadowing
-  #   include Tins::DynamicScope
-  #
-  #   dynamic_scope do
-  #     self.foo = "outer"
-  #     dynamic_scope do
-  #       self.foo = "inner"  # Shadows outer foo only in inner scope
-  #       puts foo           # => "inner"
+  #   class MyDsl
+  #     include Tins::DynamicScope
+  #
+  #     def run
+  #       dynamic_scope do
+  #         self.foo = "outer"
+  #         dynamic_scope do
+  #           self.foo = "inner"  # Shadows in inner scope
+  #           puts foo           # => "inner"
+  #         end
+  #         puts foo             # => "outer" (restored)
+  #       end
   #     end
-  #     puts foo             # => "outer" (restored from outer scope)
   #   end
   #
   # @example Variable existence checking
-  #   include Tins::DynamicScope
-  #
-  #   dynamic_scope do
-  #     assert_equal false, dynamic_defined?(:foo)
-  #     self.foo = "value"
-  #     assert_equal true, dynamic_defined?(:foo)
+  #   class MyDsl
+  #     include Tins::DynamicScope
+  #
+  #     def run
+  #       dynamic_scope do
+  #         raise unless dynamic_defined?(:foo) == false
+  #         self.foo = "value"
+  #         raise unless dynamic_defined?(:foo) == true
+  #       end
+  #     end
   #   end
   module DynamicScope
     # A specialized Hash subclass for dynamic scope contexts.
@@ -1179,18 +1214,22 @@ end
 #
 # @example Method deflection
 #   class Calculator
+#     include Tins::Deflect
+#
 #     def add(a, b)
 #       a + b
 #     end
 #   end
 #
 #   calc = Calculator.new
-#   Tins::Deflect.deflect(Calculator, :add) do |obj, method, *args|
-#     # Custom behavior for add method
+#   deflector = Tins::Deflect::Deflector.new do |obj, meth, *args|
 #     args.sum
 #   end
 #
-#   calc.add(1, 2, 3)  # => 6 (sum instead of addition)
+#   calc.deflect(Calculator, :add, deflector) do
+#     calc.add(1, 2, 3)  # => 6 (sum instead of addition)
+#   end
+#   calc.add(1, 2)       # => 3 (deflection stopped)
 #
 # @see Tins::DSLAccessor
 # @see Tins::Constant