sleeping_king_studios-tools 1.0.2 → 1.1.0.rc.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00a0525024c0fc1f2999486b96860169b8d8d09921d5fc289c53f2ee7960a796
-  data.tar.gz: '0788cece6dd1fa8ea4eb88f2bdd047f1f4804fbf610b4c4312badd1dcf7e8800'
+  metadata.gz: 8e06daa0cd40dd75a70bd47807132708527dbee294dc0abef34d870180ca3e66
+  data.tar.gz: 4ee981bc8dd164c52d399cbf73f14b07b2ccc027759e894a12502b3d7f7347fc
 SHA512:
-  metadata.gz: a54d291f7f55d911b732c2be690f51e8d33931ee353ba3504ccf68c726a2398a46dd059ae3eeb9d1253619f6e704ab557af75cc4a3900c326451afb696afbcb6
-  data.tar.gz: 784980ce5bdb0e5266e14ac5c2e6c3747aaca88ba085a7ee1983bfdb4b625a483c8e266f688e41e6d7c4e624796661253d64d93232975c84fceb64a2d7ad3c51
+  metadata.gz: 8be13ff1e4b825a1f449d0b4f073336a3b86b9616f2abd2dd196eb33f5d169ab7e1bf7611a036794a1b4991a363a5b438c1145aec6a741cea4a9fec5481465ca
+  data.tar.gz: 717bbc4c705590b75786933480570c7dd55b792a17616888bc10c4eb459bb99b7c78b2d285dba83125774cf2a40beca54151eada287dbfc69ccbf074f666170c

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+### 1.1.0
+
+Files in the `Toolbox` are now autoloaded.
+
+#### Tools
+
+Implemented `SleepingKingStudios::Tools::Assertions` with the following methods:
+
+- `#assert`
+- `#assert_boolean`
+- `#assert_class`
+- `#assert_instance_of`
+- `#assert_matches`
+- `#assert_name`
+
+Each method raises an exception if its condition is not met. `Assertions` also defines equivalent `#validate` methods, which always raise an `ArgumentError`.
+
+Added :deprecation_caller_depth option to CoreTools. When calling #deprecate with the default strategy of 'warn', will print the specified number of lines from the caller. The default value is 3.
+
+#### Toolbelt
+
+- Added `#assertions` to Toolbelt.
+
+#### Toolbox
+
+Implemented `SleepingKingStudios::Tools::Toolbox::Subclass`, which implements partial application for constructor parameters.
+
 ### 1.0.2
 
 Updated gem metadata.

data/README.md

@@ -4,7 +4,7 @@ A library of utility services and concerns to expand the functionality of core c
 
 ## About
 
-SleepingKingStudios::Tools is tested against MRI Ruby 2.5 through 3.0.
+SleepingKingStudios::Tools is tested against MRI Ruby 2.6 through 3.1.
 
 ### Documentation
 
