Module: RightSupport::Data::HashTools

Defined in:
lib/right_support/data/hash_tools.rb

Overview

various tools for manipulating hash-like classes.

Class Method Summary collapse

Class Method Details

.deep_apply_diff!(target, diff) ⇒ Object

Recursively apply diff portion of a patch (generated by deep_create_patch, etc.).

Parameters

Return

Parameters:

  • target (Hash) —

    hash where diff will be applied.

  • diff (Hash) —

    hash containing changes to apply.

  • target (Hash) —

    hash with diff applied.



249
250
251
252
253
254
255
256
257
258
 
# File 'lib/right_support/data/hash_tools.rb', line 249

def self.deep_apply_diff!(target, diff)
  diff.each do |k, v|
    if v[:left] && v[:right]
      target[k] = v[:right] if v[:left] == target[k]
    elsif target.has_key?(k)
      deep_apply_diff!(target[k], v)
    end
  end
  target
end

.deep_apply_patch!(target, patch) ⇒ Object

Perform 3-way merge using given target and a patch hash (generated by deep_create_patch, etc.). values in target whose keys are in :left_only component of patch are removed values in :right_only component of patch get deep merged into target values in target whose keys are in :diff component of patch and which are identical to left side of diff get overwritten with right side of patch

Parameters

Return

Parameters:

  • target (Hash) —

    hash where patch will be applied.

  • patch (Hash) —

    hash containing changes to apply.

  • target (Hash) —

    hash with patch applied.



234
235
236
237
238
239
 
# File 'lib/right_support/data/hash_tools.rb', line 234

def self.deep_apply_patch!(target, patch)
  deep_remove!(target, patch[:left_only])
  deep_merge!(target, patch[:right_only])
  deep_apply_diff!(target, patch[:diff])
  target
end

.deep_clone(original) {|value| ... } ⇒ Hash

Creates a deep clone of the given hash.

note that not all objects are clonable in Ruby even though all respond to clone (which is completely counter-intuitive and contrary to all other managed languages). Java, for example, has the built-in Cloneable marker interface which we will simulate here with .duplicable? (because cloneable isn’t actually a word) in case you need non-hash values to be deep-cloned by this method.

also note that .duplicable? may imply caling .dup instead of .clone but developers tend to override .clone and totally forget to override .dup (and having two names for the same method is, yes, a bad idea in any language).

Parameters

Block

Return

Parameters:

  • original (Hash) —

    hash to clone

Yield Parameters:

Yield Returns:

  • (Object) —

    cloned value of leaf or original value

Returns:

  • (Hash) —

    deep cloned hash



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/right_support/data/hash_tools.rb', line 132

def self.deep_clone(original, &leaf_callback)
  result = original.clone
  result.each do |k, v|
    if hashable?(v)
      result[k] = deep_clone(v)
    elsif leaf_callback
      result[k] = leaf_callback.call(v)
    elsif v.respond_to?(:duplicable?)
      result[k] = (v.duplicable? ? v.clone : v)
    else
      result[k] = v
    end
  end
  result
end

.deep_create_patch(left, right) ⇒ Hash

Produce a difference from two hashes. The difference excludes any values which are common to both hashes.

The result is a hash with the following keys:

- :diff = hash with key common to both input hashes and value composed of the corresponding different values: { :left => <left value>, :right => <right value> }
- :left_only = hash composed of items only found in left hash
- :right_only = hash composed of items only found in right hash

Parameters

Return

Parameters:

  • left (Hash) —

    side

  • right (Hash) —

    side

Returns:

  • (Hash) —

    result as hash of diffage



202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
 
# File 'lib/right_support/data/hash_tools.rb', line 202

def self.deep_create_patch(left, right)
  result = { :diff=>{}, :left_only=>{}, :right_only=>{} }
  right.each do |k, v|
    if left.include?(k)
      if hashable?(v) && hashable?(left[k])
        subdiff = deep_create_patch(left[k], v)
        result[:right_only].merge!(k=>subdiff[:right_only]) unless subdiff[:right_only].empty?
        result[:left_only].merge!(k=>subdiff[:left_only]) unless subdiff[:left_only].empty?
        result[:diff].merge!(k=>subdiff[:diff]) unless subdiff[:diff].empty?
      elsif v != left[k]
        result[:diff].merge!(k=>{:left => left[k], :right=>v})
      end
    else
      result[:right_only].merge!({ k => v })
    end
  end
  left.each { |k, v| result[:left_only].merge!({ k => v }) unless right.include?(k) }
  result
