sleeping_king_studios-tools 1.3.0 → 1.4.0.rc.0

data/lib/sleeping_king_studios/tools/messages/strategies/file_strategy.rb

@@ -5,20 +5,36 @@ require 'sleeping_king_studios/tools/messages/strategies/hash_strategy'
 
 module SleepingKingStudios::Tools::Messages::Strategies
   # Messaging strategy that loads message templates from the given file.
+  #
+  # Internally, the parsed templates are flattened - a nested Hash of
+  # { foo: { bar: { baz: 'template' } } } is stored as a flat Hash with
+  # { 'foo.bar.baz' => 'template' }. This makes lookup of scoped keys more
+  # efficient but prevents retrieving non-leaf nodes (such as "foo" or "foo.bar"
+  # in the above Hash). If you need to retrieve Hash values, initialize the
+  # strategy with flatten_templates: false.
   class FileStrategy < HashStrategy
     # Exception raised when reading the templates file.
     class FileError < StandardError; end
 
-    # @param file_name [String] the full path to the file with the templates
-    #   data.
-    def initialize(file_name)
+    # @overload initialize(file_name, **options)
+    #   @param file_name [String] the full path to the file with the templates
+    #     data.
+    #   @param options [Hash] additional options for the strategy.
+    #
+    #   @option options flatten_templates [true, false] if true, the templates
+    #     are flattened internally. Defaults to true.
+    #   @option options validate_values [Proc, true, false] if false, skips
+    #     validation of template values. If given a Proc, calls the Proc with
+    #     each template value; the value fails validation if the Proc returns
+    #     an error message. Defaults to true.
+    def initialize(file_name, flatten_templates: true, validate_values: true)
       validate_file_name(file_name)
 
       @file_name = file_name
       raw_data   = read_file(file_name)
       templates  = parse_templates(raw_data)
 
-      super(templates)
+      super(templates, flatten_templates:, validate_values:)
     end
 
     # @return [String] the full path to the file with the templates data.
@@ -68,6 +84,8 @@ module SleepingKingStudios::Tools::Messages::Strategies
       end
     end
 
+    def template_value_error_message = 'value is not a String'
+
     def validate_file_name(file_name)
       raise ArgumentError, "file name can't be blank" if file_name.nil?
 

data/lib/sleeping_king_studios/tools/messages/strategies/hash_strategy.rb

@@ -4,19 +4,40 @@ require 'sleeping_king_studios/tools/messages/strategies'
 
 module SleepingKingStudios::Tools::Messages::Strategies
   # Messaging strategy that refers to an internal Hash of templates.
+  #
+  # Internally, the templates Hash is flattened - a nested Hash of
+  # { foo: { bar: { baz: 'template' } } } is stored as a flat Hash with
+  # { 'foo.bar.baz' => 'template' }. This makes lookup of scoped keys more
+  # efficient but prevents retrieving non-leaf nodes (such as "foo" or "foo.bar"
+  # in the above Hash). If you need to retrieve Hash values, initialize the
+  # strategy with flatten_templates: false.
   class HashStrategy < SleepingKingStudios::Tools::Messages::Strategy
     # Exception raised when parsing the templates input.
     class ParseError < StandardError; end
 
-    # @param templates [Hash] the templates used to generate messages.
-    def initialize(templates)
+    VALID_TEMPLATE_VALUES = [Proc, String, Symbol].freeze
+    private_constant :VALID_TEMPLATE_VALUES
+
+    # @overload initialize(templates, **options)
+    #   @param templates [Hash] the templates used to generate messages.
+    #   @param options [Hash] additional options for the strategy.
+    #
+    #   @option options flatten_templates [true, false] if true, the templates
+    #     are flattened internally. Defaults to true.
+    #   @option options validate_values [Proc, true, false] if false, skips
+    #     validation of template values. If given a Proc, calls the Proc with
+    #     each template value; the value fails validation if the Proc returns
+    #     an error message. Defaults to true.
+    def initialize(templates, flatten_templates: true, validate_values: true)
       super()
 
       unless templates.is_a?(Hash)
         raise ArgumentError, 'templates is not an instance of Hash'
       end
 
