snaky_hash 2.0.1 → 2.0.2

data/lib/snaky_hash/extensions.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module SnakyHash
+  # Manages extensions that can modify values in a chain of transformations
+  #
+  # @example Adding and running an extension
+  #   extensions = Extensions.new
+  #   extensions.add(:upcase) { |value| value.to_s.upcase }
+  #   extensions.run("hello") #=> "HELLO"
+  #
+  class Extensions
+    # Initializes a new Extensions instance with an empty extensions registry
+    def initialize
+      reset
+    end
+
+    # Reset the registry of extensions to an empty state
+    #
+    # @return [Hash] an empty hash of extensions
+    def reset
+      @extensions = {}
+    end
+
+    # Adds a new extension with the given name
+    #
+    # @param name [String, Symbol] the name of the extension
+    # @yield [value] block that will be called with a value to transform
+    # @raise [SnakyHash::Error] if an extension with the given name already exists
+    # @return [Proc] the added extension block
+    def add(name, &block)
+      if has?(name)
+        raise Error, "Extension already defined named '#{name}'"
+      end
+
+      @extensions[name.to_sym] = block
+    end
+
+    # Checks if an extension with the given name exists
+    #
+    # @param name [String, Symbol] the name of the extension to check
+    # @return [Boolean] true if the extension exists, false otherwise
+    def has?(name)
+      @extensions.key?(name.to_sym)
+    end
+
+    # Runs all registered extensions in sequence on the given value
+    #
+    # @param value [Object] the value to transform through all extensions
+    # @return [Object] the final transformed value after running all extensions
+    def run(value)
+      @extensions.each_value do |block|
+        value = block.call(value)
+      end
+      value
+    end
+  end
+end

