hash_delegator 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 62b082b39fe733c614750de7ae37885d846872e0867b34846bc9329db6b5f743
+  data.tar.gz: 7892a0389be4d989747fc2a330c86196d8744c90fb1dbbecedabaf009fa19171
+SHA512:
+  metadata.gz: 3138e6b948c4828b6bad9d3811e5cfe4eb18d83059f866a321166a93fbf766ca59701d959d835a3c807592b21d3af6294273bc647a3ccdb8871684e0f24a47c5
+  data.tar.gz: 4d5859d57253c4fd6dd7ad275d8ca785a38a907ede3c94712455069249649a9aa5b4543d2b6b7204d8cc61911dbf15152d22807232da276491df7ce80e446dd5

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+vendor/bundle/

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--no-color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,8 @@
+---
+language: ruby
+cache: bundler
+rvm:
+  - 2.6.7
+  - 2.7.3
+  - 3.0.1
+before_install: gem install bundler -v 2.1.4

data/Gemfile

@@ -0,0 +1,10 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in hash_delegator.gemspec
+gemspec
+
+gem "rake", "~> 12.0"
+gem "rspec", "~> 3.0"
+
+gem "rubocop"
+gem "rubocop-rspec"

data/Gemfile.lock

@@ -0,0 +1,59 @@
+PATH
+  remote: .
+  specs:
+    hash_delegator (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    diff-lcs (1.4.4)
+    parallel (1.20.1)
+    parser (3.0.1.1)
+      ast (~> 2.4.1)
+    rainbow (3.0.0)
+    rake (12.3.3)
+    regexp_parser (2.1.1)
+    rexml (3.2.5)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.2)
+    rubocop (1.16.1)
+      parallel (~> 1.10)
+      parser (>= 3.0.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.7.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.7.0)
+      parser (>= 3.0.1.1)
+    rubocop-rspec (2.4.0)
+      rubocop (~> 1.0)
+      rubocop-ast (>= 1.1.0)
+    ruby-progressbar (1.11.0)
+    unicode-display_width (2.0.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  hash_delegator!
+  rake (~> 12.0)
+  rspec (~> 3.0)
+  rubocop
+  rubocop-rspec
+
+BUNDLED WITH
+   2.2.16

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Delon Newman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,60 @@
+[![Build Status](https://travis-ci.com/delonnewman/hash_delegator.svg?branch=master)](https://travis-ci.com/delonnewman/hash_delegator)
+
+# HashDelegator
+
+Thread-safe immutable objects that provide delegation and basic validation to hashes.
+
+## Synopsis
+
+```ruby
+class Person < HashDelegator
+  require :first_name, :last_name
+  transform_keys(&:to_sym)
+
+  def name
+    "#{first_name} #{last_name}"
+  end
+end
+
+person = Person.new(first_name: "Mary", last_name: "Lamb", age: 32)
+person.age # => 32
+person.name # => "Mary Lamb"
+
+# it supports all non-mutating methods of Hash
+person.merge!(favorite_food: "Thai") # => NoMethodError
+person.merge(favorite_food: "Thai") # => #<Person { first_name: "Mary", last_name: "Lamb", age: 32 }>
+
+# respects inheritance
+class Employee < Person
+  require :employee_id
+end
+
+Employee.new(age: 32, employee_id: 1234) # => Error, first_name attribute is required
+Employee.new(first_name: "John", last_name: "Smith", age: 23, employee_id: 3456) # => #<Employee ...>
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hash_delegator'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install hash_delegator
+
+## See Also
+
+- [Dry Struct](https://dry-rb.org/gems/dry-struct)
+- [Clojure Records](https://clojure.org/reference/datatypes#_deftype_and_defrecord)
+- [Delegator](https://rubyapi.org/3.0/o/delegator)
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/hash_delegator.gemspec

@@ -0,0 +1,29 @@
+require_relative 'lib/hash_delegator/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "hash_delegator"
+  spec.version       = HashDelegator::VERSION
+  spec.authors       = ["Delon Newman"]
+  spec.email         = ["contact@delonnewman.name"]
+
+  spec.summary       = %q{Method delegation to a hash}
+  spec.description   = spec.summary
+  spec.homepage      = "https://github.com/delonnewman/hash_delegator"
+  spec.license       = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}#changelog"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+end

data/lib/core_ext.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+if RUBY_VERSION.split('.').take(2).join('.').to_f < 3
+  class Hash
+    def except(*keys)
+      h = dup
+      keys.each do |key|
+        h.delete(key)
+      end
+      h
+    end
+  end
+end

data/lib/hash_delegator.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+require 'set'
+require 'core_ext'
+require 'hash_delegator/version'
+
+# Provides delegation and basic validation for Hashes
+class HashDelegator
+  class << self
+    # Return required attributes or nil
+    #
+    # @return [Array, nil]
+    def required_attributes
+      return @required_attributes if @required_attributes
+
+      superclass.required_attributes if superclass.respond_to?(:required_attributes)
+    end
+
+    # Specifiy required attributes
+    #
+    # @param attributes [Array]
+    # @return [HashDelegator]
+    def required(*attributes)
+      @required_attributes =
+        if superclass.respond_to?(:required_attributes) && !superclass.required_attributes.nil?
+          superclass.required_attributes + attributes
+        else
+          attributes
+        end
+
+      self
+    end
+
+    # @deprecated
+    def require(*attributes)
+      warn 'HashDelegator.require is deprecated'
+      required(*attrbutes)
+    end
+
+    # Specify the default value if the value is a Proc or a block is passed
+    # each hash's default_proc attribute will be set.
+    #
+    # @param value [Object] default value
+    # @param block [Proc] default proc
+    # @return [HashDelegator]
+    def default(value = nil, &block)
+      if block
+        @default_value = block
+        return self
+      end
+
+      if value.is_a?(Proc) && value.lambda? && value.arity != 2
+        lambda = value
+        value  = ->(*args) { lambda.call(*args.slice(0, lambda.arity)) }
+      end
+
+      @default_value = value
+
+      self
+    end
+
+    # Return the default value
+    def default_value
+      return @default_value if @default_value
+
+      superclass.default_value if superclass.respond_to?(:default_value)
+    end
+
+    # Specify the key transformer
+    def transform_keys(&block)
+      @key_transformer = block
+    end
+
+    # Return the key transformer
+    def key_transformer
+      return @key_transformer if @key_transformer
+
+      superclass.key_transformer if superclass.respond_to?(:key_transformer)
+    end
+  end
+
+  # Methods that mutate the internal hash, these cannot be called publicly.
+  MUTATING_METHODS = Set[
+    :clear,
+    :delete,
+    :update,
+    :delete_if,
+    :keep_if,
+    :compact!,
+    :filter!,
+    :merge!,
+    :reject!,
+    :select!,
+    :transform_keys!,
+    :transform_values!,
+    :default=,
+    :default_proc=,
+    :compare_by_identity,
+    :rehash,
+    :replace,
+    :initialize_copy,
+    :shift,
+    :store
+  ].freeze
+
+  # Methods that are closed (in the algebraic sense) meaning that
+  # they will not remove required keys.
+  CLOSED_METHODS = Set[
+    :compact,
+    :merge
+  ].freeze
+
+  EMPTY_HASH = {}.freeze
+  private_constant :EMPTY_HASH
+
+  # Initialize the HashDelegator with the given hash.
+  # If the hash is not frozen it will be duplicated. If a key transformer
+  # is specified the hashes keys will be processed with it (duplicating the original hash).
+  # The hash will be validated for the existance of the required attributes (note
+  # that a key with a nil value still exists in the hash).
+  #
+  #
+  # @param hash [Hash]
+  def initialize(hash = EMPTY_HASH)
+    raise 'HashDelegator should not be initialized' if instance_of?(HashDelegator)
+
+    @hash =
+      if self.class.key_transformer
+        hash.transform_keys(&self.class.key_transformer)
+      elsif hash.frozen?
+        hash
+      else
+        hash.dup
+      end
+
+    if self.class.default_value.is_a?(Proc)
+      @hash.default_proc = self.class.default_value
+    else
+      @hash.default = self.class.default_value
+    end
+
+    if self.class.required_attributes
+      self.class.required_attributes.each do |attribute|
+        attribute = self.class.key_transformer.call(attribute) if self.class.key_transformer
+        raise "#{attribute.inspect} is required, but is missing" unless key?(attribute)
+      end
+    end
+  end
+
+  # If the given keys include any required attributes
+  # the hash will be duplicated and except will be called
+  # on the duplicated hash. Otherwise a new instance of
+  # the HashDelegator will be return without the specified keys.
+  #
+  # @param keys [Array]
+  # @return [Hash, HashDelegator]
+  def except(*keys)
+    common = keys & self.class.required_attributes
+
+    if common.empty?
+      self.class.new(@hash.except(*keys))
+    else
+      to_hash.except(*keys)
+    end
+  end
+
+  # If the given keys include all of the required attributes
+  # a new HashDelegator will be returned with only the specified keys.
+  # Otherwise a internal hash will be duplicated and slice will
+  # be called on the duplicated hash.
+  #
+  # @param keys [Array]
+  # @return [Hash, HashDelegator]
+  def slice(*keys)
+    required = self.class.required_attributes
+    common   = keys & required
+
+    if keys.size == common.size && common.size == required.size
+      self.class.new(@hash.slice(*keys))
+    else
+      to_hash.slice(*keys)
+    end
+  end
+
+  # Return a duplicate of the delegated hash.
+  #
+  # @return [Hash]
+  def to_hash
+    @hash.dup
+  end
+  alias to_h to_hash
+
+  def to_s
+    "#<#{self.class} #{@hash.inspect}>"
+  end
+  alias inspect to_s
+
+  # Return the value associated with the given key. If a key transformer
+  # is special the key will be transformed first. If the key is missing
+  # the default value will be return (nil unless specified).
+  #
+  # @param key
+  def [](key)
+    if self.class.key_transformer
+      @hash[self.class.key_transformer.call(key)]
+    else
+      @hash[key]
+    end
+  end
+
+  # Return the numerical hash of the decorated hash.
+  #
+  # @return [Integer]
+  def hash
+    @hash.hash
+  end
+
+  # Return true if the other object has the same numerical hash
+  # as this object.
+  #
+  # @return [Boolean]
+  def eql?(other)
+    @hash.hash == other.hash
+  end
+
+  # Return true if the other object has all of this objects required attributes.
+  #
+  # @param other
+  def ===(other)
+    required = self.class.required_attributes
+
+    other.respond_to?(:keys) && (common = other.keys & required) &&
+      common.size == other.keys.size && common.size == required.size
+  end
+
+  # Return true if the other object is of the same class and the
+  # numerical hash of the other object and this object are equal.
+  #
+  # @param other
+  #
+  # @return [Boolean]
+  def ==(other)
+    other.instance_of?(self.class) && eql?(other)
+  end
+
+  # Return true if the superclass responds to the method
+  # or if the method is a key of the internal hash or
+  # if the hash responds to this method. Otherwise return false.
+  #
+  # @note DO NOT USE DIRECTLY
+  #
+  # @see Object#respond_to?
+  # @see Object#respond_to_missing?
+  #
+  # @param method [Symbol]
+  # @param include_all [Boolean]
+  def respond_to_missing?(method, include_all)
+    super || key?(method) || hash_respond_to?(method)
+  end
+
+  # If the method is a key of the internal hash return it's value.
+  # If the internal hash responds to the method forward the method
+  # to the hash. If the method is 'closed' retrun a new HashDelegator
+  # otherwise return the raw result. If none of these conditions hold
+  # call the superclass' method_missing.
+  #
+  # @see CLOSED_METHODS
+  # @see Object#method_missing
+  #
+  # @param method [Symbol]
+  # @param args [Array]
+  # @param block [Proc]
+  def method_missing(method, *args, &block)
+    return @hash[method] if @hash.key?(method)
+
+    if hash_respond_to?(method)
+      result = @hash.public_send(method, *args, &block)
+      return result unless CLOSED_METHODS.include?(method)
+
+      return self.class.new(result)
+    end
+
+    super
+  end
+
+  private
+
+  def hash_respond_to?(method)
+    !MUTATING_METHODS.include?(method) && @hash.respond_to?(method)
+  end
+
+  protected
+
+  # Set the key of the internal hash to the given value.
+  #
+  # @param key
+  # @param value
+  def []=(key, value)
+    @hash[key] = value
+  end
+end

data/lib/hash_delegator/version.rb

@@ -0,0 +1,3 @@
+class HashDelegator
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: hash_delegator
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Delon Newman
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2021-06-14 00:00:00.000000000 Z
+dependencies: []
+description: Method delegation to a hash
+email:
+- contact@delonnewman.name
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- hash_delegator.gemspec
+- lib/core_ext.rb
+- lib/hash_delegator.rb
+- lib/hash_delegator/version.rb
+homepage: https://github.com/delonnewman/hash_delegator
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/delonnewman/hash_delegator
+  source_code_uri: https://github.com/delonnewman/hash_delegator
+  changelog_uri: https://github.com/delonnewman/hash_delegator#changelog
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key:
+specification_version: 4
+summary: Method delegation to a hash
+test_files: []