deepmap 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e83602369521a1799962c9cba500b4f4a5c0d16a16555a7738c5de3687c5b7c5
-  data.tar.gz: a58bdf656de275c1957c6e9a42fbc4399f1480e84129f112c1cb554f8a407823
+  metadata.gz: 240ee3a7cd29cd15d11424600fc2940cfbcc7983fefe6ae01be3c22fc8683a96
+  data.tar.gz: 52145a92013910d58b1130b1f6a18a68562db6d4c833ec8d800d3ccaaca1a403
 SHA512:
-  metadata.gz: 4f6c34154cef76baca26ae3bd24bda7badc8063e865ac190bba8340c42757914dffc2aec4bd78b84132910a466131854641101576bfba8d08a648f7f474519ae
-  data.tar.gz: 91b53fcda525ab6e2cc6915de7964471d6a16e8b1e0c6b3a9a46ce57dc7ec82daeb731a19ea42b4e8517dbf21dd7f7e41bfe66a4e0eb29a04470663572556318
+  metadata.gz: d850a9b0a49e7a19734c8ab7f94b074a01eb3216089d72a9c2f2911a4abacf545ecc4f8bcdc155df6c0c2ec7a24c4684e757b64ca4063f6b0596efe534a890d2
+  data.tar.gz: 7702ed7f53b51a6030712286d870491feafdb9544aa40f35442aa07324c0b0eea2e06a4cba8dd7dd34259fb045ba450d81084f362fb00408d90ecb7f20fde928

data/lib/deepmap/deepmap.rb

@@ -2,22 +2,29 @@
 
 # Creating deep_map, key_map, val_map methods in DeepMap.
 module DeepMap
-  def deep_map(&)
-    return self unless block_given?
+  # Raised when on_collision: :raise is set and a key transform produces
+  # duplicate keys within the same hash level.
+  class KeyCollisionError < StandardError; end
 
-    recurse(&)
+  # Valid on_collision modes for deep_map and key_map.
+  COLLISION_MODES = %i[warn raise ignore].freeze
+
+  def deep_map(on_collision: :warn, &block)
+    return self unless block
+
+    recurse(self, t: 'both', on_collision: collision_mode(on_collision), &pairable(block))
   end
 
-  def key_map(&)
-    return self unless block_given?
+  def key_map(on_collision: :warn, &block)
+    return self unless block
 
-    recurse('key', &)
+    recurse(self, t: 'key', on_collision: collision_mode(on_collision), &pairable(block))
   end
 
-  def val_map(&)
-    return self unless block_given?
+  def val_map(&block)
+    return self unless block
 
-    recurse('val', &)
+    recurse(self, t: 'val', &pairable(block))
   end
 
   private
@@ -28,33 +35,59 @@ module DeepMap
   # the key is a hash, than collect the results of calling it recursively. If
   # the key is an array, then map the recursive method over each item in the
   # array. If it is niether a hash or an array, then apply the block to that
-  # item, and return the result.
+  # item, and return the result. 'k' carries the nearest ancestor hash key down
+  # through arrays/leaves so value blocks can optionally see it too.
 
-  def recurse(t = 'both', h = self, &block)
+  def recurse(h, k = nil, t:, on_collision: :warn, &block)
     case h
     when Hash
-      hash_collect(t, h, &block)
+      hash_collect(h, t:, on_collision:, &block)
 
     when Array
-      h.map { |v| recurse(t, v, &block) }
+      h.map { |v| recurse(v, k, t:, on_collision:, &block) }
 
     else # apply to value
-      t == 'key' ? h : yield(h)
+      t == 'key' ? h : yield(h, k)
 
     end
   end
 
-  def hash_collect(t, h, &block)
-    h.to_h do |k, v|
-      case t # type
-      when 'both', 'key'
-        [yield(k), recurse(t, v, &block)]
+  # Transformed keys that collide collapse in to_h (last pair wins), which is
+  # detectable as the result shrinking. Val mode never transforms keys, so it
+  # can never shrink and needs no special casing here.
+  def hash_collect(h, t:, on_collision:, &block)
+    pairs = h.map do |k, v|
+      [t == 'val' ? k : yield(k, v), recurse(v, k, t:, on_collision:, &block)]
+    end
+
+    result = pairs.to_h
+    report_collisions(pairs, on_collision) if result.size < pairs.size
+    result
+  end
 
