sleeping_king_studios-tools 1.2.1 → 1.3.0.rc.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6723d647d646ad1812b8e3ab3b290502d54bb39d8725e494f046291ff0fb6f6f
-  data.tar.gz: e87fd6269f7b9db3bf6c19b029d0757edc43c70cae8118cf3b9df2373bb2a39a
+  metadata.gz: ddf9748934072d1e7acf8ae748029ed8d616c46fd7d0a502499f0b54bc4e5d1b
+  data.tar.gz: bae72b5b57afe8404d45aab67ee59a5e8643b3656820e915c535b934016ee0d3
 SHA512:
-  metadata.gz: de56319af6a174d979e267a2de6589e4f129bee02e5fbcc47d89b011234a6e365c91bc336ae682247e812a98d0f735b594d655354ba89c1fd32f71dad983da7a
-  data.tar.gz: e690eb9b13e6125c784881024d1731695903873791647c1cba77164eaff5eb2190e1ab790b0e18ad6d7430052faee3b172eb8e71b821a719b2d5aa4826ff2b7b
+  metadata.gz: 6de4c073168e77a204afc0a1b4cc7e873619fbb9796df24177b7c2125be120df29e22034a690da73f1998822e10667d473bebfcdfb4adcd4da0a6dbea3f796c5
+  data.tar.gz: 999e795763737b1f79be6d0884f162cf436d116c7319cd6d66d4934e3bbb2048249bf4d7e9c632379d2d2e5aa01525bf0ddcc52318e5d146153af7971fa945e6

data/CHANGELOG.md

@@ -1,5 +1,104 @@
 # Changelog
 
+## 1.3.0
+
+### Tools
+
+Tools objects now define a circular `#toolbelt` reference.
+
+#### ArrayTools
+
+Added `ArrayTools#fetch`, which retrieves the value at the requested index or raises an `IndexError`.
+
+Deprecated methods with native equivalents:
+
+- Deprecated `#bisect` - use `Enumerable#partition` instead.
+- Deprecated `#count_values` - use `Enumerable#tally` instead.
+- Deprecated `#splice` - use `Array#[]=` with a range instead.
+
+#### Assertions
+
+Added the following methods to `Assertions`.
+
+- `#assert_exclusion`
+- `#assert_inclusion`
+- `#assert_inherits_from` (aliased as `#assert_subclass`)
+- `#validate_exclusion`
+- `#validate_inclusion`
+- `#validate_inherits_from` (aliased as `#validate_subclass`)
+
+Updated `Assertions#assert_instance_of` to accept a `Module` as the expected value.
+
+Assertions error messages now use `Messages`.
+
+- `Assertions#error_message_for` can be called with an unscoped key, e.g. `error_message_for(:blank)`.
+- Error messages can be overwritten by changing the messaging strategy for scope `'sleeping_king_studios.tools.assertions'`.
+
+#### CoreTools
+
+Updated `CoreTools` deprecations:
+
+- Now supports passing `deprecate(message, caller:)` to override displayed backtrace.
+- Initializing `CoreTools` with an invalid deprecation strategy now raises an `ArgumentError`.
+
+Deprecated `#require_each` method.
+
+#### HashTools
+
+Added `HashTools#fetch`, which retrieves the value at the requested key or raises a `KeyError`.
+
+#### Messages
+
+Added `Messages` tool, which allows generating user-readable messages.
+
+- Added `Messages::Registry` for defining scoped message strategies.
+- Added `Messages::Strategy` and subclasses `FileStrategy` and `HashStrategy`.
+
+#### ObjectTools
+
+Added `#[]` support to `ObjectTools#dig`, allowing access through indexed data structures.
+
+- Added `:indifferent_keys` option - if set, treats `String` and `Symbol` values as interchangeable when traversing a `Hash` using `ObjectTools#dig`.
+
+Added `ObjectTools#fetch`, which tries to find the requested value via the named method call or by calling `#[]`.
+
+Deprecated methods with native equivalents:
+
+- Deprecated `#eigenclass` - use `Object#singleton_class` instead.
+- Deprecated `#try` - use the safe access operator `&.` instead.
+
+#### StringTools
+
+Deprecated methods with native equivalents:
+
+- Deprecated `#chain` - use `Object#then {}` instead.
+
+Deprecated calling `#pluralize` with multiple arguments.
+
+### Toolbelt
+
+Implemented `Toolbelt.global`, a thread-safe singleton instance with default configuration.
+
+- Calling `Toolbelt.instance` now returns the singleton.
+
+Tools objects are now defined lazily.
+
+### Toolbox
+
+Added keyword support to `ConstantMap.new`.
+
+- The value returned by `ConstantMap#to_h` is now immutable.
+
+Corrected the scope of `Mixin#included` and `Mixin#prepended` to be `private`.
+
+#### Initializer
+
+Added `Toolbox::Initializer`, used for defining a one-time initialization for a library or project.
+
+### Undefined
+
+Added `SleepingKingStudios::Tools::Undefined`, used to represent undefined method parameters.
+
 ## 1.2.1
 
 Added support for Ruby 4.0.

