hashie 5.1.0 → 5.2.0

data/lib/hashie/extensions/mash/define_accessors.rb

@@ -1,7 +1,20 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
     module Mash
+      # Generates reusable methods as Mash properties are accessed.
+      #
+      # @example
+      #   klass = Class.new(Hashie::Mash) do
+      #     include Hashie::Extensions::Mash::DefineAccessors
+      #   end
+      #   klass.new(name: 'Ada').name # => 'Ada'
       module DefineAccessors
+        # @example Install generated accessors on a subclass
+        #   klass = Class.new(Hashie::Mash)
+        #   klass.include(Hashie::Extensions::Mash::DefineAccessors)
+        #   klass.new(quantity: 2).quantity # => 2
         def self.included(klass)
           klass.class_eval do
             mod = Ext.new
@@ -9,23 +22,40 @@ module Hashie
           end
         end
 
+        # @example Install generated accessors on one Mash
+        #   mash = Hashie::Mash.new(quantity: 2)
+        #   mash.extend(Hashie::Extensions::Mash::DefineAccessors)
+        #   mash.quantity # => 2
         def self.extended(obj)
           included(obj.singleton_class)
         end
 
+        # A module of lazily generated accessors for a Mash class.
+        #
+        # @example
+        #   accessors = Hashie::Extensions::Mash::DefineAccessors::Ext.new
+        #   klass = Class.new(Hashie::Mash) { include accessors }
+        #   mash = klass.new(name: 'Ada')
+        #   accessors.define_reader('name', :name)
+        #   mash.name # => 'Ada'
         class Ext < Module
+          # @example Generate a method on first access
+          #   accessors = Hashie::Extensions::Mash::DefineAccessors::Ext.new
+          #   klass = Class.new(Hashie::Mash) { include accessors }
+          #   klass.new(name: 'Ada').name # => 'Ada'
+          #   accessors.instance_methods(false).include?(:name) # => true
           def initialize
             mod = self
             define_method(:method_missing) do |method_name, *args, &block|
               key, suffix = method_name_and_suffix(method_name)
               case suffix
-              when '='.freeze
+              when '='
                 mod.define_writer(key, method_name)
-              when '?'.freeze
+              when '?'
                 mod.define_predicate(key, method_name)
-              when '!'.freeze
+              when '!'
                 mod.define_initializing_reader(key, method_name)
-              when '_'.freeze
+              when '_'
                 mod.define_underbang_reader(key, method_name)
               else
                 mod.define_reader(key, method_name)
@@ -34,6 +64,12 @@ module Hashie
             end
           end
 
+          # @example
+          #   accessors = Hashie::Extensions::Mash::DefineAccessors::Ext.new
+          #   klass = Class.new(Hashie::Mash) { include accessors }
+          #   mash = klass.new(name: 'Ada')
+          #   accessors.define_reader('name', :name)
+          #   mash.name # => 'Ada'
           def define_reader(key, method_name)
             define_method(method_name) do |&block|
               if key? method_name
@@ -44,40 +80,67 @@ module Hashie
             end
           end
 
+          # @example
+          #   accessors = Hashie::Extensions::Mash::DefineAccessors::Ext.new
+          #   accessors.define_writer('name', :name=)
+          #   klass = Class.new(Hashie::Mash) { include accessors }
+          #   mash = klass.new
+          #   mash.name = 'Ada'
+          #   mash['name'] # => 'Ada'
           def define_writer(key, method_name)
             define_method(method_name) do |value = nil|
               if key? method_name
-                self.[](method_name, &proc)
+                self.[](method_name)
               else
                 assign_property(key, value)
               end
             end
           end
 
+          # @example
+          #   accessors = Hashie::Extensions::Mash::DefineAccessors::Ext.new
+          #   accessors.define_predicate('name', :name?)
+          #   klass = Class.new(Hashie::Mash) { include accessors }
+          #   klass.new(name: 'Ada').name? # => true
+          #   klass.new.name? # => false
           def define_predicate(key, method_name)
             define_method(method_name) do
               if key? method_name