-      @templates = flatten_templates(templates).freeze
+      @flatten_templates = flatten_templates
+      @validate_values   = validate_values
+      @templates         = self.flatten_templates(templates).freeze
     end
 
     # @return [Hash] the templates used to generate messages.
@@ -24,27 +45,66 @@ module SleepingKingStudios::Tools::Messages::Strategies
 
     private
 
-    def flatten_templates(hsh, scope: nil, templates: {})
+    def convert_keys_to_strings(hsh, scope: nil) # rubocop:disable Metrics/MethodLength
+      hsh
+        .to_h do |key, value|
+          validate_template_key(key, scope:)
+
+          if value.is_a?(Hash)
+            local = scope ? "#{scope}.#{key}" : key.to_s
+
+            value = convert_keys_to_strings(value, scope: local)
+          else
+            validate_template_value(key, value, scope:)
+          end
+
+          [key.to_s, value]
+        end
+        .freeze
+    end
+
+    def flatten_templates(hsh, scope: nil, templates: {}) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
+      return convert_keys_to_strings(hsh, scope:) unless flatten_templates?
+
       hsh.each do |(key, value)|
         validate_template_key(key, scope:)
-        validate_template_value(key, value, scope:)
+
+        next if value.nil? || (value.respond_to?(:empty?) && value.empty?)
 
         local = scope ? "#{scope}.#{key}" : key.to_s
 
-        next if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+        if value.is_a?(Hash)
+          next flatten_templates(value, scope: local, templates:)
+        end
 
-        next templates[local] = value unless value.is_a?(Hash)
+        validate_template_value(key, value, scope:)
 
-        flatten_templates(value, scope: local, templates:)
+        templates[local] = value
       end
 
       templates
     end
 
+    def flatten_templates? = @flatten_templates
+
     def template_for(scoped_key, **)
-      templates[scoped_key]
+      return templates[scoped_key] if flatten_templates?
+
+      templates.dig(*scoped_key.split('.'))
+    end
+
+    def template_value_error(value)
+      return unless @validate_values
+
+      return @validate_values.call(value) if @validate_values.is_a?(Proc)
+
+      return if VALID_TEMPLATE_VALUES.any? { |klass| value.is_a?(klass) }
+
+      template_value_error_message
     end
 
+    def template_value_error_message = 'value is not a String or a Proc'
+
     def validate_template_key(key, scope:)
       return if (key.is_a?(String) || key.is_a?(Symbol)) && !key.empty?
 
@@ -57,14 +117,13 @@ module SleepingKingStudios::Tools::Messages::Strategies
     end
 
     def validate_template_value(key, value, scope:)
-      return if value.nil? || value.is_a?(Hash) || value.is_a?(Proc)
-      return if value.is_a?(String) || value.is_a?(Symbol)
+      error_message = template_value_error(value)
+
+      return if error_message.nil?
 
       message = 'invalid value in templates'
       message = "#{message}.#{scope}" if scope
-      message = "#{message}.#{key}"
-      message =
-        "#{message} - expected Hash, Proc, or String, got #{value.inspect}"
+      message = "#{message}.#{key} - #{error_message}, got #{value.inspect}"
 
       raise ParseError, message
     end

data/lib/sleeping_king_studios/tools/messages/strategy.rb

@@ -5,10 +5,27 @@ require 'sleeping_king_studios/tools/messages'
 module SleepingKingStudios::Tools
   # Abstract class for converting parameterized keys to user-readable messages.
   class Messages::Strategy
+    UNDEFINED = SleepingKingStudios::Tools::UNDEFINED
+    private_constant :UNDEFINED
+
     # @overload call(key, parameters: {}, scope: nil, **options)
     #   Generates a formatted string for the given key, parameters, and options.
     #
+    #   If the strategy does not define a message for the key, you can provide a
+    #   default value.
+    #
+    #   - If the default value is a Proc, it will be called with the fully
+    #     scoped key, as a positional argument as well as any additional
+    #     keywords passed to #call. The value returned by the Proc will be
+    #     returned by #call.
+    #   - If the default value is any other Object (including nil), the default
+    #     value will be returned by #call.
+    #   - If a default value is not provided, a missing message warning will be
+    #     generated and returned.
+    #
     #   @param key [String, Symbol] the key used to resolve the message.
