hashie 5.1.0 → 5.2.0

data/lib/hashie/extensions/method_access.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
     # MethodReader allows you to access keys of the hash
@@ -25,13 +27,22 @@ module Hashie
     #   user[:birthday] = nil
     #   user.birthday # => nil
     #
-    #   user.not_declared # => NoMethodError
+    #   expect { user.not_declared }.to raise_error(NoMethodError)
     module MethodReader
+      # @example Advertise readers for existing keys
+      #   hash = { name: 'Ada' }.extend(Hashie::Extensions::MethodReader)
+      #   hash.respond_to?(:name) # => true
+      #   hash.respond_to?(:missing) # => false
       def respond_to_missing?(name, include_private = false)
         return true if key?(name.to_s) || key?(name.to_sym)
+
         super
       end
 
+      # @example Read both symbol and string keys
+      #   hash = { name: 'Ada', 'age' => 42 }.extend(Hashie::Extensions::MethodReader)
+      #   hash.name # => 'Ada'
+      #   hash.age # => 42
       def method_missing(name, *args)
         if key?(name)
           self[name]
@@ -67,19 +78,29 @@ module Hashie
     #   h['awesome'] # => 'sauce'
     #
     module MethodWriter
+      # @example Advertise arbitrary writers
+      #   hash = {}.extend(Hashie::Extensions::MethodWriter)
+      #   hash.respond_to?(:name=) # => true
+      #   hash.respond_to?(:name) # => false
       def respond_to_missing?(name, include_private = false)
         return true if name.to_s =~ /=$/
+
         super
       end
 
+      # @example Write string keys with assignment syntax
+      #   hash = {}.extend(Hashie::Extensions::MethodWriter)
+      #   hash.name = 'Ada'
+      #   hash # => { 'name' => 'Ada' }
       def method_missing(name, *args)
-        if args.size == 1 && name.to_s =~ /(.*)=$/
-          return self[convert_key(Regexp.last_match[1])] = args.first
-        end
+        return self[convert_key(Regexp.last_match[1])] = args.first if args.size == 1 && name.to_s =~ /(.*)=$/
 
         super
       end
 
+      # @example Normalize a writer key
+      #   hash = {}.extend(Hashie::Extensions::MethodWriter)
+      #   hash.convert_key(:name) # => 'name'
       def convert_key(key)
         key.to_s
       end
@@ -104,8 +125,12 @@ module Hashie
     #   h.abc? # => true
     #   h['def'] = nil
     #   h.def? # => false
-    #   h.hji? # => NoMethodError
+    #   expect { h.hji? }.to raise_error(NoMethodError)
     module MethodQuery
+      # @example Advertise queries for present keys, including nil values
+      #   hash = { name: nil }.extend(Hashie::Extensions::MethodQuery)
+      #   hash.respond_to?(:name?) # => true
+      #   hash.respond_to?(:missing?) # => false
       def respond_to_missing?(name, include_private = false)
         if query_method?(name) && indifferent_key?(key_from_query_method(name))
           true
@@ -114,6 +139,10 @@ module Hashie
         end
       end
 
+      # @example Query the truthiness of values
+      #   hash = { active: true, disabled: nil }.extend(Hashie::Extensions::MethodQuery)
+      #   hash.active? # => true
+      #   hash.disabled? # => false
       def method_missing(name, *args)
         return super unless args.empty?
 
@@ -148,6 +177,12 @@ module Hashie
     # A macro module that will automatically include MethodReader,
     # MethodWriter, and MethodQuery, giving you the ability to read,
     # write, and query keys in a hash using method call shortcuts.
+    #
+    # @example Read, write, and query through methods
+    #   hash = {}.extend(Module.new { include Hashie::Extensions::MethodAccess })
+    #   hash.name = 'Ada'
+    #   hash.name # => 'Ada'
+    #   hash.name? # => true
     module MethodAccess
       def self.included(base)
         [MethodReader, MethodWriter, MethodQuery].each do |mod|
@@ -158,6 +193,16 @@ module Hashie
 
     # A module shared between MethodOverridingWriter and MethodOverridingInitializer
     # to contained shared logic. This module aids in redefining existing hash methods.
+    #
+    # @example Preserve an overridden method under a double-underscore alias
+    #   require 'hashie/extensions/method_access'
+    #   class OverridingHash < Hash
+    #     include Hashie::Extensions::MethodOverridingWriter
+    #   end
+    #   hash = OverridingHash.new
+    #   hash.size = 'large'
+    #   hash.size # => 'large'
+    #   hash.__size # => 1
     module RedefineMethod
       protected
 