-                self.[](method_name, &proc)
+                self.[](method_name)
               else
                 !!self[key]
               end
             end
           end
 
+          # @example
+          #   accessors = Hashie::Extensions::Mash::DefineAccessors::Ext.new
+          #   accessors.define_initializing_reader('address', :address!)
+          #   klass = Class.new(Hashie::Mash) { include accessors }
+          #   mash = klass.new
+          #   mash.address!.city = 'London'
+          #   mash.address.city # => 'London'
           def define_initializing_reader(key, method_name)
             define_method(method_name) do
               if key? method_name
-                self.[](method_name, &proc)
+                self.[](method_name)
               else
                 initializing_reader(key)
               end
             end
           end
 
+          # @example
+          #   accessors = Hashie::Extensions::Mash::DefineAccessors::Ext.new
+          #   accessors.define_underbang_reader('address', :address_)
+          #   klass = Class.new(Hashie::Mash) { include accessors }
+          #   mash = klass.new
+          #   mash.address_.city = 'London'
+          #   mash.key?('address') # => false
           def define_underbang_reader(key, method_name)
             define_method(method_name) do
               if key? method_name
-                self.[](key, &proc)
+                self.[](key)
               else
                 underbang_reader(key)
               end

data/lib/hashie/extensions/mash/keep_original_keys.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
     module Mash
@@ -14,8 +16,13 @@ module Hashie
       #   mash['string_key'] == mash[:string_key]  #=> true
       #   mash[:symbol_key] == mash['symbol_key']  #=> true
       module KeepOriginalKeys
+        # @example Preserve symbol keys when including the extension
+        #   klass = Class.new(Hashie::Mash) do
+        #     include Hashie::Extensions::Mash::KeepOriginalKeys
+        #   end
+        #   klass.new(name: 'Ada').keys # => [:name]
         def self.included(descendant)
-          error_message = "#{descendant} is not a kind of Hashie::Mash"
+          error_message = "`#{descendant}` is not a kind of Hashie::Mash"
           raise ArgumentError, error_message unless descendant <= Hashie::Mash
         end
 
@@ -26,13 +33,10 @@ module Hashie
         # @param [Object, String, Symbol] key the key to access.
         # @return [Object] the value assigned to the key.
         def convert_key(key)
-          if regular_key?(key)
-            key
-          elsif (converted_key = __convert(key)) && regular_key?(converted_key)
-            converted_key
-          else
-            key
-          end
+          return key if regular_key?(key)
+
+          converted_key = __convert(key)
+          converted_key && regular_key?(converted_key) ? converted_key : key
         end
 
         # Converts symbol/string keys to their alternative formats, but leaves
@@ -42,7 +46,7 @@ module Hashie
         # @return [Object, String, Symbol] the converted key.
         def __convert(key)
           case key
-          when Symbol then key.to_s
+          when Symbol then key.name
           when String then key.to_sym
           else key
           end

data/lib/hashie/extensions/mash/permissive_respond_to.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
     module Mash