data/README.md

@@ -11,7 +11,7 @@ A library of utility services and concerns to expand the functionality of core c
 
 ## About
 
-SleepingKingStudios::Tools is tested against MRI Ruby 3.1 through 3.4.
+SleepingKingStudios::Tools is tested against MRI Ruby 3.2 through 4.0.
 
 ### Documentation
 
@@ -30,3 +30,31 @@ The canonical repository for this gem is on [GitHub](https://github.com/sleeping
 ### Code of Conduct
 
 Please note that the `SleepingKingStudios::Tools` project is released with a [Contributor Code of Conduct](https://github.com/sleepingkingstudios/sleeping_king_studios-tools/blob/master/CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms.
+
+## Getting Started
+
+Add the gem to your `Gemfile` or `gemspec`:
+
+```ruby
+gem 'sleeping_king_studios-tools'
+```
+
+Require `SleepingKingStudios::Tools` in your code:
+
+```ruby
+require 'sleeping_king_studios/tools'
+```
+
+To ensure that [message definitions](./tools/messages) are loaded, call the `SleepingKingStudios::Tools` initializer:
+
+- In the [initializer](./initializers) for your project:
+
+  ```ruby
+  module Space
+    @initializer = SleepingKingStudios::Tools::Toolbox::Initializer.new do
+      SleepingKingStudios::Tools::Toolbox.initializer.call
+    end
+  end
+  ```
+
+- Or, in the entry points of your application (such as a `bin` script or `spec_helper.rb`).

data/lib/sleeping_king_studios/tools/array_tools.rb

@@ -4,7 +4,7 @@ require 'sleeping_king_studios/tools'
 
 module SleepingKingStudios::Tools
   # Tools for working with array-like enumerable objects.
-  class ArrayTools < SleepingKingStudios::Tools::Base
+  class ArrayTools < SleepingKingStudios::Tools::Base # rubocop:disable Metrics/ClassLength
     # Expected methods that an Array-like object should implement.
     ARRAY_METHODS = %i[[] count each].freeze
 
@@ -18,6 +18,7 @@ module SleepingKingStudios::Tools
         :count_values,
         :deep_dup,
         :deep_freeze,
+        :fetch,
         :humanize_list,
         :immutable?,
         :mutable?,
@@ -82,19 +83,19 @@ module SleepingKingStudios::Tools
     #   #=> [0, 2, 4, 6, 8]
     #   rejected
     #   #=> [1, 3, 5, 7, 9]
-    def bisect(ary)
+    #
+    # @deprecated v1.3.0 Use Enumerable#partition instead.
+    def bisect(ary, &)
+      toolbelt.core_tools.deprecate(
+        "#{self.class.name}#bisect",
+        message: 'Use Enumerable#partition instead.'
+      )
+
       require_array!(ary)
 
       raise ArgumentError, 'no block given' unless block_given?
 
-      selected = []
-      rejected = []
-
-      ary.each do |item|
-        (yield(item) ? selected : rejected) << item
-      end
-
-      [selected, rejected]
+      ary.each.partition(&)
     end
 
     # Counts the number of times each item or result appears in the object.
@@ -130,18 +131,21 @@ module SleepingKingStudios::Tools
     #   @example
     #     ArrayTools.count_values([1, 1, 1, 2, 2, 3]) { |i| i ** 2 }
     #     #=> { 1 => 3, 4 => 2, 9 => 1 }
-    def count_values(ary, &block)
-      require_array!(ary)
+    #
+    # @deprecated v1.3.0 Use Enumerable#tally instead.
+    def count_values(ary, &)
+      toolbelt.core_tools.deprecate(
+        "#{self.class.name}#count_values",
+        message: 'Use Enumerable#tally instead.'
+      )
 
-      ary.each.with_object({}) do |item, hsh|
-        value = block_given? ? block.call(item) : item
+      require_array!(ary)
 
-        hsh[value] = hsh.fetch(value, 0) + 1
-      end
+      (block_given? ? ary.map(&) : ary.to_a).tally
     end
     alias tally count_values
 
-    # Creates a deep copy of the object.
+    # Creates a deep copy of the array and its contents.
     #
     # Iterates over the array and returns a new Array with deep copies of each
     # array item.
@@ -171,7 +175,7 @@ module SleepingKingStudios::Tools
     def deep_dup(ary)
       require_array!(ary)
 
-      ary.map { |obj| ObjectTools.deep_dup obj }
+      ary.map { |obj| toolbelt.object_tools.deep_dup obj }
     end
 
     # Freezes the array and performs a deep freeze on each array item.
@@ -197,52 +201,110 @@ module SleepingKingStudios::Tools
 
       ary.freeze
 
-      ary.each { |obj| ObjectTools.deep_freeze obj }
+      ary.each { |obj| toolbelt.object_tools.deep_freeze obj }
     end
 
-    # Generates a human-readable string representation of the list items.
+    # @overload fetch(ary, index, default = nil)
+    #   Retrieves the value at the specified index.
     #
-    # Accepts a list of values and returns a human-readable string of the
-    # values, with the format based on the number of items.
+    #   If the value does not exist, returns the default value, or raises an
+    #   IndexError if there is no default value. If the object defines a native
+    #   #fetch method, delegates to the native implementation.
     #
-    # @param ary [Array<String>] the list of values to format. Will be
-    #   coerced to strings using #to_s.
-    # @param options [Hash] optional configuration hash.
-    # @option options [String] :last_separator the value to use to separate
-    #   the final pair of values. Defaults to " and " (note the leading and
-    #   trailing spaces). Will be combined with the :separator for lists of
-    #   length 3 or greater.
-    # @option options [String] :separator the value to use to separate pairs
-    #   of values before the last in lists of length 3 or greater. Defaults to
-    #   ", " (note the trailing space).
+    #   @param ary [Array] the array or array-like object.
+    #   @param index [Integer] the index to retrieve.
+    #   @param default [Object] the default value.
     #
-    # @return [String] the formatted string.
+    #   @return [Object] the value at the specified index.
     #
-    # @raise [ArgumentError] if the first argument is not an Array-like object.
+    #   @raise [IndexError] if the array does not have a value at that index
+    #     and there is no default value.
     #
-    # @example With Zero Items
-    #   ArrayTools.humanize_list([])
-    #   #=> ''
-    #
-    # @example With One Item
-    #   ArrayTools.humanize_list(['spam'])
-    #   #=> 'spam'
-    #
-    # @example With Two Items
-    #   ArrayTools.humanize_list(['spam', 'eggs'])
-    #   #=> 'spam and eggs'
-    #
-    # @example With Three Or More Items
-    #   ArrayTools.humanize_list(['spam', 'eggs', 'bacon', 'spam'])
-    #   #=> 'spam, eggs, bacon, and spam'
-    #
-    # @example With Three Or More Items And Options
-    #   ArrayTools.humanize_list(
-    #     ['spam', 'eggs', 'bacon', 'spam'],
-    #     :last_separator => ' or '
-    #   )
-    #   #=> 'spam, eggs, bacon, or spam'
-    def humanize_list(ary, **options, &)
+    # @overload fetch(ary, index, &default)
+    #   Retrieves the value at the specified index.
+    #
+    #   If the value does not exist, returns the value of the default block, or
+    #   raises an IndexError if there is no default block. If the object defines
+    #   a native #fetch method, delegates to the native implementation.
+    #
+    #   @param ary [Array] the array or array-like object.
+    #   @param index [Integer] the index to retrieve.
+    #
+    #   @yield generates the default value if there is no value at the index.
+    #
+    #   @yieldparam index [Integer] the requested index.
+    #
+    #   @yieldreturn [Object] the default value.
+    #
+    #   @return [Object] the value at the specified index.
+    #
+    #   @raise [IndexError] if the array does not have a value at that index
+    #     and there is no default value.
+    def fetch(ary, index, default = UNDEFINED, &block)
+      require_array!(ary)
+
+      if ary.respond_to?(:fetch)
+        return native_fetch(ary, index, default, &block)
+      end
+
+      size = ary.respond_to?(:size) ? ary.size : ary.count
+
+      return ary[index] if index < size && index >= -size
+
+      return block.call(index) if block_given?
+
+      return default unless default == UNDEFINED
+
+      raise IndexError,
+        "index #{index} outside of array bounds: -#{size}...#{size}"
+    end
+
+    # @overload def humanize_list(ary, **options, &)
+    #   Generates a human-readable string representation of the list items.
+    #
+    #   Accepts a list of values and returns a human-readable string of the
+    #   values, with the format based on the number of items.
+    #
+    #   @param ary [Array<String>] the list of values to format. Will be
+    #     coerced to strings using #to_s.
+    #   @param options [Hash] optional configuration hash.
+    #
+    #   @option options [String] :last_separator the value to use to separate
+    #     the final pair of values. Defaults to " and " (note the leading and
+    #     trailing spaces). Will be combined with the :separator for lists of
+    #     length 3 or greater.
+    #   @option options [String] :separator the value to use to separate pairs
+    #     of values before the last in lists of length 3 or greater. Defaults to
+    #     ", " (note the trailing space).
+    #
+    #   @return [String] the formatted string.
+    #
+    #   @raise [ArgumentError] if the first argument is not an Array-like
+    #     object.
+    #
+    #   @example With Zero Items
+    #     ArrayTools.humanize_list([])
+    #     #=> ''
+    #
+    #   @example With One Item
+    #     ArrayTools.humanize_list(['spam'])
+    #     #=> 'spam'
+    #
+    #   @example With Two Items
+    #     ArrayTools.humanize_list(['spam', 'eggs'])
+    #     #=> 'spam and eggs'
+    #
+    #   @example With Three Or More Items
+    #     ArrayTools.humanize_list(['spam', 'eggs', 'bacon', 'spam'])
+    #     #=> 'spam, eggs, bacon, and spam'
+    #
+    #   @example With Three Or More Items And Options
+    #     ArrayTools.humanize_list(
+    #       ['spam', 'eggs', 'bacon', 'spam'],
+    #       :last_separator => ' or '
+    #     )
+    #     #=> 'spam, eggs, bacon, or spam'
+    def humanize_list(ary, **, &)
       require_array!(ary)
 
       return '' if ary.empty?
@@ -253,7 +315,7 @@ module SleepingKingStudios::Tools
       return ary[0].to_s if size == 1
 
       separator, last_separator =
-        options_for_humanize_list(size:, **options)
+        options_for_humanize_list(size:, **)
 
       return "#{ary[0]}#{last_separator}#{ary[1]}" if size == 2
 
@@ -295,7 +357,9 @@ module SleepingKingStudios::Tools
 
       return false unless ary.frozen?
 
-      ary.each { |item| return false unless ObjectTools.immutable?(item) }
+      ary.each do |item|
+        return false unless toolbelt.object_tools.immutable?(item)
+      end
 
       true
     end
@@ -347,7 +411,14 @@ module SleepingKingStudios::Tools
     #   #=> ['crossbow']
     #   values
     #   #=> ['shortbow', 'longbow', 'arbalest', 'chu-ko-nu']
+    #
+    # @deprecated v1.3.0 Use Array#[]= with a range instead.
     def splice(ary, start, delete_count, *insert)
+      toolbelt.core_tools.deprecate(
+        "#{self.class.name}#splice",
+        message: 'Use Array#[]= with a range instead.'
+      )
+
       require_array!(ary)
 
       start  += ary.count if start.negative?
@@ -361,6 +432,12 @@ module SleepingKingStudios::Tools
 
     private
 
+    def native_fetch(ary, index, default, &)
+      return ary.fetch(index, &) if default == UNDEFINED
+
+      ary.fetch(index, default, &)
+    end
+
     def options_for_humanize_list(
       size:,
       last_separator: ' and ',

data/lib/sleeping_king_studios/tools/assertions/aggregator.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools/assertions'
+
+module SleepingKingStudios::Tools
+  # Utility for grouping multiple assertion statements.
+  #
+  # @example
+  #   rocket = Struct.new(:fuel, :launched).new(0.0, true)
+  #   aggregator = SleepingKingStudios::Tools::Assertions::Aggregator.new
+  #   aggregator.empty?
+  #   #=> true
+  #
+  #   aggregator.assert(message: 'is out of fuel') { rocket.fuel > 0 }
+  #   aggregator.assert(message: 'has already launched') { !rocket.launched }
+  #   aggregator.empty?
+  #   #=> false
+  #   aggregator.failure_message
+  #   #=> 'is out of fuel, has already launched'
+  class Assertions::Aggregator < Assertions
+    extend Forwardable
+
+    def initialize
+      super
+
+      @failures = []
+    end
+
+    # @!method <<(message)
+    #   Appends the message to the failure messages.
+    #
+    #   @param message [String] the message to append.
+    #
+    #   @return [Array] the updated failure messages.
+    #
+    #   @see Array#<<.
+
+    # @!method clear
+    #   Removes all items from the failure messages.
+    #
+    #   @return [Array] the empty failure messages.
+    #
+    #   @see Array#clear.
+
+    # @!method count
+    #   Returns a count of the failure message.
+    #
+    #   @return [Integer] the number of failure messages.
+    #
+    #   @see Array#count.
+
+    # @!method each
+    #   Iterates over the failure messages.
+    #
+    #   @overload each
+    #     Returns an enumerator that iterates over the failure messages.
+    #
+    #     @return [Enumerator] an enumerator over the messages.
+    #
+    #     @see Enumerable#each.
+    #
+    #   @overload each(&block)
+    #     Yields each failure message to the block.
+    #
+    #     @yieldparam message [String] the current failure message.
+    #
+    #     @see Enumerable#each.
+
+    # @!method empty?
+    #   Checks if there are any failure messages.
+    #
+    #   @return [true, false] true if there are no failure messages; otherwise
+    #     false.
+    #
+    #   @see Enumerable#empty?
+
+    # @!method size
+    #   Returns a count of the failure message.
+    #
+    #   @return [Integer] the number of failure messages.
+    #
+    #   @see Array#size.
+    def_delegators :@failures,
+      :<<,
+      :clear,
+      :count,
+      :each,
+      :empty?,
+      :size
+
+    # (see SleepingKingStudios::Tools::Assertions#assert_group)
+    def assert_group(error_class: AssertionError, message: nil, &assertions)
+      return super if message
+
+      raise ArgumentError, 'no block given' unless block_given?
+
+      assertions.call(self)
+    end
+    alias aggregate assert_group
+
+    # Generates a combined failure message from the configured messages.
+    #
+    # @return [String] the combined messages for each failed assertion.
+    #
+    # @example With an empty aggregator.
+    #   aggregator = SleepingKingStudios::Tools::Assertions::Aggregator.new
+    #
+    #   aggregator.failure_message
+    #   #=> ''
+    #
+    # @example With an aggregator with failure messages.
+    #   aggregator = SleepingKingStudios::Tools::Assertions::Aggregator.new
+    #   aggrgator << 'rocket is out of fuel'
+    #   aggrgator << 'rocket is not pointed toward space'
+    #
+    #   aggregator.failure_message
+    #   #=> 'rocket is out of fuel, rocket is not pointed toward space'
+    def failure_message
+      failures.join(', ')
+    end
+
+    private
+
+    attr_reader :failures
+
+    def handle_error(message:, **_)
+      failures << message
+
+      message
+    end
+  end
+end

data/lib/sleeping_king_studios/tools/assertions/messages_strategy.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools/assertions'
+
+module SleepingKingStudios::Tools
+  # Messages strategy for displaying assertions errors.
+  #
+  # Defines its own internal message templates, and automatically handles value
+  # name option (:as option) when generating messages.
+  class Assertions::MessagesStrategy < SleepingKingStudios::Tools::Messages::Strategies::HashStrategy
+    # rubocop:disable Layout/HashAlignment
+    ERROR_MESSAGES =
+      {
+        'blank' =>
+          'must be nil or empty',
+        'block' =>
+          'block returned a falsy value',
+        'boolean' =>
+          'must be true or false',
+        'class' =>
+          'is not a Class',
+        'class_or_module' =>
+          'is not a Class or Module',
+        'exclusion' =>
+          'is one of %<expected>s',
+        'exclusion_range' =>
+          'is within %<range_expr>s',
+        'inclusion' =>
+          'is not one of %<expected>s',
+        'inclusion_range' =>
+          'is outside %<range_expr>s',
+        'inherit_from' =>
+          'does not inherit from %<expected>s',
+        'instance_of' =>
+          'is not an instance of %<expected>s',
+        'instance_of_anonymous' =>
+          'is not an instance of %<expected>s (%<parent>s)',
+        'matches' =>
+          'does not match the expected value',
+        'matches_proc' =>
+          'does not match the Proc',
+        'matches_regexp' =>
+          'does not match the pattern %<pattern>s',
+        'name' =>
+          'is not a String or a Symbol',
+        'nil' =>
+          'must be nil',
+        'not_nil' =>
+          'must not be nil',
+        # @note: This value will be changed in a future version.
+        'presence' =>
+          "can't be blank"
+      }.freeze
+    # rubocop:enable Layout/HashAlignment
+
+    def initialize
+      templates =
+        ERROR_MESSAGES
+        .transform_keys do |key|
+          "sleeping_king_studios.tools.assertions.#{key}"
+        end
+        .freeze
+
+      super(templates)
+    end
+
+    private
+
+    def generate(template, as: nil, parameters: {}, **)
+      message = super
+
+      return message unless as
+
+      "#{as} #{message}"
+    end
+  end
+end