hashie 5.1.0 → 5.2.0

data/lib/hashie/rash.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Hashie
   #
   # Rash is a Hash whose keys can be Regexps, or Ranges, which will
@@ -20,9 +22,23 @@ module Hashie
   #       If this is too low or too high, you can tune it by
   #       setting: `rash.optimize_every = n`
   #
+  # @example Match strings and numbers using pattern keys
+  #   rash = Hashie::Rash.new(/^Mr\./ => 'Hello sir!', (1..5) => 'small')
+  #   rash['Mr. Austin'] # => 'Hello sir!'
+  #   rash[3] # => 'small'
   class Rash
+    # @example Configure the interval between regular-expression optimizations
+    #   rash = Hashie::Rash.new
+    #   rash.optimize_every # => 500
+    #   rash.optimize_every = 10
+    #   rash.optimize_every # => 10
     attr_accessor :optimize_every
 
+    # @example Initialize literal, regular-expression, and range keys
+    #   rash = Hashie::Rash.new('home' => 'index', /^user/ => 'profile', (1..5) => 'small')
+    #   rash['home'] # => 'index'
+    #   rash['user/1'] # => 'profile'
+    #   rash[2] # => 'small'
     def initialize(initial = {})
       @hash           = {}
       @regexes        = []
@@ -34,6 +50,11 @@ module Hashie
       update(initial)
     end
 
+    # @example Add patterns and overwrite existing literal keys
+    #   rash = Hashie::Rash.new('home' => 'old')
+    #   rash.update('home' => 'index', /^user/ => 'profile')
+    #   rash['home'] # => 'index'
+    #   rash['user/1'] # => 'profile'
     def update(other)
       other.each do |key, value|
         self[key] = value
@@ -42,6 +63,10 @@ module Hashie
       self
     end
 
+    # @example Assign a pattern with a callable value
+    #   rash = Hashie::Rash.new
+    #   rash[/^hello (.+)$/] = ->(match) { "Hello, #{match[1]}!" }
+    #   rash['hello Ada'] # => 'Hello, Ada!'
     def []=(key, value)
       case key
       when Regexp
@@ -56,6 +81,11 @@ module Hashie
     #
     # Return the first thing that matches the key.
     #
+    # @example Prefer literal matches and return nil for missing keys
+    #   rash = Hashie::Rash.new(/^user/ => 'profile', 'user/admin' => 'admin')
+    #   rash['user/admin'] # => 'admin'
+    #   rash['user/1'] # => 'profile'
+    #   rash['missing'] # => nil
     def [](key)
       all(key).first
     end
@@ -63,8 +93,22 @@ module Hashie
     #
     # Raise (or yield) unless something matches the key.
     #
+    # @example Fetch a match or compute a fallback
+    #   rash = Hashie::Rash.new(/^user/ => 'profile')
+    #   rash.fetch('user/1') # => 'profile'
+    #   rash.fetch('missing', 'fallback') # => 'fallback'
+    #   rash.fetch('missing') { |key| "unknown: #{key}" } # => 'unknown: missing'
+    #
+    # @example Raise for an unmatched key without a fallback
+    #   error = begin
+    #     Hashie::Rash.new.fetch('missing')
+    #   rescue KeyError => exception
+    #     exception
+    #   end
+    #   error.class # => KeyError
+    #   error.message # => 'key not found: `"missing"`'
     def fetch(*args)
-      raise ArgumentError, "Expected 1-2 arguments, got #{args.length}" \
+      raise ArgumentError, "expected 1-2 arguments, got `#{args.length}`" \
         unless (1..2).cover?(args.length)
 
       key, default = args
@@ -78,13 +122,19 @@ module Hashie
       elsif default
         default
       else
-        raise KeyError, "key not found: #{key.inspect}"
+        raise KeyError, "key not found: `#{key.inspect}`"
       end
     end
 
     #
     # Return everything that matches the query.
     #