+    #   @param default [Object] the default value to return if the strategy does
+    #     not define a message for the key.
     #   @param parameters [Hash] the parameters used to generate the message,
     #     such as values for a template string.
     #   @param scope [String] the namespace for the key. Combined with the given
@@ -18,18 +35,98 @@ module SleepingKingStudios::Tools
     #
     #   @return [String] the generated template string, or a generic error
     #     string if a message is not defined for the given key and parameters.
-    def call(key, parameters: {}, scope: nil, **)
+    def call(key, default: UNDEFINED, parameters: {}, scope: nil, **)
+      scoped_key = join_scope(key:, scope:)
+      template   = fetch(key, scope:, **) do
+        return apply_default(scoped_key, default, **)
+      end
+
+      generate(template, parameters:, scoped_key:, **)
+    end
+
+    # @overload fetch(key, default = nil, scope: nil, **options)
+    #   Retrieves the messages template with the given scope and options.
+    #
+    #   If there is no template matching the given key, scope, and options,
+    #   returns the default value or raises a KeyError if no default value is
+    #   provided.
+    #
+    #   @param key [String, Symbol] the key used to resolve the message.
+    #   @param default [Object] the default value to return if the strategy does
+    #     not define a message for the key.
+    #   @param scope [String] the namespace for the key. Combined with the given
+    #     key to generate the scoped key value.
+    #   @param options [Hash] additional options for resolving or generating the
+    #     message.
+    #
+    #   @return [Object] the stored template for the requested key, or the
+    #     provided default value.
+    #
+    #   @raise [KeyError] if there is no matching template and no default value
+    #     is provided.
+    #
+    # @overload fetch(key, scope: nil, **options, &default)
+    #   If there is no template matching the given key, scope, and options,
+    #   the block is called with the scoped key and the value returned by the
+    #   block is returned by #fetch.
+    #
+    #   @param key [String, Symbol] the key used to resolve the message.
+    #   @param scope [String] the namespace for the key. Combined with the given
+    #     key to generate the scoped key value.
+    #   @param options [Hash] additional options for resolving or generating the
+    #     message.
+    #
+    #   @yieldparam [String] scoped_key the fully scoped key for the requested
+    #     template, combining the given key and the given scope, if any.
+    #   @yieldparam options [Hash] additional options for resolving the message.
+    #
+    #   @yieldreturn [Object] the default value for the given scoped key.
+    #
+    #   @return [Object] the stored template for the requested key, or the value
+    #     returned by the provided default block.
+    def fetch(key, default = UNDEFINED, scope: nil, **, &block)
       scoped_key = join_scope(key:, scope:)
       template   = template_for(scoped_key, **)
 
-      return missing_message(scoped_key, **) unless template
+      return template unless template.nil?
 
-      generate(template, parameters:, scoped_key:, **)
+      return block.call(scoped_key, **) if block_given?
+
+      return default unless default == UNDEFINED
+
+      raise KeyError, "template not found: #{scoped_key.inspect}"
     end
 
+    # @overload get(key, scope: nil, **options)
+    #   Retrieves the messages template with the given scope and options.
+    #
+    #   @param key [String, Symbol] the key used to resolve the message.
+    #   @param scope [String] the namespace for the key. Combined with the given
+    #     key to generate the scoped key value.
+    #   @param options [Hash] additional options for resolving or generating the
+    #     message.
+    #
+    #   @return [Object] the stored template for the requested key, or nil if
+    #     there is no matching template.
+    def get(key, scope: nil, **) = fetch(key, nil, scope:, **)
+
     private
 
-    def generate(template, scoped_key: nil, parameters: {}, **) # rubocop:disable Metrics/MethodLength
+    def apply_default(key, default, **)
+      return missing_message(key, **) if default == UNDEFINED
+
+      return default unless default.is_a?(Proc)
+
+      default.call(key, **)
+    end
+
+    def generate( # rubocop:disable Metrics/MethodLength
+      template,
+      parameters:         {},
+      reraise_exceptions: false,
+      scoped_key:         nil,
+      **
+    )
       raise ArgumentError, "template can't be blank" if template.nil?
 
       case template
