sleeping_king_studios-tools 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b185f72aa8d793ad425987881f1a1df9a37f2a4d2778775258ffb01ee2ec6d20
-  data.tar.gz: bdd496ed87a5fc539bdf25b33f7e9af22bb1f25a6f086b3fb29aad356591fb6a
+  metadata.gz: 1e0283e289b39463cacc292d923861867d3692aa582c11ea52e093d4a669db47
+  data.tar.gz: 6974c66896e0f0a0b9b464326529e8d093f1842d5242a289d559b6508b08f3b6
 SHA512:
-  metadata.gz: e9a2cb6b86a351b4932119e60ac3f0688753183e3c6ae07ca485b105a80b0c64f7f3b75b94984b22add91b8b8ad7c1d83b4e54e57099c8f4d11d2acb1e7a2202
-  data.tar.gz: 4e4ae31ab84ee0ad8e85d2397ec7af1085c6d2a16932ad24ca15fdbd35936f094673012672b457eeac2d76c17849a9ea19eeccb9deef58a7e86821aff9603fe0
+  metadata.gz: 207672541e0507cdb35887ef670cc300157c204ddf937ca21a7c1b0243cdde20d212c7daf76f2cd2c70d734f8676ef2e6c646d30f9304933be1db36126c9d2cb
+  data.tar.gz: 5177a4f97ffd28c60b8249f9a4c8a6eafea08dd5c8fe7833273b4274e1fbb59d48e12bcda042a40d2e7d91afb850ed9e583aeeb8f728eea64feeb30c7c9da95a

data/CHANGELOG.md

@@ -1,15 +1,50 @@
 # Changelog
 
-### 1.0.0
+## 1.1.0
 
-- Removed all deprecated code from pre-1.0 releases.
+Files in the `Toolbox` are now autoloaded.
 
-#### Toolbox
+### 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.
+
+## 1.0.1
+
+Added a missing `require 'set'` to Toolbox::Inflector::Rules.
+
+## 1.0.0
+
+Removed all deprecated code from pre-1.0 releases.
+
+### Toolbox
 
 Added some Hash-like methods to ConstantMap - `#each_key`, `#each_value`,
 `#keys`, `#to_h`, and `#values`.
 
-### 0.8.0
+## 0.8.0
 
 Last minor release before 1.0.0.
 
@@ -20,14 +55,14 @@ in version 1.0.0. Update dependent code accordingly.
   functionality is still available as
   SleepingKingStudios::Tools::Toolbox::SemanticVersion.
 
-#### Tools
+### Tools
 
 - Refactored all Tools modules to classes.
 - Removed StringTools::PluralInflector. It's functionality is now handled by
   Toolbox::Inflector.
 - Added support for deprecation strategy to CoreTools#deprecate.
 
-#### Toolbelt
+### Toolbelt
 
 - Refactored Toolbelt to reference Tools instances rather than classes.
 - Defined new abbreviated helpers #ary, #hsh, #int, #obj, #str.
@@ -36,36 +71,36 @@ in version 1.0.0. Update dependent code accordingly.
 - Deprecated old abbreviated helpers #array, #core, #hash, #integer, #object,
   #string.
 
-#### Toolbox
+### Toolbox
 
 - Deprecate Toolbox::Configuration. Use a struct instead.
 - Deprecate Toolbox::Delegator. Use the stdlib Forwardable module instead.
 - Implement Toolbox::Inflector, which serves as a delegate for StringTools.
 
-### 0.7.1
+## 0.7.1
 
 - Implement CoreTools#empty_binding.
 - Implement HashTools#generate_binding.
 
-### 0.7.0
+## 0.7.0
 
-#### Tools
+### Tools
 
 - Support symbol arguments to StringTools methods.
 - Implement StringTools#chain.
 - Implement StringTools#indent.
 - Implement StringTools#map_lines.
 
-#### Toolbox
+### Toolbox
 
 - Implement Toolbox::Configuration.
 
-#### Misc.
+### Misc.
 
 - IntegerTools#pluralize now accepts 2..3 arguments, and will automatically generate the plural string using StringTools#pluralize if an explicit plural is not given.
 - SleepingKingStudios::Tools::Toolbelt is now autoloaded from SleepingKingStudios::Tools.
 