+    # @example Enumerate all matching patterns
+    #   rash = Hashie::Rash.new(/^user/ => 'profile', /admin$/ => 'admin')
+    #   rash.all('user/admin').to_a # => ['profile', 'admin']
+    #   values = []
+    #   rash.all('user/admin') { |value| values << value }
+    #   values # => ['profile', 'admin']
     def all(query)
       return to_enum(:all, query) unless block_given?
 
@@ -101,6 +151,7 @@ module Hashie
         @regexes.each do |regex|
           match = regex.match(query)
           next unless match
+
           @regex_counts[regex] += 1
           value = @hash[regex]
           if value.respond_to? :call
@@ -124,10 +175,18 @@ module Hashie
       end
     end
 
-    def method_missing(*args, &block)
-      @hash.send(*args, &block) || super
+    # @example Delegate ordinary hash operations to stored entries
+    #   rash = Hashie::Rash.new('home' => 'index')
+    #   rash.keys # => ['home']
+    #   rash.size # => 1
+    def method_missing(...)
+      @hash.send(...) || super
     end
 
+    # @example Advertise delegated hash operations
+    #   rash = Hashie::Rash.new
+    #   rash.respond_to?(:keys) # => true
+    #   rash.respond_to?(:unknown_operation) # => false
     def respond_to_missing?(method_name, _include_private = false)
       @hash.respond_to?(method_name)
     end
@@ -136,6 +195,7 @@ module Hashie
 
     def optimize_if_necessary!
       return unless (@lookups += 1) >= @optimize_every
+
       @regexes = @regexes.sort_by { |regex| -@regex_counts[regex] }
       @lookups = 0
     end

data/lib/hashie/trash.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'hashie/dash'
 require 'hashie/extensions/dash/property_translation'
 
@@ -8,6 +10,12 @@ module Hashie
   # Trashes are useful when you need to read data from another application,
   # such as a Java api, where the keys are named differently from how we would
   # in Ruby.
+  #
+  # @example Translate incoming property names
+  #   klass = Class.new(Hashie::Trash) do
+  #     property :first_name, from: :firstName
+  #   end
+  #   klass.new(firstName: 'Ada').first_name # => 'Ada'
   class Trash < Dash
     include Hashie::Extensions::Dash::PropertyTranslation
   end

data/lib/hashie/utils.rb

@@ -1,10 +1,18 @@
+# frozen_string_literal: true
+
 module Hashie
   # A collection of helper methods that can be used throughout the gem.
+  #
+  # @example Duplicate mutable values safely
+  #   Hashie::Utils.safe_dup(['Ada']) # => ['Ada']
   module Utils
     # Describes a method by where it was defined.
     #
     # @param bound_method [Method] The method to describe.
     # @return [String]
+    #
+    # @example Describe a built-in method
+    #   Hashie::Utils.method_information('name'.method(:upcase)) # => 'defined in String'
     def self.method_information(bound_method)
       if bound_method.source_location
         "defined at #{bound_method.source_location.join(':')}"
@@ -19,6 +27,14 @@ module Hashie
     #
     # @param value [Object] the value to safely duplicate
     # @return [Object] the duplicated value
+    #
+    # @example Copy a mutable value without copying immutable symbols
+    #   original = ['Ada']
+    #   copy = Hashie::Utils.safe_dup(original)
+    #   copy << 'Grace'
+    #   original # => ['Ada']
+    #   copy # => ['Ada', 'Grace']
+    #   Hashie::Utils.safe_dup(:name) # => :name
     def self.safe_dup(value)
       case value
       when Complex, FalseClass, NilClass, Rational, Method, Symbol, TrueClass, *integer_classes
@@ -33,12 +49,7 @@ module Hashie
     # @api private
     # @return [Array<Class>]
     def self.integer_classes
-      @integer_classes ||=
-        if 0.class == Integer
-          [Integer]
-        else
-          [Fixnum, Bignum] # rubocop:disable Lint/UnifiedInteger
-        end
+      @integer_classes ||= [Integer]
     end
   end
 end

data/lib/hashie/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Hashie
-  VERSION = '5.1.0'.freeze
+  VERSION = '5.2.0'
 end

data/lib/hashie.rb

@@ -1,6 +1,12 @@
+# frozen_string_literal: true
+
 require 'hashie/logger'
 require 'hashie/version'
 