@@ -41,6 +138,8 @@ module SleepingKingStudios::Tools
         raise ArgumentError, "invalid template #{template.inspect}"
       end
     rescue KeyError => exception
+      raise if reraise_exceptions
+
       missing_parameters_message(scoped_key, exception:, **)
     end
 

data/lib/sleeping_king_studios/tools/messages.rb

@@ -9,6 +9,9 @@ module SleepingKingStudios::Tools
     autoload :Strategies, 'sleeping_king_studios/tools/messages/strategies'
     autoload :Strategy,   'sleeping_king_studios/tools/messages/strategy'
 
+    UNDEFINED = SleepingKingStudios::Tools::UNDEFINED
+    private_constant :UNDEFINED
+
     # @param registry [SleepingKingStudios::Tools::Messages::Registry] the
     #   strategies registry to use for the tool. Defaults to the value of
     #   Registry.global.
@@ -29,27 +32,50 @@ module SleepingKingStudios::Tools
     #   Generates a message from the given key, scope, and parameters.
     #
     #   Internally, finds a messages strategy matching the combined key and
-    #   scope and calls that strategy. If a strategy is not found, instead
-    #   returns a generic failure message.
+    #   scope and calls that strategy.
+    #
+    #   If a strategy is not found, or if the strategy does not define a message
+    #   for the key, you can provide a default value.
+    #
+    #   - If the default value is a Proc, it will be called with the fully
+    #     scoped key, as a positional argument as well as any additional
+    #     keywords passed to #call. The value returned by the Proc will be
+    #     returned by #call.
+    #   - If the default value is any other Object (including nil), the default
+    #     value will be returned by #call.
+    #   - If a default value is not provided, a missing message warning will be
+    #     generated and returned.
     #
     #   @param key [String, Symbol] the key used to resolve the message.
+    #   @param default [Object] the default value to return if there is no
+    #     defined registry for the message, or if the strategy does not define a
+    #     message for the key.
     #   @param parameters [Hash] the parameters used to generate the message,
     #     such as values for a template string.
     #   @param scope [String] the namespace for the key. Combined with the given
     #     key to generate the scoped key value.
     #   @param options [Hash] additional options for resolving or generating the
     #     message.
-    def message(key, parameters: {}, scope: nil, **)
+    def message(key, default: UNDEFINED, parameters: {}, scope: nil, **)
       scoped_key = join_scope(key:, scope:)
       strategy   = registry.get(scoped_key)
 
-      return missing_message(scoped_key, **) unless strategy
+      return apply_default(scoped_key, default, **) unless strategy
 
-      strategy.call(key, parameters:, scope:, **)
+      strategy.call(key, default:, parameters:, scope:, **)
     end
+    alias get message
 
     private
 
+    def apply_default(key, default, **)
+      return missing_message(key, **) if default == UNDEFINED
+
+      return default unless default.is_a?(Proc)
+
+      default.call(key, **)
+    end
+
     def missing_message(scoped_key, **)
       "Message missing: #{scoped_key}"
     end

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

@@ -5,97 +5,12 @@ require 'sleeping_king_studios/tools/toolbox'
 module SleepingKingStudios::Tools::Toolbox
   # Mixin to allow defining subclasses of Data classes.
   module HeritableData
+    # Special thanks to `@havenwood` from the Ruby Discord on the solution here.
+    DEFINE = Data.singleton_class.instance_method(:define)
+    private_constant :DEFINE
+
     # Methods prepended onto the singleton class when including HeritableData.
     module ClassMethods