@@ -30,18 +30,20 @@ Please note that the `SleepingKingStudios::Tools` project is released with a [Co
 
 The tools can be accessed in a convenient form using the Toolbelt class.
 
-    require 'sleeping_king_studios/tools'
+```ruby
+require 'sleeping_king_studios/tools'
 
-    tools = ::SleepingKingStudios::Tools::Toolbelt.instance
+tools = ::SleepingKingStudios::Tools::Toolbelt.instance
 
-    tools.array.humanize_list 'one', 'two', 'three'
-    #=> calls ArrayTools#humanize_list
+tools.ary.humanize_list 'one', 'two', 'three'
+#=> calls ArrayTools#humanize_list
 
-    tools.core.deprecate 'my_method'
-    #=> calls CoreTools#deprecate
+tools.core.deprecate 'my_method'
+#=> calls CoreTools#deprecate
 
-    tools.string.underscore 'MyModuleName'
-    #=> calls StringTools#underscore
+tools.str.underscore 'MyModuleName'
+#=> calls StringTools#underscore
+```
 
 ### Array Tools
 
@@ -181,6 +183,256 @@ Accepts an array, a start value, a number of items to delete, and zero or more i
     values
     #=> ['shortbow', 'longbow', 'arbalest', 'chu-ko-nu']
 
+### Assertions
+
+Tools for validating the current application state.
+
+#### `#assert`
+
+Raises an exception unless the given block returns a truthy value.
+
+```ruby
+Assertions.assert { true == false }
+#=> raises an AssertionError with message 'block returned a falsy value'
+
+Assertions.assert { true == true }
+#=> does not raise an exception
+```
+
+It accepts the following options:
+
+- `error_class:` The class of exception to raise. Defaults to `SleepingKingStudios::Tools::Assertions::AssertionError`.
+- `message`: The error message to display.
+
+#### `#assert_boolean`
+
+Raises an exception unless the given value is either `true` or `false`.
+
+```ruby
+Assertions.assert_boolean(nil)
+#=> raises an AssertionError with message 'value must be true or false'
+
+Assertions.assert_boolean(Object.new)
+#=> raises an AssertionError with message 'value must be true or false'
+
+Assertions.assert_boolean(false)
+#=> does not raise an exception
+
+Assertions.assert_boolean(true)
+#=> does not raise an exception
+```
+
+It accepts the following options:
+
+- `as:` A short descriptor of the given value. Defaults to `"value"`.
+- `error_class:` The class of exception to raise. Defaults to `SleepingKingStudios::Tools::Assertions::AssertionError`.
+- `message`: The error message to display.
+
+#### `#assert_class`
+
+Raises an exception unless the given value is a Class.
+
+```ruby
+Assertions.assert_class(Object.new)
+#=> raises an AssertionError with message 'value is not a class'
+
+Assertions.assert_class(String)
+#=> does not raise an exception
+```
+
+It accepts the following options:
+
+- `as:` A short descriptor of the given value. Defaults to `"value"`.
+- `error_class:` The class of exception to raise. Defaults to `SleepingKingStudios::Tools::Assertions::AssertionError`.
+- `message`: The error message to display.
+
+#### `#assert_instance_of`
+
+Raises an exception unless the given value is an instance of the expected Class or Module.
+
+```ruby
+Assertions.assert_instance_of(:foo, expected: String)
+#=> raises an AssertionError with message 'value is not an instance of String'
+
+Assertions.assert_instance_of('foo', expected: String)
+#=> does not raise an exception
+```
+
+It accepts the following options:
+
+- `as:` A short descriptor of the given value. Defaults to `"value"`.
+- `error_class:` The class of exception to raise. Defaults to `SleepingKingStudios::Tools::Assertions::AssertionError`.
+- `message`: The error message to display.
+- `optional`: If true, accepts `nil` values as well as instances of the Class or Module.
+
+#### `#assert_matches`
+
+Raises an exception unless the given value matches the expected value using case equality (`#===`).
+
+
+```ruby
+Assertions.assert_matches('bar', expected: /foo/)
+#=> raises an AssertionError with message 'value does not match the pattern /foo/'
+
+Assertions.assert_matches('foo', expected: /foo/)
+#=> does not raise an exception
+```
+
+It accepts the following options:
+
+- `as:` A short descriptor of the given value. Defaults to `"value"`.
+- `error_class:` The class of exception to raise. Defaults to `SleepingKingStudios::Tools::Assertions::AssertionError`.
+- `message`: The error message to display.
+- `optional`: If true, accepts `nil` values as well as matching values.
+
+#### `#assert_name`
+
+Raises an exception unless the given value is non-empty a String or Symbol.
+
+```ruby
+Assertions.assert_name(nil)
+#=> raises an AssertionError with message "value can't be blank"
+
+Assertions.assert_name(Object.new)
+#=> raises an AssertionError with message 'value is not a String or a Symbol'
+
+Assertions.assert_name('')
+#=> raises an AssertionError with message "value can't be blank"
+
+Assertions.assert_name('foo')
+#=> does not raise an exception
+
+Assertions.assert_name(:bar)
+#=> does not raise an exception
+```
+
+It accepts the following options:
+
+- `as:` A short descriptor of the given value. Defaults to `"value"`.
+- `error_class:` The class of exception to raise. Defaults to `SleepingKingStudios::Tools::Assertions::AssertionError`.
+- `message`: The error message to display.
+- `optional`: If true, accepts `nil` values as well as valid Symbols and Strings.
+
+#### `#validate`
+
+Raises an `ArgumentError` unless the given block returns a truthy value.
+
+```ruby
+Assertions.validate { true == false }
+#=> raises an ArgumentError with message 'block returned a falsy value'
+
+Assertions.validate { true == true }
+#=> does not raise an exception
+```
+
+It accepts the following options:
+
+- `message`: The error message to display.
+
+#### `#validate_boolean`
+
+Raises an exception unless the given value is either `true` or `false`.
+
+```ruby
+Assertions.validate_boolean(nil)
+#=> raises an ArgumentError with message 'value must be true or false'
+
+Assertions.validate_boolean(Object.new)
+#=> raises an ArgumentError with message 'value must be true or false'
+
+Assertions.validate_boolean(false)
+#=> does not raise an exception
+
+Assertions.validate_boolean(true)
+#=> does not raise an exception
+```
+
+It accepts the following options:
+
+- `as:` A short descriptor of the given value. Defaults to `"value"`.
+- `message`: The error message to display.
+
+#### `#validate_class`
+
+Raises an `ArgumentError` unless the given value is a Class.
+
+```ruby
+Assertions.validate_class(Object.new)
+#=> raises an ArgumentError with message 'value is not a class'
+
+Assertions.validate_class(String)
+#=> does not raise an exception
+```
+
+It accepts the following options:
+
+- `as:` A short descriptor of the given value. Defaults to `"value"`.
+- `message`: The error message to display.
+
+#### `#validate_instance_of`
+
+Raises an `ArgumentError` unless the given value is an instance of the expected Class or Module.
+
+```ruby
+Assertions.validate_instance_of(:foo, expected: String)
+#=> raises an AssertionError with message 'value is not an instance of String'
+
+Assertions.validate_instance_of('foo', expected: String)
+#=> does not raise an exception
+```
+
+It accepts the following options:
+
+- `as:` A short descriptor of the given value. Defaults to `"value"`.
+- `message`: The error message to display.
+- `optional`: If true, accepts `nil` values as well as instances of the Class or Module.
+
+#### `#validate_matches`
+
+Raises an `ArgumentError` unless the given value matches the expected value using case equality (`#===`).
+
+
+```ruby
+Assertions.validate_matches('bar', expected: /foo/)
+#=> raises an ArgumentError with message 'value does not match the pattern /foo/'
+
+Assertions.validate_matches('foo', expected: /foo/)
+#=> does not raise an exception
+```
+
+It accepts the following options:
+
+- `as:` A short descriptor of the given value. Defaults to `"value"`.
+- `message`: The error message to display.
+- `optional`: If true, accepts `nil` values as well as matching values.
+
+#### `#validate_name`
+
+Raises an `ArgumentError` unless the given value is non-empty a String or Symbol.
+
+```ruby
+Assertions.validate_name(nil)
+#=> raises an ArgumentError with message "value can't be blank"
+
+Assertions.validate_name(Object.new)
+#=> raises an AssertionError with message 'value is not a String or a Symbol'
+
+Assertions.validate_name('')
+#=> raises an ArgumentError with message "value can't be blank"
+
+Assertions.validate_name('foo')
+#=> does not raise an exception
+
+Assertions.validate_name(:bar)
+#=> does not raise an exception
+```
+
+It accepts the following options:
+
+- `as:` A short descriptor of the given value. Defaults to `"value"`.
+- `message`: The error message to display.
+- `optional`: If true, accepts `nil` values as well as valid Symbols and Strings.
+
 ### Core Tools
 
 Tools for working with an application or working environment.
@@ -189,17 +441,40 @@ Tools for working with an application or working environment.
 
 Prints a deprecation warning.
 
-    CoreTools.deprecate 'ObjectTools#old_method'
-    #=> prints to stderr:
-
-    [WARNING] ObjectTools#old_method is deprecated.
-      called from /path/to/file.rb:4: in something_or_other
-
-    CoreTools.deprecate 'ObjectTools#old_method', '0.1.0', :format => '%s was deprecated in version %s.'
-    #=> prints to stderr:
-
-    ObjectTools#old_method was deprecated in version 0.1.0.
-      called from /path/to/file.rb:4: in something_or_other
+```ruby
+CoreTools.deprecate 'ObjectTools#old_method'
+#=> prints to stderr:
+#
+#   [WARNING] ObjectTools#old_method is deprecated.
+#       called from /path/to/file.rb:4: in something_or_other
+```
+
+You can also specify an additional message to display:
+
+```ruby
+CoreTools.deprecate 'ObjectTools#old_method',
+  'Use #new_method instead.'
+#=> prints to stderr:
+#
+#   [WARNING] ObjectTools#old_method is deprecated. Use #new_method instead.
+#     called from /path/to/file.rb:4: in something_or_other
+```
+
+You can specify a custom format for the deprecation message:
+
+```ruby
+CoreTools.deprecate 'ObjectTools#old_method',
+  '0.1.0',
+  format: '%s was deprecated in version %s.'
+#=> prints to stderr:
+#
+#   ObjectTools#old_method was deprecated in version 0.1.0.
+#     called from /path/to/file.rb:4: in something_or_other
+```
+
+By default, `#deprecate` will print the last 3 lines of the caller, excluding
+any lines from `Forwardable` and from `SleepingKingStudios::Tools` itself. To
+print a different number of lines, pass a custom `deprecation_caller_depth` parameter to `CoreTools.new` or set the `DEPRECATION_CALLER_DEPTH` environment variable.
 
 #### `#empty_binding`
 
@@ -825,3 +1100,102 @@ Concatenates the MAJOR, MINOR, and PATCH constant values with PRERELEASE and BUI
 #### `#to_version`
 
 Concatenates the MAJOR, MINOR, and PATCH constant values with PRERELEASE and BUILD (if available) to generate a semantic version string. The major, minor, and patch values are separated by dots `.`, then the prerelease (if available) preceded by a hyphen `-`, and the build (if available) preceded by a plus sign `+`.
+
+### Subclass
+
+```ruby
+require 'sleeping_king_studios/tools/toolbox/subclass'
+```
+
+The `Subclass` module provides a mechanism for performing partial application (or "currying") of constructor parameters. This is useful for defining subclasses that inject pre-defined values into the constructor.
+
+Let's consider an example. We'll start by defining a base class.
+
+```ruby
+class Query
+  extend SleepingKingStudios::Tools::Toolbox::Subclass
+
+  def initialize(entity_class, **options)
+    @entity_class = entity_class
+    @options      = options
+  end
+
+  attr_reader :entity_class
+
+  attr_reader :options
+
+  def call
+    # Querying logic here.
+  end
+end
+
+query = Query.new(Book, limit: 10)
+query.entity_class
+#=> Book
+query.options
+#=> { limit: 10 }
+```
+
+Our `Query` class is used to perform queries on some data source - a relational table, an API, or some in-memory data structure. To perform a query, we need to know what data to request. This is represented by the `:entity_class` argument. Additionally, we can pass arbitrary `:options` as keywords.
+
+```ruby
+BooksQuery = Query.subclass(Book)
+
+query = BooksQuery.new(order: :title)
+query.entity_class
+#=> Book
+query.options
+#=> { order: :title }
+```
+
+By calling `.subclass` on our `Query` class, we are defining a new subclass of `Query` that injects the given parameters and partially applies them to the constructor. In this case, we are injecting the `Book` class into our query.
+
+We can also use `.subclass` to partially apply keywords or a block.
+
+```ruby
+RecentItemsQuery = Query.subclass(order: { created_at: :desc })
+
+query = RecentItemsQuery.new(Book)
+query.entity_class
+#=> Book
+query.options
+#=> { order: { created_at: :desc } }
+```
+
+When you call the subclass's constructor with additional parameters, they are applied in addition to the configured values (if any).
+
+- Any arguments passed to `.new` are added *after* the configured arguments.
+- Any keywords passed to `.new` are merged into the configured keywords, with the values passed to `.new` taking precedence.
+- A block passed to `.new` will take precedence over a configured block.
+
+```ruby
+class Character
+  extend SleepingKingStudios::Tools::Toolbox::Subclass
+
+  def initialize(*traits, **stats, &special)
+    @traits  = traits
+    @stats   = stats
+    @special = special
+  end
+
+  attr_reader :special
+
+  attr_reader :stats
+
+  attr_reader :traits
+end
+
+Bard = Character.subclass(:musical, performance: 5, persuasion: 10) do
+  'The bard sings a cheerful tune.'
+end
+
+aoife = Bard.new(:sorcerous, magic: 5, performance: 10) do
+  'Aoife drops her lute!'
+end
+aoife.traits
+#=> [:musical, :sorcerous]
+aoife.stats
+#=> { magic: 5, performance: 10, persuasion: 10 }
+aoife.special.call
+#=> 'Aoife drops her lute!'
+```

data/lib/sleeping_king_studios/tools/array_tools.rb

@@ -302,7 +302,7 @@ module SleepingKingStudios::Tools
     def require_array!(value)
       return if array?(value)
 
-      raise ArgumentError, 'argument must be an array', caller[1..-1]
+      raise ArgumentError, 'argument must be an array', caller[1..]
     end
   end
 end

data/lib/sleeping_king_studios/tools/assertions.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools'
+
+module SleepingKingStudios::Tools
+  # Methods for asserting on the state of a function or application.
+  class Assertions < Base # rubocop:disable Metrics/ClassLength
+    # Error class for handling a failed assertion.
+    class AssertionError < StandardError; end
+
+    # Asserts that the block returns a truthy value.
+    #
+    # @param error_class [Class] The exception class to raise on a failure.
+    # @param message [String] The exception message to raise on a failure.
+    #
+    # @yield The block to evaluate.
+    # @yieldreturn [Object] The returned value of the block.
+    #
+    # @raise AssertionError if the block does not return a truthy value.
+    def assert(error_class: AssertionError, message: nil, &block)
+      return if block.call
+
+      raise error_class,
+        message || 'block returned a falsy value',
+        caller(1..-1)
+    end
+
+    # Asserts that the value is either true or false.
+    #
+    # @param value [Object] The value to assert on.
+    # @param as [String] The name of the asserted value.
+    # @param error_class [Class] The exception class to raise on a failure.
+    # @param message [String] The exception message to raise on a failure.
+    #
+    # @raise AssertionError if the value is not a Class.
+    def assert_boolean(
+      value,
+      as:          'value',
+      error_class: AssertionError,
+      message:     nil
+    )
+      return if value.equal?(true) || value.equal?(false)
+
+      raise error_class,
+        message || "#{as} must be true or false",
+        caller(1..-1)
+    end
+
+    # Asserts that the value is a Class.
+    #
+    # @param value [Object] The value to assert on.
+    # @param as [String] The name of the asserted value.
+    # @param error_class [Class] The exception class to raise on a failure.
+    # @param message [String] The exception message to raise on a failure.
+    #
+    # @raise AssertionError if the value is not a Class.
+    def assert_class(
+      value,
+      as:          'value',
+      error_class: AssertionError,
+      message:     nil
+    )
+      return if value.is_a?(Class)
+
+      raise error_class,
+        message || "#{as} is not a Class",
+        caller(1..-1)
+    end
+
+    # Asserts that the value is an example of the given Class.
+    #
+    # @param value [Object] The value to assert on.
+    # @param as [String] The name of the asserted value.
+    # @param error_class [Class] The exception class to raise on a failure.
+    # @param expected [Class] The expected class.
+    # @param message [String] The exception message to raise on a failure.
+    # @param optional [true, false] If true, allows nil values.
+    #
+    # @raise ArgumentError if the expected class is not a Class.
+    # @raise AssertionError if the value is not an instance of the expected
+    #   class.
+    def assert_instance_of( # rubocop:disable Metrics/ParameterLists
+      value,
+      expected:,
+      as:          'value',
+      error_class: AssertionError,
+      message:     nil,
+      optional:    false
+    )
+      unless expected.is_a?(Class)
+        raise ArgumentError, 'expected must be a Class'
+      end
+
+      return if optional && value.nil?
+      return if value.is_a?(expected)
+
+      raise error_class,
+        message || "#{as} is not an instance of #{class_name(expected)}",
+        caller(1..-1)
+    end
+
+    # Asserts that the value matches the expected object using #===.
+    #
+    # @param value [Object] The value to assert on.
+    # @param as [String] The name of the asserted value.
+    # @param error_class [Class] The exception class to raise on a failure.
+    # @param expected [#===] The expected object.
+    # @param message [String] The exception message to raise on a failure.
+    # @param optional [true, false] If true, allows nil values.
+    #
+    # @raise AssertionError if the value does not match the expected object.
+    def assert_matches( # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/ParameterLists
+      value,
+      expected:,
+      as:          'value',
+      error_class: AssertionError,
+      message:     nil,
+      optional:    false
+    )
+      return if optional && value.nil?
+      return if expected === value # rubocop:disable Style/CaseEquality
+
+      message ||=
+        case expected
+        when Module
+          "#{as} is not an instance of #{class_name(expected)}"
+        when Proc
+          "#{as} does not match the Proc"
+        when Regexp
+          "#{as} does not match the pattern #{expected.inspect}"
+        else
+          "#{as} does not match the expected value"
+        end
+
+      raise error_class, message, caller(1..-1)
+    end
+
+    # Asserts that the value is a non-empty String or Symbol.
+    #
+    # @param value [Object] The value to assert on.
+    # @param as [String] The name of the asserted value.
+    # @param error_class [Class] The exception class to raise on a failure.
+    # @param message [String] The exception message to raise on a failure.
+    # @param optional [true, false] If true, allows nil values.
+    #
+    # @raise AssertionError if the value is not a String or a Symbol, or if the
+    #   value is empty.
+    def assert_name( # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      value,
+      as:          'value',
+      error_class: AssertionError,
+      message:     nil,
+      optional:    false
+    )
+      if value.nil?
+        return if optional
+
+        raise error_class, message || "#{as} can't be blank", caller(1..-1)
+      end
+
+      unless value.is_a?(String) || value.is_a?(Symbol)
+        raise error_class,
+          message || "#{as} is not a String or a Symbol",
+          caller(1..-1)
+      end
+
+      return unless value.empty?
+
+      raise error_class, message || "#{as} can't be blank", caller(1..-1)
+    end
+
+    # Asserts that the block returns a truthy value.
+    #
+    # @param message [String] The exception message to raise on a failure.
+    #
+    # @yield The block to evaluate.
+    # @yieldreturn [Object] The returned value of the block.
+    #
+    # @raise ArgumentError if the block does not return a truthy value.
+    def validate(message: nil, &block)
+      return if block.call
+
+      raise ArgumentError,
+        message || 'block returned a falsy value',
+        caller(1..-1)
+    end
+
+    # Asserts that the value is either true or false.
+    #
+    # @param value [Object] The value to assert on.
+    # @param as [String] The name of the asserted value.
+    # @param message [String] The exception message to raise on a failure.
+    #
+    # @raise AssertionError if the value is not a Class.
+    def validate_boolean(value, as: 'value', message: nil)
+      return if value.equal?(true) || value.equal?(false)
+
+      raise ArgumentError,
+        message || "#{as} must be true or false",
+        caller(1..-1)
+    end
+
+    # Asserts that the value is a Class.
+    #
+    # @param value [Object] The value to assert on.
+    # @param as [String] The name of the asserted value.
+    # @param message [String] The exception message to raise on a failure.
+    #
+    # @raise ArgumentError if the value is not a Class.
+    def validate_class(value, as: 'value', message: nil)
+      return if value.is_a?(Class)
+
+      raise ArgumentError,
+        message || "#{as} is not a Class",
+        caller(1..-1)
+    end
+
+    # Asserts that the value is an example of the given Class.
+    #
+    # @param value [Object] The value to assert on.
+    # @param as [String] The name of the asserted value.
+    # @param expected [Class] The expected class.
+    # @param message [String] The exception message to raise on a failure.
+    # @param optional [true, false] If true, allows nil values.
+    #
+    # @raise ArgumentError if the expected class is not a Class.
+    # @raise AssertionError if the value is not an instance of the expected
+    #   class.
+    def validate_instance_of(
+      value,
+      expected:,
+      as:       'value',
+      message:  nil,
+      optional: false
+    )
+      unless expected.is_a?(Class)
+        raise ArgumentError, 'expected must be a Class'
+      end
+
+      return if optional && value.nil?
+      return if value.is_a?(expected)
+
+      raise ArgumentError,
+        message || "#{as} is not an instance of #{class_name(expected)}",
+        caller(1..-1)
+    end
+
+    # Asserts that the value matches the expected object using #===.
+    #
+    # @param value [Object] The value to assert on.
+    # @param as [String] The name of the asserted value.
+    # @param expected [#===] The expected object.
+    # @param message [String] The exception message to raise on a failure.
+    # @param optional [true, false] If true, allows nil values.
+    #
+    # @raise ArgumentError if the value does not match the expected object.
+    def validate_matches( # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
+      value,
+      expected:,
+      as:       'value',
+      message:  nil,
+      optional: false
+    )
+      return if optional && value.nil?
+      return if expected === value # rubocop:disable Style/CaseEquality
+
+      message ||=
+        case expected
+        when Module
+          "#{as} is not an instance of #{class_name(expected)}"
+        when Proc
+          "#{as} does not match the Proc"
+        when Regexp
+          "#{as} does not match the pattern #{expected.inspect}"
+        else
+          "#{as} does not match the expected value"
+        end
+
+      raise ArgumentError, message, caller(1..-1)
+    end
+
+    # Asserts that the value is a non-empty String or Symbol.
+    #
+    # @param value [Object] The value to assert on.
+    # @param as [String] The name of the asserted value.
+    # @param message [String] The exception message to raise on a failure.
+    # @param optional [true, false] If true, allows nil values.
+    #
+    # @raise ArgumentError if the value is not a String or a Symbol, or if the
+    #   value is empty.
+    def validate_name( # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      value,
+      as:       'value',
+      message:  nil,
+      optional: false
+    )
+      if value.nil?
+        return if optional
+
+        raise ArgumentError, message || "#{as} can't be blank", caller(1..-1)
+      end
+
+      unless value.is_a?(String) || value.is_a?(Symbol)
+        raise ArgumentError,
+          message || "#{as} is not a String or a Symbol",
+          caller(1..-1)
+      end
+
+      return unless value.empty?
+
+      raise ArgumentError, message || "#{as} can't be blank", caller(1..-1)
+    end
+
+    private
+
+    def class_name(expected)
+      return expected.name if expected.name
+
+      "#{expected.inspect} (#{expected.ancestors.find(&:name).name})"
+    end
+  end
+end

data/lib/sleeping_king_studios/tools/core_tools.rb

@@ -16,16 +16,28 @@ module SleepingKingStudios::Tools
         :require_each
     end
 
+    # @param deprecation_caller_depth [Integer] The number of backtrace lines to
+    #   display when outputting a deprecation warning.
     # @param deprecation_strategy [String] The name of the strategy used when
     #   deprecated code is called. Must be 'ignore', 'raise', or 'warn'.
-    def initialize(deprecation_strategy: nil)
+    def initialize(
+      deprecation_caller_depth: nil,
+      deprecation_strategy:     nil
+    )
       super()
 
+      @deprecation_caller_depth =
+        deprecation_caller_depth ||
+        ENV.fetch('DEPRECATION_CALLER_DEPTH', '3').to_i
       @deprecation_strategy =
         deprecation_strategy || ENV.fetch('DEPRECATION_STRATEGY', 'warn')
     end
 
-    # @return [String] The current deprecation strategy.
+    # @return [Integer] the number of backtrace lines to display when outputting
+    #   a deprecation warning.
+    attr_reader :deprecation_caller_depth
+
+    # @return [String] the current deprecation strategy.
     attr_reader :deprecation_strategy
 
     # @overload deprecate(name, message: nil)
@@ -92,19 +104,21 @@ module SleepingKingStudios::Tools
 
       str = format % args
       str << ' ' << message if message
-
-      str << "\n  called from #{external_caller}"
+      str << format_caller
 
       Kernel.warn str
     end
 
-    def external_caller
-      caller.find do |line|
-        !(
-          line.include?('forwardable.rb') ||
-          line.include?('sleeping_king_studios-tools')
-        )
+    def format_caller
+      lines = caller
+      start = lines.find_index do |line|
+        !line.include?('forwardable.rb') &&
+          !line.include?('sleeping_king_studios-tools')
       end
+
+      lines[start...(start + deprecation_caller_depth)]
+        .map { |line| "\n  called from #{line}" }
+        .join
     end
   end
 end

data/lib/sleeping_king_studios/tools/hash_tools.rb

@@ -168,7 +168,7 @@ module SleepingKingStudios::Tools
     def require_hash!(value)
       return if hash?(value)
 
-      raise ArgumentError, 'argument must be a hash', caller[1..-1]
+      raise ArgumentError, 'argument must be a hash', caller[1..]
     end
   end
 end

data/lib/sleeping_king_studios/tools/integer_tools.rb

@@ -108,7 +108,7 @@ module SleepingKingStudios::Tools
     # @return [Array<String>] The digits of the decomposed integer,
     #   represented as a bigendian array of strings.
     def digits(integer, base: 10)
-      integer.to_s(base).split('')
+      integer.to_s(base).chars
     end
 
     # Returns true if the object is an Integer.

data/lib/sleeping_king_studios/tools/string_tools.rb

@@ -167,7 +167,7 @@ module SleepingKingStudios::Tools
 
       return value.to_s if value.is_a?(Symbol)
 
-      raise ArgumentError, 'argument must be a string', caller[1..-1]
+      raise ArgumentError, 'argument must be a string', caller[1..]
     end
   end
 end

data/lib/sleeping_king_studios/tools/toolbelt.rb

@@ -18,6 +18,7 @@ module SleepingKingStudios::Tools
     #   ActiveSupport::Inflector .
     def initialize(deprecation_strategy: nil, inflector: nil)
       @array_tools   = ::SleepingKingStudios::Tools::ArrayTools.new
+      @assertions    = ::SleepingKingStudios::Tools::Assertions.new
       @core_tools    = ::SleepingKingStudios::Tools::CoreTools.new(
         deprecation_strategy: deprecation_strategy
       )
@@ -30,6 +31,8 @@ module SleepingKingStudios::Tools
 
     attr_reader :array_tools
 
+    attr_reader :assertions
+
     attr_reader :core_tools
 
     attr_reader :hash_tools

data/lib/sleeping_king_studios/tools/toolbox/inflector.rb

@@ -47,7 +47,7 @@ module SleepingKingStudios::Tools::Toolbox
 
       word = word.to_s.gsub(/(\b|[_-])([a-z])/) { Regexp.last_match(2).upcase }
 
-      (uppercase_first_letter ? word[0].upcase : word[0].downcase) + word[1..-1]
+      (uppercase_first_letter ? word[0].upcase : word[0].downcase) + word[1..]
     end
 
     # rubocop:disable Metrics/AbcSize

data/lib/sleeping_king_studios/tools/toolbox/subclass.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools/toolbox'
+
+module SleepingKingStudios::Tools::Toolbox
+  # Mixin for partially applying constructor parameters.
+  #
+  # @example
+  #   class Character
+  #     extend SleepingKingStudios::Tools::Toolbox::Subclass
+  #
+  #     def initialize(*traits)
+  #       @traits = traits
+  #     end
+  #
+  #     attr_reader :traits
+  #   end
+  #
+  #   Bard = Character.subclass(:charismatic, :musical)
+  #
+  #   aoife = Bard.new(:sorcerous)
+  #   aoife.traits
+  #   #=> [:charismatic, :musical, :sorcerous]
+  module Subclass
+    # Creates a subclass with partially applied constructor parameters.
+    #
+    # @param class_arguments [Array] The arguments, if any, to apply to the
+    #   constructor. These arguments will be added before any args passed
+    #   directly to the constructor.
+    # @param class_keywords [Hash] The keywords, if any, to apply to the
+    #   constructor. These keywords will be added before any kwargs passed
+    #   directly to the constructor.
+    #
+    # @yield The block, if any, to pass to the constructor. This will be
+    #   overriden by a block passed directly to the constructor.
+    #
+    # @return [Class] the generated subclass.
+    def subclass(*class_arguments, **class_keywords, &class_block) # rubocop:disable Metrics/MethodLength
+      subclass = Class.new(self)
+
+      subclass.define_method :initialize do |*args, **kwargs, &block|
+        super(
+          *class_arguments,
+          *args,
+          **class_keywords,
+          **kwargs,
+          &(block || class_block)
+        )
+      end
+
+      subclass
+    end
+  end
+end

data/lib/sleeping_king_studios/tools/toolbox.rb

@@ -6,5 +6,16 @@ module SleepingKingStudios::Tools
   # Namespace for common objects or patterns that are useful across projects but
   # are larger than or do not fit the functional paradigm of the tools.*
   # pattern.
-  module Toolbox; end
+  module Toolbox
+    autoload :ConstantMap,
+      'sleeping_king_studios/tools/toolbox/constant_map'
+    autoload :Inflector,
+      'sleeping_king_studios/tools/toolbox/inflector'
+    autoload :Mixin,
+      'sleeping_king_studios/tools/toolbox/mixin'
+    autoload :SemanticVersion,
+      'sleeping_king_studios/tools/toolbox/semantic_version'
+    autoload :Subclass,
+      'sleeping_king_studios/tools/toolbox/subclass'
+  end
 end

data/lib/sleeping_king_studios/tools/version.rb

@@ -13,13 +13,13 @@ module SleepingKingStudios
       # Major version.
       MAJOR = 1
       # Minor version.
-      MINOR = 0
+      MINOR = 1
       # Patch version.
-      PATCH = 2
+      PATCH = 0
       # Prerelease version.
-      PRERELEASE = nil
+      PRERELEASE = :rc
       # Build metadata.
-      BUILD = nil
+      BUILD = 0
     end
 
     # The current version of the gem.

data/lib/sleeping_king_studios/tools.rb

@@ -7,12 +7,14 @@ module SleepingKingStudios
   module Tools
     autoload :Base,         'sleeping_king_studios/tools/base'
     autoload :ArrayTools,   'sleeping_king_studios/tools/array_tools'
+    autoload :Assertions,   'sleeping_king_studios/tools/assertions'
     autoload :CoreTools,    'sleeping_king_studios/tools/core_tools'
     autoload :HashTools,    'sleeping_king_studios/tools/hash_tools'
     autoload :IntegerTools, 'sleeping_king_studios/tools/integer_tools'
     autoload :ObjectTools,  'sleeping_king_studios/tools/object_tools'
     autoload :StringTools,  'sleeping_king_studios/tools/string_tools'
     autoload :Toolbelt,     'sleeping_king_studios/tools/toolbelt'
+    autoload :Toolbox,      'sleeping_king_studios/tools/toolbox'
     autoload :Version,      'sleeping_king_studios/tools/version'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sleeping_king_studios-tools
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0.rc.0
 platform: ruby
 authors:
 - Rob "Merlin" Smith
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-02-14 00:00:00.000000000 Z
+date: 2022-05-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: byebug
@@ -58,42 +58,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: '1.29'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: '1.29'
 - !ruby/object:Gem::Dependency
   name: rubocop-rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: '0.6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: '0.6'
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '2.10'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '2.10'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -128,28 +128,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.5'
+        version: '2.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.5'
-- !ruby/object:Gem::Dependency
-  name: sleeping_king_studios-tasks
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.4'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '2.7'
 description: |
   A library of utility services and concerns to expand the functionality of
   core classes without polluting the global namespace.
@@ -166,6 +152,7 @@ files:
 - README.md
 - lib/sleeping_king_studios/tools.rb
 - lib/sleeping_king_studios/tools/array_tools.rb
+- lib/sleeping_king_studios/tools/assertions.rb
 - lib/sleeping_king_studios/tools/base.rb
 - lib/sleeping_king_studios/tools/core_tools.rb
 - lib/sleeping_king_studios/tools/hash_tools.rb
@@ -179,6 +166,7 @@ files:
 - lib/sleeping_king_studios/tools/toolbox/inflector/rules.rb
 - lib/sleeping_king_studios/tools/toolbox/mixin.rb
 - lib/sleeping_king_studios/tools/toolbox/semantic_version.rb
+- lib/sleeping_king_studios/tools/toolbox/subclass.rb
 - lib/sleeping_king_studios/tools/version.rb
 homepage: http://sleepingkingstudios.com
 licenses:
@@ -186,6 +174,7 @@ licenses:
 metadata:
   bug_tracker_uri: https://github.com/sleepingkingstudios/sleeping_king_studios-tools/issues
   source_code_uri: https://github.com/sleepingkingstudios/sleeping_king_studios-tools
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -194,12 +183,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.5.0
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.2.3
 signing_key: