hashie 4.1.0 → 5.2.0

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rubygems'
 require 'bundler'
 Bundler.setup
@@ -10,12 +12,39 @@ RSpec::Core::RakeTask.new do |spec|
   spec.exclude_pattern = 'spec/integration/**/*_spec.rb'
 end
 
+namespace :docs do
+  desc 'Validate executable YARD examples and public API documentation coverage'
+  task :examples do
+    ruby '-Ilib', 'script/test_documentation_examples.rb'
+  end
+
+  desc 'Validate every README Ruby example with the isolated documentation bundle'
+  task :readme do
+    Bundler.with_unbundled_env do
+      sh({ 'BUNDLE_GEMFILE' => 'spec/documentation/Gemfile' }, 'bundle', 'exec', 'ruby', '-Ilib', 'script/test_readme_examples.rb')
+    end
+  end
+end
+
 require 'rubocop/rake_task'
 RuboCop::RakeTask.new(:rubocop)
+if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('3.2')
+  RuboCop::RakeTask.new(:rubocop_exception_messages) do |task|
+    task.patterns = ['lib/**/*.rb', 'spec/**/*.rb']
+    task.options = [
+      '--only',
+      'ExceptionMessages/Casing,ExceptionMessages/Punctuation,' \
+      'ExceptionMessages/QuoteStyle,ExceptionMessages/RedundantExceptionName'
+    ]
+  end
+  Rake::Task[:rubocop].enhance([:rubocop_exception_messages])
+end
 
 require_relative 'spec/support/integration_specs'
+desc 'Install integration dependencies and run integration specs'
 task :integration_specs do
   next if ENV['CI']
+
   status_codes = []
   handler = lambda do |status_code|
     status_codes << status_code unless status_code.zero?
@@ -29,4 +58,6 @@ task :integration_specs do
   end
 end
 
-task default: %i[rubocop spec integration_specs]
+default_tasks = %i[spec integration_specs]
+default_tasks.unshift(:rubocop) if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('3.2')
+task default: default_tasks

data/UPGRADING.md

@@ -1,6 +1,62 @@
 Upgrading Hashie
 ================
 
+### Upgrading to 5.2.0
+
+#### Safer YAML loading
+
+`Hashie::Mash.load` continues to use `YamlErbParser` by default for compatibility, and that parser evaluates ERB. Do not load untrusted input with the default parser. To opt in to YAML parsing without ERB evaluation, pass `parser: Hashie::Extensions::Parsers::YamlParser`.
+
+#### Ruby version
+
+Hashie now requires Ruby 3.0 or newer. Ruby 2.7 is no longer supported; upgrade Ruby before updating Hashie.
+
+#### Exception messages
+
+Exception messages now begin with lowercase words, omit trailing periods, quote interpolated values
+with backticks, and use consistent wording. Exception classes and the conditions under which
+exceptions are raised have not changed.
+
+Applications and tests that compare exact exception message strings must update their expectations.
+
+### Upgrading to 5.0.0
+
+#### Mash initialization key conversion
+
+Mash initialization now only converts to string keys which can be represented as symbols.
+
+```ruby
+Hashie::Mash.new(
+  {foo: "bar"} => "baz",
+  "1" => "one string",
+  :"1" => "one sym",
+  1 => "one num"
+)
+
+# Before
+{"{:foo=>\"bar\"}"=>"baz", "1"=>"one num"}
+
+# After
+{{:foo=>"bar"}=>"baz", "1"=>"one sym", 1=>"one num"}
+```
+
+#### Mash#dig with numeric keys
+
+`Hashie::Mash#dig` no longer considers numeric keys for indifferent access.
+
+```ruby
+my_mash = Hashie::Mash.new("1" => "a") # => {"1"=>"a"}
+
+my_mash.dig("1") # => "a"
+my_mash.dig(:"1") # => "a"
+
+# Before
+my_mash.dig(1) # => "a"
+
+# After
+my_mash.dig(1) # => nil
+```
+
 ### Upgrading to 4.0.0
 
 #### Non-destructive Hash methods called on Mash