data/lib/snaky_hash/serializer.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SnakyHash
+  # Provides JSON serialization and deserialization capabilities with extensible value transformation
+  #
+  # @example Basic usage
+  #   class MyHash < Hashie::Mash
+  #     extend SnakyHash::Serializer
+  #   end
+  #   hash = MyHash.load('{"key": "value"}')
+  #   hash.dump #=> '{"key":"value"}'
+  #
+  module Serializer
+    class << self
+      # Extends the base class with serialization capabilities
+      #
+      # @param base [Class] the class being extended
+      # @return [void]
+      def extended(base)
+        extended_module = Modulizer.to_extended_mod
+        base.extend(extended_module)
+        # :nocov:
+        # This will be run in CI on Ruby 2.3, but we only collect coverage from current Ruby
+        unless base.instance_methods.include?(:transform_values)
+          base.include(BackportedInstanceMethods)
+        end
+        # :nocov:
+      end
+    end
+
+    # Serializes a hash object to JSON
+    #
+    # @param obj [Hash] the hash to serialize
+    # @return [String] JSON string representation of the hash
+    def dump(obj)
+      hash = dump_hash(obj)
+      hash.to_json
+    end
+
+    # Deserializes a JSON string into a hash object
+    #
+    # @param raw_hash [String, nil] JSON string to deserialize
+    # @return [Hash] deserialized hash object
+    def load(raw_hash)
+      hash = JSON.parse(presence(raw_hash) || "{}")
+      hash = load_value(new(hash))
+      new(hash)
+    end
+
+    # Internal module for generating extension methods
+    module Modulizer
+      class << self
+        # Creates a new module with extension management methods
+        #
+        # @return [Module] a module containing extension management methods
+        def to_extended_mod
+          Module.new do
+            define_method :load_extensions do
+              @load_extensions ||= Extensions.new
+            end
+
+            define_method :dump_extensions do
+              @dump_extensions ||= Extensions.new
+            end
+
+            define_method :load_hash_extensions do
+              @load_hash_extensions ||= Extensions.new
+            end
+          end
+        end
+      end
+    end
+
+    # Provides backported methods for older Ruby versions
+    module BackportedInstanceMethods
+      # :nocov:
+      # Transforms values of a hash using the given block
+      #
+      # @yield [Object] block to transform each value
+      # @return [Hash] new hash with transformed values
+      # @return [Enumerator] if no block given
+      # @note This will be run in CI on Ruby 2.3, but we only collect coverage from current Ruby
+      #       Rails <= 5.2 had a transform_values method, which was added to Ruby in version 2.4.
+      #       This method is a backport of that original Rails method for Ruby 2.2 and 2.3.
+      def transform_values(&block)
+        return enum_for(:transform_values) { size } unless block_given?
+        return {} if empty?
+        result = self.class.new
+        each do |key, value|
+          result[key] = yield(value)
+        end
+        result
+      end
+      # :nocov:
+    end
+
+  private
+
+    # Checks if a value is blank (nil or empty string)
+    #
+    # @param value [Object] value to check
+    # @return [Boolean] true if value is blank
+    def blank?(value)
+      return true if value.nil?
+      return true if value.is_a?(String) && value.empty?
+
+      false
+    end
+
+    # Returns nil if value is blank, otherwise returns the value
+    #
+    # @param value [Object] value to check
+    # @return [Object, nil] the value or nil if blank
+    def presence(value)
+      blank?(value) ? nil : value
+    end
+
+    # Processes a hash for dumping, transforming its values
+    #
+    # @param hash [Hash] hash to process
+    # @return [Hash] processed hash with transformed values
+    def dump_hash(hash)
+      hash = self[hash].transform_values do |value|
+        dump_value(value)
+      end
+      hash.reject { |_, v| blank?(v) }
+    end
+
+    # Processes a single value for dumping
+    #
+    # @param value [Object] value to process
+    # @return [Object, nil] processed value
+    def dump_value(value)
+      if blank?(value)
+        return
+      end
+
+      if value.is_a?(::Hash)
+        return dump_hash(value)
+      end
+
+      if value.is_a?(::Array)
+        return value.map { |v| dump_value(v) }.compact
+      end
+
+      dump_extensions.run(value)
+    end
+
+    # Processes a hash for loading, transforming its values
+    #
+    # @param hash [Hash] hash to process
+    # @return [Hash] processed hash with transformed values
+    def load_hash(hash)
+      hash.transform_values do |value|
+        load_value(value)
+      end
+    end
+
+    # Processes a single value for loading
+    #
+    # @param value [Object] value to process
+    # @return [Object] processed value
+    def load_value(value)
+      if value.is_a?(::Hash)
+        hash = load_hash_extensions.run(new(value))
+        return load_hash(new(hash)) if hash.is_a?(::Hash)
+        return load_value(hash)
+      end
+
+      return value.map { |v| load_value(v) } if value.is_a?(Array)
+
+      load_extensions.run(value)
+    end
+  end
+end

data/lib/snaky_hash/snake.rb

@@ -1,69 +1,114 @@
 # This is a module-class hybrid.
 #
+# A flexible key conversion system that supports both String and Symbol keys,
+# with optional serialization capabilities.
+#
+# @example Basic usage with string keys
+#   class MyHash < Hashie::Mash
+#     include SnakyHash::Snake.new(key_type: :string)
+#   end
+#
+# @example Usage with symbol keys and serialization
+#   class MySerializableHash < Hashie::Mash
+#     include SnakyHash::Snake.new(key_type: :symbol, serializer: true)
+#   end
+#
 # Hashie's standard SymbolizeKeys is similar to the functionality we want.
 # ... but not quite.  We need to support both String (for oauth2) and Symbol keys (for oauth).
-# include Hashie::Extensions::Mash::SymbolizeKeys
+# see: Hashie::Extensions::Mash::SymbolizeKeys
+#
 module SnakyHash
+  # Creates a module that provides key conversion functionality when included
+  #
+  # @note Unlike Hashie::Mash, this implementation allows for both String and Symbol key types
   class Snake < Module
