Class: Hm

Inherits:
Object
  • Object
show all
Defined in:
lib/hm.rb,
lib/hm/dig.rb,
lib/hm/algo.rb,
lib/hm/version.rb

Overview

Hm is a wrapper for chainable, terse, idiomatic Hash modifications.

Examples:

order = {
  'items' => {
    '#1' => {'title' => 'Beef', 'price' => '18.00'},
    '#2' => {'title' => 'Potato', 'price' => '8.20'}
  }
}
Hm(order)
  .transform_keys(&:to_sym)
  .transform(i[items *] => :items)
  .transform_values(i[items * price], &:to_f)
  .reduce(i[items * price] => :total, &:+)
  .to_h
# => {:items=>[{:title=>"Beef", :price=>18.0}, {:title=>"Potato", :price=>8.2}], :total=>26.2}

See Also:

Defined Under Namespace

Modules: Algo, Dig

Constant Summary collapse

WILDCARD = 
:*
MAJOR = 
0
MINOR = 
0
PATCH = 
4
PRE = 
nil
VERSION = 
[MAJOR, MINOR, PATCH, PRE].compact.join('.')

Instance Method Summary collapse

Constructor Details

#initialize(collection) ⇒ Hm

Note:

‘Hm.new(collection)` is also available as top-level method `Hm(collection)`.

Returns a new instance of Hm.

Parameters:

  • collection —

    Any Ruby collection that has #dig method. Note though, that most of transformations only work with hashes & arrays, while #dig is useful for anything diggable.



28
29
30
 
# File 'lib/hm.rb', line 28

def initialize(collection)
  @hash = Algo.deep_copy(collection)
end

Instance Method Details

#bury(*path, value) ⇒ self

Stores value into deeply nested collection. path supports wildcards (“store at each matched path”) the same way #dig and other methods do. If specified path does not exists, it is created, with a “rule of thumb”: if next key is Integer, Array is created, otherwise it is Hash.

Caveats:

  • when :*-referred path does not exists, just :* key is stored;

  • as most of transformational methods, bury does not created and tested to work with Struct.

Examples:

order = {items: [{title: "Beef", price: 18.0}, {title: "Potato", price: 8.2}], total: 26.2}

Hm(order).bury(:items, 0, :price, 16.5).to_h
# => {:items=>[{:title=>"Beef", :price=>16.5}, {:title=>"Potato", :price=>8.2}], :total=>26.2}

# with wildcard
Hm(order).bury(:items, :*, :discount, true).to_h
# => {:items=>[{:title=>"Beef", :price=>18.0, :discount=>true}, {:title=>"Potato", :price=>8.2, :discount=>true}], :total=>26.2}

# creating nested structure (note that 0 produces Array item)
Hm(order).bury(:payments, 0, :amount, 20.0).to_h
# => {:items=>[...], :total=>26.2, :payments=>[{:amount=>20.0}]}

# :* in nested insert is not very useful
Hm(order).bury(:payments, :*, :amount, 20.0).to_h
# => {:items=>[...], :total=>26.2, :payments=>{:*=>{:amount=>20.0}}}

Parameters:

  • path —

    One key or list of keys leading to the target. :* is treated as each matched subpath.

  • value —

    Any value to store at path

Returns:

  • (self) 


116
117
118
119
120
121
122
 
# File 'lib/hm.rb', line 116

def bury(*path, value)
  Algo.visit(
    @hash, path,
    not_found: ->(at, pth, rest) { at[pth.last] = Algo.nest_hashes(value, *rest) }
  ) { |at, pth, _| at[pth.last] = value }
  self
end

#cleanup ⇒ self

Removes all “empty” values and subcollections (‘nil`s, empty strings, hashes and arrays), including nested structures. Empty subcollections are removed recoursively.

Examples:

order = {items: [{title: "Beef", price: 18.2}, {title: '', price: nil}], total: 26.2}
Hm(order).cleanup.to_h
# => {:items=>[{:title=>"Beef", :price=>18.2}], :total=>26.2}

Returns:

  • (self) 


332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
 
# File 'lib/hm.rb', line 332

def cleanup
  deletions = -1
  # We do several runs to delete recursively: {a: {b: [nil]}}
  # first: {a: {b: []}}
  # second: {a: {}}
  # third: {}
  # More effective would be some "inside out" visiting, probably
  until deletions.zero?
    deletions = 0
    Algo.visit_all(@hash) do |at, path, val|
      if val.nil? || val.respond_to?(:empty?) && val.empty?
        deletions += 1
        Algo.delete(at, path.last)
      end
    end
  end
  self