+# Hash-like objects and extensions for structured data.
+#
+# @example Access nested data using a Mash
+#   Hashie::Mash.new(author: { name: 'Ada' }).author.name # => 'Ada'
 module Hashie
   autoload :Clash,              'hashie/clash'
   autoload :Dash,               'hashie/dash'
@@ -11,9 +17,17 @@ module Hashie
   autoload :Array,              'hashie/array'
   autoload :Utils,              'hashie/utils'
 
+  # Optional capabilities for Hash-like objects.
+  #
+  # @example Add recursive string keys to an ordinary hash
+  #   hash = { count: 2 }.extend(Hashie::Extensions::StringifyKeys)
+  #   hash.stringify_keys # => { 'count' => 2 }
   module Extensions
+    autoload :BlockAccess,        'hashie/extensions/block_access'
     autoload :Coercion,           'hashie/extensions/coercion'
+    autoload :KernelCoercion,     'hashie/extensions/kernel_coercion'
     autoload :DeepMerge,          'hashie/extensions/deep_merge'
+    autoload :DeepMergeInitializer, 'hashie/extensions/deep_merge_initializer'
     autoload :IgnoreUndeclared,   'hashie/extensions/ignore_undeclared'
     autoload :IndifferentAccess,  'hashie/extensions/indifferent_access'
     autoload :MergeInitializer,   'hashie/extensions/merge_initializer'
@@ -21,11 +35,13 @@ module Hashie
     autoload :MethodQuery,        'hashie/extensions/method_access'
     autoload :MethodReader,       'hashie/extensions/method_access'
     autoload :MethodWriter,       'hashie/extensions/method_access'
+    autoload :Persistable,        'hashie/extensions/persistable'
     autoload :StringifyKeys,      'hashie/extensions/stringify_keys'
     autoload :SymbolizeKeys,      'hashie/extensions/symbolize_keys'
     autoload :DeepFetch,          'hashie/extensions/deep_fetch'
     autoload :DeepFind,           'hashie/extensions/deep_find'
     autoload :DeepLocate,         'hashie/extensions/deep_locate'
+    autoload :DeepGrep,           'hashie/extensions/deep_grep'
     autoload :PrettyInspect,      'hashie/extensions/pretty_inspect'
     autoload :KeyConversion,      'hashie/extensions/key_conversion'
     autoload :MethodAccessWithOverride, 'hashie/extensions/method_access'
@@ -33,25 +49,54 @@ module Hashie
     autoload :RubyVersion,        'hashie/extensions/ruby_version'
     autoload :RubyVersionCheck,   'hashie/extensions/ruby_version_check'
 
+    # Parsers used when loading persisted hashes.
+    #
+    # @example Select the YAML parser without ERB evaluation
+    #   Hashie::Extensions::Parsers::YamlParser.respond_to?(:perform) # => true
     module Parsers
+      autoload :YamlParser, 'hashie/extensions/parsers/yaml_parser'
       autoload :YamlErbParser, 'hashie/extensions/parsers/yaml_erb_parser'
     end
 
+    # Optional extensions for defined-property hashes.
+    #
+    # @example Allow string access to declared symbol properties
+    #   klass = Class.new(Hashie::Dash) do
+    #     include Hashie::Extensions::Dash::IndifferentAccess
+    #     property :name
+    #   end
+    #   klass.new(name: 'Ada')['name'] # => 'Ada'
     module Dash
       autoload :IndifferentAccess, 'hashie/extensions/dash/indifferent_access'
       autoload :PropertyTranslation, 'hashie/extensions/dash/property_translation'
       autoload :Coercion, 'hashie/extensions/dash/coercion'
+      autoload :Lazy, 'hashie/extensions/dash/lazy'
       autoload :PredefinedValues, 'hashie/extensions/dash/predefined_values'
     end
 