data/hashie.gemspec

@@ -1,4 +1,6 @@
-require File.expand_path('../lib/hashie/version', __FILE__)
+# frozen_string_literal: true
+
+require File.expand_path('lib/hashie/version', __dir__)
 
 Gem::Specification.new do |gem|
   gem.name          = 'hashie'
@@ -17,12 +19,15 @@ Gem::Specification.new do |gem|
 
   if gem.respond_to?(:metadata)
     gem.metadata = {
-      'bug_tracker_uri'   => 'https://github.com/hashie/hashie/issues',
-      'changelog_uri'     => 'https://github.com/hashie/hashie/blob/master/CHANGELOG.md',
+      'bug_tracker_uri' => 'https://github.com/hashie/hashie/issues',
+      'changelog_uri' => 'https://github.com/hashie/hashie/blob/master/CHANGELOG.md',
       'documentation_uri' => 'https://www.rubydoc.info/gems/hashie',
-      'source_code_uri'   => 'https://github.com/hashie/hashie'
+      'source_code_uri' => 'https://github.com/hashie/hashie',
+      'rubygems_mfa_required' => 'true'
     }
   end
 
-  gem.add_development_dependency 'bundler'
+  gem.required_ruby_version = '>= 3.0'
+
+  gem.add_dependency 'logger' # for Ruby >= 3.4
 end

data/lib/hashie/array.rb

@@ -1,21 +1,24 @@
+# frozen_string_literal: true
+
 require 'hashie/extensions/array/pretty_inspect'
-require 'hashie/extensions/ruby_version_check'
 
 module Hashie
+  # An array with readable inspection and string-index digging.
+  #
+  # @example Build a Hashie array
+  #   Hashie::Array[10, 20].dig('1') # => 20
   class Array < ::Array
     include Hashie::Extensions::Array::PrettyInspect
-    include Hashie::Extensions::RubyVersionCheck
-    with_minimum_ruby('2.3.0') do
-      def dig(*indexes)
-        converted_indexes = indexes.map do |idx|
-          begin
-            Integer(idx)
-          rescue ArgumentError
-            idx
-          end
-        end
-        super(*converted_indexes)
+
+    # @example Accept string indexes when traversing nested arrays
+    #   Hashie::Array[Hashie::Array['first', 'second']].dig('0', '1') # => 'second'
+    def dig(*indexes)
+      converted_indexes = indexes.map do |idx|
+        Integer(idx)
+      rescue ArgumentError
+        idx
       end
+      super(*converted_indexes)
     end
   end
 end

data/lib/hashie/clash.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'hashie/hash'
 
 module Hashie
@@ -21,14 +23,34 @@ module Hashie
   # all keys are converted to symbols since many libraries expect symbols explicitly
   # for keys.
   #
+  # @example Build an options hash through chained calls
+  #   options = Hashie::Clash.new.conditions!.active(true)._end!.limit(10)
+  #   options # => { conditions: { active: true }, limit: 10 }
   class Clash < ::Hash
+    # Raised when bang chaining encounters a value that is not a hash.
+    #
+    # @example Reject chaining into a scalar
+    #   error = begin
+    #     Hashie::Clash.new(limit: 10).limit!
+    #   rescue Hashie::Clash::ChainError => exception
+    #     exception
+    #   end
+    #   error.class # => Hashie::Clash::ChainError
+    #   error.message # => 'tried to chain into a non-hash key'
     class ChainError < ::StandardError; end
     # The parent Clash if this Clash was created via chaining.
+    #
+    # @example Find the containing options hash
+    #   root = Hashie::Clash.new
+    #   root.conditions!._parent.equal?(root) # => true
     attr_reader :_parent
 
     # Initialize a new clash by passing in a Hash to
     # convert and, optionally, the parent to which this
     # Clash is chained.
+    #
+    # @example Normalize initial keys to symbols
+    #   Hashie::Clash.new('limit' => 10) # => { limit: 10 }
     def initialize(other_hash = {}, parent = nil)
       @_parent = parent
       other_hash.each_pair do |k, v|