@@ -185,6 +230,7 @@ module Hashie
     # appropriately as true.
     #
     # @example
+    #   require 'hashie/extensions/method_access'
     #   class MyHash < Hash
     #     include Hashie::Extensions::MethodOverridingWriter
     #   end
@@ -194,15 +240,25 @@ module Hashie
     #   h['awesome'] # => 'sauce'
     #   h.zip = 'a-dee-doo-dah'
     #   h.zip # => 'a-dee-doo-dah'
-    #   h.__zip # => [[['awesome', 'sauce'], ['zip', 'a-dee-doo-dah']]]
+    #   h.__zip # => [[['awesome', 'sauce']], [['zip', 'a-dee-doo-dah']]]
     #
     module MethodOverridingWriter
       include RedefineMethod
 
+      # @example Normalize keys before storage
+      #   require 'hashie/extensions/method_access'
+      #   hash = {}.extend(Hashie::Extensions::MethodOverridingWriter)
+      #   hash.convert_key(:size) # => 'size'
       def convert_key(key)
         key.to_s
       end
 
+      # @example Override a Hash method and keep access to the original
+      #   require 'hashie/extensions/method_access'
+      #   hash = {}.extend(Hashie::Extensions::MethodOverridingWriter)
+      #   hash.size = 'large'
+      #   hash.size # => 'large'
+      #   hash.__size # => 1
       def method_missing(name, *args)
         if args.size == 1 && name.to_s =~ /(.*)=$/
           key = Regexp.last_match[1]
@@ -213,8 +269,13 @@ module Hashie
         super
       end
 
+      # @example Advertise method-overriding writers
+      #   require 'hashie/extensions/method_access'
+      #   hash = {}.extend(Hashie::Extensions::MethodOverridingWriter)
+      #   hash.respond_to?(:size=) # => true
       def respond_to_missing?(name, include_private = false)
         return true if name.to_s.end_with?('=')
+
         super
       end
 
@@ -231,6 +292,16 @@ module Hashie
     # shortcuts that can override object methods. Any overridden
     # object method is automatically aliased with two leading
     # underscores.