data/lib/hashie/extensions/mash/required_keys.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Hashie
+  module Extensions
+    module Mash
+      # Extends a Mash with the ability to require specific keys to be
+      # set (non-nil) when constructed, while still allowing arbitrary,
+      # undeclared keys to be assigned - unlike Hashie::Dash, which
+      # restricts assignment to only pre-declared properties.
+      #
+      # @example
+      #
+      #   class PersonMash < Hashie::Mash
+      #     include Hashie::Extensions::Mash::RequiredKeys
+      #
+      #     required_keys :name, :email
+      #   end
+      #
+      #   expect { PersonMash.new(email: 'bob@example.com') }
+      #     .to raise_error(ArgumentError, 'the following keys are required: `name`')
+      #
+      #   person = PersonMash.new(name: 'Bob', email: 'bob@example.com')
+      #   person.age = 42 # arbitrary, undeclared keys are still allowed
+      #   person.age # => 42
+      module RequiredKeys
+        # @example Install required-key declarations
+        #   klass = Class.new(Hashie::Mash) do
+        #     include Hashie::Extensions::Mash::RequiredKeys
+        #   end
+        #   klass.required_keys # => []
+        def self.included(base)
+          base.instance_variable_set(:@required_keys, [])
+          base.extend(ClassMethods)
+          base.include(InstanceMethods)
+        end
+
+        # Class-level required-key declarations inherited by subclasses.
+        #
+        # @example
+        #   klass = Class.new(Hashie::Mash) do
+        #     include Hashie::Extensions::Mash::RequiredKeys
+        #     required_keys :name
+        #   end
+        #   klass.required_keys # => ['name']
+        module ClassMethods
+          # @example Copy required keys when subclassing
+          #   parent = Class.new(Hashie::Mash) do
+          #     include Hashie::Extensions::Mash::RequiredKeys
+          #     required_keys :name
+          #   end
+          #   child = Class.new(parent)
+          #   child.required_keys :email
+          #   child.required_keys # => ['name', 'email']
+          #   parent.required_keys # => ['name']
+          def inherited(klass)
+            super
+            klass.instance_variable_set(:@required_keys, required_keys.dup)
+          end
+
+          # With no arguments, returns the keys currently declared as
+          # required. With one or more arguments, declares those keys
+          # as required. Keys are stored and compared as strings, so
+          # both symbol and string keys are accepted.
+          #
+          # @example
+          #   klass = Class.new(Hashie::Mash) do
+          #     include Hashie::Extensions::Mash::RequiredKeys
+          #     required_keys :name, 'email', :name
+          #   end
+          #   klass.required_keys # => ['name', 'email']
+          def required_keys(*keys)
+            return @required_keys if keys.empty?
+
+            @required_keys |= keys.map(&:to_s)
+          end
+        end
+
+        # Checks required values when constructing a Mash.
+        #
+        # @example
+        #   klass = Class.new(Hashie::Mash) do
+        #     include Hashie::Extensions::Mash::RequiredKeys
+        #     required_keys :name
+        #   end
+        #   klass.new(name: 'Ada').name # => 'Ada'
+        module InstanceMethods
+          # @example Reject nil or missing required values
+          #   klass = Class.new(Hashie::Mash) do
+          #     include Hashie::Extensions::Mash::RequiredKeys
+          #     required_keys :name
+          #   end
+          #   expect { klass.new(name: nil) }.to raise_error(ArgumentError, /name/)
+          #   klass.new(name: 'Ada', age: 37).age # => 37
+          def initialize(*args, &block)
+            super
+            assert_required_keys_set!
+          end
+
+          private
+
+          def assert_required_keys_set!
+            missing_keys = self.class.required_keys.select { |key| self[key].nil? }
+            return if missing_keys.empty?
+
+            raise ArgumentError, "the following keys are required: `#{missing_keys.join(', ')}`"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hashie/extensions/mash/safe_assignment.rb

@@ -1,14 +1,32 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
     module Mash
+      # Rejects assignments that would shadow existing Mash methods.
+      #
+      # @example
+      #   klass = Class.new(Hashie::Mash) do
+      #     include Hashie::Extensions::Mash::SafeAssignment
+      #   end
+      #   mash = klass.new
+      #   expect { mash[:size] = 2 }.to raise_error(ArgumentError, /clashes/)
+      #   mash.empty? # => true
       module SafeAssignment
-        def custom_writer(key, *args) #:nodoc:
-          if !key?(key) && respond_to?(key, true)
-            raise ArgumentError, "The property #{key} clashes with an existing method."
-          end
+        def custom_writer(key, *args) # :nodoc:
+          raise ArgumentError, "the property `#{key}` clashes with an existing method" if !key?(key) && respond_to?(key, true)
+
           super
         end
 
+        # @example
+        #   klass = Class.new(Hashie::Mash) do
+        #     include Hashie::Extensions::Mash::SafeAssignment
+        #   end
+        #   mash = klass.new
+        #   mash[:name] = 'Ada'
+        #   mash.name # => 'Ada'
+        #   expect { mash[:size] = 2 }.to raise_error(ArgumentError, /clashes/)
         def []=(*args)
           custom_writer(*args)
         end