@@ -42,15 +64,40 @@ module Hashie
     # c = Hashie::Clash.new.foo('bar')
     # c.baz!.foo(123) # => c[:baz]
     # c.baz!._end! # => c
+    #
+    # @example Continue building the parent hash
+    #   Hashie::Clash.new.conditions!.active(true)._end!.limit(10) # => { conditions: { active: true }, limit: 10 }
     def _end!
       _parent
     end
 
-    def id(*args) #:nodoc:
+    # @example Serialize a Clash through YAML's encoding callback
+    #   require 'yaml'
+    #   options = Hashie::Clash.new.limit(10)
+    #   YAML.unsafe_load(YAML.dump(options)) # => { limit: 10 }
+    def encode_with(coder)
+      coder['hash'] = to_h
+      coder['parent'] = _parent
+    end
+
+    # @example Restore a chained Clash through YAML's loading callback
+    #   require 'yaml'
+    #   root = Hashie::Clash.new.conditions!.active(true)._end!
+    #   restored = YAML.unsafe_load(YAML.dump(root))
+    #   restored[:conditions]._parent.equal?(restored) # => true
+    def init_with(coder)
+      initialize(coder['hash'], coder['parent'])
+    end
+
+    # @example Build an id option without colliding with object identity
+    #   Hashie::Clash.new.id(42) # => { id: 42 }
+    def id(*args) # :nodoc:
       method_missing(:id, *args)
     end
 
-    def merge_store(key, *args) #:nodoc:
+    # @example Merge repeated hash options through chained builder calls
+    #   Hashie::Clash.new.conditions(active: true).conditions(role: 'admin') # => { conditions: { active: true, role: 'admin' } }
+    def merge_store(key, *args) # :nodoc:
       case args.length
       when 1
         val = args.first
@@ -63,7 +110,9 @@ module Hashie
       self
     end
 
-    def method_missing(name, *args) #:nodoc:
+    # @example Build nested options with dynamic method names
+    #   Hashie::Clash.new.conditions!.active(true)._end!.limit(10) # => { conditions: { active: true }, limit: 10 }
+    def method_missing(name, *args) # :nodoc:
       if args.empty? && name.to_s.end_with?('!')
         key = name[0...-1].to_sym
 
@@ -75,7 +124,7 @@ module Hashie
         when Hash
           self[key] = self.class.new(self[key], self)
         else
-          raise ChainError, 'Tried to chain into a non-hash key.'
+          raise ChainError, 'tried to chain into a non-hash key'
         end
       elsif args.any?
         merge_store(name, *args)
@@ -84,8 +133,14 @@ module Hashie
       end
     end
 
+    # @example Discover supported builder calls
+    #   options = Hashie::Clash.new(limit: 10)
+    #   options.respond_to?(:conditions!) # => true
+    #   options.respond_to?(:limit!) # => false
+    #   options.respond_to?(:order) # => true
     def respond_to_missing?(method_name, _include_private = false)
       method_name = method_name.to_s
+      return super if %w[marshal_dump marshal_load _dump _load].include?(method_name)
 
       if method_name.end_with?('!')
         key = method_name[0...-1].to_sym

data/lib/hashie/dash.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'hashie/hash'
 require 'set'
 
@@ -10,29 +12,42 @@ module Hashie
   # lightweight data object that needs even fewer options and
   # resources than something like a DataMapper resource.
   #
-  # It is preferrable to a Struct because of the in-class
+  # It is preferable to a Struct because of the in-class
   # API for defining properties as well as per-property defaults.
+  #
+  # @example Define a lightweight data object
+  #   klass = Class.new(Hashie::Dash) { property :name, default: 'Ada' }
+  #   klass.new.name # => 'Ada'
   class Dash < Hash
     include Hashie::Extensions::PrettyInspect
 
