hashie 4.1.0 → 5.2.0

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

data/lib/hashie/extensions/strict_key_access.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
     # SRP: This extension will fail an error whenever a key is accessed
@@ -19,11 +21,21 @@ module Hashie
     # NOTE: For googlers coming from Python to Ruby, this extension makes a Hash
     # behave more like a "Dictionary".
     #
+    # @example Raise on missing keys
+    #   hash = { name: 'Ada' }.extend(Hashie::Extensions::StrictKeyAccess)
+    #   hash[:name] # => 'Ada'
+    #   expect { hash[:missing] }.to raise_error(KeyError)
     module StrictKeyAccess
+      # @example Explain why defaults are unsupported
+      #   error = Hashie::Extensions::StrictKeyAccess::DefaultError.new
+      #   error.message # => 'Setting or using a default with Hashie::Extensions::StrictKeyAccess does not make sense'
       class DefaultError < StandardError
+        # @example Construct a default-access error
+        #   error = Hashie::Extensions::StrictKeyAccess::DefaultError.new
+        #   error.message # => 'Setting or using a default with Hashie::Extensions::StrictKeyAccess does not make sense'
         def initialize
-          super('Setting or using a default with Hashie::Extensions::StrictKeyAccess'\
-                ' does not make sense'
+          super('Setting or using a default with Hashie::Extensions::StrictKeyAccess ' \
+                'does not make sense'
           )
         end
       end
@@ -45,31 +57,73 @@ module Hashie
       #     >> a["noes"]
       #       KeyError: key not found: "noes"
       #
+      # @example Fetch an existing value without a default fallback
+      #   hash = { name: 'Ada' }.extend(Hashie::Extensions::StrictKeyAccess)
+      #   hash[:name] # => 'Ada'
+      #   expect { hash[:missing] }.to raise_error(KeyError)
       def [](key)
         fetch(key)
       end
 
+      # @example Reject reading the default value
+      #   hash = {}.extend(Hashie::Extensions::StrictKeyAccess)
+      #   error_class = begin
+      #     hash.default
+      #   rescue Hashie::Extensions::StrictKeyAccess::DefaultError => error
+      #     error.class
+      #   end
+      #   error_class # => Hashie::Extensions::StrictKeyAccess::DefaultError
       def default(_ = nil)
         raise DefaultError
       end
 
+      # @example Reject assigning a default value
+      #   hash = {}.extend(Hashie::Extensions::StrictKeyAccess)
+      #   rejected = begin
+      #     hash.default = 'unknown'
+      #     false
+      #   rescue Hashie::Extensions::StrictKeyAccess::DefaultError
+      #     true
+      #   end
+      #   rejected # => true
       def default=(_)
         raise DefaultError
       end
 
+      # @example Reject reading a default proc
+      #   hash = {}.extend(Hashie::Extensions::StrictKeyAccess)
+      #   rejected = begin
+      #     hash.default_proc
+      #     false
+      #   rescue Hashie::Extensions::StrictKeyAccess::DefaultError
+      #     true
+      #   end
+      #   rejected # => true
       def default_proc
         raise DefaultError
       end
 
+      # @example Reject assigning a default proc
+      #   hash = {}.extend(Hashie::Extensions::StrictKeyAccess)
+      #   rejected = begin
+      #     hash.default_proc = ->(_hash, _key) { 'unknown' }
+      #     false
+      #   rescue Hashie::Extensions::StrictKeyAccess::DefaultError
+      #     true
+      #   end
+      #   rejected # => true
       def default_proc=(_)
         raise DefaultError
       end
 
+      # @example Find an existing key and reject missing values
+      #   hash = { name: 'Ada', nil => false }.extend(Hashie::Extensions::StrictKeyAccess)
+      #   hash.key('Ada') # => :name
+      #   hash.key(false) # => nil
+      #   expect { hash.key('Grace') }.to raise_error(KeyError)
       def key(value)
         super.tap do |result|
-          if result.nil? && (!key?(result) || self[result] != value)
-            raise KeyError, "key not found with value of #{value.inspect}"
-          end
+          raise KeyError, "no key found for value `#{value.inspect}`" if result.nil? && (!key?(result) || self[result] != value)
         end
       end
     end

data/lib/hashie/extensions/stringify_keys.rb

@@ -1,31 +1,75 @@
+# frozen_string_literal: true
+
 module Hashie
   module Extensions
+    # Extends a Hash with the ability to convert its keys to strings.
+    #
+    # @example Extend a pre-existing Hash object
+    #   hash = { test: 'value' }
+    #   hash.extend(Hashie::Extensions::StringifyKeys)
+    #   hash.stringify_keys!
+    #   hash # => { 'test' => 'value' }
+    #
+    # @example Create a Hash class with this capability
+    #   class StringifyingHash < Hash
+    #     include Hashie::Extensions::StringifyKeys
+    #   end
+    #
+    #   hash = StringifyingHash.new
+    #   hash[:test] = 'value'
+    #   hash.stringify_keys!
+    #   hash # => { 'test' => 'value' }
+    #
+    # @example Use the module function to stringify keys in a hash
+    #   hash = { test: 'value' }
+    #   Hashie::Extensions::StringifyKeys.stringify_keys!(hash)
+    #   hash # => { 'test' => 'value' }
     module StringifyKeys
-      # Convert all keys in the hash to strings.
+      # Converts all keys in the hash and nested hashes and arrays to strings.
       #
-      # @example
-      #   test = {:abc => 'def'}
+      # @example Convert keys in place
+      #   test = { abc: [{ def: 'value' }] }
+      #   test.extend(Hashie::Extensions::StringifyKeys)
       #   test.stringify_keys!
-      #   test # => {'abc' => 'def'}
+      #   test # => { 'abc' => [{ 'def' => 'value' }] }
+      #
+      # @api public
+      # @return [Hash] the receiver with its keys converted to strings
       def stringify_keys!
         StringifyKeys.stringify_keys!(self)
         self
       end
 
-      # Return a new hash with all keys converted
-      # to strings.
+      # Returns a shallow copy with all keys recursively converted to strings.
+      # Nested hashes and arrays are shared with the original and are modified.
+      #
+      # @example Copy a flat hash without modifying the original
+      #   test = { abc: 'def' }
+      #   test.extend(Hashie::Extensions::StringifyKeys)
+      #   test.stringify_keys # => { 'abc' => 'def' }
+      #   test # => { abc: 'def' }
+      #
+      # @example Nested values are shared, not deep copied
+      #   test = { abc: [{ def: 'value' }] }
+      #   test.extend(Hashie::Extensions::StringifyKeys)
+      #   test.stringify_keys # => { 'abc' => [{ 'def' => 'value' }] }
+      #   test # => { abc: [{ 'def' => 'value' }] }
+      #
+      # @api public
+      # @return [Hash] a shallow copy with stringified keys
       def stringify_keys
         StringifyKeys.stringify_keys(self)
       end
 
+      # @example Add recursive conversion functions to an object
+      #   converter = Object.new.extend(Hashie::Extensions::StringifyKeys::ClassMethods)
+      #   converter.stringify_keys(user: { name: 'Ada' }) # => { 'user' => { 'name' => 'Ada' } }
       module ClassMethods
         # Stringify all keys recursively within nested
         # hashes and arrays.
         # @api private
         def stringify_keys_recursively!(object)
           case object
-          when self.class
-            stringify_keys!(object)
           when ::Array
             object.each do |i|
               stringify_keys_recursively!(i)
@@ -35,13 +79,16 @@ module Hashie
           end
         end
 
-        # Convert all keys in the hash to strings.
+        # Converts all keys in a hash recursively to strings, in place.
+        #
+        # @example Convert keys through Hashie's module function
+        #   test = { abc: 'def' }
+        #   Hashie.stringify_keys!(test)
+        #   test # => { 'abc' => 'def' }
         #
-        # @param [::Hash] hash
-        # @example
-        #   test = {:abc => 'def'}
-        #   test.stringify_keys!
-        #   test # => {'abc' => 'def'}
+        # @api public
+        # @param [Hash] hash
+        # @return [Hash] the passed hash with stringified keys
         def stringify_keys!(hash)
           hash.extend(Hashie::Extensions::StringifyKeys) unless hash.respond_to?(:stringify_keys!)
           hash.keys.each do |k| # rubocop:disable Performance/HashEachMethods
@@ -51,9 +98,17 @@ module Hashie
           hash
         end
 
-        # Return a copy of hash with all keys converted
-        # to strings.
-        # @param [::Hash] hash
+        # Returns a shallow copy of a hash with recursively stringified keys.
+        # Nested hashes and arrays are shared with the original and are modified.
+        #
+        # @example Copy keys through Hashie's module function
+        #   test = { abc: 'def' }
+        #   Hashie.stringify_keys(test) # => { 'abc' => 'def' }
+        #   test # => { abc: 'def' }
+        #
+        # @api public
+        # @param [Hash] hash
+        # @return [Hash] a shallow copy with stringified keys
         def stringify_keys(hash)
           copy = hash.dup
           copy.extend(Hashie::Extensions::StringifyKeys) unless copy.respond_to?(:stringify_keys!)