hm 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 49f552a6aaf919dbd0d5909c5e88b6e16a949fe4
+  data.tar.gz: 5d0b3b428620f7542e276ba0431ff9278e256643
+SHA512:
+  metadata.gz: 3f0e5d2db2a5bc0a0e5b39aa05aed137b235d4ec115739e063dc1bdde4eab15842a5220202e5eb4ffb4b42fdc4015cdacb0d97582ac79d4ac92a9f2422b4c881
+  data.tar.gz: 7fd96ca72e8218a82663176b38549f3688e040f6efc74d923bd815006571aae1c83bacf20ff4bb3a0f3609aac0d1ceedf42421019c3f1dff7708f87807780b94

data/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Victor 'zverok' Shepelev
+
+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,183 @@
+# Hm? Hm!
+
+[![Gem Version](https://badge.fury.io/rb/hm.svg)](http://badge.fury.io/rb/hm)
+[![Build Status](https://travis-ci.org/zverok/hm.svg?branch=master)](https://travis-ci.org/zverok/hm)
+
+**Hm** is an experimental Ruby gem trying to provide effective, idiomatic, chainable **H**ash
+**m**odifications (transformations) DSL.
+
+## Showcase
+
+```ruby
+api_json = <<-JSON
+{
+  "coord": {"lon": -0.13, "lat": 51.51},
+  "weather": [{"id": 300, "main": "Drizzle", "description": "light intensity drizzle", "icon": "09d"}],
+  "base": "stations",
+  "main": {"temp": 280.32, "pressure": 1012, "humidity": 81, "temp_min": 279.15, "temp_max": 281.15},
+  "visibility": 10000,
+  "wind": {"speed": 4.1, "deg": 80},
+  "clouds": {"all": 90},
+  "dt": 1485789600,
+  "sys": {"type": 1, "id": 5091, "message": 0.0103, "country": "GB", "sunrise": 1485762037, "sunset": 1485794875},
+  "id": 2643743,
+  "name": "London",
+  "cod": 200
+}
+JSON
+
+weather = JSON.parse(api_json)
+pp Hm.new(weather)
+  .transform_keys(&:to_sym)                         # symbolize all keys
+  .except(:id, :cod, %i[sys id], %i[weather * id])  # remove some system values
+  .transform(
+    %i[main *] => :*,                               # move all {main: {temp: X}} to just {temp: X}
+    %i[sys *] => :*,                                # same for :sys
+    %i[coord *] => :coord,                          # gather values for coord.lat, coord.lng into Array in :coord
+    [:weather, 0] => :weather,                      # move first of :weather Array to just :weather key
+    dt: :timestamp                                  # rename :dt to :timestamp
+  )
+  .cleanup                                          # remove now empty main: {} and sys: {} hashes
+  .transform_values(
+    :timestamp, :sunrise, :sunset,
+    &Time.method(:at))                              # parse timestamps
+  .bury(:weather, :comment, 'BAD')                  # insert some random new key
+  .to_h
+# {
+#  :coord=>[-0.13, 51.51],
+#  :weather=> {:main=>"Drizzle", :description=>"light intensity drizzle", :icon=>"09d", :comment=>"BAD"},
+#  :base=>"stations",
+#  :visibility=>10000,
+#  :wind=>{:speed=>4.1, :deg=>80},
+#  :clouds=>{:all=>90},
+#  :name=>"London",
+#  :temp=>280.32,
+#  :pressure=>1012,
+#  :humidity=>81,
+#  :temp_min=>279.15,
+#  :temp_max=>281.15,
+#  :type=>1,
+#  :message=>0.0103,
+#  :country=>"GB",
+#  :sunrise=>2017-01-30 09:40:37 +0200,
+#  :sunset=>2017-01-30 18:47:55 +0200,
+#  :timestamp=>2017-01-30 17:20:00 +0200}
+# }
+```
+
+## Features/problems
+
+* Small, no-dependencies, no-monkey patching, just "plug and play";
+* Idiomatic, terse, chainable;
+* Very new and experimental, works on the cases I've extracted from different production problems and
+  invented on the road, but may not work for yours;
+* Most of the methods work on Arrays and Hashes, but not on `Struct` and `OpenStruct` (which are
+  `dig`-able in Ruby), though, base `#dig` and `#dig!` should work on them too;
+* API is subject to polish and change in future.
+
+## Usage
+
+Install it with `gem install hm` or adding `gem 'hm'` in your `Gemfile`.
+
+One of the most important concepts of `Hm` is "path" through the structure. It is the same list of
+keys Ruby's native `#dig()` supports, with one, yet powerful, addition: `:*` stands for `each` (works
+with any `Enumerable` that is met at the structure at this point):
+
+```ruby
+order = {
+  date: Date.today,
+  items: [
+    {title: 'Beer', price: 10.0},
+    {title: 'Beef', price: 5.0},
+    {title: 'Potato', price: 7.8}
+  ]
+}
+Hm(order).dig(:items, :*, :price) # => [10.0, 5.0, 7.8]
+```
+
+On top of that, `Hm` provides a set of chainable transformations, which can be used this way:
+
+```ruby
+Hm(some_hash)
+  .transformation(...)
+  .transformation(...)
+  .transformation(...)
+  .to_h # => return the processed hash
+```
+
+List of currently available transformations:
+
+* `bury(:key1, :key2, :key3, value)` — opposite to `dig`, stores value in a nested structure;
+* `transform([:path, :to, :key] => [:other, :path], [:multiple, :*, :values] => [:other, :*])` —
+  powerful key renaming, with wildcards support;
+* `transform_keys(path, path, path) { |key| ... }` — works with nested hashes (so you can just
+  `transform_keys(&:to_sym)` to deep symbolize keys), and is able to limit processing to only
+  specified pathes, like `transform_keys([:order, :items, :*, :*], &:capitalize)`
+* `transform_values(path, path, path) { |key| ... }`
+* `update` — same as `transform`, but copies source key to target ones, instead of moving;
+* `slice(:key1, :key2, [:path, :to, :*, :key3])` — extracts only list of specified key pathes;
+* `except(:key1, :key2, [:path, :to, :*, :key3])` — removes list of specified key pathes;
+* `compact` removes all `nil` values, including nested collections;
+* `cleanup` recursively removes all "empty" values (empty strings, hashes, arrays, `nil`s);
+* `select(path, path) { |val| ... }` — selects only parts of hash that match specified pathes and
+  specified block;
+* `reject(path, path) { |val| ... }` — drops parts of hash that match specified pathes and
+  specified block;
+* `reduce([:path, :to, :*, :values] => [:path, :to, :result]) { |memo, val| ... }` — reduce several
+  values into one, like `reduce(%i[items * price] => :total, &:+)`.
+
+Look at [API docs](http://www.rubydoc.info/gems/hm) for details about each method.
+
+## Further goals
+
+Currently, I am planning to just use existing one in several projects and see how it will go. The
+ideas to where it can be developed further exist, though:
+
+* Just add more useful methods (like `merge` probably), and make their addition modular;
+* There is a temptation for more powerful "dig path language", I am looking for a real non-imaginary
+   cases for those, theoretically pretty enchancements:
+  * `:**` for arbitrary depth;
+  * `/foo/` and `(0..1)` for selecting key ranges;
+  * `[:weather, [:sunrise, :sunset]]` for selecting `weather.sunrise` AND `weather.sunset` path;
+  * `[:items, {title: 'Potato'}]` for selecting whole hashes from `:items`, which have `title: 'Potato'`
+    in them.
+* `Hm()` idiom for storing necessary transformations in constants:
+
+```ruby
+WEATHER_TRANSFORM = Hm()
+  .tranform(%w[temp min] => :temp_min, %w[temp max] => :temp_max)
+  .transform_values(:dt, &Time.method(:at))
+
+# ...later...
+weathers.map(&WEATHER_TRANSFORM)
+```
+* "Inline expectations framework":
+
+```ruby
+Hm(api_response)
+  .expect(:results, 0, :id) # raises if api_response[:results][0][:id] is absent
+  .transform(something, something) # continue with our tranformations
+```
+
+If you find something of the above useful for production use-cases, drop me a note (or GitHub issue;
+or, even better, PR!).
+
+## Prior art
+
+Hash transformers:
+
+* https://github.com/solnic/transproc
+* https://github.com/deseretbook/hashformer
+
+Hash paths:
+
+* https://github.com/nickcharlton/keypath-ruby
+* https://github.com/maiha/hash-path
+
+## Author
+
+[Victor Shepelev aka @zverok](https://zverok.github.io)
+
+## License
+
+MIT

data/lib/hm.rb

@@ -0,0 +1,483 @@
+# `Hm` is a wrapper for chainable, terse, idiomatic Hash modifications.
+#
+# @example
+#    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 #Hm
+class Hm
+  # @private
+  WILDCARD = :*
+
+  # @note
+  #   `Hm.new(collection)` is also available as top-level method `Hm(collection)`.
+  #
+  # @param 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.
+  def initialize(collection)
+    @hash = Algo.deep_copy(collection)
+  end
+
+  # Like Ruby's [#dig](https://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.
+  #
+  # @example
+  #   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
+  #
+  # @param path Array of keys.
+  # @return Object found or `nil`,
+  def dig(*path)
+    Algo.visit(@hash, path) { |_, _, val| val }
+  end
+
+  # Like {#dig!} but raises when key at any level is not found. This behavior can be changed by
+  # passed block.
+  #
+  # @example
+  #   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
+  #
+  # @param path Array of keys.
+  # @yieldparam collection Substructure "inside" which we are currently looking
+  # @yieldparam path Path that led us to non-existent value (including current key)
+  # @yieldparam rest Rest of the requested path we'd need to look if here would not be a missing value.
+  # @return Object found or `nil`,
+  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
+
+  # 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`.
+  #
+  # @example
+  #   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}}}
+  #
+  # @param path One key or list of keys leading to the target. `:*` is treated as
+  #   each matched subpath.
+  # @param value Any value to store at path
+  # @return [self]
+  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
+
+  # Low-level collection walking mechanism.
+  #
+  # @example
+  #   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!
+  #
+  # @param path Path to values to visit, `:*` wildcard is supported.
+  # @param not_found [Proc] 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).
+  # @yieldparam collection Current subcollection we are looking at
+  # @yieldparam path [Array] Current path we are at (in place of `:*` wildcards there are real
+  #   keys).
+  # @yieldparam value Current value
+  # @return [self]
+  def visit(*path, not_found: ->(*) {}, &block)
+    Algo.visit(@hash, path, not_found: not_found, &block)
+    self
+  end
+
+  # Renames input pathes to target pathes, with wildcard support.
+  #
+  # @note
+  #   Currently, only one wildcard per each from and to pattern is supported.
+  #
+  # @example
+  #   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}}
+  #
+  # @see #transform_keys
+  # @see #transform_values
+  # @see #update
+  # @param 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.
+  # @param processor [Proc] Optional block to process value with while moving.
+  # @yieldparam value
+  # @return [self]
+  def transform(keys_to_keys, &processor)
+    keys_to_keys.each { |from, to| transform_one(Array(from), Array(to), &processor) }
+    self
+  end
+
+  # Like {#transform}, but copies values instead of moving them (original keys/values are preserved).
+  #
+  # @example
+  #   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}
+  #
+  # @see #transform_keys
+  # @see #transform_values
+  # @see #transform
+  # @param 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.
+  # @param processor [Proc] Optional block to process value with while copying.
+  # @yieldparam value
+  # @return [self]
+  def update(keys_to_keys, &processor)
+    keys_to_keys.each { |from, to| transform_one(Array(from), Array(to), remove: false, &processor) }
+    self
+  end
+
+  # 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.
+  #
+  # @example
+  #   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}
+  #
+  # @see #transform_values
+  # @see #transform
+  # @param pathes [Array] List of pathes (each being singular key, or array of keys, including
+  #   `:*` wildcard) to look at.
+  # @yieldparam key [Array] Current key to process.
+  # @return [self]
+  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
+
+  # Performs specified transformations on values of input sequence, limited only by specified
+  # pathes.
+  #
+  # @note
+  #   Unlike {#transform_keys}, this method does nothing when no pathes are passed (e.g. not runs
+  #   transformation on each value), because the semantic would be unclear. In our `:order` example,
+  #   list of all items is a value _too_, at `:items` key, so should it be also transformed?
+  #
+  # @example
+  #   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"}
+  #
+  # @see #transform_values
+  # @see #transform
+  # @param pathes [Array] List of pathes (each being singular key, or array of keys, including
+  #   `:*` wildcard) to look at.
+  # @yieldparam value [Array] Current value to process.
+  # @return [self]
+  def transform_values(*pathes)
+    pathes.each do |path|
+      Algo.visit(@hash, path) { |at, pth, val| at[pth.last] = yield(val) }
+    end
+    self
+  end
+
+  # Removes all specified pathes from input sequence.
+  #
+  # @example
+  #   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}]}
+  #
+  # @see #slice
+  # @param pathes [Array] List of pathes (each being singular key, or array of keys, including
+  #   `:*` wildcard) to look at.
+  # @return [self]
+  def except(*pathes)
+    pathes.each do |path|
+      Algo.visit(@hash, path) { |what, pth, _| Algo.delete(what, pth.last) }
+    end
+    self
+  end
+
+  # Preserves only specified pathes from input sequence.
+  #
+  # @example
+  #   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"}]}
+  #
+  # @see #except
+  # @param pathes [Array] List of pathes (each being singular key, or array of keys, including
+  #   `:*` wildcard) to look at.
+  # @return [self]
+  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
+
+  # Removes all `nil` values, including nested structures.
+  #
+  # @example
+  #   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}
+  #
+  # @return [self]
+  def compact
+    Algo.visit_all(@hash) do |at, path, val|
+      Algo.delete(at, path.last) if val.nil?
+    end
+  end
+
+  # Removes all "empty" values and subcollections (`nil`s, empty strings, hashes and arrays),
+  # including nested structures. Empty subcollections are removed recoursively.
+  #
+  # @example
+  #   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}
+  #
+  # @return [self]
+  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
+
+  # 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}.
+  #
+  # @example
+  #   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}]}
+  #
+  # @see #reject
+  # @param pathes [Array] List of pathes (each being singular key, or array of keys, including
+  #   `:*` wildcard) to look at.
+  # @yieldparam path [Array] Current path at which the value is found
+  # @yieldparam value Current value
+  # @yieldreturn [true, false] Preserve value (with corresponding key) if true.
+  # @return [self]
+  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
+
+  # Drops subset of the collection by provided block (optionally looking only at pathes specified).
+  #
+  # @example
+  #   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}
+  #
+  # @see #select
+  # @param pathes [Array] List of pathes (each being singular key, or array of keys, including
+  #   `:*` wildcard) to look at.
+  # @yieldparam path [Array] Current path at which the value is found
+  # @yieldparam value Current value
+  # @yieldreturn [true, false] Remove value (with corresponding key) if true.
+  # @return [self]
+  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
+
+  # Calculates one value from several values at specified pathes, using specified block.
+  #
+  # @example
+  #   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"}
+  #
+  # @param 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.
+  # @yieldparam memo
+  # @yieldparam value
+  # @return [self]
+  def reduce(keys_to_keys, &block)
+    keys_to_keys.each do |from, to|
+      bury(*to, dig(*from).reduce(&block))
+    end
+    self
+  end
+
+  # 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.
+  #
+  # @return [Hash]
+  def to_h
+    @hash
+  end
+
+  alias to_hash to_h
+
+  private
+
+  def transform_one(from, to, remove: true, &_processor) # rubocop:disable Metrics/AbcSize,Metrics/PerceivedComplexity,Metrics/CyclomaticComplexity
+    to.count(:*) > 1 || from.count(:*) > 1 and
+      fail NotImplementedError, 'Transforming to multi-wildcards is not implemented'
+
+    from_values = {}
+    Algo.visit(
+      @hash, from,
+      # [:item, :*, :price] -- if one item is priceless, should go to output sequence
+      # ...but what if last key is :*? something like from_values.keys.last.succ or?..
+      not_found: ->(_, path, rest) { from_values[path + rest] = nil }
+    ) { |_, path, val| from_values[path] = block_given? ? yield(val) : val }
+    except(from) if remove
+    if (ti = to.index(:*))
+      fi = from.index(:*) # TODO: what if `from` had no wildcard?
+
+      # we unpack [:items, :*, :price] with keys we got from gathering values,
+      # like [:items, 0, :price], [:items, 1, :price] etc.
+      from_values
+        .map { |key, val| [to.dup.tap { |a| a[ti] = key[fi] }, val] }
+        .each { |path, val| bury(*path, val) }
+    else
+      val = from_values.count == 1 ? from_values.values.first : from_values.values
+      bury(*to, val)
+    end
+  end
+end
+
+require_relative 'hm/algo'
+
+# Shortcut for {Hm}.new
+def Hm(hash) # rubocop:disable Naming/MethodName
+  Hm.new(hash)
+end

data/lib/hm/algo.rb

@@ -0,0 +1,95 @@
+class Hm
+  # @private
+  module Algo
+    module_function
+
+    def delete(collection, key)
+      collection.is_a?(Array) ? collection.delete_at(key) : collection.delete(key)
+    end
+
+    # JRuby, I am looking at you
+    NONDUPABLE = [Symbol, Numeric, NilClass, TrueClass, FalseClass].freeze
+
+    def deep_copy(value)
+      # FIXME: ignores Struct/OpenStruct (which are diggable too)
+      case value
+      when Hash
+        value.map { |key, val| [key, deep_copy(val)] }.to_h
+      when Array
+        value.map(&method(:deep_copy))
+      when *NONDUPABLE
+        value
+      else
+        value.dup
+      end
+    end
+
+    def to_pairs(collection)
+      case
+      when collection.respond_to?(:each_pair)
+        collection.each_pair.to_a
+      when collection.respond_to?(:each)
+        collection.each_with_index.to_a.map(&:reverse)
+      else
+        fail TypeError, "Can't dig/* in #{collection.class}"
+      end
+    end
+
+    # Enumerates through entire collection with "current key/current values" at each point, even
+    # if elements are deleted in a process of enumeration
+    def robust_enumerator(collection)
+      return to_pairs(collection) if collection.is_a?(Hash)
+
+      # Only Arrays need this kind of trickery
+      Enumerator.new do |y|
+        cur = collection.size
+        until cur.zero?
+          pairs = to_pairs(collection)
+          pos = pairs.size - cur
+          y << pairs[pos]
+          cur -= 1
+        end
+      end
+    end
+
+    def nest_hashes(value, *keys)
+      return value if keys.empty?
+      key = keys.shift
+      val = keys.empty? ? value : nest_hashes(value, *keys)
+      key.is_a?(Integer) ? [].tap { |arr| arr[key] = val } : {key => val}
+    end
+
+    def visit(what, rest, path = [], not_found: ->(*) {}, &found)
+      what.respond_to?(:dig) or fail TypeError, "#{what.class} is not diggable"
+
+      key, *rst = rest
+      if key == WILDCARD
+        visit_wildcard(what, rst, path, found: found, not_found: not_found)
+      else
+        visit_regular(what, key, rst, path, found: found, not_found: not_found)
+      end
+    end
+
+    def visit_all(what, path = [], &block)
+      robust_enumerator(what).each do |key, val|
+        yield(what, [*path, key], val)
+        visit_all(val, [*path, key], &block) if val.respond_to?(:dig)
+      end
+    end
+
+    def visit_wildcard(what, rest, path, found:, not_found:)
+      iterator = robust_enumerator(what)
+      if rest.empty?
+        iterator.map { |key, val| found.(what, [*path, key], val) }
+      else
+        iterator.map { |key, el| visit(el, rest, [*path, key], not_found: not_found, &found) }
+      end
+    end
+
+    def visit_regular(what, key, rest, path, found:, not_found:) # rubocop:disable Metrics/ParameterLists
+      internal = what.dig(key) or return not_found.(what, [*path, key], rest)
+      rest.empty? and return found.(what, [*path, key], internal)
+      visit(internal, rest, [*path, key], not_found: not_found, &found)
+    end
+  end
+end

metadata

@@ -0,0 +1,218 @@
+--- !ruby/object:Gem::Specification
+name: hm
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Victor Shepelev
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-02-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: github-markup
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard-junk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.7.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.7.0
+- !ruby/object:Gem::Dependency
+  name: rspec-its
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: saharspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubygems-tasks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |2
+      Hm is a library for clean, idiomatic and chainable processing of complicated Ruby structures,
+      typically unpacked from JSON. It provides smart dig and bury, keys replacement,
+      nested transformations and more.
+email: zverok.offline@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/hm.rb
+- lib/hm/algo.rb
+homepage: https://github.com/zverok/hm
+licenses:
+- MIT
+metadata: {}
+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: []
+rubyforge_project: 
+rubygems_version: 2.6.14
+signing_key: 
+specification_version: 4
+summary: Idiomatic nested hash modifications
+test_files: []