+    # @example Inspect declared properties
+    #   klass = Class.new(Hashie::Dash) { property :name }
+    #   klass.new(name: 'Ada').to_s.include?('name="Ada"') # => true
     alias to_s inspect
 
     # Defines a property on the Dash. Options are
     # as follows:
     #
-    # * <tt>:default</tt> - Specify a default value for this property,
+    # * `:default` - Specify a default value for this property,
     #   to be returned before a value is set on the property in a new
     #   Dash.
     #
-    # * <tt>:required</tt> - Specify the value as required for this
+    # * `:required` - Specify the value as required for this
     #   property, to raise an error if a value is unset in a new or
     #   existing Dash. If a Proc is provided, it will be run in the
     #   context of the Dash instance. If a Symbol is provided, the
     #   property it represents must not be nil. The property is only
     #   required if the value is truthy.
     #
-    # * <tt>:message</tt> - Specify custom error message for required property
+    # * `:message` - Specify custom error message for required property
     #
+    # @example Declare a required property and a default
+    #   klass = Class.new(Hashie::Dash) do
+    #     property :name, required: true
+    #     property :active, default: true
+    #   end
+    #   klass.new(name: 'Ada').to_h # => { name: 'Ada', active: true }
     def self.property(property_name, options = {})
       properties << property_name
 
@@ -49,16 +64,32 @@ module Hashie
 
       condition = options.delete(:required)
       if condition
-        message = options.delete(:message) || "is required for #{name}."
+        message = options.delete(:message) || "is required for `#{name}`"
         required_properties[property_name] = { condition: condition, message: message }
       elsif options.key?(:message)
-        raise ArgumentError, 'The :message option should be used with :required option.'
+        raise ArgumentError, 'the :message option should be used with :required option'
       end
     end
 
     class << self
-      attr_reader :properties, :defaults
+      # @example List the declared properties
+      #   klass = Class.new(Hashie::Dash) { property :name }
+      #   klass.properties.to_a # => [:name]
+      attr_reader :properties
+
+      # @example Read declared default values
+      #   klass = Class.new(Hashie::Dash) { property :active, default: true }
+      #   klass.defaults # => { active: true }
+      attr_reader :defaults
+
+      # @example List generated getter names
+      #   klass = Class.new(Hashie::Dash) { property :name }
+      #   klass.getters.to_a # => [:name]
       attr_reader :getters
+
+      # @example Inspect the requirement configured for a property
+      #   klass = Class.new(Hashie::Dash) { property :name, required: true, message: 'must be supplied' }
+      #   klass.required_properties # => { name: { condition: true, message: 'must be supplied' } }
       attr_reader :required_properties
     end
     instance_variable_set('@properties', Set.new)
@@ -66,6 +97,11 @@ module Hashie
     instance_variable_set('@defaults', {})
     instance_variable_set('@required_properties', {})
 
+    # @example Subclasses inherit independent property definitions
+    #   parent = Class.new(Hashie::Dash) { property :name, default: 'Ada' }
+    #   child = Class.new(parent) { property :active, default: true }
+    #   child.new.to_h # => { name: 'Ada', active: true }
+    #   parent.properties.to_a # => [:name]
     def self.inherited(klass)
       super
       (@subclasses ||= Set.new) << klass
@@ -77,46 +113,52 @@ module Hashie
 
     # Check to see if the specified property has already been
     # defined.
+    #
+    # @example Check declared and undeclared properties
+    #   klass = Class.new(Hashie::Dash) { property :name }
+    #   klass.property?(:name) # => true
+    #   klass.property?(:missing) # => false
     def self.property?(name)
       properties.include? name
     end
 
     # Check to see if the specified property is
     # required.
+    #
+    # @example Identify a required declaration
+    #   klass = Class.new(Hashie::Dash) { property :name, required: true }
+    #   klass.required?(:name) # => true
+    #   klass.required?(:missing) # => false
     def self.required?(name)
       required_properties.key? name
     end
 
     private_class_method def self.define_getter_for(property_name)
       return if getters.include?(property_name)