-    def initialize(key_type: :string)
+    # Initialize a new Snake module
+    #
+    # @param key_type [Symbol] the type to convert keys to (:string or :symbol)
+    # @param serializer [Boolean] whether to include serialization capabilities
+    # @raise [ArgumentError] if key_type is not :string or :symbol
+    def initialize(key_type: :string, serializer: false)
       super()
       @key_type = key_type
+      @serializer = serializer
     end
 
+    # Includes appropriate conversion methods into the base class
+    #
+    # @param base [Class] the class including this module
+    # @return [void]
     def included(base)
       conversions_module = SnakyModulizer.to_mod(@key_type)
       base.include(conversions_module)
+      if @serializer
+        base.extend(SnakyHash::Serializer)
+      end
     end
 
+    # Internal module factory for creating key conversion functionality
     module SnakyModulizer
-      def self.to_mod(key_type)
-        Module.new do
-          # Converts a key to a symbol, or a string, depending on key_type,
-          #   but only if it is able to be converted to a symbol,
-          #   and after underscoring it.
-          #
-          # @api private
-          # @param [<K>] key the key to attempt convert to a symbol
-          # @return [Symbol, K]
-
-          case key_type
-          when :string then
-            define_method(:convert_key) { |key| key.respond_to?(:to_sym) ? underscore_string(key.to_s) : key }
-          when :symbol then
-            define_method(:convert_key) { |key| key.respond_to?(:to_sym) ? underscore_string(key.to_s).to_sym : key }
-          else
-            raise ArgumentError, "SnakyHash: Unhandled key_type: #{key_type}"
-          end
-
-          # Unlike its parent Mash, a SnakyHash::Snake will convert other
-          #   Hashie::Hash values to a SnakyHash::Snake when assigning
-          #   instead of respecting the existing subclass
-          define_method :convert_value do |val, duping = false| #:nodoc:
-            case val
-            when self.class
-              val.dup
-            when ::Hash
-              val = val.dup if duping
-              self.class.new(val)
-            when ::Array
-              val.collect { |e| convert_value(e) }
+      class << self
+        # Creates a new module with key conversion methods based on the specified key type
+        #
+        # @param key_type [Symbol] the type to convert keys to (:string or :symbol)
+        # @return [Module] a new module with conversion methods
+        # @raise [ArgumentError] if key_type is not supported
+        def to_mod(key_type)
+          Module.new do
+            case key_type
+            when :string then
+              # Converts a key to a string if possible, after underscoring
+              #
+              # @param key [Object] the key to convert
+              # @return [String, Object] the converted key or original if not convertible
+              define_method(:convert_key) { |key| key.respond_to?(:to_sym) ? underscore_string(key.to_s) : key }
+            when :symbol then
+              # Converts a key to a symbol if possible, after underscoring
+              #
+              # @param key [Object] the key to convert
+              # @return [Symbol, Object] the converted key or original if not convertible
+              define_method(:convert_key) { |key| key.respond_to?(:to_sym) ? underscore_string(key.to_s).to_sym : key }
             else
-              val
+              raise ArgumentError, "SnakyHash: Unhandled key_type: #{key_type}"
             end
-          end
 