data/lib/hashie/extensions/mash/strict_key_access.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Hashie
+  module Extensions
+    module Mash
+      # Overrides Mash's default behavior of returning nil for keys that
+      # aren't set, raising a KeyError instead.
+      #
+      # Unlike Hashie::Extensions::StrictKeyAccess, this extension is aware
+      # of Mash's special suffixed methods (e.g. +?+, +!+, +_+ and +=+) so
+      # that they continue to work as expected instead of always raising.
+      #
+      # Because nested Hashes are converted into instances of +self.class+,
+      # this extension is automatically applied to any nested Mash as well.
+      #
+      # @example
+      #   class StrictMash < Hashie::Mash
+      #     include Hashie::Extensions::Mash::StrictKeyAccess
+      #   end
+      #
+      #   mash = StrictMash.new(name: 'Bob')
+      #   mash.name  #=> 'Bob'
+      #   expect { mash.age }.to raise_error(KeyError, 'key not found: `age`')
+      #
+      #   mash.name? #=> true
+      #   mash.age?  #=> false
+      #
+      #   mash.address!.city = 'Springfield'
+      #   mash.address.city  #=> 'Springfield'
+      #
+      # @api public
+      module StrictKeyAccess
+        # Hook for being included in a class
+        #
+        # @api private
+        # @return [void]
+        # @raise [ArgumentError] when the base class isn't a Mash
+        def self.included(descendant)
+          error_message = "#{descendant} is not a kind of Hashie::Mash"
+          raise ArgumentError, error_message unless descendant <= Hashie::Mash
+        end
+
+        # @api private
+        def method_missing(method_name, *args, &blk)
+          return super if key?(method_name)
+
+          name, suffix = method_name_and_suffix(method_name)
+          raise KeyError, "key not found: `#{name}`" if !key?(name) && !suffix
+
+          super
+        end
+
+        # @api private
+        def respond_to_missing?(method_name, *args)
+          return true if key?(method_name)
+
+          _, suffix = method_name_and_suffix(method_name)
+          return false unless suffix
+
+          super
+        end
+      end
+    end
+  end
+end

data/lib/hashie/extensions/mash/symbolize_keys.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
     module Mash
@@ -9,7 +11,7 @@ module Hashie
       #   end
       #
       #   response = LazyResponse.new("id" => 123, "name" => "Rey").to_h
-      #   #=> {id: 123, name: "Rey"}
+      #   response # => {id: 123, name: "Rey"}
       #
       # @api public
       module SymbolizeKeys
@@ -19,7 +21,9 @@ module Hashie
         # @return [void]
         # @raise [ArgumentError] when the base class isn't a Mash
         def self.included(base)
-          raise ArgumentError, "#{base} must descent from Hashie::Mash" unless base <= Hashie::Mash
+          return if base <= Hashie::Mash
+
+          raise ArgumentError, "`#{base}` must descend from Hashie::Mash"
         end
 
         private