-      # Compares `self` and `other`.
-      #
-      # @param other [Object] the object to compare.
-      #
-      # @return [true] if self is a subclass of other, or if self inherits Data
-      #   members and methods from other.
-      # @return [false] if self and other are the same class, if other is a
-      #   subclass of self, or if other inherits Data members and methods from
-      #   self.
-      # @return [nil] if none of the above is true.
-      def <(other)
-        (self <=> other)&.then { |cmp| cmp == -1 }
-      end
-
-      # Compares `self` and `other`.
-      #
-      # @param other [Object] the object to compare.
-      #
-      # @return [true] if self and other are the same class, if self is a
-      #   subclass of other, or if self inherits Data members and methods from
-      #   other.
-      # @return [false] if other is a subclass of self, or if other inherits
-      #   Data members and methods from self.
-      # @return [nil] if none of the above is true.
-      def <=(other)
-        (self <=> other)&.then { |cmp| cmp < 1 }
-      end
-
-      # Compares `self` and `other`.
-      #
-      # @param other [Object] the object to compare.
-      #
-      # @return [-1] if self is a subclass of other, or if self inherits Data
-      #   members and methods from other.
-      # @return [0] if self and other are the same class.
-      # @return [1] if self is a parent class of other, or if other inherits
-      #   Data members and methods from self.
-      # @return [nil] if none of the above is true.
-      def <=>(other)
-        return super unless other.is_a?(Class)
-
-        return -1 if other.equal?(Data)
-        return 0  if other.equal?(self)
-
-        return nil unless other.const_defined?(:HeritableMethods)
-
-        return -1 if include?(other::HeritableMethods)
-        return 1 if other.include?(self::HeritableMethods)
-
-        nil
-      end
-
-      # @return [true] if the object is an instance of the data class, or if the
-      #   object is an instance of a Data class that inherits members and
-      #   methods from self.
-      def ===(object)
-        return true if super
-
-        (self > object.class) || false
-      end
-
-      # Compares `self` and `other`.
-      #
-      # @param other [Object] the object to compare.
-      #
-      # @return [true] if other is a subclass of other, or if other inherits
-      #   Data members and methods from self.
-      # @return [false] if self and other are the same class, if self is a
-      #   subclass of other, or if self inherits Data members and methods from
-      #   other.
-      # @return [nil] if none of the above is true.
-      def >(other)
-        (self <=> other)&.then { |cmp| cmp == 1 }
-      end
-
-      # Compares `self` and `other`.
-      #
-      # @param other [Object] the object to compare.
-      #
-      # @return [true] if self and other are the same class, if other is a
-      #   subclass of other, or if other inherits Data members and methods from
-      #   self.
-      # @return [false] if self is a subclass of other, or if self inherits Data
-      #   members and methods from other.
-      # @return [nil] if none of the above is true.
-      def >=(other)
-        (self <=> other)&.then { |cmp| cmp > -1 }
-      end
-
       # Defines a new Data class including the members/methods of this class.
       #
       # The defined data class will include HeritableData, and will be able to
@@ -106,40 +21,53 @@ module SleepingKingStudios::Tools::Toolbox
       #   parent Data class.
       #
       # @yield additional methods to define on the new Data class.
-      def define(*symbols, &)
-        HeritableData.define(*symbols, parent_class: self, &)
+      def define(*symbols, &block)
+        # @deprecated v2.0
+        block = wrap_class_block(block)
+
+        DEFINE
+          .bind_call(self, *members, *symbols, &block)
+          .include(HeritableData)
+          .tap do |data_class|
+            # @deprecated v2.0
+            handle_deprecated_lifecycle_hooks(data_class)
+          end
       end
-    end
-
-    # Custom module used to propagate heritable methods across Data classes.
-    #
-    # @private
-    class HeritableMethods < Module
-      # @param parent_class [Class, nil] the parent data class, if any.
-      #
-      # @yield additional methods to define on the Data class.
-      def initialize(parent_class: nil, &methods)
-        super(&nil)
+      alias with define
 
-        @parent_class = parent_class
+      private
 
-        class_exec(&methods) if methods
+      # @deprecated v2.0
+      def handle_deprecated_lifecycle_hooks(data_class)
+        return if data_class.method(:included).owner == Module
+
+        SleepingKingStudios::Tools::Toolbelt
+          .instance
+          .core_tools
+          .deprecate(
+            'Defining class methods or including modules using an `included` ' \
+            'hook is deprecated. Define the methods or include the modules ' \
+            'directly in the block.'
+          )
+
+        # Ensure legacy class methods defined via .included hook are defined for
+        # the child class.
+        data_class.send(:included, data_class)
       end
 
-      # @return [Class, nil] the parent data class.
-      attr_reader :parent_class
-
-      # Iterates over the ::HeritableMethods modules for parent classes.
-      def each_heritable_module
-        return enum_for(:each_heritable_module) unless block_given?
+      # @deprecated v2.0
+      def wrap_class_block(block)
+        return block unless block&.lambda? && block.arity.zero?
 