-### 0.6.0
+## 0.6.0
 
 - Implement HashTools#convert_keys_to_strings and #convert_keys_to_symbols.
 - Implement ObjectTools#dig.
@@ -75,69 +110,67 @@ in version 1.0.0. Update dependent code accordingly.
 - Implement Toolbox::Mixin.
 - Add support for Ruby 2.4.0.
 
-### 0.5.0
+## 0.5.0
 
 - Implement CoreTools#require_each.
 - Implement StringTools#camelize.
 - Add an optional block argument to ArrayTools#humanize_list.
 
-#### Toolbox
+### Toolbox
 
 - Implement Delegator#delegate, Delegator#wrap_delegate.
 - Refactor SemanticVersion to the Toolbox namespace. Accessing SemanticVersion as Tools::SemanticVersion is now deprecated, use Tools::Toolbox::SemanticVersion.
 
-#### Identity Methods
+### Identity Methods
 
 - Implement a set of methods to classify objects by type: ArrayTools#array?, HashTools#hash?, IntegerTools#integer?, ObjectTools#object?, and StringTools#string?.
 
-#### Mutability Methods
+### Mutability Methods
 
 Implement #immutable? and #mutable? for ObjectTools, ArrayTools, and HashTools, which indicate whether or not a given object is mutable.
 
 Implement #deep_freeze for ObjectTools, ArrayTools, and HashTools which recursively freezes the object and any children (array items, hash keys, and hash values).
 
-## Previous Releases
-
-### 0.4.0
+## 0.4.0
 
-#### CoreTools
+### CoreTools
 
 Implement CoreTools#deprecate.
 
-#### IntegerTools
+### IntegerTools
 
 Implement #pluralize.
 
-#### StringTools
+### StringTools
 
 Implement #pluralize and #singularize. The previous behavior of #pluralize is deprecated; use IntegerTools#pluralize.
 
-### 0.3.0
+## 0.3.0
 
 Implement ArrayTools#bisect and ArrayTools#splice.
 
-#### StringTools
+### StringTools
 
 Implement #underscore.
 
-### 0.2.0
+## 0.2.0
 
 Split EnumerableTools into ArrayTools and HashTools.
 
 Implement ArrayTools#deep_dup, HashTools#deep_dup and ObjectTools#deep_dup.
 
-### 0.1.3
+## 0.1.3
 
 Properly support both keywords and optional arguments in ObjectTools#apply.
 
-### 0.1.2
+## 0.1.2
 
 Fix loading order issues when loading SemanticVersion in isolation.
 
-### 0.1.1
+## 0.1.1
 
 Add configuration options to EnumerableTools#humanize_list.
 
-### 0.1.0
+## 0.1.0
 
 Initial release.

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.
@@ -177,8 +177,8 @@ module SleepingKingStudios::Tools
       return if (ROMANIZE_MIN..ROMANIZE_MAX).include?(integer)
 
       error_message =
-        "integer to romanize must be within range #{ROMANIZE_MIN} to" \
-        " #{ROMANIZE_MAX}"
+        "integer to romanize must be within range #{ROMANIZE_MIN} to " \
+        "#{ROMANIZE_MAX}"
 
       raise RangeError, error_message, caller(1..-1)
     end

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/rules.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'set'
+
 require 'sleeping_king_studios/tools/toolbox'
 
 class SleepingKingStudios::Tools::Toolbox::Inflector

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,7 +13,7 @@ module SleepingKingStudios
       # Major version.
       MAJOR = 1
       # Minor version.
-      MINOR = 0
+      MINOR = 1
       # Patch version.
       PATCH = 0
       # Prerelease version.

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.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Rob "Merlin" Smith
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-01-19 00:00:00.000000000 Z
+date: 2022-09-01 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.35'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: '1.35'
 - !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.12'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '2.12'
 - !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,11 +166,15 @@ 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:
 - MIT
-metadata: {}
+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:
@@ -192,7 +183,7 @@ 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:
   - - ">="