data/lib/hashie/extensions/mash/transform_keys.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Hashie
+  module Extensions
+    module Mash
+      # Applies a class-configured normalization to string and symbol Mash keys.
+      #
+      # @example
+      #   klass = Class.new(Hashie::Mash) do
+      #     include Hashie::Extensions::Mash::TransformKeys
+      #     transform_keys_with(&:downcase)
+      #   end
+      #   klass.new('NAME' => 'Ada').name # => 'Ada'
+      module TransformKeys
+        # @example Install class-level transformation configuration
+        #   klass = Class.new(Hashie::Mash) do
+        #     include Hashie::Extensions::Mash::TransformKeys
+        #   end
+        #   klass.key_transformer # => nil
+        def self.included(base)
+          raise ArgumentError, "`#{base}` must descend from Hashie::Mash" unless base <= Hashie::Mash
+
+          base.extend(ClassMethods)
+        end
+
+        # Configures key normalization independently for each subclass.
+        #
+        # @example
+        #   klass = Class.new(Hashie::Mash) do
+        #     include Hashie::Extensions::Mash::TransformKeys
+        #     transform_keys_with(&:downcase)
+        #   end
+        #   klass.new('NAME' => 'Ada')['name'] # => 'Ada'
+        module ClassMethods
+          # @example Inherit a transformer without sharing later configuration
+          #   parent = Class.new(Hashie::Mash) do
+          #     include Hashie::Extensions::Mash::TransformKeys
+          #     transform_keys_with(&:downcase)
+          #   end
+          #   child = Class.new(parent)
+          #   child.new('NAME' => 'Ada').name # => 'Ada'
+          #   child.transform_keys_with(&:upcase)
+          #   parent.new('NAME' => 'Ada').keys # => ['name']
+          def inherited(klass)
+            super
+            klass.instance_variable_set(:@key_transformer, key_transformer)
+          end
+
+          # @example Configure with a callable or a block
+          #   klass = Class.new(Hashie::Mash) do
+          #     include Hashie::Extensions::Mash::TransformKeys
+          #     transform_keys_with(->(key) { key.downcase })
+          #   end
+          #   klass.new('NAME' => 'Ada').keys # => ['name']
+          #   klass.transform_keys_with { |key| key.upcase }
+          #   klass.new(name: 'Ada').keys # => ['NAME']
+          def transform_keys_with(callable = nil, &block)
+            raise ArgumentError, 'provide one callable or block' if (callable && block) || !(callable || block).respond_to?(:call)
+
+            @key_transformer = callable || block
+          end
+
+          # @example Read the configured callable
+          #   klass = Class.new(Hashie::Mash) do
+          #     include Hashie::Extensions::Mash::TransformKeys
+          #     transform_keys_with(&:downcase)
+          #   end
+          #   klass.key_transformer.call('NAME') # => 'name'
+          attr_reader :key_transformer
+        end
+
+        private
+
+        def convert_key(key)
+          transformer = self.class.key_transformer
+          return super unless transformer && (key.is_a?(String) || key.is_a?(Symbol))
+
+          transformed = transformer.call(key.to_s)
+          raise TypeError, 'key transformer must return a String' unless transformed.is_a?(String)
+
+          super(transformed)
+        end
+      end
+    end
+  end
+end

data/lib/hashie/extensions/mash/underscore_keys.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'hashie/extensions/mash/transform_keys'
+
+module Hashie
+  module Extensions
+    module Mash
+      # Normalizes camel-case and hyphenated Mash keys to lowercase underscores.
+      #
+      # @example
+      #   klass = Class.new(Hashie::Mash) do
+      #     include Hashie::Extensions::Mash::UnderscoreKeys
+      #   end
+      #   klass.new('firstName' => 'Ada', 'last-name' => 'Lovelace').to_h # => {'first_name' => 'Ada', 'last_name' => 'Lovelace'}
+      module UnderscoreKeys
+        # @example Configure underscore normalization on inclusion
+        #   klass = Class.new(Hashie::Mash) do
+        #     include Hashie::Extensions::Mash::UnderscoreKeys
+        #   end
+        #   klass.key_transformer.call('HTTPStatus') # => 'http_status'
+        def self.included(base)
+          base.include(TransformKeys) unless base < TransformKeys
+          base.transform_keys_with do |key|
+            key.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+               .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+               .tr('-', '_').downcase
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hashie/extensions/merge_initializer.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
     # The MergeInitializer is a super-simple mixin that allows
@@ -15,6 +17,13 @@ module Hashie
     #   h[:abc] # => 'def'
     #
     module MergeInitializer
+      # @example Initialize entries and a default value
+      #   class InitializedHash < Hash
+      #     include Hashie::Extensions::MergeInitializer
+      #   end
+      #   hash = InitializedHash.new({ name: 'Ada' }, 'unknown')
+      #   hash[:name] # => 'Ada'
+      #   hash[:missing] # => 'unknown'
       def initialize(hash = {}, default = nil, &block)
         default ? super(default) : super(&block)
         hash.each do |key, value|