+
       define_method(property_name) { |&block| self.[](property_name, &block) }
       getters << property_name
     end
 
     private_class_method def self.define_setter_for(property_name)
       setter = :"#{property_name}="
-      return if instance_methods.include?(setter)
+      return if method_defined?(setter)
+
       define_method(setter) { |value| self.[]=(property_name, value) }
     end
 
     # You may initialize a Dash with an attributes hash
     # just like you would many other kinds of data objects.
+    #
+    # @example Initialize declared attributes and defaults
+    #   klass = Class.new(Hashie::Dash) do
+    #     property :name
+    #     property :active, default: true
+    #   end
+    #   klass.new(name: 'Ada').to_h # => { name: 'Ada', active: true }
     def initialize(attributes = {}, &block)
       super(&block)
 
-      self.class.defaults.each_pair do |prop, value|
-        self[prop] = begin
-          val = value.dup
-          if val.is_a?(Proc)
-            val.arity == 1 ? val.call(self) : val.call
-          else
-            val
-          end
-        rescue TypeError
-          value
-        end
-      end
-
       initialize_attributes(attributes)
       assert_required_attributes_set!
     end
@@ -127,9 +169,13 @@ module Hashie
 
     # Retrieve a value from the Dash (will return the
     # property's default value if it hasn't been set).
+    #
+    # @example Read a declared value by key
+    #   klass = Class.new(Hashie::Dash) { property :name, default: 'Ada' }
+    #   klass.new[:name] # => 'Ada'
     def [](property)
       assert_property_exists! property
-      value = super(property)
+      value = super
       # If the value is a lambda, proc, or whatever answers to call, eval the thing!
       if value.is_a? Proc
         self[property] = value.call # Set the result of the call as a value
@@ -141,12 +187,23 @@ module Hashie
 
     # Set a value on the Dash in a Hash-like way. Only works
     # on pre-existing properties.
+    #
+    # @example Assign a declared property
+    #   klass = Class.new(Hashie::Dash) { property :name }
+    #   dash = klass.new
+    #   dash[:name] = 'Ada'
+    #   dash.name # => 'Ada'
     def []=(property, value)
       assert_property_required! property, value
       assert_property_exists! property
-      super(property, value)
+      super
     end
 
+    # @example Merge into a copy with conflict resolution
+    #   klass = Class.new(Hashie::Dash) { property :count }
+    #   dash = klass.new(count: 2)
+    #   dash.merge(count: 3) { |_key, old, new| old + new }.to_h # => { count: 5 }
+    #   dash.count # => 2
     def merge(other_hash)
       new_dash = dup
       other_hash.each do |k, v|
@@ -155,6 +212,11 @@ module Hashie
       new_dash
     end
 
+    # @example Merge declared values in place
+    #   klass = Class.new(Hashie::Dash) { property :name }
+    #   dash = klass.new(name: 'Ada')
+    #   dash.merge!(name: 'Grace')
+    #   dash.name # => 'Grace'
     def merge!(other_hash)
       other_hash.each do |k, v|
         self[k] = block_given? ? yield(k, self[k], v) : v
@@ -162,6 +224,13 @@ module Hashie
       self
     end
 
+    # @example Restore defaults for omitted attributes
+    #   klass = Class.new(Hashie::Dash) do
+    #     property :name
+    #     property :active, default: true
+    #   end
+    #   dash = klass.new(name: 'Ada', active: false)
+    #   dash.replace(name: 'Grace').to_h # => { name: 'Grace', active: true }
     def replace(other_hash)
       other_hash = self.class.defaults.merge(other_hash)
       (keys - other_hash.keys).each { |key| delete(key) }
@@ -169,17 +238,61 @@ module Hashie
       self
     end
 