end

.deep_get(hash, path) ⇒ Object

Gets a value from a (deep) hash using a path given as an array of keys.

Parameters

Return

Parameters:

  • hash (Hash) —

    for lookup or nil or empty

  • path (Array) —

    to existing value as array of keys or nil or empty

Returns:



63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/right_support/data/hash_tools.rb', line 63

def self.deep_get(hash, path)
  hash ||= {}
  path ||= []
  last_index = path.size - 1
  path.each_with_index do |key, index|
    value = hash[key]
    if index == last_index
      return value
    elsif hashable?(value)
      hash = value
    else
      break
    end
  end
  nil
end

.deep_merge!(target, source) ⇒ Hash

Performs a deep merge (but not a deep clone) of one hash into another.

Parameters

Return

Parameters:

  • target (Hash) —

    hash to contain original and merged data

  • source (Hash) —

    hash containing data to recursively assign or nil or empty

Returns:

  • (Hash) —

    to_hash result of merge



156
157
158
159
160
161
162
163
164
165
 
# File 'lib/right_support/data/hash_tools.rb', line 156

def self.deep_merge!(target, source)
  source.each do |k, v|
    if hashable?(target[k]) && hashable?(v)
      deep_merge!(target[k], v)
    else
      target[k] = v
    end
  end if source
  target
end

.deep_remove!(target, source) ⇒ Hash

Remove recursively values that exist equivalently in the match hash.

Parameters

Return

Parameters:

  • target (Hash) —

    hash from which to remove matching values

  • source (Hash) —

    hash to compare against target for removal or nil or empty

Returns:

  • (Hash) —

    target hash with matching values removed, if any



175
176
177
178
179
180
181
182
183
184
185
186
 
# File 'lib/right_support/data/hash_tools.rb', line 175

def self.deep_remove!(target, source)
  source.each do |k, v|
    if target.has_key?(k)
      if target[k] == v
        target.delete(k)
      elsif hashable?(v) && hashable?(target[k])
        deep_remove!(target[k], v)
      end
    end
  end if source
  target
end

.deep_set!(hash, path, value, clazz = nil) ⇒ TrueClass

Set a given value on a (deep) hash using a path given as an array of keys.

Parameters

Return

Parameters:

  • hash (Hash) —

    for insertion

  • path (Array) —

    to new value as array of keys

  • value (Object) —

    to insert

  • clazz (Class) (defaults to: nil) —

    to allocate as needed when building deep hash or nil to infer from hash argument

Returns:

  • (TrueClass) —

    always true

Raises:

  • (ArgumentError) 


90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/right_support/data/hash_tools.rb', line 90

def self.deep_set!(hash, path, value, clazz=nil)
  raise ArgumentError.new("hash is invalid") unless hashable?(hash)
  raise ArgumentError.new("path is invalid") if path.empty?
  clazz ||= hash.class
  raise ArgumentError.new("clazz is invalid") unless hash_like?(clazz)
  last_index = path.size - 1
  path.each_with_index do |key, index|
    if index == last_index
      hash[key] = value
    else
      subhash = hash[key]
      unless hashable?(subhash)
        subhash = clazz.new
        hash[key] = subhash
      end
      hash = subhash
    end
  end
  true
end

.hash_like?(clazz) ⇒ TrueClass|FalseClass

Determines if given class is hash-like (i.e. instance of class responds to hash methods).

Parameters

Return

Parameters:

  • clazz (Class) —

    to be tested

Returns:

  • (TrueClass|FalseClass) —

    true if clazz is hash-like, false otherwise



51
52
53
 
# File 'lib/right_support/data/hash_tools.rb', line 51

def self.hash_like?(clazz)
  clazz.public_method_defined?('has_key?')
end

.hashable?(object) ⇒ TrueClass|FalseClass

Determines if given object is hashable (i.e. object responds to hash methods).

Parameters

Return

Parameters:

  • object (Object) —

    to be tested

Returns:

  • (TrueClass|FalseClass) —

    true if object is hashable, false otherwise



35
36
37
38
39
40
41
42
 
# File 'lib/right_support/data/hash_tools.rb', line 35

def self.hashable?(object)
  # note that we could obviously be more critical here, but this test has always been
  # sufficient and excludes Arrays and Strings which respond to [] but not has_key?
  #
  # what we specifically don't want to do is .kind_of?(Hash) because that excludes the
  # range of hash-like classes (such as Chef::Node::Attribute)
  object.respond_to?(:has_key?)
end