-        ancestor = self
+        SleepingKingStudios::Tools::Toolbelt
+          .instance
+          .core_tools
+          .deprecate(
+            'Data.define with a lambda of arity zero is not supported. This ' \
+            'will raise an ArgumentError starting in version 2.0.'
+          )
 
-        while ancestor
-          yield ancestor
-
-          ancestor = ancestor.parent_class&.then { |mod| mod::HeritableMethods }
-        end
+        ->(mod) { mod.class_exec(&block) }
       end
     end
 
@@ -151,23 +79,51 @@ module SleepingKingStudios::Tools::Toolbox
       #   methods from.
       #
       # @yield additional methods to define on the new Data class.
-      def define(*symbols, parent_class: nil, &)
-        Data.define(*parent_class&.members, *symbols).tap do |data_class|
-          data_class.include(HeritableData)
-
-          define_mixin_for(data_class, parent_class, &)
+      def define(*symbols, parent_class: nil, &block) # rubocop:disable Metrics/MethodLength
+        # @deprecated v2.0
+        if parent_class
+          SleepingKingStudios::Tools::Toolbelt
+            .instance
+            .core_tools
+            .deprecate(
+              'HeritableData.define with a parent class is deprecated and ' \
+              'will be removed starting in version 2.0.'
+            )
+
+          return parent_class.define(*symbols, &block)
         end
+
+        # @deprecated v2.0
+        block = wrap_class_block(block)
+
+        Data
+          .define(*symbols, &block)
+          .include(HeritableData)
+          .tap do |data_class|
+            # @deprecated v2.0
+            handle_deprecated_lifecycle_hooks(data_class)
+          end
       end
+      alias with define
 
       private
 
-      def define_mixin_for(data_class, parent_class = nil, &)
-        data_class.const_set(
-          :HeritableMethods,
-          HeritableData::HeritableMethods.new(parent_class:, &)
-        )
-
-        data_class.include(*data_class::HeritableMethods.each_heritable_module)
+      # @deprecated v2.0
+      def handle_deprecated_lifecycle_hooks(data_class)
+        return if data_class.method(:included).owner == Module
+
+        SleepingKingStudios::Tools::Toolbelt
+          .instance
+          .core_tools
+          .deprecate(
+            'Defining class methods or including modules using an `included` ' \
+            'hook is deprecated. Define the methods or include the modules ' \
+            'directly in the block.'
+          )
+
+        # Ensure legacy class methods defined via .included hook are defined for
+        # the child class.
+        data_class.send(:included, data_class)
       end
 
       def included(other)
@@ -175,17 +131,21 @@ module SleepingKingStudios::Tools::Toolbox
 
         other.singleton_class.prepend(ClassMethods)
       end
-    end
 
-    # Checks if the object class inherits from type.
-    #
-    # @param type [Module] the type to check.
-    #
-    # @return [true] if the object class inherits from type, or if the object
-    #   class inherits members and methods from the given type.
-    def is_a?(type)
-      super || self.class < type || false
+      # @deprecated v2.0
+      def wrap_class_block(block)
+        return block unless block&.lambda? && block.arity.zero?
+
+        SleepingKingStudios::Tools::Toolbelt
+          .instance
+          .core_tools
+          .deprecate(
+            'Data.define with a lambda of arity zero is not supported. This ' \
+            'will raise an ArgumentError starting in version 2.0.'
+          )
+
+        ->(mod) { mod.class_exec(&block) }
+      end
     end
-    alias kind_of? is_a?
   end
 end

data/lib/sleeping_king_studios/tools/version.rb

@@ -9,13 +9,13 @@ module SleepingKingStudios
       # Major version.
       MAJOR = 1
       # Minor version.
-      MINOR = 3
+      MINOR = 4
       # Patch version.
       PATCH = 0
       # Prerelease version.
-      PRERELEASE = nil
+      PRERELEASE = :rc
       # Build metadata.
-      BUILD = nil
+      BUILD = 0
 
       class << self
         # Generates the gem version string from the Version constants.