+    # @example Include declared but unset properties in a plain hash
+    #   klass = Class.new(Hashie::Dash) { property :name }
+    #   klass.new.to_h # => { name: nil }
+    #   klass.new.to_h.class # => Hash
+    def to_h
+      defaults = self.class.properties.to_h { |prop| [prop, self.class.defaults[prop]] }
+
+      defaults.merge(self)
+    end
+    # @example Convert a Dash to a plain hash
+    #   klass = Class.new(Hashie::Dash) { property :name }
+    #   klass.new(name: 'Ada').to_hash # => { name: 'Ada' }
+    alias to_hash to_h
+
+    # ActiveSupport's Hash#deep_transform_keys builds up its result via
+    # `self.class.new`, expecting to be able to start from an empty hash
+    # and fill in keys one at a time. Since Dash enforces required
+    # properties at initialization and restricts which keys may be set,
+    # this breaks for Dash (and Trash) - see
+    # https://github.com/hashie/hashie/issues/559. Deep transforming a
+    # Dash's keys no longer produces a valid Dash anyway (the resulting
+    # keys may not correspond to any defined property), so fall back to
+    # operating on a plain Hash instead.
+    #
+    # @example Transform nested keys without Dash's property restrictions
+    #   klass = Class.new(Hashie::Dash) { property :user }
+    #   dash = klass.new(user: { name: 'Ada' })
+    #   dash.deep_transform_keys(&:to_s) # => { 'user' => { 'name' => 'Ada' } }
+    def deep_transform_keys(&block)
+      _deep_transform_keys_in_object(to_h, &block)
+    end
+
+    # @example Update attributes and reapply defaults for nil values
+    #   klass = Class.new(Hashie::Dash) { property :name, default: 'Ada' }
+    #   dash = klass.new(name: 'Grace')
+    #   dash.update_attributes!(name: nil)
+    #   dash.name # => 'Ada'
     def update_attributes!(attributes)
       update_attributes(attributes)
 
       self.class.defaults.each_pair do |prop, value|
-        next unless self[prop].nil?
+        next unless fetch(prop, nil).nil?
+
         self[prop] = begin
-          value.dup
+          val = value.dup
+          if val.is_a?(Proc)
+            val.arity == 1 ? val.call(self) : val.call
+          else
+            val
+          end
         rescue TypeError
           value
         end
       end
+
       assert_required_attributes_set!
     end
 
@@ -188,8 +301,8 @@ module Hashie
     def initialize_attributes(attributes)
       return unless attributes
 
-      cleaned_attributes = attributes.reject { |_attr, value| value.nil? }
-      update_attributes(cleaned_attributes)
+      cleaned_attributes = attributes.compact
+      update_attributes!(cleaned_attributes)
     end
 
     def update_attributes(attributes)
@@ -211,23 +324,25 @@ module Hashie
     end
 
     def assert_property_set!(property)
-      fail_property_required_error!(property) if send(property).nil? && required?(property)
+      fail_property_required_error!(property) if send(property).nil? && _required?(property)
     end
 
     def assert_property_required!(property, value)
-      fail_property_required_error!(property) if value.nil? && required?(property)
+      fail_property_required_error!(property) if value.nil? && _required?(property)
     end
 
     def fail_property_required_error!(property)
+      message = self.class.required_properties[property][:message]
       raise ArgumentError,
-            "The property '#{property}' #{self.class.required_properties[property][:message]}"
+            "the property `#{property}` " + message
     end
 
     def fail_no_property_error!(property)
-      raise NoMethodError, "The property '#{property}' is not defined for #{self.class.name}."
+      raise NoMethodError,
+            "the property `#{property}` is not defined for `#{self.class.name || 'anonymous class'}`"
     end
 
-    def required?(property)
+    def _required?(property)
       return false unless self.class.required?(property)
 
       condition = self.class.required_properties[property][:condition]
@@ -237,5 +352,18 @@ module Hashie
       else             !!condition
       end
     end
+
+    def _deep_transform_keys_in_object(object, &block)
+      case object
+      when ::Hash
+        object.each_with_object({}) do |(key, value), result|
+          result[yield(key)] = _deep_transform_keys_in_object(value, &block)
+        end
+      when ::Array
+        object.map { |e| _deep_transform_keys_in_object(e, &block) }
+      else
+        object
+      end
+    end
   end
 end