-          # converts a camel_cased string to a underscore string
-          # subs spaces with underscores, strips whitespace
-          # Same way ActiveSupport does string.underscore
-          define_method :underscore_string do |str|
-            str.to_s.strip
-               .tr(" ", "_")
-               .gsub(/::/, "/")
-               .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
-               .gsub(/([a-z\d])([A-Z])/, '\1_\2')
-               .tr("-", "_")
-               .squeeze("_")
-               .downcase
+            # Converts hash values to the appropriate type when assigning
+            #
+            # @param val [Object] the value to convert
+            # @param duping [Boolean] whether the value is being duplicated
+            # @return [Object] the converted value
+            define_method :convert_value do |val, duping = false| #:nodoc:
+              case val
+              when self.class
+                val.dup
+              when ::Hash
+                val = val.dup if duping
+                self.class.new(val)
+              when ::Array
+                val.collect { |e| convert_value(e) }
+              else
+                val
+              end
+            end
+
+            # Converts a string to underscore case
+            #
+            # @param str [String, #to_s] the string to convert
+            # @return [String] the underscored string
+            # @example
+            #   underscore_string("CamelCase")  #=> "camel_case"
+            #   underscore_string("API::V1")    #=> "api/v1"
+            # @note This is the same as ActiveSupport's String#underscore
+            define_method :underscore_string do |str|
+              str.to_s.strip.
+                tr(" ", "_").
+                gsub("::", "/").
+                gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').
+                gsub(/([a-z\d])([A-Z])/, '\1_\2').
+                tr("-", "_").
+                squeeze("_").
+                downcase
+            end
           end
         end
       end

data/lib/snaky_hash/string_keyed.rb

@@ -1,5 +1,13 @@
 module SnakyHash
+  # serializer is being introduced as an always disabled option for backwards compatibility.
+  # In snaky_hash v3 it will default to true.
+  # If you want to start using it immediately, reopen this class and add the Serializer module:
+  #
+  #   SnakyHash::StringKeyed.class_eval do
+  #     extend SnakyHash::Serializer
+  #   end
+  #
   class StringKeyed < Hashie::Mash
-    include SnakyHash::Snake.new(key_type: :string)
+    include SnakyHash::Snake.new(key_type: :string, serializer: false)
   end
 end

data/lib/snaky_hash/symbol_keyed.rb

@@ -1,5 +1,13 @@
 module SnakyHash
+  # serializer is being introduced as an always disabled option for backwards compatibility.
+  # In snaky_hash v3 it will default to true.
+  # If you want to start using it immediately, reopen this class and add the Serializer module:
+  #
+  #   SnakyHash::SymbolKeyed.class_eval do
+  #     extend SnakyHash::Serializer
+  #   end
+  #
   class SymbolKeyed < Hashie::Mash
-    include SnakyHash::Snake.new(key_type: :symbol)
+    include SnakyHash::Snake.new(key_type: :symbol, serializer: false)
   end
 end

data/lib/snaky_hash/version.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 module SnakyHash
+  # Defines the version information for SnakyHash
+  #
+  # @api public
   module Version
-    VERSION = "2.0.1".freeze
+    # Current version of SnakyHash
+    #
+    # @return [String] the current version in semantic versioning format
+    VERSION = "2.0.2"
   end
 end

data/lib/snaky_hash.rb

@@ -5,14 +5,38 @@ require "hashie"
 require "version_gem"
 
 require_relative "snaky_hash/version"
+require_relative "snaky_hash/extensions"
+require_relative "snaky_hash/serializer"
 require_relative "snaky_hash/snake"
 require_relative "snaky_hash/string_keyed"
 require_relative "snaky_hash/symbol_keyed"
 
-# This is the namespace for this gem
+# SnakyHash provides hash-like objects with automatic key conversion capabilities
+#
+# @example Using StringKeyed hash
+#   hash = SnakyHash::StringKeyed.new
+#   hash["camelCase"] = "value"
+#   hash["camel_case"] # => "value"
+#
+# @example Using SymbolKeyed hash
+#   hash = SnakyHash::SymbolKeyed.new
+#   hash["camelCase"] = "value"
+#   hash[:camel_case] # => "value"
+#
+# @see SnakyHash::StringKeyed
+# @see SnakyHash::SymbolKeyed
+# @see SnakyHash::Snake
 module SnakyHash
+  # Base error class for all SnakyHash errors
+  #
+  # @api public
+  class Error < StandardError
+  end
 end
 
+# Enable version introspection via VersionGem
+#
+# @api private
 SnakyHash::Version.class_eval do
   extend VersionGem::Basic
 end