+    #
+    # @example Initialize, read, write, and query a conflicting key
+    #   class OverridingHash < Hash
+    #     include Hashie::Extensions::MethodAccessWithOverride
+    #   end
+    #   hash = OverridingHash.new(size: 'large')
+    #   hash.size # => 'large'
+    #   hash.size = 'small'
+    #   hash.size? # => true
+    #   hash.__size # => 1
     module MethodAccessWithOverride
       def self.included(base)
         [MethodReader, MethodOverridingWriter,
@@ -245,6 +316,7 @@ module Hashie
     # methods are aliased with two leading underscores.
     #
     # @example
+    #   require 'hashie/extensions/method_access'
     #   class MyHash < Hash
     #     include Hashie::Extensions::MethodOverridingInitializer
     #   end
@@ -255,7 +327,21 @@ module Hashie
     module MethodOverridingInitializer
       include RedefineMethod
 
-      def initialize(hash = {})
+      # @example Initialize conflicting keys and preserve a default
+      #   require 'hashie/extensions/method_access'
+      #   class OverridingHash < Hash
+      #     include Hashie::Extensions::MethodOverridingInitializer
+      #   end
+      #   hash = OverridingHash.new({ size: 'large' }, false)
+      #   hash.size # => 'large'
+      #   hash.__size # => 1
+      #   hash[:missing] # => false
+      def initialize(hash = {}, default = nil, &block)
+        raise ArgumentError, 'cannot specify both a default value and a default block' if default && block
+
+        self.default = default unless default.nil?
+        self.default_proc = block if block
+
         hash.each do |key, value|
           skey = key.to_s
           redefine_method(skey) if method?(skey)

data/lib/hashie/extensions/parsers/yaml_erb_parser.rb

@@ -1,46 +1,39 @@
-require 'yaml'
+# frozen_string_literal: true
+
 require 'erb'
-require 'pathname'
+require 'hashie/extensions/parsers/yaml_parser'
 
 module Hashie
   module Extensions
     module Parsers
-      class YamlErbParser
-        def initialize(file_path, options = {})
-          @content = File.read(file_path)
-          @file_path = file_path.is_a?(Pathname) ? file_path.to_s : file_path
-          @options = options
-        end
-
+      # Parses YAML after evaluating ERB templates.
+      #
+      # @example
+      #   require 'tempfile'
+      #   file = Tempfile.new(['hashie-example', '.yml'], '.')
+      #   begin
+      #     file.write("count: <%= 1 + 2 %>\n")
+      #     file.close
+      #     Hashie::Extensions::Parsers::YamlErbParser.perform(file.path) # => {'count' => 3}
+      #   ensure
+      #     file.close!
+      #   end
+      class YamlErbParser < YamlParser
+        # @example Evaluate ERB before safely loading YAML
+        #   require 'tempfile'
+        #   file = Tempfile.new(['hashie-example', '.yml'], '.')
+        #   begin
+        #     file.write("count: <%= 2 * 3 %>\n")
+        #     file.close
+        #     parser = Hashie::Extensions::Parsers::YamlErbParser.new(file.path)
+        #     parser.perform # => {'count' => 6}
+        #   ensure
+        #     file.close!
+        #   end
         def perform
           template = ERB.new(@content)
           template.filename = @file_path
-          permitted_classes = @options.fetch(:permitted_classes) { [] }
-          permitted_symbols = @options.fetch(:permitted_symbols) { [] }
-          aliases = @options.fetch(:aliases) { true }
-
-          yaml_safe_load(template, permitted_classes, permitted_symbols, aliases)
-        end
-
-        def self.perform(file_path, options = {})
-          new(file_path, options).perform
-        end
-
-        private
-
-        if Gem::Version.new(Psych::VERSION) >= Gem::Version.new('3.1.0') # Ruby 2.6+
-          def yaml_safe_load(template, permitted_classes, permitted_symbols, aliases)
-            YAML.safe_load(
-              template.result,
-              permitted_classes: permitted_classes,
-              permitted_symbols: permitted_symbols,
-              aliases: aliases
-            )
-          end
-        else
-          def yaml_safe_load(template, permitted_classes, permitted_symbols, aliases)
-            YAML.safe_load(template.result, permitted_classes, permitted_symbols, aliases)
-          end
+          yaml_safe_load(template.result)
         end
       end
     end

data/lib/hashie/extensions/parsers/yaml_parser.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'pathname'
+
+module Hashie
+  module Extensions
+    module Parsers
+      # Parses YAML without evaluating ERB templates.
+      #
+      # @example
+      #   require 'tempfile'
+      #   file = Tempfile.new(['hashie-example', '.yml'], '.')
+      #   begin
+      #     file.write("name: Ada\n")
+      #     file.close
+      #     Hashie::Extensions::Parsers::YamlParser.perform(file.path) # => {'name' => 'Ada'}
+      #   ensure
+      #     file.close!
+      #   end
+      class YamlParser
+        # @example Read a Pathname and retain parsing options
+        #   require 'tempfile'
+        #   file = Tempfile.new(['hashie-example', '.yml'], '.')
+        #   begin
+        #     file.write("name: Ada\n")
+        #     file.close
+        #     parser = Hashie::Extensions::Parsers::YamlParser.new(Pathname.new(file.path), aliases: false)
+        #     parser.perform # => {'name' => 'Ada'}
+        #   ensure
+        #     file.close!
+        #   end
+        def initialize(file_path, options = {})
+          @content = File.read(file_path)
+          @file_path = file_path.is_a?(Pathname) ? file_path.to_s : file_path
+          @options = options
+        end
+
+        # @example Leave ERB untouched when loading YAML
+        #   require 'tempfile'
+        #   file = Tempfile.new(['hashie-example', '.yml'], '.')
+        #   begin
+        #     file.write("value: <%= 1 + 2 %>\n")
+        #     file.close
+        #     parser = Hashie::Extensions::Parsers::YamlParser.new(file.path)
+        #     parser.perform # => {'value' => '<%= 1 + 2 %>'}
+        #   ensure
+        #     file.close!
+        #   end
+        def perform
+          yaml_safe_load(@content)
+        end
+
+        # @example Load YAML in one step
+        #   require 'tempfile'
+        #   file = Tempfile.new(['hashie-example', '.yml'], '.')
+        #   begin
+        #     file.write("count: 3\n")
+        #     file.close
+        #     Hashie::Extensions::Parsers::YamlParser.perform(file.path, aliases: false) # => {'count' => 3}
+        #   ensure
+        #     file.close!
+        #   end
+        def self.perform(file_path, options = {})
+          new(file_path, options).perform
+        end
+
+        private
+
+        def yaml_safe_load(content)
+          YAML.safe_load(
+            content,
+            permitted_classes: @options.fetch(:permitted_classes) { [] },
+            permitted_symbols: @options.fetch(:permitted_symbols) { [] },
+            aliases: @options.fetch(:aliases, true)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/hashie/extensions/persistable.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'psych'
+require 'tempfile'
+
+module Hashie
+  module Extensions
+    # Opt-in YAML file persistence for classes initialized from a hash.
+    #
+    # @example Save and reload a hash subclass
+    #   class Settings < Hash
+    #     include Hashie::Extensions::MergeInitializer
+    #     include Hashie::Extensions::Persistable
+    #   end
+    #   file = Tempfile.new(['hashie-example', '.yaml'], Dir.pwd)
+    #   begin
+    #     settings = Settings.new('theme' => 'dark')
+    #     settings.save(file.path)
+    #     Settings.load(file.path)['theme'] # => 'dark'
+    #   ensure
+    #     file.close!
+    #   end
+    module Persistable
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      # @example Add a YAML loader by including Persistable
+      #   class Settings < Hash
+      #     include Hashie::Extensions::MergeInitializer
+      #     include Hashie::Extensions::Persistable
+      #   end
+      #   file = Tempfile.new(['hashie-example', '.yaml'], Dir.pwd)
+      #   begin
+      #     file.write("---\ntheme: dark\n")
+      #     file.flush
+      #     Settings.load(file.path) # => { 'theme' => 'dark' }
+      #   ensure
+      #     file.close!
+      #   end
+      module ClassMethods
+        # @example Load safe YAML data and remember its path
+        #   class Settings < Hash
+        #     include Hashie::Extensions::MergeInitializer
+        #     include Hashie::Extensions::Persistable
+        #   end
+        #   file = Tempfile.new(['hashie-example', '.yaml'], Dir.pwd)
+        #   begin
+        #     file.write("---\ntheme: dark\n")
+        #     file.flush
+        #     settings = Settings.load(file.path)
+        #     settings['theme'] # => 'dark'
+        #     settings.persistable_path # => File.expand_path(file.path)
+        #   ensure
+        #     file.close!
+        #   end
+        def load(path)
+          path = File.expand_path(File.path(path))
+          data = Psych.safe_load(File.read(path), permitted_classes: [Symbol], aliases: false)
+          raise TypeError, 'persisted YAML must contain a hash' unless data.is_a?(::Hash)
+
+          new(data).tap { |object| object.instance_variable_set(:@persistable_path, path) }
+        end
+      end
+
+      # @example Remember the last successful save location
+      #   class Settings < Hash
+      #     include Hashie::Extensions::MergeInitializer
+      #     include Hashie::Extensions::Persistable
+      #   end
+      #   file = Tempfile.new(['hashie-example', '.yaml'], Dir.pwd)
+      #   begin
+      #     settings = Settings.new('theme' => 'dark')
+      #     settings.persistable_path # => nil
+      #     settings.save(file.path)
+      #     settings.persistable_path # => File.expand_path(file.path)
+      #   ensure
+      #     file.close!
+      #   end
+      attr_reader :persistable_path
+
+      # @example Save again without repeating the path
+      #   class Settings < Hash
+      #     include Hashie::Extensions::MergeInitializer
+      #     include Hashie::Extensions::Persistable
+      #   end
+      #   file = Tempfile.new(['hashie-example', '.yaml'], Dir.pwd)
+      #   begin
+      #     settings = Settings.new('theme' => 'dark')
+      #     settings.save(file.path)
+      #     settings['theme'] = 'light'
+      #     settings.save
+      #     Settings.load(file.path)['theme'] # => 'light'
+      #   ensure
+      #     file.close!
+      #   end
+      def save(path = persistable_path)
+        raise ArgumentError, 'a persistence path is required' if path.nil?
+
+        path = File.expand_path(File.path(path))
+        yaml = Psych.dump(persistable_data(self))
+        Tempfile.create(['.hashie-', '.yaml'], File.dirname(path)) do |file|
+          file.chmod(File.stat(path).mode & 0o777) if File.exist?(path)
+          file.write(yaml)
+          file.flush
+          file.fsync
+          file.close
+          File.rename(file.path, path)
+        end
+        @persistable_path = path
+      end
+
+      private
+
+      def persistable_data(value, ancestors = [])
+        raise ArgumentError, 'cannot persist cyclic data' if ancestors.any? { |ancestor| ancestor.equal?(value) }
+
+        case value
+        when ::Hash
+          value.each_with_object({}) do |(key, child), data|
+            raise TypeError, 'persisted hash keys must be strings or symbols' unless key.is_a?(String) || key.is_a?(Symbol)
+
+            data[persistable_data(key)] = persistable_data(child, ancestors + [value])
+          end
+        when ::Array
+          value.map { |child| persistable_data(child, ancestors + [value]) }
+        when String
+          value.dup
+        when Symbol, Integer, Float, TrueClass, FalseClass, NilClass
+          value
+        else
+          raise TypeError, "cannot persist a value of class `#{value.class}`"
+        end
+      end
+    end
+  end
+end

data/lib/hashie/extensions/pretty_inspect.rb

@@ -1,11 +1,25 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
+    # @example Inspect sorted hash entries
+    #   class Settings < Hash
+    #     include Hashie::Extensions::PrettyInspect
+    #   end
+    #   hash = Settings[:z, 2, :a, 1]
+    #   hash.inspect # => "#<#{Settings} a=1 z=2>"
     module PrettyInspect
       def self.included(base)
         base.send :alias_method, :hash_inspect, :inspect
         base.send :alias_method, :inspect, :hashie_inspect
       end
 
+      # @example Include the class and sorted key/value pairs
+      #   class Settings < Hash
+      #     include Hashie::Extensions::PrettyInspect
+      #   end
+      #   hash = Settings[:z, 2, :a, 1]
+      #   hash.hashie_inspect # => "#<#{Settings} a=1 z=2>"
       def hashie_inspect
         ret = "#<#{self.class}"
         keys.sort_by(&:to_s).each do |key|

data/lib/hashie/extensions/ruby_version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright (c) Chad Fowler, Rich Kilmer, Jim Weirich and others.
 # Portions copyright (c) Engine Yard and Andre Arko
 #
@@ -14,22 +16,37 @@
 
 module Hashie
   module Extensions
+    # @example Compare versions numerically
+    #   Hashie::Extensions::RubyVersion.new('3.10') > Hashie::Extensions::RubyVersion.new('3.9') # => true
     class RubyVersion
       include Comparable
 
+      # @example Inspect and replace parsed version segments
+      #   version = Hashie::Extensions::RubyVersion.new('3.2.0.preview1')
+      #   version.segments # => [3, 2, 0, 'preview', 1]
+      #   version.segments = [3, 3, 0]
+      #   version == Hashie::Extensions::RubyVersion.new('3.3') # => true
       attr_accessor :segments
 
+      # @example Parse numeric and prerelease segments
+      #   version = Hashie::Extensions::RubyVersion.new('3.2.0.rc1')
+      #   version.segments # => [3, 2, 0, 'rc', 1]
       def initialize(version)
         @segments = split_to_segments(version)
       end
 
+      # @example Ignore trailing zeros and order prereleases before releases
+      #   version = Hashie::Extensions::RubyVersion
+      #   version.new('3.2') <=> version.new('3.2.0') # => 0
+      #   version.new('3.2.rc1') <=> version.new('3.2') # => -1
+      #   version.new('3.10') <=> version.new('3.9') # => 1
       def <=>(other)
         lhsegments = segments
         rhsegments = other.segments
 
         lhsize = lhsegments.size
         rhsize = rhsegments.size
-        limit  = (lhsize > rhsize ? lhsize : rhsize) - 1
+        limit  = [lhsize, rhsize].max - 1
 
         i = 0
 

data/lib/hashie/extensions/ruby_version_check.rb

@@ -1,17 +1,34 @@
+# frozen_string_literal: true
+
 require 'hashie/extensions/ruby_version'
 
 module Hashie
   module Extensions
+    # @example Conditionally run code for the current Ruby
+    #   klass = Class.new { include Hashie::Extensions::RubyVersionCheck }
+    #   klass.with_minimum_ruby(RUBY_VERSION) { 'supported' } # => 'supported'
     module RubyVersionCheck
       def self.included(base)
         base.extend ClassMethods
       end
 
+      # @example Add version checks to a class
+      #   klass = Class.new { include Hashie::Extensions::RubyVersionCheck }
+      #   klass.with_minimum_ruby?('0.0.0') # => true
+      #   klass.with_minimum_ruby?('999.0.0') # => false
       module ClassMethods
+        # @example Run the block only when the minimum is satisfied
+        #   klass = Class.new { include Hashie::Extensions::RubyVersionCheck }
+        #   klass.with_minimum_ruby('0.0.0') { 'supported' } # => 'supported'
+        #   klass.with_minimum_ruby('999.0.0') { raise 'not reached' } # => nil
         def with_minimum_ruby(version)
           yield if with_minimum_ruby?(version)
         end
 
+        # @example Accept the current version as a minimum
+        #   klass = Class.new { include Hashie::Extensions::RubyVersionCheck }
+        #   klass.with_minimum_ruby?(RUBY_VERSION) # => true
+        #   klass.with_minimum_ruby?('999.0.0') # => false
         def with_minimum_ruby?(version)
           RubyVersion.new(RUBY_VERSION) >= RubyVersion.new(version)
         end