-      when 'val'
-        [k, recurse(t, v, &block)]
+  def report_collisions(pairs, on_collision)
+    return if on_collision == :ignore
 
-      end
-    end
+    dupes = pairs.map(&:first).tally.select { |_, count| count > 1 }.keys
+    message = "deepmap: key collision(s) produced duplicate key(s) #{dupes.inspect}; " \
+              'earlier entries will be overwritten'
+    raise KeyCollisionError, message if on_collision == :raise
+
+    warn message
+  end
+
+  def collision_mode(mode)
+    return mode if COLLISION_MODES.include?(mode)
+
+    raise ArgumentError, "on_collision must be one of #{COLLISION_MODES.inspect}, got #{mode.inspect}"
+  end
+
+  # Blocks are yielded two arguments (the mapped item plus its counterpart).
+  # Plain blocks that mention one argument just discard the second, but strict
+  # arity callables (&:method, method references, lambdas) would not -- wrap
+  # those so they keep receiving the single argument they expect.
+  def pairable(block)
+    block.lambda? && block.arity != 2 ? proc { |a| block.call(a) } : block
   end
 end
 

data/lib/deepmap/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DeepMap
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

data/readme.md

@@ -57,6 +57,45 @@ irb(main):005:0> test.val_map(&:upcase)
 => {"a"=>"B", "c"=>["D", "E"], "f"=>{"g"=>["H", "I", {"j"=>"K"}]}}
 ```
 
+Blocks may also take a second argument to make decisions based on both the key
+and the value, even while nominally mapping over just one of them. For
+`key_map`, the first argument is the key and the second is the value; for
+`val_map` it's the other way around, so single-argument blocks (including the
+`&:method` shortcut) keep working exactly as before:
+
+```ruby
+irb(main):002:0> test = { 1 => 'a', -2 => 'b', 3 => 'c' }
+=> {1=>"a", -2=>"b", 3=>"c"}
+
+irb(main):003:0> test.key_map {|k, v| k.positive? ? k * 10 : v }
+=> {10=>"a", "b"=>"b", 30=>"c"}
+
+irb(main):004:0> test.val_map {|v, k| k.positive? ? v.upcase : v }
+=> {1=>"A", -2=>"b", 3=>"C"}
+```
+
+## key collisions
+
+Since `key_map` and `deep_map` can map two different keys to the same new key,
+it's possible for the resulting hash to silently drop an entry (the last pair
+wins). By default this is checked for and reported with a warning; pass
+`on_collision:` to `key_map`/`deep_map` to change that behavior:
+
+```ruby
+irb(main):002:0> { 1 => 'a', 2 => 'b' }.key_map {|k| 0 }
+deepmap: key collision(s) produced duplicate key(s) [0]; earlier entries will be overwritten
+=> {0=>"b"}
+
+irb(main):003:0> { 1 => 'a', 2 => 'b' }.key_map(on_collision: :raise) {|k| 0 }
+DeepMap::KeyCollisionError: deepmap: key collision(s) produced duplicate key(s) [0]; earlier entries will be overwritten
+
+irb(main):004:0> { 1 => 'a', 2 => 'b' }.key_map(on_collision: :ignore) {|k| 0 }
+=> {0=>"b"}
+```
+
+`val_map` never transforms keys, so it has no `on_collision` option. Passing
+anything other than `:warn`, `:raise`, or `:ignore` raises an `ArgumentError`.
+
 ## development / testing
 
 First, clone this repo:
@@ -79,10 +118,3 @@ tests. To run the full suite:
 
     just ci
 
-## todo
-
-* collison checking/warning/confirmation workflow
-* support key-val iteration in mapping over vals/keys. This would allow support
-  for mapping conditionally based on a key/value, even if you are iterating
-  over all values/keys (`key_map {|k, v| k > 0 ? k : v }`).
-

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: deepmap
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Jeremy Warner