end

#compact ⇒ self

Removes all nil values, including nested structures.

Examples:

order = {items: [{title: "Beef", price: nil}, nil, {title: "Potato", price: 8.2}], total: 26.2}
Hm(order).compact.to_h
# => {:items=>[{:title=>"Beef"}, {:title=>"Potato", :price=>8.2}], :total=>26.2}

Returns:

  • (self) 


317
318
319
320
321
 
# File 'lib/hm.rb', line 317

def compact
  Algo.visit_all(@hash) do |at, path, val|
    Algo.delete(at, path.last) if val.nil?
  end
end

#dig(*path) ⇒ Object

Like Ruby’s [#dig](docs.ruby-lang.org/en/2.4.0/Hash.html#method-i-dig), but supports wildcard key :* meaning “each item at this point”.

Each level of data structure should have #dig method, otherwise TypeError is raised.

Examples:

order = {items: [{title: "Beef", price: 18.0}, {title: "Potato", price: 8.2}], total: 26.2}
Hm(order).dig(:items, 0, :title)
# => "Beef"
Hm(order).dig(:items, :*, :title)
# => ["Beef", "Potato"]
Hm(order).dig(:items, 0, :*)
# => ["Beef", 18.0]
Hm(order).dig(:items, :*, :*)
# => [["Beef", 18.0], ["Potato", 8.2]]
Hm(order).dig(:items, 3, :*)
# => nil
Hm(order).dig(:total, :count)
# TypeError: Float is not diggable

Parameters:

  • path —

    Array of keys.

Returns:

  • Object found or nil,



54
55
56
 
# File 'lib/hm.rb', line 54

def dig(*path)
  Algo.visit(@hash, path) { |_, _, val| val }
end

#dig!(*path) {|collection, path, rest| ... } ⇒ Object

Like #dig! but raises when key at any level is not found. This behavior can be changed by passed block.

Examples:

order = {items: [{title: "Beef", price: 18.0}, {title: "Potato", price: 8.2}], total: 26.2}
Hm(order).dig!(:items, 0, :title)
# => "Beef"
Hm(order).dig!(:items, 2, :title)
# KeyError: Key not found: :items/2
Hm(order).dig!(:items, 2, :title) { |collection, path, rest|
  puts "At #{path}, #{collection} does not have a key #{path.last}. Rest of path: #{rest}";
  111
}
# At [:items, 2], [{:title=>"Beef", :price=>18.0}, {:title=>"Potato", :price=>8.2}] does not have a key 2. Rest of path: [:title]
# => 111

Parameters:

  • path —

    Array of keys.

Yield Parameters:

  • collection —

    Substructure “inside” which we are currently looking

  • path —

    Path that led us to non-existent value (including current key)

  • rest —

    Rest of the requested path we’d need to look if here would not be a missing value.

Returns:

  • Object found or nil,



79
80
81
82
83
 
# File 'lib/hm.rb', line 79

def dig!(*path, &not_found)
  not_found ||=
    ->(_, pth, _) { fail KeyError, "Key not found: #{pth.map(&:inspect).join('/')}" }
  Algo.visit(@hash, path, not_found: not_found) { |_, _, val| val }
end

#except(*pathes) ⇒ self

Removes all specified pathes from input sequence.

Examples:

order = {items: [{title: "Beef", price: 18.0}, {title: "Potato", price: 8.2}], total: 26.2}
Hm(order).except(i[items * title]).to_h
# => {:items=>[{:price=>18.0}, {:price=>8.2}], :total=>26.2}
Hm(order).except([:items, 0, :title], :total).to_h
# => {:items=>[{:price=>18.0}, {:title=>"Potato", :price=>8.2}]}

Parameters:

  • pathes (Array) —

    List of pathes (each being singular key, or array of keys, including :* wildcard) to look at.

Returns:

  • (self)

See Also:



282
283
284
285
286
287
 
# File 'lib/hm.rb', line 282

def except(*pathes)
  pathes.each do |path|
    Algo.visit(@hash, path) { |what, pth, _| Algo.delete(what, pth.last) }
  end
  self
end

#partition(*pathes) {|value| ... } ⇒ Array<Hash>

Split hash into two: the one with the substructure matching pathes, and the with thos that do not.

Examples:

order = {items: [{title: "Beef", price: 18.0}, {title: "Potato", price: 8.2}], total: 26.2}
Hm(order).partition(i[items * price], :total)
# => [
#  {:items=>[{:price=>18.0}, {:price=>8.2}], :total=>26.2},
#  {:items=>[{:title=>"Beef"}, {:title=>"Potato"}]}
# ]

Parameters:

  • pathes (Array) —

    List of pathes (each being singular key, or array of keys, including :* wildcard) to look at.

Yield Parameters:

  • value (Array) —

    Current value to process.

Returns:

  • (Array<Hash>) —

    Two hashes



457
458
459
460
461
462
463
464
 
# File 'lib/hm.rb', line 457

def partition(*pathes)
  # FIXME: this implementation is naive, it performs 2 additional deep copies and 2 full cycles of
  # visiting instead of just splitting existing data in one pass. It works, though
  [
    Hm(@hash).slice(*pathes).to_h,
    Hm(@hash).except(*pathes).to_h
  ]
end

#reduce(keys_to_keys) {|memo, value| ... } ⇒ self

Calculates one value from several values at specified pathes, using specified block.

Examples:

order = {items: [{title: "Beef", price: 18.0}, {title: "Potato", price: 8.2}]}
Hm(order).reduce(i[items * price] => :total, &:+).to_h
# => {:items=>[{:title=>"Beef", :price=>18.0}, {:title=>"Potato", :price=>8.2}], :total=>26.2}
Hm(order).reduce(i[items * price] => :total, i[items * title] => :title, &:+).to_h
# => {:items=>[{:title=>"Beef", :price=>18.0}, {:title=>"Potato", :price=>8.2}], :total=>26.2, :title=>"BeefPotato"}

Parameters:

  • keys_to_keys (Hash) —

    Each key-value pair of input hash represents “source path to take values” => “target path to store result of reduce”. Each can be single key or nested path, including :* wildcard.

Yield Parameters:

  • memo
  • value

Returns:

  • (self) 


435
436
437
438
439
440
 
# File 'lib/hm.rb', line 435

def reduce(keys_to_keys, &block)
  keys_to_keys.each do |from, to|
    bury(*to, dig(*from).reduce(&block))
  end
  self
end

#reject(*pathes) {|path, value| ... } ⇒ self

Drops subset of the collection by provided block (optionally looking only at pathes specified).

Examples:

order = {items: [{title: "Beef", price: 18.0}, {title: "Potato", price: 8.2}], total: 26.2}
Hm(order).reject { |path, val| val.is_a?(Float) && val < 10 }.to_h
# => {:items=>[{:title=>"Beef", :price=>18.0}, {:title=>"Potato"}], :total=>26.2}
Hm(order).reject(i[items * price]) { |path, val| val < 10 }.to_h
# => {:items=>[{:title=>"Beef", :price=>18.0}, {:title=>"Potato"}], :total=>26.2}
Hm(order).reject(i[items *]) { |path, val| val[:price] < 10 }.to_h
# => {:items=>[{:title=>"Beef", :price=>18.0}], :total=>26.2}

Parameters:

  • pathes (Array) —

    List of pathes (each being singular key, or array of keys, including :* wildcard) to look at.

Yield Parameters:

  • path (Array) —

    Current path at which the value is found

  • value —

    Current value

Yield Returns:

  • (true, false) —

    Remove value (with corresponding key) if true.

Returns:

  • (self)

See Also:



405
406
407
408
409
410
411
412
413
414
415
416
417
418
 
# File 'lib/hm.rb', line 405

def reject(*pathes)
  if pathes.empty?
    Algo.visit_all(@hash) do |at, path, val|
      Algo.delete(at, path.last) if yield(path, val)
    end
  else
    pathes.each do |path|
      Algo.visit(@hash, path) do |at, pth, val|
        Algo.delete(at, pth.last) if yield(pth, val)
      end
    end
  end
  self
end

#select(*pathes) {|path, value| ... } ⇒ self

Select subset of the collection by provided block (optionally looking only at pathes specified).

Method is added mostly for completeness, as filtering out wrong values is better done with #reject, and selecting just by subset of keys by #slice and #except.

Examples:

order = {items: [{title: "Beef", price: 18.0}, {title: "Potato", price: 8.2}], total: 26.2}
Hm(order).select { |path, val| val.is_a?(Float) }.to_h
# => {:items=>[{:price=>18.0}, {:price=>8.2}], :total=>26.2}
Hm(order).select([:items, :*, :price]) { |path, val| val > 10 }.to_h
# => {:items=>[{:price=>18.0}]}

Parameters:

  • pathes (Array) —

    List of pathes (each being singular key, or array of keys, including :* wildcard) to look at.

Yield Parameters:

  • path (Array) —

    Current path at which the value is found

  • value —

    Current value

Yield Returns:

  • (true, false) —

    Preserve value (with corresponding key) if true.

Returns:

  • (self)

See Also:



370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
 
# File 'lib/hm.rb', line 370

def select(*pathes)
  res = Hm.new({})
  if pathes.empty?
    Algo.visit_all(@hash) do |_, path, val|
      res.bury(*path, val) if yield(path, val)
    end
  else
    pathes.each do |path|
      Algo.visit(@hash, path) do |_, pth, val|
        res.bury(*pth, val) if yield(pth, val)
      end
    end
  end
  @hash = res.to_h
  self
end

#slice(*pathes) ⇒ self

Preserves only specified pathes from input sequence.

Examples:

order = {items: [{title: "Beef", price: 18.0}, {title: "Potato", price: 8.2}], total: 26.2}
Hm(order).slice(i[items * title]).to_h
# => {:items=>[{:title=>"Beef"}, {:title=>"Potato"}]}

Parameters:

  • pathes (Array) —

    List of pathes (each being singular key, or array of keys, including :* wildcard) to look at.

Returns:

  • (self)

See Also:



300
301
302
303
304
305
306
307
 
# File 'lib/hm.rb', line 300

def slice(*pathes)
  result = Hm.new({})
  pathes.each do |path|
    Algo.visit(@hash, path) { |_, new_path, val| result.bury(*new_path, val) }
  end
  @hash = result.to_h
  self
end

#to_h ⇒ Hash Also known as: to_hash

Returns the result of all the processings inside the Hm object.

Note, that you can pass an Array as a top-level structure to Hm, and in this case to_h will return the processed Array… Not sure what to do about that currently.

Returns:

  • (Hash) 


472
473
474
 
# File 'lib/hm.rb', line 472

def to_h
  @hash
end

#transform(keys_to_keys, &processor) {|value| ... } ⇒ self

Note:

Currently, only one wildcard per each from and to pattern is supported.

Renames input pathes to target pathes, with wildcard support.

Examples:

order = {items: [{title: "Beef", price: 18.0}, {title: "Potato", price: 8.2}], total: 26.2}
Hm(order).transform(i[items * price] => i[items * price_cents]).to_h
# => {:items=>[{:title=>"Beef", :price_cents=>18.0}, {:title=>"Potato", :price_cents=>8.2}], :total=>26.2}
Hm(order).transform(i[items * price] => i[items * price_usd]) { |val| val / 100.0 }.to_h
# => {:items=>[{:title=>"Beef", :price_usd=>0.18}, {:title=>"Potato", :price_usd=>0.082}], :total=>26.2}
Hm(order).transform(i[items *] => :*).to_h # copying them out
# => {:items=>[], :total=>26.2, 0=>{:title=>"Beef", :price=>18.0}, 1=>{:title=>"Potato", :price=>8.2}}

Parameters:

  • keys_to_keys (Hash) —

    Each key-value pair of input hash represents “source path to take values” => “target path to store values”. Each can be single key or nested path, including :* wildcard.

  • processor (Proc) —

    Optional block to process value with while moving.

Yield Parameters:

  • value

Returns:

  • (self)

See Also:



171
172
173
174
 
# File 'lib/hm.rb', line 171

def transform(keys_to_keys, &processor)
  keys_to_keys.each { |from, to| transform_one(Array(from), Array(to), &processor) }
  self
end

#transform_keys(*pathes) {|key| ... } ⇒ self

Performs specified transformations on keys of input sequence, optionally limited only by specified pathes.

Note that when pathes parameter is passed, only keys directly matching the pathes are processed, not entire sub-collection under this path.

Examples:

order = {items: [{title: "Beef", price: 18.0}, {title: "Potato", price: 8.2}], total: 26.2}
Hm(order).transform_keys(&:to_s).to_h
# => {"items"=>[{"title"=>"Beef", "price"=>18.0}, {"title"=>"Potato", "price"=>8.2}], "total"=>26.2}
Hm(order)
  .transform_keys(&:to_s)
  .transform_keys(['items', :*, :*], &:capitalize)
  .transform_keys(:*, &:upcase).to_h
# => {"ITEMS"=>[{"Title"=>"Beef", "Price"=>18.0}, {"Title"=>"Potato", "Price"=>8.2}], "TOTAL"=>26.2}

Parameters:

  • pathes (Array) —

    List of pathes (each being singular key, or array of keys, including :* wildcard) to look at.

Yield Parameters:

  • key (Array) —

    Current key to process.

Returns:

  • (self)

See Also:



219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
 
# File 'lib/hm.rb', line 219

def transform_keys(*pathes)
  if pathes.empty?
    Algo.visit_all(@hash) do |at, path, val|
      if at.is_a?(Hash)
        at.delete(path.last)
        at[yield(path.last)] = val
      end
    end
  else
    pathes.each do |path|
      Algo.visit(@hash, path) do |at, pth, val|
        Algo.delete(at, pth.last)
        at[yield(pth.last)] = val
      end
    end
  end
  self
end

#transform_values(*pathes) {|value| ... } ⇒ self

Performs specified transformations on values of input sequence, limited only by specified pathes.

If no pathes are passed, all “terminal” values (e.g. not diggable) are yielded and transformed.

Examples:

order = {items: [{title: "Beef", price: 18.0}, {title: "Potato", price: 8.2}], total: 26.2}
Hm(order).transform_values(i[items * price], :total, &:to_s).to_h
# => {:items=>[{:title=>"Beef", :price=>"18.0"}, {:title=>"Potato", :price=>"8.2"}], :total=>"26.2"}
Hm(order).transform_values(&:to_s).to_h
# => {:items=>[{:title=>"Beef", :price=>"18.0"}, {:title=>"Potato", :price=>"8.2"}], :total=>"26.2"}

Parameters:

  • pathes (Array) —

    List of pathes (each being singular key, or array of keys, including :* wildcard) to look at.

Yield Parameters:

  • value (Array) —

    Current value to process.

Returns:

  • (self)

See Also:



256
257
258
259
260
261
262
263
264
265
266
267
 
# File 'lib/hm.rb', line 256

def transform_values(*pathes)
  if pathes.empty?
    Algo.visit_all(@hash) do |at, pth, val|
      at[pth.last] = yield(val) unless Dig.diggable?(val)
    end
  else
    pathes.each do |path|
      Algo.visit(@hash, path) { |at, pth, val| at[pth.last] = yield(val) }
    end
  end
  self
end

#update(keys_to_keys, &processor) {|value| ... } ⇒ self

Like #transform, but copies values instead of moving them (original keys/values are preserved).

Examples:

order = {items: [{title: "Beef", price: 18.0}, {title: "Potato", price: 8.2}], total: 26.2}
Hm(order).update(i[items * price] => i[items * price_usd]) { |val| val / 100.0 }.to_h
# => {:items=>[{:title=>"Beef", :price=>18.0, :price_usd=>0.18}, {:title=>"Potato", :price=>8.2, :price_usd=>0.082}], :total=>26.2}

Parameters:

  • keys_to_keys (Hash) —

    Each key-value pair of input hash represents “source path to take values” => “target path to store values”. Each can be single key or nested path, including :* wildcard.

  • processor (Proc) —

    Optional block to process value with while copying.

Yield Parameters:

  • value

Returns:

  • (self)

See Also:



192
193
194
195
 
# File 'lib/hm.rb', line 192

def update(keys_to_keys, &processor)
  keys_to_keys.each { |from, to| transform_one(Array(from), Array(to), remove: false, &processor) }
  self
end

#visit(*path, not_found: ->(*) {}) {|collection, path, value| ... } ⇒ self

Low-level collection walking mechanism.

Examples:

order = {items: [{title: "Beef", price: 18.0}, {title: "Potato"}]}
order.visit(:items, :*, :price,
  not_found: ->(at, path, rest) { puts "#{at} at #{path}: nothing here!" }
) { |at, path, val| puts "#{at} at #{path}: #{val} is here!" }
# {:title=>"Beef", :price=>18.0} at [:items, 0, :price]: 18.0 is here!
# {:title=>"Potato"} at [:items, 1, :price]: nothing here!

Parameters:

  • path —

    Path to values to visit, :* wildcard is supported.

  • not_found (Proc) (defaults to: ->(*) {}) —

    Optional proc to call when specified path is not found. Params are collection (current sub-collection where key is not found), path (current path) and rest (the rest of path we need to walk).

Yield Parameters:

  • collection —

    Current subcollection we are looking at

  • path (Array) —

    Current path we are at (in place of :* wildcards there are real keys).

  • value —

    Current value

Returns:

  • (self) 


143
144
145
146
 
# File 'lib/hm.rb', line 143

def visit(*path, not_found: ->(*) {}, &block)
  Algo.visit(@hash, path, not_found: not_found, &block)
  self
end