+    # Optional extensions for method-accessible hashes.
+    #
+    # @example Generate accessors for existing keys
+    #   mash = Hashie::Mash.new(name: 'Ada')
+    #   mash.extend(Hashie::Extensions::Mash::DefineAccessors)
+    #   mash.name # => 'Ada'
     module Mash
       autoload :KeepOriginalKeys, 'hashie/extensions/mash/keep_original_keys'
       autoload :PermissiveRespondTo, 'hashie/extensions/mash/permissive_respond_to'
       autoload :SafeAssignment, 'hashie/extensions/mash/safe_assignment'
       autoload :SymbolizeKeys, 'hashie/extensions/mash/symbolize_keys'
       autoload :DefineAccessors, 'hashie/extensions/mash/define_accessors'
+      autoload :StrictKeyAccess, 'hashie/extensions/mash/strict_key_access'
+      autoload :RequiredKeys, 'hashie/extensions/mash/required_keys'
+      autoload :TransformKeys, 'hashie/extensions/mash/transform_keys'
+      autoload :UnderscoreKeys, 'hashie/extensions/mash/underscore_keys'
     end
 
+    # Optional extensions for arrays.
+    #
+    # @example Add Hashie-style inspection to an array
+    #   klass = Class.new(::Array) { include Hashie::Extensions::Array::PrettyInspect }
+    #   klass.new([1, 2]).inspect # => "#<#{klass} [1, 2]>"
     module Array
       autoload :PrettyInspect, 'hashie/extensions/array/pretty_inspect'
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hashie
 version: !ruby/object:Gem::Version
-  version: 5.1.0
+  version: 5.2.0
 platform: ruby
 authors:
 - Michael Bleigh
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-12-24 00:00:00.000000000 Z
+date: 2026-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger
@@ -25,20 +25,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 description: Hashie is a collection of classes and mixins that make hashes more powerful.
 email:
 - michael@intridea.com
@@ -61,27 +47,38 @@ files:
 - lib/hashie/dash.rb
 - lib/hashie/extensions/active_support/core_ext/hash.rb
 - lib/hashie/extensions/array/pretty_inspect.rb
+- lib/hashie/extensions/block_access.rb
 - lib/hashie/extensions/coercion.rb
 - lib/hashie/extensions/dash/coercion.rb
 - lib/hashie/extensions/dash/indifferent_access.rb
+- lib/hashie/extensions/dash/lazy.rb
 - lib/hashie/extensions/dash/predefined_values.rb
 - lib/hashie/extensions/dash/property_translation.rb
 - lib/hashie/extensions/deep_fetch.rb
 - lib/hashie/extensions/deep_find.rb
+- lib/hashie/extensions/deep_grep.rb
 - lib/hashie/extensions/deep_locate.rb
 - lib/hashie/extensions/deep_merge.rb
+- lib/hashie/extensions/deep_merge_initializer.rb
 - lib/hashie/extensions/ignore_undeclared.rb
 - lib/hashie/extensions/indifferent_access.rb
+- lib/hashie/extensions/kernel_coercion.rb
 - lib/hashie/extensions/key_conflict_warning.rb
 - lib/hashie/extensions/key_conversion.rb
 - lib/hashie/extensions/mash/define_accessors.rb
 - lib/hashie/extensions/mash/keep_original_keys.rb
 - lib/hashie/extensions/mash/permissive_respond_to.rb
+- lib/hashie/extensions/mash/required_keys.rb
 - lib/hashie/extensions/mash/safe_assignment.rb
+- lib/hashie/extensions/mash/strict_key_access.rb
 - lib/hashie/extensions/mash/symbolize_keys.rb
+- lib/hashie/extensions/mash/transform_keys.rb
+- lib/hashie/extensions/mash/underscore_keys.rb
 - lib/hashie/extensions/merge_initializer.rb
 - lib/hashie/extensions/method_access.rb
 - lib/hashie/extensions/parsers/yaml_erb_parser.rb
+- lib/hashie/extensions/parsers/yaml_parser.rb
+- lib/hashie/extensions/persistable.rb
 - lib/hashie/extensions/pretty_inspect.rb
 - lib/hashie/extensions/ruby_version.rb
 - lib/hashie/extensions/ruby_version_check.rb
@@ -104,6 +101,7 @@ metadata:
   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
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -112,7 +110,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="